improve-agents-md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

improve-agents-md

改进AGENTS.md/CLAUDE.md文件

Progressively improve (or bootstrap from scratch) a project's agent-instruction file. Works on both

AGENTS.md

(vendor-neutral convention from OpenAI Codex, also read by Cursor, Claude Code, and others) and

CLAUDE.md

(Claude-specific). Keeps one canonical file on disk and symlinks the other, so every agent reads the same source of truth.

逐步改进（或从头创建）项目的Agent指令文件。适用于

AGENTS.md

（OpenAI Codex提出的厂商中立规范，Cursor、Claude Code等工具均支持读取）和

CLAUDE.md

（Claude专属文件）。在磁盘中保留一个标准文件，并为另一个文件创建符号链接，确保所有Agent读取的是同一真实数据源。

When to Use

使用场景

User invokes
```
/improve-agents-md
```
(or
```
/improve-claude-md
```
pointed here)
User asks you to "clean up", "shorten", "audit", or "rewrite" their CLAUDE.md / AGENTS.md
User complains that Claude (or another agent) keeps ignoring their project rules
User is about to onboard a new agent and wants to check their instructions are any good
No AGENTS.md / CLAUDE.md exists and the user wants to set one up properly

用户调用
```
/improve-agents-md
```
（或指向此技能的
```
/improve-claude-md
```
）
用户要求你“整理”“缩短”“审核”或“重写”他们的CLAUDE.md / AGENTS.md
用户抱怨Claude（或其他Agent）持续忽略其项目规则
用户即将引入新Agent，希望确认指令是否合理
不存在AGENTS.md / CLAUDE.md，用户希望正确配置相关文件

The Core Problem

核心问题

Claude Code (and most other agents) inject the project agent-file with a system reminder that says:

"this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task."

So the agent will ignore parts it deems irrelevant. The more content that isn't applicable to the current task, the more likely the agent is to ignore the entire file — including the parts that matter right now. Long, undifferentiated agent files are self-defeating.

Two levers fix this:

Cut ruthlessly. Anything a linter, formatter, or pre-commit hook can enforce does not belong here. Anything discoverable from existing code patterns (LLMs are in-context learners) does not belong here. Anything vague ("write clean code", "follow best practices") does not belong here.
Wrap conditionally. Domain-specific guidance gets wrapped in
```
<important if="...">
```
blocks with narrow, specific conditions. This piggybacks on the same XML tag pattern Claude Code uses in its own system prompt, giving the model an explicit relevance signal that cuts through the "may or may not be relevant" framing.

The result is a short file where foundational context is always visible and domain guidance only "lights up" when it matches the task at hand.

Claude Code（及大多数其他Agent）会在项目Agent文件中注入一条系统提示：

"此上下文可能与你的任务相关，也可能无关。除非与当前任务高度相关，否则你无需响应此上下文。"

因此Agent会忽略它认为无关的内容。与当前任务无关的内容越多，Agent就越有可能忽略整个文件——包括当前任务真正需要的部分。冗长、无区分的Agent文件会适得其反。

有两种方法可以解决这个问题：

无情删减：任何可通过代码检查工具、格式化工具或预提交钩子强制执行的内容，都不应出现在此文件中。任何可从现有代码模式中发现的内容（LLM具备上下文学习能力），也不应出现在此文件中。任何模糊表述（如“编写整洁代码”“遵循最佳实践”）同样不应保留。
条件包裹：特定领域的指引需包裹在带有精准条件的
```
<important if="...">
```
块中。这复用了Claude Code自身系统提示中使用的XML标签模式，为模型提供明确的相关性信号，打破“可能相关也可能无关”的框架限制。

最终得到的文件会非常精简：基础上下文始终可见，领域指引仅在与当前任务匹配时才“生效”。

File Resolution: which file is canonical?

文件解析：哪个文件是标准文件？

The skill runs inside Claude Code, so the canonical on-disk file is

CLAUDE.md

AGENTS.md

exists as a symlink pointing to

CLAUDE.md

so vendor-neutral agents (Codex, Cursor, Copilot workspace) read the same source of truth.

