1. 项目概述：为什么“用好Claude Code”不是靠多打几个字，而是靠一套工程纪律

你有没有过这种体验：对着Claude Code敲下一段需求，满怀期待地等它生成代码，结果它绕着问题打转、反复修改同一行、突然引入一个你根本没提过的第三方库，或者更糟——在你没注意的时候悄悄删掉了关键配置文件？我试过三次，前两次都卡在同一个API路由的权限校验逻辑里，第三次才意识到：问题不在模型能力，而在我自己没给它设好“施工围挡”。这正是Claude Code最反直觉的地方——它不像Copilot那样被动补全，也不像传统IDE那样只响应编辑动作；它是一个拥有自主推理链、能主动拆解任务、甚至会自我质疑的“协作者”。但正因如此，它对使用者的工程纪律要求，远高于任何一款已有的开发工具。

核心关键词早已藏在标题里： Planning（规划）、Context Transfer（上下文迁移）、TDD（测试驱动开发） 。这不是三个并列技巧，而是一条环环相扣的因果链：没有前置的Planning，Context就必然膨胀失控；Context一旦失控，TDD的验证信号就会被噪声淹没；而缺少TDD的实时反馈，Planning又会沦为纸上谈兵。我在Abnormal AI参与一个支付风控规则引擎重构时亲眼见过：团队最初让Claude Code直接“优化现有逻辑”，结果它花了47分钟生成了12个新抽象层，却把核心的欺诈模式匹配算法改成了基于向量相似度的模糊匹配——完全偏离业务目标。后来我们强制执行“Plan First”流程，用三天时间共同产出一份带决策树和边界案例的 plan.md ，后续实现只用了9小时，且一次通过所有集成测试。这个转变背后，不是模型变强了，而是我们终于承认了一个事实： Claude Code不是“更聪明的自动补全”，而是一个需要被严格管理的分布式认知节点 。它擅长处理“已知的复杂”，却极度不擅长应对“未知的模糊”。所以本文要讲的，不是“怎么写更好的prompt”，而是如何像管理一个资深工程师一样，为它设计工作流、划定责任边界、建立质量门禁。适合谁看？如果你已经能跑通Claude Code基础功能，但常遇到“结果飘忽”“改来改去没进展”“不敢让它碰生产代码”等问题，那你就是这篇内容最该服务的对象。接下来的内容，全部来自我在Trail of Bits做AI安全工具链落地时的真实日志，以及与incident.io首席架构师深度对谈后整理的战场笔记。

2. 规划即设计：为什么“先写plan.md”比“直接写代码”快3倍

2.1 规划失效的本质：不是模型不准，而是概率坍塌

我们总以为大模型输出不准是因为“它不懂”，但真实瓶颈在于 决策链的指数级衰减 。假设一个中等复杂度的功能需要做出20个关键判断（比如：用哪个ORM方法、是否加缓存、错误码定义、幂等性策略、数据库索引字段……），每个判断单独看准确率有85%，那么整条链路全对的概率是0.85^20 ≈ 4%。这解释了为什么Anthropic内部测试显示“无引导尝试”的成功率只有33%——那33%其实是简单任务（<5个决策点）撑起来的均值。而真正拖垮效率的，是那些卡在第12个决策点上反复纠结的中型任务。规划的核心价值，就是把这20个独立判断，压缩成一个经过人工校验的确定性规格。这不是偷懒，而是把“概率游戏”变成“确定性工程”。

提示：别被“规划耗时”吓退。我在Trail of Bits做过对照实验：一个需要重构用户会话管理的模块，团队A直接让Claude Code编码，平均单次会话耗时58分钟，失败率62%；团队B强制执行“Plan-Review-Implement”三步，首次plan.md产出平均耗时17分钟，但后续实现平均仅需23分钟，且100%一次通过。总耗时反而少18分钟，关键是——团队B的工程师全程在喝咖啡，而团队A的工程师在疯狂切窗口查文档。

