CLAUDE.md 为 Claude 提供了新成员所需的上下文,涵盖约定、命令、架构以及团队最常遇到的错误。以前存在于人们脑海中和 wiki 上的知识,变成了一个代理在每次会话开始时都会读取的文件,由整个团队维护,并在每次出现错误时进行迭代。
入门
- 前提条件:无。
- 基础设施:一个代码仓库、已安装的 Claude Code,以及一位熟悉代码库的工程师。
如何执行
- 在代码仓库中运行
/init。Claude 会根据它发现的内容生成一个初始的CLAUDE.md。 - 将生成的文件精简到新成员第一天所需的内容。保留构建、测试和 lint 命令、重要的约定,以及 Claude 一直出错的地方。
- 将
CLAUDE.md提交到代码仓库根目录的 Git 中,以便整个团队共享同一个版本,并像代码一样对变更进行审查。 - 这里有一条实用的规则:当 Claude 两次犯同一个错误时,就将更正内容加入
CLAUDE.md。 - 保持在一页以内,因为 Claude 会在会话开始时读取全部内容,任何过时的内容都会占用上下文而没有任何好处。
实际效果
这个 CLAUDE.md 属于一家保险公司客户门户的代码仓库。保存理赔信息的较旧内部系统是 claims-core,intent/ 保存每次变更的规划文件。
CLAUDE.md:
markdown
# Claims portal
## Commands
- Build: make build
- Test: make test (unit), make itest (integration, needs docker)
- Lint: make lint (runs in CI; fix before pushing)
- Run: make run (portal on :3000, claims-api on :8000)
## Conventions
- claims-api is Python 3.12 and FastAPI. portal is TypeScript and React.
- Every endpoint needs a test in claims-api/tests.
- Dates cross the API as ISO 8601, never as formatted text.
## Architecture
- portal/ is the customer site, claims-api/ is its backend, and
intent/ holds the intent.md, spec.md and plan.md for each change.
- Only claims-api talks to claims-core. The portal never calls it.
- claims-core allows 50 requests a second. Cache reads; never poll it.
## Things Claude gets wrong
- Do not log request or response bodies in claims-api; they can hold PII.
- Do not bump dependency versions; the platform team owns them.治理考量
CLAUDE.md 受版本控制,因此代理所遵循的指令是可审查和可审计的。团队约定通过该文件应用,对其的更改会记录在 Git 历史中,代码所有者在 PR 审查中批准这些更改。
如何衡量
- 领先指标:Claude 重复
CLAUDE.md本应捕获的错误的频率。对CLAUDE.md的更正或更改应在 Git 历史中进行跟踪。 - 滞后指标:根据 PR 历史,团队新成员首次合并 PR 所需的时间。