Resolution logic at the start of every run:

Check for
```
CLAUDE.md
```
and
```
AGENTS.md
```
at the repo root (and in subdirectory if the user invokes from one).
Branch on what's present:
- Only
  CLAUDE.md
  → operate on it; at the end, offer to create
```
AGENTS.md
```
  as a symlink →
```
CLAUDE.md
```
  .
- Only
  AGENTS.md
  (real file, not a symlink) → offer to rename it to
```
CLAUDE.md
```
  and create
```
AGENTS.md
```
  →
```
CLAUDE.md
```
  symlink. If user declines the rename, edit
```
AGENTS.md
```
  directly.
- Both exist, one is a symlink → edit the real file; leave the symlink alone.
- Both exist, both are real files → this is a drift bug. Use AskUserQuestion to ask which one is canonical; offer to replace the other with a symlink after the edit.
- Neither exists → use AskUserQuestion: 1. Bootstrap a new
```
CLAUDE.md
```
  from the codebase, 2. Abort.

Always use

ls -la

(or equivalent) to detect symlinks; never assume from the filename.

此技能运行在Claude Code中，因此磁盘上的标准文件为

CLAUDE.md

。

AGENTS.md

作为指向

CLAUDE.md

的符号链接存在，确保厂商中立的Agent（如Codex、Cursor、Copilot workspace）读取的是同一真实数据源。

每次运行时的解析逻辑：

在仓库根目录（若用户从子目录调用则同时检查子目录）查找
```
CLAUDE.md
```
和
```
AGENTS.md
```
。
根据文件存在情况分支处理：
- 仅存在
  CLAUDE.md
  → 对此文件进行操作；结束时，提议创建指向
```
CLAUDE.md
```
  的
```
AGENTS.md
```
  符号链接。
- 仅存在
  AGENTS.md
  （真实文件，非符号链接）→ 提议将其重命名为
```
CLAUDE.md
```
  ，并创建指向
```
CLAUDE.md
```
  的
```
AGENTS.md
```
  符号链接。若用户拒绝重命名，则直接编辑
```
AGENTS.md
```
  。
- 两者均存在，其中一个是符号链接 → 编辑真实文件；保留符号链接不变。
- 两者均存在，且均为真实文件 → 这是一个文件漂移问题。使用AskUserQuestion询问用户哪个是标准文件；编辑完成后，提议将另一个文件替换为符号链接。
- 两者均不存在 → 使用AskUserQuestion：1. 基于代码库从头创建
```
CLAUDE.md
```
  ；2. 终止操作。

始终使用

ls -la

（或等效命令）检测符号链接；切勿仅通过文件名进行假设。

Interactive Flow

交互流程

This skill is progressive, not one-shot. Use AskUserQuestion at decision points so the user stays in control. The flow below is the default; skip steps if the input file is already clean or the user asks to go faster.

此技能采用渐进式而非一次性处理方式。在决策节点使用AskUserQuestion，确保用户掌控全局。以下为默认流程；若输入文件已足够整洁或用户要求加快进度，可跳过部分步骤。

Step 1 — Resolve the target file

步骤1 — 确定目标文件

Follow the resolution logic above. State clearly which file you'll be editing and why.

遵循上述解析逻辑。明确告知用户将编辑哪个文件及原因。

Step 2 — Read and categorize

步骤2 — 读取并分类

Read the full file. Categorize every top-level section into one of:

Category	Examples	Treatment
Foundational (always relevant)	project identity (1 sentence), project map (directory listing), tech stack (1-2 lines)	Leave bare at top.
Commands	build/test/lint/dev commands	Wrap in a single `<important if="you need to run commands to build, test, lint, or generate code">` block. Keep all commands.
Conditional rule	"use Zod for request validation", "API routes go in X"	Wrap in its own `<important if>` block with a narrow trigger.
Domain section	testing setup, state management, i18n, auth	Wrap in one `<important if>` per section.
Lint/formatter territory	camelCase, `const` over `let` , strict equality, JSDoc	Delete. Suggest a pre-commit hook instead.
Vague exhortation	"follow best practices", "leverage the X agent", "think carefully"	Delete.
Stale code snippet	20-line example of a component	Delete. Replace with a file path reference ( `see src/utils/example.ts` ).

