跳到主要内容
api工厂
AI 开发

Claude Code 高效用法:plan 模式、CLAUDE.md 与子代理

api工厂资讯栏目 约 6 分钟阅读
本文由 AI 辅助生成,内容基于公开资讯整理改写,技术细节以官方文档为准。

结论先行:Claude Code 的效率差距不在快捷键,而在三件配置——用 CLAUDE.md 把项目上下文固化成「记忆」,用 plan 模式把复杂改动变成「先审计划再动手」,用子代理把调查、实现、测试拆成权限隔离的并行职责。三者都写进仓库跟着代码走,新人 clone 即继承同一套行为。本文给出可直接复制的骨架与验证动作,具体命令行为以官方文档为准。

一、CLAUDE.md:投入产出比最高的一步

CLAUDE.md 放在项目根目录,每次会话自动加载。/init 能生成初版,但真正有价值的是手动补进去的团队约定。骨架示例:

markdown
# 项目: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 切换,或启动时指定:

bash
claude --permission-mode plan

适合跨多文件重构、新功能开发、架构调整;不适合单文件小修——为改一行文案走完整规划纯属浪费。好的计划请求自带约束:

text
分析:把 order.service 里的支付调用抽到 payment 适配层。
约束:1. 对外接口签名不变 2. 现有测试全部通过
3. 给出分步计划,标注每步影响的文件。先只给计划。

审阅计划本身比审阅代码便宜得多:看到「直接删除旧函数」这种激进步骤,在计划阶段就拦下来改成「标记 deprecated 下版本再删」。确认后退出 plan 模式执行,执行中发现偏差再切回来重新规划。这个「规划-审阅-执行」循环是复杂任务返工率最低的工作流。

三、子代理:职责隔离与并行

子代理定义在 .claude/agents/ 下,每个是一个带 frontmatter 的 Markdown。一个只读审查代理:

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 里配置事件钩子,可以在工具调用前后强制执行检查:

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 与网站。

提示词工程AI编程验收标准

提示词工程实战:验收标准驱动的任务描述

给 AI 写任务最有效的结构是验收标准驱动:完成条件写成可执行命令与可观察行为。本文用三组前后对比示例说明差距,给出可复用模板与规则沉淀方法。

AI 开发约 5 分钟阅读
CursorAI编程团队规范

Cursor Rules 实战:把团队规范写进 .cursor/rules

Cursor 项目规则用 .mdc 文件进 Git 共享,四种加载方式按需注入。本文给出最小四块骨架、可复制配置示例与三步验证法,帮团队把 AI 编码从自由发挥拉回按仓规改。

AI 开发约 5 分钟阅读