来源：https://academy.claude.com/courses/ai-native-sdlc-playbook/claude-md 读这篇之前：04 Plan mode；这课没有先决条件，也可先读 不确定：ZH 是 Clint 译官方英文课体，不是 Anthropic 中文。
本课词汇
| English | 中文 | 怎么记 |
|---|---|---|
| CLAUDE.md | 给 Claude 的说明书 | 仓库根目录，每次会话开头都读 |
| /init | 初始化命令 | 让 Claude 根据仓库生成一份草稿 |
| new joiner | 新同事 | 裁剪标准：第一天需要知道的才留 |
| stale | 过时内容 | 占上下文、没好处，删 |
对照正文
它是什么 / What CLAUDE.md is
EN CLAUDE.md gives Claude the context a new joiner would need, covering conventions, commands, architecture, and the mistakes the team sees most often. Knowledge that used to sit in people’s heads and on wikis becomes a file the agent reads at the start of every session, maintained by the whole team and iterated on whenever a mistake is made.
ZH CLAUDE.md 给 Claude 的是新同事需要的上下文：约定、命令、架构、团队最常见的错。以前在人脑子里和 wiki 上的知识，变成 agent 每次会话开头都读的文件，全队维护，错一次就改。
怎么起步 / Getting started
EN Prerequisites: None.
Infrastructure: A repo, Claude Code installed, and one engineer who knows the codebase well.
ZH 先决条件：无。
基础设施：一个仓库、装了 Claude Code、一位熟代码库的工程师。
怎么做 / How to execute it
EN 1. Run /init in the repo. Claude generates a starting CLAUDE.md from what it finds.
2. Cut the generated file down to what a new joiner would need on day one. Keep the build, test, and lint commands, the conventions that matter, and the things Claude keeps getting wrong.
3. Check CLAUDE.md into Git at the repo root so the whole team shares one version and changes are reviewed like code.
4. A working rule helps here. When Claude makes a mistake twice, the correction goes into CLAUDE.md.
5. Keep it under a page, because Claude reads all of it at the start of a session and anything stale is taking up context for no benefit.
ZH 1. 在仓库里跑 /init。Claude 根据看到的生成一份起始 CLAUDE.md。
2. 裁到新同事第一天需要的。留下构建、测试、lint 命令，真正要紧的约定，以及 Claude 老是搞错的事。
3. 把 CLAUDE.md 提交到仓库根目录，全队共用一个版本，改动像代码一样审。
4. 一条能用的规矩：Claude 同样的错犯两次，改正写进 CLAUDE.md。
5. 压在一页以内。Claude 开局会读完全文，过时的东西白占上下文。
长什么样 / What it looks like
EN CLAUDE.md:
ZH CLAUDE.md：
# Payments service
## Commands
- Build: make build
- Test: make test (unit), make itest (integration, needs docker)
- Lint: make lint (runs in CI; fix before pushing)
## Conventions
- Java 21, Spring Boot 3. No new Lombok.
- Money is always BigDecimal, never double.
- Every endpoint needs an integration test in src/itest.
## Architecture
- api/ holds REST controllers, core/ holds domain logic,
adapters/ talks to external systems.
- Kafka events are defined in schemas/; never edit generated classes.
## Things Claude gets wrong
- Do not bump dependency versions; the platform team owns them.
- The legacy v1/ package is frozen; changes go in v2/.ZH 官方示例，保持英文。支付服务：命令、约定（钱用 BigDecimal）、架构、Claude 常错的（别自己升依赖、v1 冻结）。
治理 / Governance considerations
EN CLAUDE.md is version controlled, so the instructions the agent works to are reviewable and auditable. Team conventions are applied through the file, changes to it are logged in Git history, and code owners approve those changes in PR review.
ZH CLAUDE.md 进版本库，所以 agent 按什么说明干活，可审可审计。团队约定经这个文件落地，改动记在 Git 历史，code owner 在 PR 里批这些改动。
怎么衡量 / How to measure it
EN Leading indicator: How often Claude repeats a mistake CLAUDE.md should have caught. The corrections or changes to the CLAUDE.md should be tracked within the Git history.
Lagging indicator: Time to first merged PR for a new member of the team from PR history.
ZH 领先指标：Claude 重复犯 CLAUDE.md 本该拦住的错，有多频繁。对 CLAUDE.md 的改正应能在 Git 历史里追到。
滞后指标：新成员从进组到第一份合并 PR 的时间，从 PR 历史读。
读完能记住的三句话
EN CLAUDE.md is what a new joiner needs on day one, read at the start of every session.
ZH CLAUDE.md 是新同事第一天要的东西，每次会话开头都读。
EN If Claude makes a mistake twice, the correction goes in the file. Keep it under a page. ZH 同样的错犯两次，改正写进文件。压在一页以内。
EN Check it into Git at the repo root and review changes like code. ZH 放仓库根目录，改动像代码一样审。