结论先行:Claude Code 的效率差距不在快捷键,而在三件配置——用 CLAUDE.md 把项目上下文固化成「记忆」,用 plan 模式把复杂改动变成「先审计划再动手」,用子代理把调查、实现、测试拆成权限隔离的并行职责。三者都写进仓库跟着代码走,新人 clone 即继承同一套行为。本文给出可直接复制的骨架与验证动作,具体命令行为以官方文档为准。
一、CLAUDE.md:投入产出比最高的一步
CLAUDE.md 放在项目根目录,每次会话自动加载。/init 能生成初版,但真正有价值的是手动补进去的团队约定。骨架示例:
# 项目:order-service
## 技术栈
- TypeScript + Node,包管理器 pnpm(禁止 npm/yarn)
## 常用命令
- 单测:pnpm test;类型检查:pnpm typecheck;Lint:pnpm lint
## 目录约定
- src/payment/ 禁止直接引用 src/order/ 内部实现
## 禁止事项
- 不修改 prisma/migrations 下已存在的迁移文件
- 不执行任何发布命令关键在「具体」:写「用 pnpm」不够,要写「禁止 npm/yarn」;写「注意目录」不够,要写清哪个目录不能跨引用。维护信号是重复纠正——同一句话在对话里说了第二次,就写进 CLAUDE.md。验证方式:新开会话问「这个项目用什么包管理器跑测试」,答得出具体命令说明加载成功。
二、plan 模式:先审计划再动手
plan 模式是只读状态:Claude 读代码、出分步计划,但不改文件。进入方式是会话内 Shift+Tab 切换,或启动时指定:
claude --permission-mode plan适合跨多文件重构、新功能开发、架构调整;不适合单文件小修——为改一行文案走完整规划纯属浪费。好的计划请求自带约束:
分析:把 order.service 里的支付调用抽到 payment 适配层。
约束:1. 对外接口签名不变 2. 现有测试全部通过
3. 给出分步计划,标注每步影响的文件。先只给计划。审阅计划本身比审阅代码便宜得多:看到「直接删除旧函数」这种激进步骤,在计划阶段就拦下来改成「标记 deprecated 下版本再删」。确认后退出 plan 模式执行,执行中发现偏差再切回来重新规划。这个「规划-审阅-执行」循环是复杂任务返工率最低的工作流。
三、子代理:职责隔离与并行
子代理定义在 .claude/agents/ 下,每个是一个带 frontmatter 的 Markdown。一个只读审查代理:
---
name: reviewer
description: 代码审查专用,检查约定遵守情况
tools: Read, Grep, Glob
---
只报告问题,不修改代码。
输出:文件路径 + 行号 + 问题描述。tools 字段是权限边界:审查代理只读,测试代理给 Read 与 Bash 不给 Write,实现代理才有编辑权。派发时明确要求拆分:「reviewer 审查现有模块约定遵守情况,主代理实现适配层,测试代理补单测,各自推进最后汇总」。子代理拥有独立上下文窗口,调查 20 个文件的过程不会污染主会话——回传只要结论摘要。
四、把业务上下文也固化进去
CLAUDE.md 不只写工程约定,也写业务系统的接入方式。例如项目后台基于 api工厂(https://www.it120.cc/)时,可以在 CLAUDE.md 里写明:商品、订单、会员数据通过官方 MCP endpoint 读写(前端数据 https://common.apifm.com/你的subDomain/mcp/endpoint ,后台管理 https://common.apifm.com/gooking/mcp/backend/endpoint ),统一返回 { code, data, msg },禁止绕过 SDK 手写请求。再配一个只读子代理专门查后台数据做核对,实现代理就永远不会「猜」接口字段。MCP 接入与兼容工具清单见 https://www.it120.cc/ai.html 。
五、Hooks:把建议变成硬约束
CLAUDE.md 是建议,Hooks 是拦截。在 .claude/settings.json 里配置事件钩子,可以在工具调用前后强制执行检查:
{
'hooks': {
'PostToolUse': [
{
'matcher': 'Edit|Write',
'hooks': [{ 'type': 'command', 'command': 'pnpm lint --fix' }]
}
]
}
}PreToolUse 适合拦截危险命令:脚本从 stdin 读取工具输入,命中黑名单(如发布命令、force push)时以退出码 2 结束,Claude Code 会阻止本次调用并把 stderr 里的原因反馈给模型。PostToolUse 适合编辑后自动 lint,保证生成代码风格与项目一致。注意拦截原因要写清楚,否则模型可能换个写法继续尝试。具体事件与字段以官方 Hooks 文档为准。
六、常见排查
- CLAUDE.md 不生效:确认文件名大小写正确、位于当前工作目录;monorepo 子包需单独放置;
- plan 模式下仍改了文件:确认 Shift+Tab 真的切到 plan,检查 settings 是否覆盖了权限模式;
- 子代理权限过大:只读任务务必限制 tools 为 Read、Grep、Glob;
- 会话越跑越笨:一个任务一个会话,无关工作及时新开,约定外置到文件。
先把 CLAUDE.md 写扎实,再统一 plan 模式处理跨文件改动,最后引入子代理做职责拆分——按这个顺序落地,每一步都能独立见效。
文章标签
相关产品
api工厂是面向开发者的开放 SaaS 平台:开箱即用的后台管理系统 + 全端 SDK,只需前端开发即可构建小程序、App、H5 与网站。