# 02 — Claude Code 我们在每个项目里怎么配置和使用 Claude Code。 ## 配置文件 每个项目应该有: ``` / ├── 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/`)—— 装一次到处可用 - **项目级**(`/.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 拉回来做新主题。陈旧上下文会 渗进来。