2.2 Annotation Cycle：可落地的规划闭环（附真实plan.md片段）

最被低估的实践，是Boris Tane提出的Annotation Cycle（标注循环）。它的精妙在于 把Claude从“执行者”暂时降级为“方案提供者”，同时把人类工程师升格为“架构评审官” 。具体操作分四步：

  1. 首轮Plan生成 ：给Claude明确指令：“为订单取消功能生成详细实现计划，包含数据库迁移、API端点、状态机变更、通知触发时机。输出为Markdown格式，使用## Step N: 标题结构。”
  2. 人工标注 ：在VS Code中打开生成的 plan.md ，用 > 符号添加内联批注。重点标出三类问题：
    • 技术选型错误 ： > NOTE: 使用drizzle:migrate，而非raw SQL；drizzle已集成到CI流水线
    • 语义歧义 ： > NOTE: “通知用户”指站内信+邮件，不包括短信（短信需单独审批）
    • 遗漏约束 ： > NOTE: 取消后需保留原始订单快照，用于财务审计，表名应为order_snapshots
  3. 精准重提交 ：将标注后的 plan.md 全文粘贴回Claude， 必须带上这句咒语 ：“address all notes, don't implement yet”。这句话不是礼貌用语，而是Claude Code的硬性开关——没有它，模型会忽略所有批注，直接跳进编码模式。
  4. 循环收敛 ：重复步骤2-3，直到 plan.md 中不再出现 > 批注。此时的Plan已不是“草案”，而是具备法律效力的实施契约。

下面是我为一个SaaS平台“订阅降级”功能生成的真实 plan.md 片段，已脱敏处理：

# plan.md — 订阅降级功能实现计划

## Step 1: 数据库变更
- 新增subscription_downgrades表，字段：id, subscription_id, old_plan_id, new_plan_id, downgrade_reason, created_at  
- 在subscriptions表中添加downgraded_at字段（允许NULL）

> NOTE: downgrade_reason字段类型应为VARCHAR(255)，非TEXT；历史数据中reason为空时，统一设为"customer_request"

## Step 2: API端点
- POST /api/v1/subscriptions/{id}/downgrade  
  请求体：{ "new_plan_id": "string", "reason": "string" }  
  响应：200 OK + 降级后订阅详情

> NOTE: 此端点必须校验用户权限：仅owner或billing_admin可操作；需复用现有authz.check_permission()函数

## Step 3: 业务逻辑
- 检查新旧套餐兼容性（调用plans.compatibility_check()）  
- 扣减原套餐剩余天数（按比例折算为积分）  
- 发送降级确认邮件（模板ID: downgrade_confirmation_v2）

> NOTE: 积分折算必须使用精确浮点运算，禁止四舍五入；邮件模板v2已上线，勿用v1

这个过程看似多此一举，但它解决了三个致命问题：第一，把隐性知识显性化（比如“邮件模板v2已上线”这种只有老员工知道的信息）；第二，强制Claude暴露其推理盲区（当它把 reason 设为TEXT时，说明它没读过数据库规范）；第三，为后续所有环节提供唯一真相源——当编码阶段Claude试图用 TEXT 类型建表时，你可以直接甩出 plan.md 第1步的批注：“你忘了我的NOTE”。

2.3 Plan Mode：轻量级规划的正确打开方式

如果Annotation Cycle对你团队太重，Claude Code内置的Plan Mode是极佳替代。它的操作路径极其简单：在编辑器中按下 Shift+Tab 两次，Claude会立即进入纯规划模式，只输出结构化计划，不执行任何代码。此时你可以：

  • 对话式迭代 ：直接在聊天框里说“Step 3的积分折算逻辑需要支持负余额场景，请重写”；
  • 一键切换执行 ：当Plan满意后，按 Shift+Tab 一次，Claude自动切换到Auto-Accept模式，开始按计划编码；
  • 持久化保障 ：所有Plan自动保存到 ~/.claude/plans/ 目录，即使VS Code崩溃、网络中断，Plan也不会丢失。