读取完整文件。将每个顶级章节归类为以下类别之一：

类别	示例	处理方式
基础内容（始终相关）	项目标识（1句话）、项目目录结构、技术栈（1-2行）	保留在文件顶部，无需包裹。
命令	构建/测试/代码检查/开发命令	统一包裹在 `<important if="you need to run commands to build, test, lint, or generate code">` 块中。保留所有命令。
条件规则	"使用Zod进行请求验证"、"API路由存放于X目录"	为每条规则单独创建 `<important if>` 块，并设置精准触发条件。
领域章节	测试设置、状态管理、国际化、认证	每个领域章节单独包裹在一个 `<important if>` 块中。
代码检查/格式化工具管辖范围	camelCase命名、优先使用 `const` 而非 `let` 、严格相等、JSDoc	删除。建议改用预提交钩子。
模糊表述	"遵循最佳实践"、"利用X Agent"、"仔细思考"	删除。
过时代码片段	20行组件示例	删除。替换为文件路径引用（如 `see src/utils/example.ts` ）。

Step 3 — Propose cuts

步骤3 — 提议删减内容

Before rewriting, use AskUserQuestion to confirm the deletions that might be controversial. Don't ask about every cut — only the ones where reasonable people could disagree. Batch them into a single question with a multi-select list:

Example:

"I'd like to drop the following from your CLAUDE.md because they're either linter territory or too vague to act on. Which of these are you OK losing?"

camelCase / PascalCase rules (linter territory)

"Write JSDoc for all public functions" (linter can enforce, also stale)

"Follow clean code principles" (too vague)

Keep all of them anyway

Skip this step if nothing controversial is being cut.

重写前，使用AskUserQuestion确认可能存在争议的删减内容。无需询问每一项删减，仅针对可能存在分歧的内容。将这些内容整合为一个带有多选列表的问题：

示例：

"我想从你的CLAUDE.md中删除以下内容，因为它们属于代码检查工具管辖范围或表述过于模糊，无法落地执行。请问哪些内容你同意删除？"

camelCase / PascalCase命名规则（代码检查工具管辖范围）

"为所有公共函数编写JSDoc"（可由代码检查工具强制执行，且已过时）

"遵循整洁代码原则"（表述模糊）

全部保留

若无争议内容需删减，可跳过此步骤。

Step 4 — Propose the new structure

步骤4 — 提议新结构

Show the user the proposed section list with their

<important if>

conditions — not the full rewrite yet, just the outline. This is cheap and catches disagreements before you do the full rewrite.

Use AskUserQuestion to confirm, with options like:

"Looks good — rewrite it"
"Change some conditions" (collect which)
"Add a section I'm missing" (collect which)

向用户展示带有

<important if>

条件的章节列表提议——无需展示完整重写内容，仅需大纲即可。这种方式成本低，可在完成完整重写前发现分歧。

使用AskUserQuestion确认，提供如下选项：

"看起来不错——开始重写"
"修改部分条件"（收集具体修改内容）
"添加我遗漏的章节"（收集具体章节）

Step 5 — Snapshot the original

步骤5 — 备份原始文件

Before writing anything, copy the current file so you can compute before/after metrics and so the user has a rollback:

bash

cp CLAUDE.md /tmp/CLAUDE.md.before-$(date +%s)

Remember the snapshot path — you'll need it in Step 7.

开始写入前，复制当前文件，以便计算修改前后的指标，并为用户提供回滚选项：

bash

cp CLAUDE.md /tmp/CLAUDE.md.before-$(date +%s)

记住备份文件路径——步骤7会用到。

Step 6 — Rewrite and diff

步骤6 — 重写并展示差异

Write the new file. Show the user a concise diff summary (sections added / removed / reworded). Don't dump the full file into chat — they can read it on disk.

编写新文件。向用户展示简洁的差异摘要（新增/删除/改写的章节）。无需将完整文件粘贴到聊天中——用户可直接在磁盘上查看。

