Files
praxis/docs/02-claude-code.md
T
阿白叔andClaude Opus 4.7 154f592f3c docs: split language by audience, add Codex / AGENTS.md spec
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>
2026-05-20 09:44:15 +08:00

123 lines
4.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 拉回来做新主题。陈旧上下文会
渗进来。