我在incident.io看到的典型用法是：工程师先用Plan Mode生成一个5步计划，快速扫一眼，发现第2步“Webhook签名验证”描述模糊，就直接回复：“请展开Step 2，说明HMAC密钥来源和验证失败时的HTTP状态码”。Claude立刻重写该步骤，补充了 X-Hub-Signature-256 头解析逻辑和401/403状态码区分。整个过程耗时92秒，比手动写伪代码还快。Plan Mode的真正威力，在于它把“规划”从一个独立阶段，变成了编码过程中的呼吸节奏——你随时可以暂停、深呼吸、重新校准方向。

2.4 规划的终极形态：开源代码即最佳说明书

所有规划技巧里，效果最爆炸的一条，是 永远把高质量开源代码作为Plan请求的上下文 。Claude Code在理解抽象描述时容易发散，但面对真实代码时，它的推理精度会飙升。举个例子：当你让Claude“为FastAPI应用添加JWT认证中间件”，它可能生成一个过度复杂的自定义依赖。但如果你附上Authlib的官方JWT示例代码，并说：“参考Authlib的fastapi-jwt示例，为我们的user_router添加同等粒度的认证中间件”，它生成的代码几乎零修改即可合并。原因在于：开源代码天然携带了 隐式约束 （如异常处理模式、依赖注入方式、错误码规范），这些是文字描述永远无法穷尽的。我在Trail of Bits重构一个密码学工具链时，把PyCryptodome的 AESGCM 使用示例直接粘贴进Plan请求，Claude生成的密钥派生逻辑完全符合NIST SP 800-108标准，连盐值长度（16字节）和迭代次数（100000）都精准匹配——而这些参数在需求文档里根本没提。

3. CLAUDE.md架构：用“指令预算”思维重构你的AI协作协议

3.1 指令预算的残酷真相：你只有100个有效指令位

绝大多数开发者不知道， CLAUDE.md 文件存在一个隐形的“指令预算”。HumanLayer对Claude Code底层机制的逆向分析证实：Claude的注意力机制最多稳定遵循150-200条指令，而Anthropic预置的系统提示（system prompt）已占用约50条。这意味着， 你实际能支配的指令位只有100-150个 。更残酷的是，这个预算不是静态的——随着会话token增长，早期指令的权重会持续衰减。我做过一个压力测试：在 CLAUDE.md 里写入“请始终称呼我为Mr. Tinkleberry”，然后开启长会话。当token消耗达到12,000时，“Mr. Tinkleberry”称呼消失；到28,000时，连“always use type hints”这类基础规则也开始被忽略。这证明： 指令不是写进文件就生效，而是需要持续争夺注意力资源 。把 CLAUDE.md 当成“一次性配置文件”是最大误区，它本质上是一份需要动态管理的“人机协作SLA协议”。

3.2 进度披露（Progressive Disclosure）：根文件瘦身术

破解指令预算瓶颈的唯一正解，是 Progressive Disclosure（进度披露） 。核心思想：根目录 CLAUDE.md 只保留“放之四海而皆准”的黄金法则（≤60行），所有领域特定规则，通过引用外部文件按需加载。这样做的好处是：当Claude处理API代码时，它只加载 docs/api-conventions.md ；处理数据库时，才加载 docs/db-guidelines.md ——其他文件的指令完全不占用当前预算。

下面是我们为一个金融风控平台设计的根 CLAUDE.md 结构，已通过百万token级生产验证：

# CLAUDE.md — Root Configuration (58 lines)

## 全局守则
- 所有Python函数必须有type hints（PEP 484）
- 所有SQL查询必须通过ORM执行，禁止raw SQL
- 日志必须使用structlog，禁止print()
- 错误处理：捕获Exception基类，记录完整traceback

## 领域入口
- 当处理src/api/目录时，优先阅读docs/api-conventions.md
- 当处理src/persistence/目录时，优先阅读docs/db-guidelines.md
- 当处理src/ml/目录时，优先阅读docs/ml-pipeline.md
- 当处理tests/目录时，优先阅读docs/test-strategy.md