Step 7 — Report metrics

步骤7 — 报告指标

Compute and show a before/after comparison. The four numbers that matter:

Metric	How to compute
Chars	`wc -c <file>`
Lines	`wc -l <file>`
KB	`ls -lk <file>` (or `du -k <file>` )
Tokens (est.)	`chars / 4` — rough English heuristic. Good enough to show direction; don't over-invest in precision.

Run it for both

before

(the

/tmp/...

snapshot) and

after

(the rewritten file). Present as a compact table:

                  before      after       Δ
chars             8,412       3,104       −63%
lines               247          92       −63%
KB                  8.2         3.0       −63%
tokens (est.)     2,103         776       −63%

One-shot bash helper (adjust paths):

bash

metrics() {
  local f=$1
  local chars=$(wc -c < "$f" | tr -d ' ')
  local lines=$(wc -l < "$f" | tr -d ' ')
  local kb=$(awk "BEGIN {printf \"%.1f\", $chars/1024}")
  local tokens=$((chars / 4))
  printf "%s\tchars=%s lines=%s kb=%s tokens~%s\n" "$f" "$chars" "$lines" "$kb" "$tokens"
}
metrics /tmp/CLAUDE.md.before-XXXXX
metrics CLAUDE.md

If the

after

file isn't meaningfully shorter (say, <10% reduction) and the user came in wanting a cleanup, that's a signal you didn't cut aggressively enough — consider a second pass before finalizing. If it got longer, you probably added invented rules; reread your output against the "What Not to Do" list.

计算并展示修改前后的对比数据。以下四个指标最为重要：

指标	计算方式
字符数	`wc -c <file>`
行数	`wc -l <file>`
大小（KB）	`ls -lk <file>` （或 `du -k <file>` ）
预估Token数	`chars / 4` ——英文文本的粗略估算方法。只需体现变化趋势即可；无需追求高精度。

分别对

before

（

/tmp/...

备份文件）和

after

（重写后的文件）计算指标。以紧凑表格形式展示：

                  before      after       Δ
chars             8,412       3,104       −63%
lines               247          92       −63%
KB                  8.2         3.0       −63%
tokens (est.)     2,103         776       −63%

一键式bash辅助脚本（需调整路径）：

bash

metrics() {
  local f=$1
  local chars=$(wc -c < "$f" | tr -d ' ')
  local lines=$(wc -l < "$f" | tr -d ' ')
  local kb=$(awk "BEGIN {printf \"%.1f\", $chars/1024}")
  local tokens=$((chars / 4))
  printf "%s\tchars=%s lines=%s kb=%s tokens~%s\n" "$f" "$chars" "$lines" "$kb" "$tokens"
}
metrics /tmp/CLAUDE.md.before-XXXXX
metrics CLAUDE.md

若修改后的文件未显著缩短（比如缩减比例<10%），且用户原本要求整理文件，则说明删减力度不足——考虑在最终确定前进行二次处理。若文件变长，则可能是添加了未授权的规则；请对照“禁止事项”列表重新检查输出内容。

Verdict thresholds

判定阈值

Label the

after

file so the user has a one-word takeaway. Tokens are primary; lines/chars are secondary signals.

Tokens (est.)	Verdict	What it means
< 500	Lean ✓	Foundational + a few focused `<important if>` blocks. Target for most projects.
500 – 1,000	Good	Healthy for mid-sized projects. Still fully attended-to by the model.
1,000 – 2,000	Fat ⚠	Almost certainly has linter territory, stale snippets, or grouped rules without narrow triggers. Cut harder.
> 2,000	Bloated ✗	Most of it will be ignored under "may or may not be relevant". Major rewrite warranted.

Caveats to apply with judgment, not rigidly:

Monorepo root files legitimately run larger than per-package ones. A root file covering many distinct domains may land in "Fat" without being unhealthy.
Well-tagged files pay a lower effective cost. A 1,500-token file where most content is scoped by narrow
```
<important if>
```
triggers is healthier than a 900-token file of bare prose — the model only "spends attention" on blocks whose condition matches.
Lines-to-sections ratio is a secondary smell: 300 lines across 25 blocks is fine; 300 lines across 3 blocks is a rewrite.

