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

4.4 KiB
Raw Blame History

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 按这个顺序回答:

  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。

Sub-agent(子 agent)

什么时候开 sub-agent(用 Agent 工具):

  • 任务要跨很多文件搜索,又不想把搜索结果塞进主上下文。
  • 想让另一个独立视角再看一遍设计或 diff。
  • 工作真的并行(比如同时调研三个方案)。

主 agent 两次工具调用就能搞定的事,别开 sub-agent。交接成本不是免费 的。

Session

  • 一个 session 一个任务。新任务开新 session。
  • session 跑长了、上下文条快满了:先收尾当前步骤,把状态总结进 plan 或 PR draft,然后开新 session。
  • 别用 --continue 把昨天的 session 拉回来做新主题。陈旧上下文会 渗进来。