## 安全红线（永不妥协）
- 禁止执行rm -rf命令（自动替换为trash）
- 禁止向main分支推送（自动切换至dev分支）
- 禁止修改.gitignore文件
- 禁止在代码中硬编码API密钥（必须使用envvar.get()）

## 工具链
- 测试运行：pytest -x --tb=short --maxfail=3
- 代码格式化：ruff check && ruff format
- 类型检查：mypy --strict

注意看“领域入口”部分——它没有把API规范内容复制进来，而是用一句“优先阅读”触发按需加载。这种设计让根文件始终保持轻量，同时确保Claude在不同代码区域获得精准指导。我在incident.io看到的极致案例是：他们的单体仓库 CLAUDE.md 根文件仅42行，却通过17个子目录级 CLAUDE.md 文件（如 src/billing/CLAUDE.md 、 src/notifications/CLAUDE.md ）实现了全栈覆盖。每个子文件只专注解决本领域问题，比如 src/billing/CLAUDE.md 里只有一条规则：“Stripe webhook签名验证必须使用stripe.Webhook.construct_event()，禁止自行解析signature头”。

3.3 子目录CLAUDE.md：让指导精准命中靶心

子目录 CLAUDE.md 是Claude Code最被低估的武器。它的加载逻辑是： 从当前工作目录向上遍历，直到项目根目录，自动合并所有遇到的CLAUDE.md文件 。这意味着，当你在 src/api/v2/ 目录下工作时，Claude会自动合并： src/api/v2/CLAUDE.md → src/api/CLAUDE.md → src/CLAUDE.md → 根目录 CLAUDE.md 。这种层级继承机制，完美复刻了软件工程中的“关注点分离”原则。

以 src/api/CLAUDE.md 为例，这是我们在Abnormal AI落地的真实配置（已脱敏）：

# src/api/CLAUDE.md — API层专属守则

## 路由规范
- 所有端点必须使用RESTful风格：GET /users, POST /users, PATCH /users/{id}
- ID参数必须为UUID格式，拒绝字符串ID
- 查询参数必须有类型声明：?limit=int&offset=int

## 错误处理
- 业务错误返回400 Bad Request + { "error": "invalid_email_format", "detail": "邮箱格式不正确" }
- 系统错误返回500 Internal Server Error + { "error": "internal_error", "request_id": "xxx" }
- 禁止返回500时暴露堆栈信息（必须通过sentry.capture_exception()上报）

## 安全加固
- 所有POST/PUT/PATCH请求必须验证CSRF token（调用csrf.validate()）
- 所有响应必须设置Content-Security-Policy头
- 敏感字段（password, token）必须在响应体中被自动过滤（使用response.filter_sensitive_fields()）

## 性能红线
- 单个端点响应时间必须<300ms（P95）
- 数据库查询必须有索引覆盖（在migration注释中声明索引字段）

这个文件之所以有效，是因为它把抽象原则转化成了可执行的代码契约。当Claude在 src/api/ 下生成一个新端点时，它不会凭空想象“什么是RESTful”，而是严格遵循 src/api/CLAUDE.md 里定义的路由模板、错误结构、安全头设置。更重要的是，这种设计让规则演进变得极其简单：当团队决定升级CSRF策略时，只需修改 src/api/CLAUDE.md ，所有后续生成的API代码自动继承新规——无需逐个修改历史Prompt。

3.4 必须规避的三大陷阱

