agentsmd-claudemd-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AGENTS.md & CLAUDE.md Generator

What You'll Do

你将完成的工作

Generate two files for the repository:

AGENTS.md
— Cross-tool agent instructions following the open standard (https://agents.md). Supported by Claude Code, Cursor, Windsurf, Zed, GitHub Copilot, OpenAI Codex, Aider, and many others. This is the primary file containing project context, conventions, and workflows.
CLAUDE.md
— Claude Code-specific configuration that references AGENTS.md via
```
@import
```
and adds any Claude-specific instructions. This avoids duplicating content across two files.

为仓库生成两个文件：

AGENTS.md
—— 遵循开放标准（https://agents.md）的跨工具Agent指令，支持Claude Code、Cursor、Windsurf、Zed、GitHub Copilot、OpenAI Codex、Aider等多款工具。这是核心文件，包含项目上下文、约定和工作流。
CLAUDE.md
—— 专为Claude Code打造的配置文件，通过
```
@import
```
引用AGENTS.md，还可添加任何Claude专属的指令，避免两个文件内容重复。

Why two files?

为什么需要两个文件？

AGENTS.md is the cross-tool standard — any AI coding tool reads it. Put all project knowledge here.
CLAUDE.md is Claude Code-specific. It should be thin: point to AGENTS.md and only add what's Claude-unique.
This means you maintain docs in one place (AGENTS.md) and every tool benefits.

AGENTS.md 是跨工具标准，所有AI编码工具都能读取，请将所有项目相关知识都放在这里。
CLAUDE.md 是Claude Code专属配置，应该尽可能精简：仅指向AGENTS.md，只添加Claude独有的配置内容。
这意味着你只需要在一个地方（AGENTS.md）维护文档，所有工具都能复用这些内容。

Reference Documentation

参考文档

Always prefer pointing users to these docs rather than reciting their contents:

AGENTS.md spec: https://agents.md
CLAUDE.md memory docs: https://code.claude.com/docs/en/memory
CLAUDE.md guide (Builder.io): https://www.builder.io/blog/claude-md-guide

请优先引导用户查阅以下文档，不要复述文档内容：

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

Phase 1 · Understand the Repository

第一阶段 · 了解仓库

Check for existing files
- Look for existing
```
AGENTS.md
```
  ,
```
CLAUDE.md
```
  ,
```
CLAUDE.local.md
```
  ,
```
.claude/CLAUDE.md
```
  , and
```
.claude/rules/
```
  in the repo.
- If files exist, plan to update/extend rather than overwrite.
Read core docs
- Skim
```
README.md
```
  ,
```
CONTRIBUTING.md
```
  , and any
```
docs/
```
  directory.
- Note project philosophy, setup steps, and workflows.
Survey project layout
- Identify primary directories, languages, frameworks, and ownership.
- Run
```
tree --gitignore -a -L 3
```
  to get a directory snapshot. Trim to top 2-3 levels.
Identify tooling and commands
- Find the project's build, test, lint, format, and deploy commands — whatever tool the project actually uses.
- Note environment requirements: runtimes, package managers, env vars,
```
.env.example
```
  files.
Identify existing documentation
- Check if project docs already cover code style, conventions, patterns, or best practices (e.g.,
```
docs/best_practices.md
```
  ,
```
CONTRIBUTING.md
```
  , style guides).
- These docs are the source of truth — AGENTS.md should reference them via
```
@import
```
  , not duplicate their content.
- For core docs that apply to nearly every code change (style guides, conventions, patterns): use
```
@import
```
  so they're always loaded into context.
- For docs only relevant occasionally (deployment, setup): use plain markdown links.
- Watch for size: before recommending
```
@import
```
  , check the file size. Files over ~300 lines (~1,500 tokens) are worth flagging to the developer — warn them that large
```
@import
```
  s eat into the context window on every conversation. Suggest they either import only the most critical sections, or keep it as a plain link for on-demand reading.
Resolve ambiguities
- Ask the developer to confirm the tech stack — don't assume completeness from code alone (CI tools, infrastructure, and platform-specific details are easy to miss).
- Ask which commands are the main ones developers use daily — don't just list everything from package.json/Makefile.
- Ask the developer when conventions or ownership are unclear. Do not guess.

Outcome: Structured notes covering layout, tooling, commands, testing, conventions, and open questions.

检查现有文件
- 查找仓库中已有的
```
AGENTS.md
```
  、
```
CLAUDE.md
```
  、
```
CLAUDE.local.md
```
  、
```
.claude/CLAUDE.md
```
  和
```
.claude/rules/
```
  。
- 如果已有相关文件，请计划更新/扩展而非直接覆盖。
阅读核心文档
- 浏览
```
README.md
```
  、
```
CONTRIBUTING.md
```
  和所有
```
docs/
```
  目录下的内容。
- 记录项目理念、环境搭建步骤和工作流。
梳理项目结构
- 识别核心目录、使用的语言、框架和所有权。
- 运行
```
tree --gitignore -a -L 3
```
  获取目录快照，仅保留前2-3级目录即可。
识别工具和命令
- 找到项目实际使用的构建、测试、lint、格式化和部署命令。
- 记录环境要求：运行时、包管理器、环境变量、
```
.env.example
```
  文件。
识别现有文档
- 检查项目文档是否已经涵盖代码风格、约定、模式或最佳实践（比如
```
docs/best_practices.md
```
  、
```
CONTRIBUTING.md
```
  、风格指南等）。
- 这些文档是唯一可信源——AGENTS.md应该通过
```
@import
```
  引用它们，不要重复内容。
- 对于几乎所有代码变更都适用的核心文档（风格指南、约定、模式）：使用
```
@import
```
  ，这样它们会始终被加载到上下文中。
- 对于仅偶尔需要的文档（部署、搭建指南）：使用普通markdown链接即可。
- 注意文件大小：推荐使用
```
@import
```
  前，请检查文件大小。超过约300行（约1500 token）的文件需要告知开发者——提醒他们大体积的
```
@import
```
  会在每次对话中占用上下文窗口，建议他们要么仅导入最关键的部分，要么保留为普通链接供按需阅读。
消除歧义
- 请开发者确认技术栈——不要仅通过代码判断完整性（CI工具、基础设施、平台专属细节很容易遗漏）。
- 询问开发者日常使用的核心命令有哪些——不要直接罗列package.json/Makefile里的所有命令。
- 当约定或所有权不明确时询问开发者，不要猜测。

产出：涵盖结构、工具、命令、测试、约定和待确认问题的结构化笔记。

Phase 2 · Generate AGENTS.md

第二阶段 · 生成AGENTS.md

Place at the repository root. Follow this section order for consistency:

markdown

undefined

放在仓库根目录，遵循以下章节顺序保持一致性：

markdown

undefined

Agent Guidelines

Brief one-line project description.

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

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

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

```
<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.

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

@docs/best_practices.md

File Organization

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

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

Workflow

Branching model
PR / review expectations
Commit message format

Branching model
PR / review expectations
Commit message format

Gotchas

Non-obvious project quirks
Common pitfalls

Non-obvious project quirks
Common pitfalls

Further Documentation

Topic
And more in @docs

undefined

Topic
And more in @docs

undefined

Writing guidelines

编写指南

Never duplicate existing docs — if the project already documents code style, patterns, or conventions (in files like
```
best_practices.md
```
,
```
CONTRIBUTING.md
```
, style guides), use
```
@import
```
to pull them into context instead of restating the content. Use
```
@import
```
for docs agents should always have (conventions, patterns, style rules). Use plain markdown links for docs only needed occasionally. AGENTS.md should complement existing docs, not copy them.
Warn about large imports — before adding an
```
@import
```
, check the file size. If a doc is over ~300 lines, warn the developer that it will consume significant context window space on every conversation and ask whether they want to import it fully, import only key sections, or keep it as a plain link.
Ask the developer to confirm the tech stack and which commands are the main ones. Don't assume completeness from code inspection alone — CI tools, infrastructure, and daily-use commands are easy to miss or over-include.
Keep it actionable — agents should follow instructions verbatim, not interpret vague guidance.
"Use X for Y" — map tools to purposes so agents pick the right library (only when not already covered by existing docs).
Exact commands — include the actual shell commands, not descriptions of what to do. Only list the commands developers use most — don't dump the full scripts section from package.json.
Pre-commit checks — always include a verification block with commands to run before committing.
Reference deeper docs — use
```
@imports
```
to link to detailed docs instead of duplicating content.
Annotate the file tree — don't dump raw
```
tree
```
output; curate it with inline descriptions.
Stay under 300 lines. Only include sections relevant to the project — skip empty ones.

永远不要重复现有文档内容——如果项目已经在
```
best_practices.md
```
、
```
CONTRIBUTING.md
```
、风格指南等文件中记录了代码风格、模式或约定，请使用
```
@import
```
将其引入上下文，不要复述内容。对于Agent应该始终加载的文档（约定、模式、风格规则）使用
```
@import
```
，仅偶尔需要的文档使用普通markdown链接。AGENTS.md应该是现有文档的补充，而非复制。
提醒大体积导入的风险：添加
```
@import
```
前检查文件大小，如果文档超过约300行，提醒开发者它会在每次对话中占用大量上下文窗口空间，询问他们是否要完整导入、仅导入关键部分，还是保留为普通链接。
请开发者确认技术栈和核心命令，不要仅通过检查代码就判定内容完整——CI工具、基础设施、日常使用的命令很容易遗漏或者多列。
保持内容可执行——Agent应该可以直接遵循指令，不需要解读模糊的引导。
"使用X实现Y"——明确工具对应的用途，让Agent选择正确的库（仅当现有文档没有覆盖时补充）。
精确命令——包含实际的shell命令，不要仅描述要做什么。仅列出开发者最常用的命令，不要把package.json里的所有scripts都列出来。
预提交检查——始终包含一个验证块，列出提交前需要运行的命令。
关联更详细的文档——使用
```
@imports
```
链接到详细文档，不要重复内容。
给文件树添加注释——不要直接输出原始的
```
tree
```
结果，添加内联说明整理后再展示。
保持内容在300行以内，仅包含和项目相关的章节，跳过空章节。

Phase 3 · Generate CLAUDE.md

第三阶段 · 生成CLAUDE.md

Place at the repository root alongside AGENTS.md. This file should be thin — its job is to point to AGENTS.md. For most projects, this is all you need:

markdown

undefined

放在仓库根目录，和AGENTS.md同层级。这个文件应该非常精简——它的作用是指向AGENTS.md，对于大多数项目，以下内容就足够了：

markdown

undefined

CLAUDE.md

See @AGENTS.md


That's often the entire file, and that's fine. Only add a Claude-specific section if the project actually uses Claude-only features:

- **`.claude/rules/`** — references to modular rule files in the project
- **`.claude/commands/`** — custom slash commands available in the project
- **`.claude/agents/`** — custom subagents available in the project
- **Behavioral preferences tied to Claude capabilities** — e.g., "Use plan mode for non-trivial tasks", "Use subagents for parallel research"
- **Tool permission hints** — e.g., "You have permission to run `npm test` without asking"

If none of these apply, don't add them. An empty Claude-specific section is worse than no section.

See @AGENTS.md


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

- **`.claude/rules/`**——引用项目中的模块化规则文件
- **`.claude/commands/`**——项目中可用的自定义斜杠命令
- **`.claude/agents/`**——项目中可用的自定义子Agent
- **和Claude能力绑定的行为偏好**——比如"非trivial任务使用规划模式"、"并行调研使用子Agent"
- **工具权限提示**——比如"你可以直接运行`npm test`无需询问"

如果没有以上场景，不要添加这些内容，空的Claude专属章节还不如没有。

Additional Claude memory features

额外的Claude内存功能

Point the developer to the docs (https://code.claude.com/docs/en/memory) for advanced features like

CLAUDE.local.md

.claude/rules/

@imports

/init

, and auto memory.

引导开发者查阅文档（https://code.claude.com/docs/en/memory）了解高级功能，比如`CLAUDE.local.md`、`.claude/rules/`、`@imports`、`/init`和自动内存。

Phase 4 · Validate & Wrap Up

第四阶段 · 验证和收尾

Both files exist at the repo root.
CLAUDE.md references AGENTS.md via
```
See @AGENTS.md
```
.
No duplication — project knowledge lives in AGENTS.md only.
Commands are accurate — all listed commands actually work.
Concise — both files are scannable and under 300 lines.
Handoff summary — tell the developer what was added, flag open questions, and point to the official docs for advanced features.

两个文件都已存在于仓库根目录。
CLAUDE.md通过
See @AGENTS.md
引用了AGENTS.md。
没有内容重复——项目知识仅存放在AGENTS.md中。
命令准确——所有列出的命令都可以正常运行。
简洁——两个文件都方便浏览，且长度在300行以内。
交付总结——告知开发者添加了哪些内容，标注待确认的问题，引导用户查阅官方文档了解高级功能。