Report the verdict alongside the before/after table so the user sees direction + magnitude + label in one glance.

为修改后的文件添加标签，让用户一目了然。预估Token数为主要判定依据；行数/字符数为次要参考。

预估Token数	判定结果	说明
< 500	精简 ✓	仅包含基础内容+少量聚焦的 `<important if>` 块。为大多数项目的目标状态。
500 – 1,000	良好	适合中等规模项目。模型可完全关注到所有内容。
1,000 – 2,000	冗余 ⚠	几乎肯定包含代码检查工具管辖内容、过时片段或未设置精准触发条件的分组规则。需进一步删减。
> 2,000	臃肿 ✗	在“可能相关也可能无关”的框架下，大部分内容会被忽略。需进行重大重写。

需灵活应用以下注意事项，切勿僵化执行：

单仓库根目录文件规模合理上限更高，大于子包文件。覆盖多个不同领域的根目录文件可能处于“冗余”区间，但仍属健康状态。
标签精准的文件有效成本更低。一个1500Token的文件，若大部分内容通过精准
```
<important if>
```
触发条件限定范围，比一个900Token的纯文本文件更健康——模型仅会“关注”条件匹配的块。
行数与章节数的比例是次要参考信号：300行内容分为25个章节是合理的；300行内容分为3个章节则需要重写。

在修改前后对比表格旁展示判定结果，让用户一眼看到变化方向、幅度和标签。

Step 8 — Symlink

步骤8 — 创建符号链接

Offer to create the companion symlink if it doesn't exist:

bash

ln -s CLAUDE.md AGENTS.md   # from repo root

Verify with

ls -la CLAUDE.md AGENTS.md

that the symlink resolves to a real file.

若配套符号链接不存在，提议创建：

bash

ln -s CLAUDE.md AGENTS.md   # 从仓库根目录执行

使用

ls -la CLAUDE.md AGENTS.md

验证符号链接是否指向真实文件。

Step 9 — Offer follow-ups

步骤9 — 提供后续选项

Use AskUserQuestion to offer:

"Open the result in file-review so I can leave comments" (
```
/file-review:file-review
```
)
"Also scan subdirectory CLAUDE.md files in this repo"
"Done"

使用AskUserQuestion提供以下选项：

"打开结果文件进行审阅，我将添加评论"（
```
/file-review:file-review
```
）
"同时扫描此仓库中的子目录CLAUDE.md文件"
"完成"

Principles

原则

1. Foundational context stays bare, domain guidance gets wrapped

1. 基础内容保持原样，领域指引进行条件包裹

If it's relevant to 90%+ of tasks, leave it as plain markdown at the top. If it's relevant to a specific kind of work, wrap it in

<important if>

若内容与90%+的任务相关，则作为纯markdown保留在文件顶部。若仅与特定类型的任务相关，则包裹在

<important if>

块中。

2. Conditions must be specific and targeted

2. 条件必须精准且有针对性

Bad — one broad condition swallowing everything:

<important if="you are writing or modifying any code">
- Use absolute imports
- Use functional components
- Use camelCase filenames
</important>

Good — each rule gets its own narrow trigger:

<important if="you are adding or modifying imports">
- Use `@/` absolute imports (see tsconfig.json for path aliases)
- Avoid default exports except in route files
</important>

<important if="you are creating new components">
- Use functional components with explicit prop interfaces
</important>

<important if="you are creating new files or directories">
- Use camelCase for file and directory names
</important>

The whole point of the mechanism is precision. A condition that matches "anytime you write code" is no signal at all.

错误示例——用宽泛条件包裹所有内容：

<important if="you are writing or modifying any code">
- 使用绝对导入
- 使用函数式组件
- 使用camelCase文件名
</important>

正确示例——每条规则使用独立的精准触发条件：

<important if="you are adding or modifying imports">
- 使用`@/`绝对导入（详见tsconfig.json中的路径别名）
- 除路由文件外，避免使用默认导出
</important>

<important if="you are creating new components">
- 使用带有显式属性接口的函数式组件
</important>

