agentsmd-claudemd-generator

AGENTS.md 和 CLAUDE.md 生成器

你将要做什么

为代码仓库生成两个文件：

1. AGENTS.md——遵循开放标准（https://agents.md）的跨工具 Agent 指令。Claude Code、Cursor、Windsurf、Zed、GitHub Copilot、OpenAI Codex、Aider 等众多工具均支持此标准。这是主要文件，包含项目背景、约定和工作流。
2. CLAUDE.md——Claude Code 专用配置，通过 @import 引用 AGENTS.md，并补充任何 Claude 专属指令。这样可以避免在两个文件中重复内容。

为什么需要两个文件？

• AGENTS.md 是跨工具标准——任何 AI 编码工具都会读取它。将所有项目知识放在这里。
• CLAUDE.md 是 Claude Code 专用文件。内容应保持精简：指向 AGENTS.md，并且只添加 Claude 专属内容。
• 这样，你只需在一个地方（AGENTS.md）维护文档，所有工具都能受益。

---

参考文档

请始终优先引导用户查阅以下文档，而不是复述其中的内容：

• AGENTS.md 规范：https://agents.md
• CLAUDE.md 记忆文档：https://code.claude.com/docs/en/memory
• CLAUDE.md 指南（Builder.io）：https://www.builder.io/blog/claude-md-guide

---

阶段 1 · 了解代码仓库

1. 检查现有文件

   • 查找代码仓库中是否已有 AGENTS.md、CLAUDE.md、CLAUDE.local.md、.claude/CLAUDE.md 和 .claude/rules/。
   • 如果存在这些文件，请计划更新或扩展，而不是覆盖。

2. 阅读核心文档

   • 浏览 README.md、CONTRIBUTING.md 以及任何 docs/ 目录。
   • 记录项目理念、设置步骤和工作流。

3. 查看项目布局

   • 确认主要目录、语言、框架和所有权归属。
   • 运行 tree --gitignore -a -L 3 获取目录概况。将内容精简至前 2-3 层。

4. 确认工具和命令

   • 查找项目实际使用的构建、测试、检查、格式化和部署命令。
   • 记录环境要求：运行时、包管理器、环境变量和 .env.example 文件。

5. 确认现有文档

   • 检查项目文档是否已介绍代码风格、约定、模式或最佳实践（例如 docs/best_practices.md、CONTRIBUTING.md、风格指南）。
   • 这些文档是事实来源——AGENTS.md 应通过 @import 引用它们，而不是重复其中的内容。
   • 对几乎适用于每次代码变更的核心文档（风格指南、约定、模式）：使用 @import，使其始终加载到上下文中。
   • 对仅偶尔需要的文档（部署、设置）：使用普通 Markdown 链接。
   • 留意文档长度：建议使用 @import 前，先检查文件大小。超过约 300 行（约 1,500 个 token）的文件值得提醒开发者——大型 @import 会在每次对话中占用上下文窗口。建议仅导入最关键的章节，或保留为普通链接以便按需阅读。

6. 解决不明确之处

   • 请开发者确认技术栈——不要仅凭代码推断其是否完整（CI 工具、基础设施和平台专属细节很容易遗漏）。
   • 询问开发者日常使用的主要命令——不要只罗列 package.json 或 Makefile 中的所有命令。
   • 如果约定或所有权归属不明确，请询问开发者。不要猜测。

**预期结果：**涵盖项目布局、工具、命令、测试、约定和待解决问题的结构化笔记。

---

阶段 2 · 生成 AGENTS.md

将文件放在代码仓库根目录。请遵循以下章节顺序，以保持一致：

# Agent Guidelines

Brief one-line project description.

Detailed docs live in @docs/... — reference them with @imports rather than duplicating here.

## Tech Stack

- **React** - Component framework
- **TypeScript** - Language (strict mode)
- **Relay** - GraphQL data fetching


## Common Commands

- `<lint command>` — run on changed files
- `<test command>` — run on changed files
- `<type-check command>` — verify types
- `<build command>` — production build

