把主文件控制在 250 行以内。
如果 CLAUDE.md 要花几分钟才能扫完，它就会变成背景噪音。把长期有效的规则放在主文件里，把长例子、历史记录、自动生成的清单放到链接文档里。
强的 CLAUDE.md 不是给 model 写品牌手册。它是 repo 的运行契约：哪些事必须为真，怎么验证，agent 应该在哪里停。它也要和 AGENTS.md、Cursor 规则（.cursor/rules）保持一致。
如果 CLAUDE.md 要花几分钟才能扫完，它就会变成背景噪音。把长期有效的规则放在主文件里，把长例子、历史记录、自动生成的清单放到链接文档里。
好规则能让 reviewer 判断 agent 到底有没有做到。把“注意安全”这种建议，改成具体动作、边界、命令或输出要求。
如果一条规则保护安全、数据、发布或钱，它就不该只停留在文字里。用 CI、hooks、permissions 或必跑检查把它兜住。
agent 更需要分支规则，而不是人格描述。写清楚什么时候问、什么时候继续、什么时候停，以及什么证据会改变决定。
CLAUDE.md、AGENTS.md、Cursor 规则（.cursor/rules）、Copilot instructions 很容易漂移。如果同一条 policy 出现在多个文件里，要么指定 source of truth，要么机械同步。
告诉 agent 怎么汇报工作、失败、不确定性和用户可见变化。这属于 harness，因为它影响每次 handoff，不只是某一次任务。
原则只有在解释 repo 真实取舍时才有用。保持短，并且把每条原则连到文件里的具体规则。
工具、测试、owner、发布流程一变，agent rules 就会过期。至少每季度检查一次，也要在框架、CI 或 agent 升级后检查。
巨大的“important notes”通常混着无关约束、旧 caveat 和一次性偏好。把它拆成有 owner、有范围、有 enforcement 的规则。
一大段“应该怎么思考”很少改变行为。把它压成短原则，再加上能执行的决策规则。
迁移说明、事故历史、旧命令，如果 agent 现在用不上，就不要放在主规则文件里。链接到 archive 就够了。
同一条规则在多个文件里重复，一旦其中一份改了就会变危险。选一个 canonical 位置，让其他层指过去。
AgentLint 用 33 项有证据的检查审计 CLAUDE.md、AGENTS.md、Cursor 规则（.cursor/rules）、CI、hooks 和附近的 harness 文件。
用 AgentLint 检查 CLAUDE.md