加载中

CLAUDE.md 为 Claude 提供了新成员所需的上下文,涵盖约定、命令、架构以及团队最常遇到的错误。以前存在于人们脑海中和 wiki 上的知识,变成了一个代理在每次会话开始时都会读取的文件,由整个团队维护,并在每次出现错误时进行迭代。

入门

  • 前提条件:无。
  • 基础设施:一个代码仓库、已安装的 Claude Code,以及一位熟悉代码库的工程师。

如何执行

  1. 在代码仓库中运行 /init。Claude 会根据它发现的内容生成一个初始的 CLAUDE.md。
  2. 将生成的文件精简到新成员第一天所需的内容。保留构建、测试和 lint 命令、重要的约定,以及 Claude 一直出错的地方。
  3. 将 CLAUDE.md 提交到代码仓库根目录的 Git 中,以便整个团队共享同一个版本,并像代码一样对变更进行审查。
  4. 这里有一条实用的规则:当 Claude 两次犯同一个错误时,就将更正内容加入 CLAUDE.md。
  5. 保持在一页以内,因为 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 所需的时间。