<important if="you are creating new files or directories">
- 文件和目录名使用camelCase
</important>

此机制的核心在于精准性。匹配“任何编写代码场景”的条件毫无信号价值。

3. Keep it inline — no progressive sharding

3. 保持内联——无需渐进式分片

Do not shard the file into separate referenced docs that require the agent to make extra tool calls to discover — unless the extra content is genuinely verbose (say, >200 lines) and only rarely relevant.

<important if>

blocks are the progressive-disclosure mechanism; they make everything visible but conditionally weighted.

除非额外内容确实非常冗长（比如>200行）且极少用到，否则不要将文件拆分为需要Agent额外调用工具才能发现的独立文档。

<important if>

块就是渐进式披露机制；它让所有内容可见，但仅在条件匹配时赋予权重。

4. Less is more

4. 少即是多

Frontier models can reliably follow a few hundred instructions; Claude Code's own system prompt and tools already spend ~50 of that budget. Your file should be lean.

Cut anything a linter, formatter, or hook can enforce.
Cut anything the agent can discover from existing code patterns.
Cut code snippets — they go stale. Reference a file path instead.
Cut vague exhortations.

前沿模型可可靠遵循数百条指令；Claude Code自身的系统提示和工具已占用约50个Token的预算。你的文件应保持精简。

删除任何可通过代码检查工具、格式化工具或钩子强制执行的内容。
删除任何Agent可从现有代码模式中发现的内容。
删除代码片段——它们会过时。改用文件路径引用。
删除模糊表述。

5. Keep all commands

5. 保留所有命令

Commands are the one section where completeness beats brevity. The agent needs to know what's available even if a command is used rarely. Keep every command from the original; you may drop redundant descriptions, not the command itself.

命令是唯一需要完整性而非简洁性的章节。即使某些命令很少使用，Agent也需要了解其存在。保留原始文件中的所有命令；可删除冗余描述，但不可删除命令本身。

6. Explain the "why" on anything non-obvious

6. 对非显而易见的规则说明“原因”

If a rule isn't self-explanatory, add a short reason.

Use prismaMock from packages/db/test

is clearer as

Use prismaMock from packages/db/test — real DB connections in tests flake on CI

. The agent uses the reason to make better judgment calls on edge cases.

若规则并非不言自明，添加简短说明。

Use prismaMock from packages/db/test

改为

Use prismaMock from packages/db/test — 测试中使用真实数据库连接会导致CI不稳定

会更清晰。Agent可利用原因在边缘案例中做出更好的判断。

Output Structure

输出结构

Target layout when rewriting. Use this as a skeleton:

markdown

undefined

重写时的目标布局。以此为框架：

markdown

undefined

CLAUDE.md