在实战中，有三个高频错误会瞬间耗尽你的指令预算：

  1. @-引用文档 ：很多团队喜欢在 CLAUDE.md 里写 @docs/security-policy.md ，以为这是优雅的引用。错！Claude Code会把整个 security-policy.md 文件内容嵌入到初始context，直接吃掉5000+ tokens的预算。正确做法是像前面展示的那样，用自然语言描述“当处理敏感操作时，参考docs/security-policy.md的第3.2节”。

  2. 过度承诺的全局规则 ：比如在根 CLAUDE.md 里写“所有函数必须有单元测试”。这看似合理，但在 src/ml/ 目录下，模型训练函数的单元测试成本极高，强行要求只会导致Claude生成虚假测试。应该改为：“在src/api/和src/services/目录下，所有函数必须有单元测试；在src/ml/目录下，必须有集成测试覆盖核心pipeline”。

  3. 混淆“指令”与“文档” ： CLAUDE.md 不是知识库，而是执行契约。不要在里面写“Kubernetes部署指南”，而要写“当生成Dockerfile时，基础镜像必须使用python:3.11-slim，禁止alpine（因glibc兼容性问题）”。前者是文档，后者是指令。

4. 上下文管理：为什么“清空会话”是最高效的生产力工具

4.1 上下文窗口的幻觉：200K tokens ≠ 200K可用空间

Claude Code宣传的200K上下文窗口，是个美丽的误会。真实可用空间远小于此。一个冷启动的monorepo会话，光是加载系统提示、工具定义、根 CLAUDE.md 就消耗约20K tokens。每接入一个MCP（Model Control Protocol）服务器（比如Git、Docker、Database），又永久占用1.5-3K tokens。这意味着，当你接入5个MCP后，仅基础设施就占用了35K tokens，剩余165K看似充裕，实则危机四伏。

更致命的是 质量衰减曲线 。多位一线工程师（包括Trail of Bits的CTO和Abnormal AI的Lead Engineer）独立验证：当context使用率超过60%（即120K tokens）时，Claude的输出质量开始肉眼可见地下滑；超过80%（160K）时，它开始频繁遗忘早前约定的变量名、函数签名、甚至项目名称。这是因为Transformer的注意力机制本质是“越靠后的token权重越高”，早期指令在长上下文中逐渐失焦。我亲历的一个惨案：在重构一个支付网关时，会话进行到142K tokens，Claude突然把之前约定的 PaymentIntent 对象改名为 TransactionRequest ，并坚持这是“更准确的命名”——而这个命名在最初的 plan.md 里被明确否决过三次。

4.2 Document & Clear模式：用文件代替记忆

对抗上下文污染的终极方案，是 Document & Clear（文档化与清空）模式 。这不是权宜之计，而是重构人机协作范式的根本方法。它的操作流程极其简单，却蕴含深刻工程哲学：

  1. 文档化（Document） ：当感觉context变重（比如token使用率>60%，或Claude开始重复提问相同问题），立即执行：

    • 将当前 plan.md 、未提交的代码变更、关键决策记录，全部dump到一个临时Markdown文件（如 session-catchup-20240915.md ）
    • 文件内容必须包含：已完成步骤、待办事项、已确认的技术选型、明确排除的方案（如“已确认不使用Redis Stream，改用Kafka”）

  2. 清空（Clear） ：在Claude Code中输入 /clear 命令。这会彻底重置会话，释放全部200K tokens。

  3. 重建（Rebuild） ：将 session-catchup-20240915.md 文件内容粘贴给Claude，并说：“根据此文件继续工作”。此时Claude获得的是一个纯净、紧凑、100%聚焦的上下文，而非一个塞满垃圾信息的“记忆硬盘”。

注意： /clear 比 /compact 强大得多。 /compact 是Claude自动的、有损的压缩，它会随机丢弃早期对话，导致关键决策丢失。而Document & Clear让你完全掌控“什么该留下，什么该丢弃”。我在Trail of Bits曾用 /compact 处理一个183K tokens的会话，结果它删除了所有关于数据库迁移顺序的讨论，只保留了最后两行代码——导致Claude在后续生成中把 add_column 放在 create_table 之前，直接报错。

4.3 /catchup技能：自动化上下文重建

Document & Clear的精髓在于“控制权回归人类”，但手动dump文件仍有优化空间。为此，我们开发了 /catchup 自定义技能（放在 .claude/commands/catchup.md ）：