## Pre-Commit Verification

Before every commit, verify code quality on pending files:

\`\`\`sh
<type-check command>
<test command on changed files>
<lint command on changed files>
\`\`\`

Never commit code that fails these checks.

## Code Style & Common Patterns



@docs/best_practices.md



## File Organization


\`\`\`
src/
├── Apps/           # Sub-applications
├── Components/     # Shared across apps
└── System/         # Framework code
\`\`\`

## Workflow

- Branching model
- PR / review expectations
- Commit message format

## Gotchas

- Non-obvious project quirks
- Common pitfalls

## Further Documentation

- [Topic](docs/topic.md)
- And more in @docs

编写指南

• 切勿重复已有文档 — 如果项目已在文件（如 best_practices.md、CONTRIBUTING.md、风格指南）中说明代码风格、模式或约定，请使用 @import 将其引入上下文，而不是重述内容。对于 Agent 始终需要了解的文档（约定、模式、风格规则），请使用 @import。对于仅偶尔需要查阅的文档，请使用普通 Markdown 链接。AGENTS.md 应补充现有文档，而非复制它们。
• 大型导入前发出提醒 — 添加 @import 前，先检查文件大小。如果文档超过约 300 行，请提醒开发者：每次对话都会因此消耗大量上下文窗口空间，并询问他们是要完整导入、仅导入关键章节，还是保留为普通链接。
• 请开发者确认技术栈以及哪些命令是主要命令。不要仅凭代码检查就假定信息完整——CI 工具、基础设施和日常使用的命令很容易遗漏或过度收录。
• 保持可执行 — Agent 应逐字遵循指令，而不是自行解读模糊的指导。
• “将 X 用于 Y” — 将工具与用途对应起来，帮助 Agent 选择合适的库（仅限现有文档尚未涵盖的情况）。
• 精确命令 — 写出实际的 Shell 命令，而不是对操作的描述。仅列出开发者最常用的命令，不要直接搬出 package.json 中的完整脚本部分。
• 提交前检查 — 始终加入验证区块，列出提交前要运行的命令。
• 引用更详细的文档 — 使用 @imports 链接到详细文档，而不是复制其内容。
• 为文件树添加注释 — 不要直接粘贴原始 tree 输出；应整理文件树，并在行内添加说明。
• 少于 300 行。仅包含与项目相关的章节，跳过空章节。

---

第 3 阶段 · 生成 CLAUDE.md

将文件放在仓库根目录，与 AGENTS.md 并列。此文件应当精简——其作用是指向 AGENTS.md。对大多数项目来说，以下内容就足够了：

# CLAUDE.md

See @AGENTS.md

这通常就是整个文件的全部内容，这样完全没问题。只有在项目确实使用 Claude 专属功能时，才添加 Claude 专属章节：

• .claude/rules/ — 项目中模块化规则文件的引用
• .claude/commands/ — 项目中可用的自定义斜杠命令
• .claude/agents/ — 项目中可用的自定义子 Agent
• 与 Claude 功能相关的行为偏好 — 例如：“非简单任务使用计划模式”“使用子 Agent 并行调研”
• 工具权限提示 — 例如：“无需询问即可运行 npm test”

如果以上都不适用，就不要添加这些内容。空的 Claude 专属章节不如不添加。

Claude 记忆功能补充说明

请引导开发者查看文档（https://code.claude.com/docs/en/memory），了解 CLAUDE.local.md、.claude/rules/、@imports、/init 和自动记忆等高级功能。

---

第 4 阶段 · 验证并收尾

1. 仓库根目录中存在这两个文件。
2. CLAUDE.md 通过 See @AGENTS.md 引用 AGENTS.md。
3. 无重复内容 — 项目知识仅保存在 AGENTS.md 中。
4. 命令准确 — 所有列出的命令都能正常运行。
5. 简洁 — 两个文件都便于浏览，且少于 300 行。
6. 交接摘要 — 告知开发者添加了哪些内容，指出尚待确认的问题，并提供高级功能的官方文档链接。