Language policy: Chinese for human-facing files (README, docs/, human-fillable templates), English for AI-facing files (CLAUDE.md, AGENTS.md, AI templates). Commits / PRs / branches / tags stay English. - Translate docs/01-06 to Chinese - Translate README.md, PR / handoff / project README templates to Chinese - Drop README.en.md (redundant once language policy is explicit) - Rewrite CLAUDE.md and CLAUDE.md.template under the new policy - Add AGENTS.md (root) and templates/AGENTS.md.template for Codex - Add docs/07-codex.md covering Codex usage and AGENTS.md / CLAUDE.md sync rules Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
4.4 KiB
02 — Claude Code
我们在每个项目里怎么配置和使用 Claude Code。
配置文件
每个项目应该有:
<repo>/
├── CLAUDE.md ← 项目上下文(提交进仓库)
├── AGENTS.md ← Codex / 通用 agent 上下文(提交)
└── .claude/
├── settings.json ← 共享设置(提交)
├── settings.local.json ← 个人覆盖(gitignore)
└── skills/ ← 项目级 skill(提交)
settings.local.json 永远 gitignore。个人 API key、本地路径、
个人 hook 调整都放这里。
AGENTS.md 见 docs/07-codex.md——给 Claude 看 CLAUDE.md,
给 Codex 看 AGENTS.md,两个文件内容大体一致,工具读各自的。
CLAUDE.md 的内容
每个 CLAUDE.md 按这个顺序回答:
- 这是个什么项目? 最多两句话。
- 怎么跑? Build、test、lint 命令,写成 bash 块。
- 架构一段话。 入口在哪、数据怎么流。除非能省字,否则不画图。
- 本仓库特有的约定。 命名、目录、那些不看注释看不出来的模式。
- 不要做的事。 Claude 以前在这里翻过的车,每条一行。
新人(人或 AI)读一遍就该能上手干活。CLAUDE.md 超过 100 行,说明
它已经偷偷变成"文档"了,应该拆出去。
用 templates/CLAUDE.md.template 起手。
权限(permission)
默认姿态:只读自由放行,能改的都问一下。
.claude/settings.json 里可以无提示放行:
- 所有
Read、Glob、Grep Bash(git status)、Bash(git diff)、Bash(git log)、Bash(git branch)- 项目特定的只读命令(
Bash(npm test)、Bash(pytest)这类)
永远要弹窗确认:
- 工作树之外的
Edit/Write - 带破坏动词的
Bash(rm、mv、git push、git reset --hard、装包) - 任何会跟外部服务对话的 MCP 工具
如果你发现自己在反复批准同一类提示,跑一下 fewer-permission-prompts
skill——它会扫 transcript 给你列一份允许列表。
Hook(钩子)
Hook 是让 harness 自动执行规则的方式——AI 自己不可靠地记住"以后 都要 X",跨 session 会忘。
适合用 hook 的事:
- 文件保存后自动格式化(Prettier、ruff、gofmt)
- 阻止改受保护路径(
.env、生成文件、dist/) - 写测试路径后自动跑测试
- session 结束 / 长任务完成时通知
不适合用 hook 的:
- 一次性检查("这周记得 X 一下")
- 任何依赖 AI 判断的("觉得有必要就跑")
通过 update-config skill 配置,或者直接编辑 .claude/settings.json。
JSON 里每个 hook 加一行注释说明。
Memory(记忆)
Harness 有按机器的记忆系统。用法:
- User:你是谁、角色、偏好。
- Feedback:你给 AI 的纠正,要跨 session 保留的(带上为什么)。
- Project:进行中工作的事实,代码里没写的(截止日期、相关方决策、 为什么要重构)。
- Reference:外部资源指针(Linear 项目、Grafana dashboard、内网 wiki)。
不要把 memory 内容塞进 CLAUDE.md。CLAUDE.md 是项目上下文,团队共享。
Memory 是个人的、按机器的,不进仓库。
不要把 memory 当便签本用。任务级别的东西塞进 plan 或 PR description。
Skill(技能)
Skill 在三个地方:
- 用户级(
~/.claude/skills/)—— 装一次到处可用 - 项目级(
<repo>/.claude/skills/)—— 提交进仓库,团队共享 - 插件—— 通过 marketplace 安装
同一个流程做了三次都一样,就提升成 skill。目录见 docs/04-skills-and-planning.md。
Sub-agent(子 agent)
什么时候开 sub-agent(用 Agent 工具):
- 任务要跨很多文件搜索,又不想把搜索结果塞进主上下文。
- 想让另一个独立视角再看一遍设计或 diff。
- 工作真的并行(比如同时调研三个方案)。
主 agent 两次工具调用就能搞定的事,别开 sub-agent。交接成本不是免费 的。
Session
- 一个 session 一个任务。新任务开新 session。
- session 跑长了、上下文条快满了:先收尾当前步骤,把状态总结进 plan 或 PR draft,然后开新 session。
- 别用
--continue把昨天的 session 拉回来做新主题。陈旧上下文会 渗进来。