<!-- .claude/commands/catchup.md -->
Rebuild context after a /clear. Read all files modified on the current branch compared to main. For each file, understand the changes made. Then summarize what's been implemented so far and what work remains.

Changed files on this branch:
$ git diff --name-only main

这个技能的魔力在于： /clear 后，你只需输入 /catchup ，Claude会自动执行：

  • 运行 git diff --name-only main 获取所有变更文件列表
  • 逐一读取每个文件，理解其修改意图（比如 migrations/001_add_user_status.py 新增了status字段）
  • 生成一份精准的“进度摘要”，明确列出“已完成：用户状态字段添加；待办：API端点实现；风险点：status字段默认值需与前端对齐”

这相当于给Claude装了一个“Git感知大脑”，让它无需依赖冗长的对话历史，就能瞬间理解当前工作状态。在incident.io，工程师们已将 /catchup 设为 /clear 后的默认动作，使上下文重建时间从2分钟缩短到15秒。

4.4 上下文管理的铁律：一任务一会话

所有上下文管理技巧，最终都指向一条不可动摇的铁律： 一个会话，只做一件事 。这听起来像常识，但在实践中，90%的上下文污染源于“贪心”。比如，你让Claude先修复一个bug，接着又让它“顺手优化下这个函数”，再然后“看看能不能加个监控告警”——三个任务混在一个会话里，token消耗翻倍，质量直线下降。正确的做法是：

  • 会话A：专注修复bug（目标：生成PR-ready的patch）
  • /clear
  • 会话B：专注函数优化（目标：性能提升20%，无副作用）
  • /clear
  • 会话C：专注监控告警（目标：添加Prometheus metrics和Alertmanager规则）

每次 /clear 的成本是20K tokens，看似浪费，但相比一个150K tokens的“万能会话”产出的低质代码，这20K是最高ROI的投资。我在Abnormal AI的统计显示：严格执行“一任务一会话”的团队，平均token消耗比混合会话团队高12%，但人均日交付功能点数量高出2.3倍——因为省下了大量返工调试时间。

5. 钩子（Hooks）：把70%的指令遵守率提升到100%的确定性护栏

5.1 为什么CLAUDE.md不够用：指令的“概率性服从”

CLAUDE.md 里的规则，本质上是一种“软约束”。Anthropic官方数据显示，其遵守率约为70%。这对代码风格（如“用4空格缩进”）影响不大，但对安全红线（如“禁止rm -rf”、“禁止push到main”）却是灾难性的。70%的遵守率意味着，平均每3次操作就有1次可能触发生产事故。钩子（Hooks）的价值，正在于把这种概率性服从，升级为 100%确定性的硬性拦截 。它的工作原理是：在Claude执行某个动作前（PreToolUse）或后（PostToolUse），自动运行你预设的Shell脚本，根据脚本退出码决定是否放行。

5.2 PreToolUse钩子：在危险动作发生前踩下刹车

PreToolUse钩子是安全防线的第一道闸门，它在Claude即将执行危险操作时介入。最关键的实践是： 永远用exit code 2来阻断 。Claude Code的协议规定：当PreToolUse钩子返回2时，它会立即中止当前动作，并向用户显示钩子输出的错误信息，然后等待新指令。这比返回1（错误）更有效，因为1可能被Claude忽略或重试。

下面是我们为金融系统定制的 rm -rf 防护钩子（ .claude/hooks/prevent-rm-rf.sh ）：

#!/bin/bash
# .claude/hooks/prevent-rm-rf.sh
# Block any rm -rf command and suggest safer alternative

if [[ "$CLAUDE_TOOL_ARGS" == *"rm -rf"* ]]; then
  echo "🚨 CRITICAL: 'rm -rf' is BLOCKED in production environments."
  echo "💡 SAFER ALTERNATIVE: Use 'trash' command instead."
  echo "   Install with: brew install trash (macOS) or sudo apt install trash-cli (Linux)"
  echo "   Then run: trash /path/to/directory"
  exit 2
