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>
123 lines
4.4 KiB
Markdown
123 lines
4.4 KiB
Markdown
# 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](07-codex.md)——给 Claude 看 `CLAUDE.md`,
|
||
给 Codex 看 `AGENTS.md`,两个文件内容大体一致,工具读各自的。
|
||
|
||
## CLAUDE.md 的内容
|
||
|
||
每个 `CLAUDE.md` 按这个顺序回答:
|
||
|
||
1. **这是个什么项目?** 最多两句话。
|
||
2. **怎么跑?** Build、test、lint 命令,写成 bash 块。
|
||
3. **架构一段话。** 入口在哪、数据怎么流。除非能省字,否则不画图。
|
||
4. **本仓库特有的约定。** 命名、目录、那些不看注释看不出来的模式。
|
||
5. **不要做的事。** 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](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 拉回来做新主题。陈旧上下文会
|
||
渗进来。
|