[one-line project identity — what it is, what it's built with]

[一句话项目标识——项目用途、技术栈]

Project map

[directory listing with brief descriptions — keep bare]

[commands table — ALL commands from the original]

</important> <important if="<specific trigger for rule 1>">

[rule 1]

</important> <important if="<specific trigger for rule 2>">

[rule 2]

</important> <important if="<specific trigger for domain area 1>">

[guidance for that domain]

</important>

... more sections, each with its own targeted condition ...


Notes:
- The title (`# CLAUDE.md` or `# AGENTS.md`) should match the canonical file's name.
- Project identity on line 3 is one sentence, not a paragraph.
- Blank lines inside `<important if>` blocks help rendering in some agents — keep them.

[带简要说明的目录列表——保持原样]

[命令表格——包含原始文件中的所有命令]

</important> <important if="<规则1的精准触发条件>">

[规则1]

</important> <important if="<规则2的精准触发条件>">

[规则2]

</important> <important if="<领域1的精准触发条件>">

[该领域的指引]

</important>

... 更多章节，每个章节均带有独立的精准触发条件 ...


注意事项：
- 标题（`# CLAUDE.md`或`# AGENTS.md`）应与标准文件的名称一致。
- 第3行的项目标识为一句话，而非段落。
- `<important if>`块中的空行有助于部分Agent渲染——请保留。

Bootstrap Mode (greenfield)

从头创建模式（全新项目）

When there's no existing file and the user opted into bootstrap:

Read the repo root:
```
ls
```
,
```
cat package.json
```
/
```
pyproject.toml
```
/ equivalent, identify the primary language and runtime.
Detect scripts: parse
```
package.json
```
scripts, or
```
Makefile
```
/
```
justfile
```
/
```
Taskfile
```
targets, or
```
pyproject.toml
```
tool configs. Translate to a commands table.
Walk the directory tree one level deep (two levels if it's a monorepo) for the project map.
Ask the user via AskUserQuestion for anything that can't be inferred:
- Is this a monorepo, single service, or library?
- Are there non-obvious conventions (e.g., "routes live in X")?
- Is there a testing framework in use, and any test setup the agent should know?
Draft a minimal file — foundational + commands only. Don't invent rules the user didn't give you. An agent file with fewer rules is better than one with invented rules.

当不存在现有文件且用户选择从头创建时：

读取仓库根目录：
```
ls
```
、
```
cat package.json
```
/
```
pyproject.toml
```
/等效文件，确定主要语言和运行环境。
检测脚本：解析
```
package.json
```
中的scripts、
```
Makefile
```
/
```
justfile
```
/
```
Taskfile
```
中的目标，或
```
pyproject.toml
```
中的工具配置。转换为命令表格。
遍历目录树一级深度（若为单仓库则遍历两级）以生成项目目录结构。
使用AskUserQuestion询问无法推断的信息：
- 这是单仓库、独立服务还是类库？
- 是否存在非显而易见的约定（如“路由存放于X目录”）？
- 使用了哪些测试框架，Agent需要了解哪些测试设置？
起草最小化文件——仅包含基础内容和命令。不要添加用户未提及的规则。规则更少的Agent文件比包含自创规则的文件更好。

Example Transform

转换示例

Input (

CLAUDE.md

before):

markdown

undefined

输入（修改前的

CLAUDE.md

）：

markdown

undefined

CLAUDE.md

This is an Express API with a React frontend in a Turborepo monorepo.

Commands

Command	Description
`turbo build`	Build all packages
`turbo test`	Run all tests
`turbo lint`	Lint all packages
`turbo dev`	Start dev server
`turbo db:generate`	Generate Prisma client
`turbo db:migrate`	Run database migrations

Command	Description
`turbo build`	Build all packages
`turbo test`	Run all tests
`turbo lint`	Lint all packages
`turbo dev`	Start dev server
`turbo db:generate`	Generate Prisma client
`turbo db:migrate`	Run database migrations

Project Structure

```
apps/api/
```
- Express REST API
```
apps/web/
```
- React SPA
```
packages/db/
```
- Prisma schema and client
```
packages/ui/
```
- Shared component library

```
apps/api/
```
- Express REST API
```
apps/web/
```
- React SPA
```
packages/db/
```
- Prisma schema and client
```
packages/ui/
```
- Shared component library

Coding Standards

Use named exports
Use functional components with TypeScript interfaces for props
Use camelCase for variables, PascalCase for components
Prefer
```
const
```
over
```
let
```
Always use strict equality (
```
===
```
)
Write JSDoc comments for all public functions

Use named exports
Use functional components with TypeScript interfaces for props
Use camelCase for variables, PascalCase for components
Prefer
```
const
```
over
```
let
```
Always use strict equality (
```
===
```
)
Write JSDoc comments for all public functions

API Development

All routes go in
```
apps/api/src/routes/
```
Use Zod for request validation
Use Prisma for database access
Error responses follow RFC 7807 format
Authentication via JWT middleware

All routes go in
```
apps/api/src/routes/
```
Use Zod for request validation
Use Prisma for database access
Error responses follow RFC 7807 format
Authentication via JWT middleware

Testing

Jest + Supertest for API tests
Vitest + Testing Library for frontend
Mock database with
```
prismaMock
```
from
```
packages/db/test
```


**Output** (`CLAUDE.md` after):

```markdown

Jest + Supertest for API tests
Vitest + Testing Library for frontend
Mock database with
```
prismaMock
```
from
```
packages/db/test
```


**输出**（修改后的`CLAUDE.md`）：

```markdown

CLAUDE.md

Express API + React frontend in a Turborepo monorepo.

Project map

```
apps/api/
```
— Express REST API
```
apps/web/
```
— React SPA
```
packages/db/
```
— Prisma schema and client
```
packages/ui/
```
— Shared component library

Run with

turbo

from the repo root.

Command	What it does
`turbo build`	Build all packages
`turbo test`	Run all tests
`turbo lint`	Lint all packages
`turbo dev`	Start dev server
`turbo db:generate`	Regenerate Prisma client after schema changes
`turbo db:migrate`	Run database migrations

</important> <important if="you are adding or modifying imports or exports"> - Use named exports (no default exports). </important> <important if="you are creating new components"> - Functional components with TypeScript interfaces for props. </important> <important if="you are adding or modifying API routes">

Routes live in
```
apps/api/src/routes/
```
.
Use Zod for request validation.
Use Prisma for database access.
Error responses follow RFC 7807.
Auth via JWT middleware — see
```
apps/api/src/middleware/auth.ts
```
.

</important> <important if="you are writing or modifying tests">

API: Jest + Supertest.
Frontend: Vitest + Testing Library.
Mock database with
```
prismaMock
```
from
```
packages/db/test
```
— real DB in tests flakes on CI.

</important> ```

What was cut and why:

camelCase/PascalCase,
```
const
```
vs
```
let
```
, strict equality, JSDoc → linter/formatter territory.
"Coding Standards" as a grouped section → split into targeted
```
<important if>
```
blocks.
Prose padding ("This is an...") → collapsed to one line.

What was preserved:

Every command.
Project map (bare, foundational).
All domain-specific rules, regrouped under narrower triggers.

```
apps/api/
```
— Express REST API
```
apps/web/
```
— React SPA
```
packages/db/
```
— Prisma schema and client
```
packages/ui/
```
— Shared component library

Run with

turbo

from the repo root.

Command	What it does
`turbo build`	Build all packages
`turbo test`	Run all tests
`turbo lint`	Lint all packages
`turbo dev`	Start dev server
`turbo db:generate`	Regenerate Prisma client after schema changes
`turbo db:migrate`	Run database migrations

Routes live in
```
apps/api/src/routes/
```
.
Use Zod for request validation.
Use Prisma for database access.
Error responses follow RFC 7807.
Auth via JWT middleware — see
```
apps/api/src/middleware/auth.ts
```
.

</important> <important if="you are writing or modifying tests">

API: Jest + Supertest.
Frontend: Vitest + Testing Library.
Mock database with
```
prismaMock
```
from
```
packages/db/test
```
— real DB in tests flakes on CI.

</important> ```

删减内容及原因：

camelCase/PascalCase命名、
```
const
```
vs
```
let
```
、严格相等、JSDoc → 代码检查/格式化工具管辖范围。
“编码规范”分组章节 → 拆分为精准的
```
<important if>
```
块。
冗余表述（"This is an..."）→ 精简为一句话。

保留内容：

所有命令。
项目目录结构（基础内容，保持原样）。
所有特定领域规则，重新分组到更精准的触发条件下。

What Not to Do

禁止事项

Don't invent rules. If a rule wasn't in the original and the user didn't confirm it, don't add it.
Don't strip commands. Every command stays.
Don't group unrelated rules under one
```
<important if>
```
. Specificity is the whole point.
Don't replace the file without showing the user the diff summary first.
Don't blow away a real file for a symlink without explicit confirmation.
Don't recurse into
node_modules/
,
dist/
,
.git/
,
vendor/
during bootstrap.

不要自创规则。若规则未出现在原始文件中且未得到用户确认，请勿添加。
不要删除命令。所有命令均需保留。
不要将无关规则分组到同一个
```
<important if>
```
块中。精准性是此机制的核心。
不要在展示差异摘要前替换文件。
不要未经明确确认就用符号链接替换真实文件。
从头创建时不要递归进入
node_modules/
、
dist/
、
.git/
、
vendor/
目录。