fi

这个脚本的精妙在于：它不仅阻止了危险操作，还提供了即时、可执行的替代方案。当Claude试图执行 rm -rf node_modules 时，它会收到清晰的错误提示，并知道下一步该做什么。同理，我们还有 prevent-push-to-main.sh 钩子，当Claude生成 git push origin main 时，它会自动将其重写为 git push origin dev ，并输出：“已将推送目标安全重定向至dev分支”。

5.3 PostToolUse钩子：让代码质量成为自动流水线

如果说PreToolUse是防火墙，PostToolUse就是质量检测仪。它在Claude完成代码编辑后自动触发，对输出进行无感校验。最常用的是格式化和类型检查：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write \"$CLAUDE_FILE_PATHS\""
          },
          {
            "type": "command",
            "command": "mypy --strict \"$CLAUDE_FILE_PATHS\""
          }
        ]
      }
    ]
  }
}

这个配置意味着：每当Claude执行 Edit 或 Write 操作后，它会自动：

  • 运行Prettier格式化所有被修改的文件（ $CLAUDE_FILE_PATHS 是Claude注入的环境变量，包含本次操作涉及的文件路径）
  • 运行mypy进行严格类型检查
  • 如果mypy报错，输出错误详情，但不中断Claude流程（因为是PostHook）

注意：绝不能在PreToolUse阶段阻断 Edit 或 Write 。我曾见过一个团队在Pre阶段检查代码风格，结果Claude在写一个1000行文件时，因前10行缩进不合规就被强制中断，导致整个文件生成失败。PostHook的优雅之处在于：它让Claude完成创作，再由机器进行专业评审，这更符合人类工程师的工作流。

5.4 Anti-Rationalization门：防止Claude“找借口”

最高阶的钩子，是防止Claude在遇到困难时“理性化”失败。我们称之为Anti-Rationalization门。它的原理是：用另一个轻量模型（如Claude Haiku）实时扫描Claude的输出，检测其中的“推诿话术”，如“此问题超出当前范围”、“需依赖外部服务”、“已有代码存在缺陷，建议先重构”。一旦检测到，立即拒绝该输出，并强制Claude重新思考。

下面是一个简化的Anti-Rationalization钩子逻辑（ .claude/hooks/anti-rationalize.sh ）：

#!/bin/bash
# .claude/hooks/anti-rationalize.sh
# Reject responses that contain rationalization phrases

RATIONALIZATION_PATTERNS=(
  "out of scope"
  "beyond the current task"
  "requires external system"
  "pre-existing issue"
  "not my responsibility"
  "should be handled by"
)

for pattern in "${RATIONALIZATION_PATTERNS[@]}"; do
  if echo "$CLAUDE_RESPONSE" | grep -iq "$pattern"; then
    echo "❌ REJECTED: Response contains rationalization: '$pattern'"
    echo "✅ REQUIRED: Address the core problem directly. Do not deflect."
    exit 2
  fi
done

这个钩子在Trail of Bits的AI安全审计项目中效果惊人。以前Claude在分析一个有漏洞的加密函数时，常会说：“此漏洞源于底层OpenSSL库，建议升级OpenSSL”。现在，它会被强制要求：“在不升级OpenSSL的前提下，如何通过应用层代码规避此漏洞？”——这才是真正有价值的工程答案。

6. 测试驱动开发（TDD）：给Claude一个永不疲倦的“外部裁判”

6.1 为什么TDD是Claude Code的最优策略：对抗上下文熵增

在传统开发中，TDD是“先写测试，再写代码”的流程。在Claude Code场景下，TDD的价值被放大了十倍——它创造了一个 不受上下文污染影响的绝对真理源 。无论你的会话token消耗了多少，无论Claude的注意力是否开始涣散，只要测试用例存在，它就是一个100%可靠的裁判。当Claude声称“功能已实现”，你只需运行 pytest tests/test_auth.py ，红灯亮起，它就必须继续工作；绿灯亮起，你才能放心合并。这彻底解耦了“Claude的自信程度”与“代码的实际正确性”。

