为 AI Agent 准备的准则文件，核心目标：减少 LLM 常见编码失误。
A rulebook for AI agents, with one goal: reduce common LLM coding mistakes.
前四条规则覆盖了"想清楚、简单写、改精准、目标驱动"，但漏了一个关键环节：修改之后怎么确认没错？
LLM 的常见模式是做完所有修改、最后一起验证。问题在于：3 个修改 + 1 次验证 → 失败时不知道哪个改坏了。错误会级联，定位成本指数级上升。
第五条的核心原则：每一步变更立即验证，验证通过才进入下一步。 这本质上是故障隔离 —— 和 CI/CD 中"小步提交、即时反馈"是同样的道理。CLAUDE.md 里那句话概括了全部理由："Gated verification isolates failure to a single change. Skipped gates spread the blame across the batch."
CLAUDE.md 刻意不规定"如何接收信息"和"如何交付产出"。原因有三：
-
它是行为框架，不是项目规范。 输入形式（PR 描述、需求文档、对话指令）和输出形式（PR、commit、部署）因项目而异。把 I/O 格式写进准则，会让它变得脆弱、难以跨项目复用。
-
可变的环节不需要约束，稳定的薄弱点才需要。 AI Agent 在"理解输入"和"输出格式"上通常不是问题 —— 真正容易翻车的环节是思维方式：跳过思考直接写代码、过度设计、改完不验证。五条规则全部针对这些稳定且脆弱的环节。
-
过度的 I/O 规范会限制适应性。 如果规定了"必须用 XXX 格式接收需求"，遇到非标输入时 Agent 会机械套用模板，而不是根据上下文灵活处理。CLAUDE.md 选择相信 Agent 的判断力，把规范留给更合适的层面（项目级 AGENTS.md、CONTRIBUTING.md）。
简单说：怎么输入、怎么输出是项目的事；怎么思考、怎么验证才是 Agent 的底层能力。 CLAUDE.md 只管后者。
The first four rules cover "think first, keep it simple, be surgical, and be goal-driven." But they miss a critical step: how do you know your change is correct?
LLMs have a pattern of making all changes first, then verifying everything at the end. The problem: 3 changes + 1 verification → when it fails, you can't tell which change broke it. Errors cascade, and debugging cost grows exponentially.
The core principle: verify every change immediately, and only proceed after it passes. This is fault isolation — the same principle behind small commits and fast feedback in CI/CD. The line in CLAUDE.md says it all: "Gated verification isolates failure to a single change. Skipped gates spread the blame across the batch."
CLAUDE.md deliberately avoids specifying "how to receive information" and "how to deliver output." Three reasons:
-
It's a behavioral framework, not a project spec. Input formats (PR descriptions, requirements docs, chat instructions) and output formats (PRs, commits, deployments) vary across projects. Baking I/O formats into the rules would make them brittle and hard to reuse.
-
Constrain what's unstable, not what's reliable. AI agents rarely fail at understanding input or formatting output. They fail at the thinking layer: skipping analysis, over-engineering, not verifying changes. All five rules target these stable, fragile points.
-
Over-specifying I/O limits adaptability. If the rules mandate "requirements must arrive in format X," the agent mechanically applies the template to non-standard input instead of adapting. CLAUDE.md trusts the agent's judgment and leaves format specifications to the appropriate layer (project-level AGENTS.md, CONTRIBUTING.md).
In short: how to input and output is the project's concern; how to think and verify is the agent's foundation. CLAUDE.md governs only the latter.