agents-md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AGENTS.md / CLAUDE.md Audit

AGENTS.md / CLAUDE.md 审核

AGENTS.md and CLAUDE.md are execution contracts, not knowledge bases.

Litmus test for every line: "Would removing this cause the agent to make a mistake?" If no, cut it. Bloated instruction files cause agents to ignore actual rules.

AGENTS.md和CLAUDE.md是执行契约，而非知识库。

每一行的验证标准："如果删除这一行，会导致Agent出错吗？"如果不会，就删掉它。冗余的指令文件会导致Agent忽略实际规则。

Reference Files

参考文件

File	Read When
`references/quick-checklist.md`	Default: fast triage (10 checks, target >= 8/10)
`references/quality-criteria.md`	Full audit mode or when quick audit fails
`references/refactor-workflow.md`	File is bloated (>150 lines) or low-signal
`references/root-content-guidance.md`	Deciding what stays in root vs separate files
`references/templates.md`	Drafting new file or rebuilding from scratch

文件	适用场景
`references/quick-checklist.md`	默认：快速分类排查（10项检查，目标得分≥8/10）
`references/quality-criteria.md`	完整审核模式或快速审核未通过时使用
`references/refactor-workflow.md`	文件冗余（超过150行）或有效信息占比低时使用
`references/root-content-guidance.md`	决定内容保留在根文件还是拆分到独立文件时使用
`references/templates.md`	起草新文件或从零重建文件时使用

Quick Example

快速示例

Input: AGENTS.md with stale commands and generic advice Quick audit result: 5/10 (Fail) Key issues: Missing test command, generic "follow best practices" advice, dead link to deleted folder Fix: Add

npm test

, replace generic advice with specific gotcha, remove dead link After: 9/10 (Pass)

**输入：**包含过时命令和通用建议的AGENTS.md文件 **快速审核结果：**5/10（未通过） **核心问题：**缺少测试命令、通用的"遵循最佳实践"建议、指向已删除文件夹的无效链接 **修复方案：**添加

npm test

命令，将通用建议替换为具体注意事项，移除无效链接 **修复后：**9/10（通过）

How to Use

使用方法

Default path:

Start with quick audit using
```
references/quick-checklist.md
```
(10 checks)
Escalate to full audit (
```
references/quality-criteria.md
```
) only when quick audit fails, file is high-risk, or user requests it
Apply edits only after reporting findings and getting confirmation

Progressive loading:

Always load the checklist for the selected audit mode
Load
```
references/refactor-workflow.md
```
only for low-signal files (below target score, stale commands, or root file over ~150 lines)
Load
```
references/templates.md
```
only when drafting a new file or rebuilding from scratch
Load
```
references/root-content-guidance.md
```
only when deciding what stays in root vs moved out

默认流程：

首先使用
```
references/quick-checklist.md
```
进行快速审核（10项检查）
仅当快速审核未通过、文件为高风险文件或用户要求时，才升级为完整审核（使用
```
references/quality-criteria.md
```
）
仅在报告审核结果并获得确认后，再进行编辑操作

渐进式加载：

始终加载所选审核模式对应的检查清单
仅针对低有效信息文件（得分低于目标、存在过时命令或根文件超过约150行）加载
```
references/refactor-workflow.md
```
仅在起草新文件或从零重建文件时加载
```
references/templates.md
```
仅在决定内容保留在根文件还是拆分到其他文件时加载
```
references/root-content-guidance.md
```

Audit Workflow

审核流程

Copy this checklist to track progress:

Audit Progress:
- [ ] Step 1: Discover files
- [ ] Step 2: Select audit mode (quick or full)
- [ ] Step 3: Run audit against checklist
- [ ] Step 4: Report findings with score table
- [ ] Step 5: Propose minimal diffs
- [ ] Step 6: Validate changes
- [ ] Step 7: Apply and verify

复制以下检查清单以跟踪进度：

Audit Progress:
- [ ] Step 1: Discover files
- [ ] Step 2: Select audit mode (quick or full)
- [ ] Step 3: Run audit against checklist
- [ ] Step 4: Report findings with score table
- [ ] Step 5: Propose minimal diffs
- [ ] Step 6: Validate changes
- [ ] Step 7: Apply and verify

Step 1: Discover files

步骤1：发现文件

Run:

bash