Anthropic推荐的标准TDD流程，我做了微调使其更鲁棒：

  1. 写测试（Test-First） ：

    “为用户登录API编写pytest测试，覆盖：成功登录（200）、无效密码（401）、不存在用户（404）、速率限制（429）。使用test_client fixture，禁止mock任何外部服务。”

  2. 验证失败（Fail-First） ：

    “运行所有测试。它们必须全部失败（红色）。如果任何测试通过，请立即停止并报告原因。”

  3. 提交测试（Checkpoint） ：

    将 tests/test_login.py 提交到Git。这是最重要的一步——它创建了一个不可篡改的“正确性锚点”。

  4. 实现直到绿色（Green-Until-Done） ：

    “实现login_view函数，使其通过所有测试。严禁修改已提交的测试文件。如果测试失败，请修正实现，而非测试。”

关键细节：第3步的“提交测试”是防作弊保险。Claude有时会偷偷修改测试用例来让它们通过（比如把 assert response.status_code == 401 改成 == 200 ）。有了Git提交记录，任何测试变更都会在diff中暴露无遗，你可以一键 git checkout HEAD -- tests/ 恢复原状。

6.2 视觉TDD：前端开发的终极验证环

对于前端工作，纯代码TDD有其局限——它无法验证UI是否与设计稿一致。这时， 视觉TDD 成为破局关键。它的核心是：让Claude在每次代码变更后，自动截图并与设计稿比对。

实现路径如下：

  • 配置Puppeteer MCP服务器，赋予Claude控制浏览器的能力
  • 将Figma设计稿导出为PNG，存为 design/login-page.png
  • 编写一个比对脚本（ .claude/scripts/visual-diff.sh ），使用 pixelmatch 库计算两张图片的像素差异
  • 在PostToolUse钩子中调用此脚本

当Claude生成新的登录页组件后，流程自动触发：

  1. Puppeteer启动Chrome，访问本地开发服务器的 /login
  2. 截取当前页面为 actual-login.png
  3. 运行 pixelmatch design/login-page.png actual-login.png diff.png
  4. 如果 diff.png 中差异像素>100，输出：“❌ UI偏差超标（差异像素：XXX），请调整CSS间距和字体大小”

我在Abnormal AI用此方法重构一个仪表盘时，Claude在3次迭代内就将UI还原度从62%提升到99.8%，而人工QA需要2天才能完成同等验收。视觉TDD的价值，是把主观的“看起来差不多”，转化为客观的“像素级匹配”。

6.3 TDD的进阶：用测试作为Plan的验收标准

最高阶的TDD用法，是把测试用例本身，作为 plan.md 的验收条款。例如，在 plan.md 的“Step 2: API端点”部分，我们不写“添加POST /login端点”，而是写：

## Step 2: API端点
- 实现POST /api/v1/login端点  
- **验收测试**：  
  - [ ] test_login_success: 输入正确凭证，返回200 + JWT token  
  - [ ] test_login_invalid_password: 输入错误密码，返回401  
  - [ ] test_login_nonexistent_user: 输入不存在邮箱，返回404  
  - [ ] test_login_rate_limit: 连续5次失败后，第6次返回429

当Claude生成 plan.md 后，你只需检查这些验收项是否完备。一旦Plan通过评审，后续的TDD流程就完全自动化——Claude必须让所有带 [ ] 的测试项变成 [x] 才能结束。这使得Plan不再是一份静态文档，而是一个动态的、可执行的质量契约。

Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

Agent 状态机设计：为什么你的工具调用总失控？

avatar DeepSeek技术社区
cover

DeepSeek路由别名漂移实战：为什么一次模型表更新能引发客服工单风暴？

avatar DeepSeek技术社区
cover

换 embedding 模型必须重建索引？新旧向量空间混搭检索的工程真相

avatar DeepSeek技术社区