1. 为什么“没有计划不写码”在 AI 原生研发里成了硬规矩AI 原生研发AI-Native SDLC走到 Build 阶段最容易被忽略的一件事是agent 写代码的速度已经远远超过人类审代码的速度。你让 Claude Code 直接开干它唰一下吐出大半个 diff文件改了七八个测试也顺手补了——问题是你敢直接合吗我见过太多团队卡在这一步AI 写码很快但团队整体交付反而更慢因为评审、返工、对齐上下文的时间全被吃掉了。plan mode 和 CLAUDE.md 解决的就是这个错位。核心逻辑一句话没有“被接受的计划”就不实现机构知识变成仓库里的文件护栏跑在代码层。plan mode 让 agent 先产出 plan.md——它可以读代码、查目录、跑只读命令但不改任何文件。你审的是“计划”不是“改完的 diff”。审完提交再让它去实现。这一步把评审从“事后救火”挪到了“事前对齐”成本差了一个数量级。而 CLAUDE.md 是把团队里那些“新人不说就懂”的隐性知识——构建命令、目录约定、易错点、冻结模块——沉淀成 agent 每次会话都会读的“新人手册”。Skills 把“我们怎么做 XX”封装成可复用的 SKILL.mdHooks 则在构建期做确定性拦截。三者配合机构知识才真正变成可执行、可校验的工程资产而不是散落在某个人脑子里的经验。这篇适合谁正在用 Claude Code 或类似 agent 做团队协作的工程师、Tech Lead以及想把 AI 编码从“个人玩具”推进到“团队流水线”的人。下面我会给出 CLAUDE.md 骨架、Skills/Hooks 配置片段以及一次完整的 plan mode 验证动作你可以直接照着改。2. 前置准备TaoToken 接入与 Claude Code 环境在讲 CLAUDE.md 之前先把模型接入这条链路打通。我用的是 TaoToken 作为统一入口它兼容 Anthropic 的 API 协议Claude Code 可以直接指过去省去在多个 key 之间来回切换的麻烦。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台生成 API Key。拿到 key 之后Claude Code 侧需要设置两个环境变量。Anthropic 官方的 Claude Code 默认走 Anthropic 端点我们把它指向 TaoToken 的 API 地址即可export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥如果你用的是 Claude Code 的配置文件方式也可以写进~/.claude/settings.json的 env 段这样每个会话自动生效。注意 API 地址不要带 UTM 参数保持干净。验证接入是否成功最直接的方式是发一个最小请求curl https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: reply with ok}] }返回里能看到content字段带文本就说明链路通了。这一步别跳过后面 plan mode 跑不起来八成是这里没通。密钥管理建议走控制台的 API Keys 页面按项目或按人分发方便后续轮换和审计。3. 可复制配置CLAUDE.md 骨架 Skills Hooks3.1 CLAUDE.md 骨架给 agent 的“新人手册”CLAUDE.md 放在仓库根目录Claude Code 每次会话自动读取。用/init可以生成初版但生成完一定要剪——目标是一页以内只留 agent 真正会用到的东西。原则是凡是 Claude 错两次的就写进文件。下面是我在一个支付服务里用的骨架你可以按自己项目替换# Payments service ## Commands - Build: make build - Test: make test (unit), make itest (integration, needs docker) - Lint: make lint (runs in CI; fix before pushing) ## Conventions - Java 21, Spring Boot 3. No new Lombok. - Money is always BigDecimal, never double. - Every endpoint needs an integration test in src/itest. ## Architecture - api/ holds REST controllers, core/ holds domain logic, adapters/ talks to external systems. - Kafka events are defined in schemas/; never edit generated classes. ## Things Claude gets wrong - Do not bump dependency versions; the platform team owns them. - The legacy v1/ package is frozen; changes go in v2/.这份文件的价值在于“事实源”明确命令以 Makefile 为准约定以这里为准架构以目录结构为准。每个 artifact 都要声明哪个系统是唯一事实源——repo 为源还是旧系统比如 Jira为源通过 MCP connector 写回或者只放最低限度链接。不要让两份东西“都算数”否则 agent 会在冲突信息里随机选一个。3.2 Skills把“我们怎么做 XX”封装成文件Skills 放在.claude/skills/name/SKILL.md或者走插件分发。它和 CLAUDE.md 的区别是CLAUDE.md 是全局上下文Skills 是按需触发的专项流程。比如一个 API 安全审查 skill--- name: secure-api-review description: Apply the API security standard. Use whenever creating or modifying an external-facing endpoint, reviewing API code, or generating an OpenAPI spec. --- # Secure API review When you create or change an API endpoint: 1. Authentication: every endpoint requires the gateway JWT; no anonymous routes outside /health. 2. Input validation: validate request bodies against the OpenAPI schema and reject unknown fields. 3. Audit: every state-changing endpoint emits an audit event with actor, action, entity and timestamp. 4. Data classification: fields tagged pii in the schema must never appear in logs or error messages. Run scripts/check-endpoints.sh and include its output in your summary.注意 description 里写了触发条件——agent 在创建或修改对外端点时会自动加载这个 skill。这就是机构知识变成可执行文件的样子不是文档里的一段话而是 agent 会主动执行的检查清单。3.3 Hooks构建期的确定性护栏Skills 是“建议性”的Hooks 是“确定性”的。它挡在工具调用前后做那些不能靠模型自觉的事挡住对保护路径的编辑、跑 formatter/linter、挡住密钥进 diff。被“背书”的 skill必须有 hook 或 PR 复查兜底。在.claude/settings.json里配置 PreToolUse hook拦截对schemas/generated/的写入{ hooks: { PreToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: python3 .claude/hooks/guard_paths.py } ] } ] } }guard_paths.py读 stdin 的 JSON检查tool_input.file_path是否命中保护路径命中就返回非零退出码并打印原因Claude Code 会把这个反馈给 agent让它换路径。这样“不要改生成代码”就从一句约定变成了硬约束。3.4 并行会话与子智能体计划批准后Claude 可以进入 auto mode 自动改代码前提是护栏已经调熟——CLAUDE.md、skills、hooks、测试都到位。成熟之后例常工作默认 auto-accept再配合 worktree 并行推进多个特性claude --worktree feature-auth每个 worktree 是独立的 Claude Code 实例加独立 git 分支互不干扰。子智能体在.claude/agents/定义比如一个只“验工不修”的 verifier--- name: verifier description: Runs the app and checks the change works before the session reports done tools: Bash, Read --- Start the app with make run. Exercise the changed behavior and the two nearest neighboring flows. Report what you ran, what you saw, and any behavior that does not match plan.md. Do not fix anything; report only.这个 verifier 的边界很关键只报告不修改。它把“验收”从主会话里拆出来避免 agent 一边改一边自我背书。4. 验证跑一次 plan mode看计划先于代码配置就位后用一次真实任务验证整条链路。假设要给 claims 服务加一个状态自助查询面板。第一步进入 plan mode让 Claude 只读不写claude --permission-mode plan然后在会话里给出意图比如“为 claims 服务增加状态自助查询面板参考 intent.md”。Claude 会去读代码、查目录、看测试产出一份 plan.md。一份合格的 plan.md 长这样# Plan: claims status self-service (from intent.md 2026-06-02) ## Files that change portal/src/claims/StatusPanel.tsx (new), claims-api/routes/status.py, claims-api/tests/test_status.py ## Order of work 1. Add the status endpoint behind existing auth. 2. Panel against the endpoint. 3. Wire into the portal nav. ## Risks The claims-core API rate-limits at 50 rps; the panel must cache. ## Proof test_status.py covers the four claim states; screenshot matches the approved mock.你要审的就是这份东西文件清单对不对、顺序合不合理、风险有没有漏、验收标准是否可执行。审完提交再让它进入实现阶段。实测下来这一步能挡掉大部分“方向错了但代码写完了”的返工。验证成功的标志有三个plan.md 里明确列出了变更文件和顺序风险段落提到了真实的约束比如限流Proof 段落给出了可执行的验收动作。如果 plan.md 只是把需求复述一遍没有文件级细节说明 CLAUDE.md 里的架构信息不够回去补。5. 本篇常见错排查plan mode 下 agent 还是改了文件。检查启动参数是不是--permission-mode plan以及 settings.json 里有没有覆盖权限模式的配置。另外确认没有 hook 在 plan 阶段误触发写操作。CLAUDE.md 写了但 agent 不遵守。最常见的原因是文件太长关键信息被淹没。剪到一页以内把“Things Claude gets wrong”放在显眼位置。另一个原因是命令和实际 Makefile 不一致agent 试了一次失败后就绕过了所以命令必须真实可跑。Skill 不触发。检查 description 里的触发条件是否覆盖了实际场景。description 写得太窄agent 就不知道什么时候该加载。可以先用/skills看当前会话加载了哪些 skill。Hook 报错但看不到原因。Hook 脚本的 stderr 会回传给 agent但如果你在脚本里吞了异常agent 就只看到失败。确保脚本在拦截时打印清晰原因比如“schemas/generated/ is generated; edit schemas/source/ instead”。API 请求 401 或超时。回到第 2 节确认ANTHROPIC_BASE_URL指向https://taotoken.net/apikey 没有多余空格且账户有余额。接入文档里有各语言的完整示例排障时对照一遍最快。并行 worktree 之间互相污染。每个 worktree 必须独立分支且 CLAUDE.md 里的命令不能依赖全局状态。如果测试需要 docker确认每个 worktree 用不同的端口或容器名。6. 把机构知识变成文件从下一次会话开始这套东西落地不需要大动干戈。你可以从今天开始在仓库根目录跑一次/init生成 CLAUDE.md剪到一页把团队最常被新人问到的三条约定写成第一个 SKILL.md给最容易被误改的目录加一个 PreToolUse hook。然后开一次 plan mode让 agent 先出计划再写码。接入和排障相关的细节可以对照 TaoToken 的接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 逐项核对密钥在控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 管理想先验证模型行为再去改仓库用模型对话 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 试几轮如果要把这套流程长期跑在编码和 Agent 任务上Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 更适合按量推进。下一篇讲 Test 阶段怎么让 agent 在把成果交给你之前自己先验收一遍——反馈回路加 CI 里的持续 evals。