find . \( -name "AGENTS.md" -o -name "CLAUDE.md" -o -name "CLAUDE.local.md" \) 2>/dev/null | sort

Also check for a home-level file:

~/.claude/CLAUDE.md

(applies to all sessions).

CLAUDE.md files can exist at multiple levels — project root, parent directories, and child directories are all loaded automatically.

CLAUDE.local.md

is the gitignored personal variant. Audit each level independently.

For monorepos, include workspace-level instruction files.

运行以下命令：

bash

find . \( -name "AGENTS.md" -o -name "CLAUDE.md" -o -name "CLAUDE.local.md" \) 2>/dev/null | sort

同时检查主目录级别的文件：

~/.claude/CLAUDE.md

（适用于所有会话）。

CLAUDE.md文件可能存在于多个层级——项目根目录、父目录和子目录都会被自动加载。

CLAUDE.local.md

是被Git忽略的个人变体文件。需独立审核每个层级的文件。

对于单体仓库，需包含工作区级别的指令文件。

Step 2: Select audit mode

步骤2：选择审核模式

Quick audit: Default for most files (10 checks, target >= 8/10)
Full audit: When quick audit fails, file is high-risk, or user requests full scoring

**快速审核：**适用于大多数文件（10项检查，目标得分≥8/10）
**完整审核：**当快速审核未通过、文件为高风险文件或用户要求完整评分时使用

Step 3: Run audit

步骤3：执行审核

Quick audit target: >= 8/10 checks from
```
references/quick-checklist.md
```
Full audit file-quality target: >= 91% of applicable points from
```
references/quality-criteria.md
```
Full audit execution target: 2/2 when producing an edit proposal
Score each root file independently

快速审核目标：≥8/10（基于
```
references/quick-checklist.md
```
的检查项）
完整审核文件质量目标：**≥91%**的适用得分（基于
```
references/quality-criteria.md
```
）
完整审核执行目标：生成编辑提案时需达到2/2的要求
独立为每个根文件评分

Step 4: Report findings

步骤4：报告审核结果

Output a concise report before edits:

markdown

undefined

在进行编辑前输出简洁的报告：

markdown

undefined

AGENTS.md Quality Report

File	Mode	Score	Grade	Key Issues
./AGENTS.md	Quick	6/10	Fail	Missing test command, stale path, doc-heavy section

undefined

File	Mode	Score	Grade	Key Issues
./AGENTS.md	Quick	6/10	Fail	Missing test command, stale path, doc-heavy section

undefined

Step 5: Propose minimal diffs

步骤5：提出最小化差异修改建议

Fix broken/stale commands first
Remove generic, duplicate, or obsolete guidance
Move deep detail into linked files using
```
@path/to/file.md
```
import syntax
Use emphasis ("IMPORTANT:", "YOU MUST") on critical rules that agents tend to skip
Keep rewrites incremental and preserve useful wording when possible

Show each proposed change with rationale and a diff snippet.

优先修复失效/过时的命令
移除通用、重复或过时的指导内容
使用
```
@path/to/file.md
```
导入语法，将深层细节内容迁移到链接文件中
对Agent容易忽略的关键规则使用强调格式（如"IMPORTANT:", "YOU MUST"）
保持增量式重写，尽可能保留有用的表述

展示每个拟议修改的理由和差异片段。

Step 6: Validate changes

步骤6：验证修改内容

Validation loop:

Run smoke checks for core commands (
```
dev
```
,
```
test
```
,
```
build
```
,
```
lint/typecheck
```
) when applicable
If commands cannot be run, verify script existence and note the limitation
Check that linked paths resolve
Confirm no contradictory rules remain
If issues found → revise → validate again
Only proceed when validation passes

验证循环：

适用时，对核心命令（
```
dev
```
,
```
test
```
,
```
build
```
,
```
lint/typecheck
```
）运行冒烟测试
如果无法运行命令，验证脚本是否存在并记录限制条件
检查链接路径是否可解析
确认不存在相互矛盾的规则
若发现问题 → 修改 → 再次验证
仅当验证通过后再继续

Step 7: Apply and verify

步骤7：应用并验证修改

Apply approved edits
After each PR, add at most one new gotcha only if it prevented or fixed a real mistake
Verify changes by re-running relevant commands

应用已获批的修改
每次PR后，仅当新注意事项确实预防或修复了实际错误时，最多添加一条新注意事项
通过重新运行相关命令验证修改效果