前言上个月我尝试了一件听起来很丝滑的事把项目的架构设计文档丢给 Claude让它自动生成总纲、概要设计、详细设计、开发规约然后按模块逐个开发。想象中文档进 → PRD 出 → 代码跑全程 AI 包办我喝茶看报。实际上文档进 → 冲突出 → 反复修 → 上下文炸 → 重新喂我比没 AI 还累。这篇文章复盘我从盲目乐观到摸清边界的全过程——不是教你怎么用 Claude而是告诉你 Claude 在复杂工程场景下到底哪里行、哪里不行**以及怎么把不行的部分补上。背景为什么会有这个想法我们项目有一套比较完善的架构设计文档系统分层、模块划分、数据流向、接口约定都有明确定义。但文档归文档落地开发还是要人一行行写。我就想既然 Claude 号称能理解长文档、能写代码能不能直接把架构文档喂给它让它先产出全套设计文档总纲→概设→详设→开发规约再按模块逐个生成 PRD最后根据各模块 PRD 写代码流程设计是这样的架构设计文档输入 ↓ Claude 生成《项目总纲》← 定范围、定目标、定约束 ↓ Claude 生成《概要设计》← 模块划分、接口定义、数据流向 ↓ Claude 生成《详细设计》← 类图、时序图、字段级定义 ↓ Claude 生成《开发规约》← 命名规范、代码结构、异常处理约定 ↓ 按模块逐个生成《模块PRD》← 每个模块的技术方案、接口清单、数据模型 ↓ 按模块逐个开发 ← 基于对应的模块PRD生成代码为什么要加模块 PRD这一步因为详设和开发规约是宏观约束落到具体模块时接口签名、参数校验规则、异常场景处理都需要一个更细粒度的施工图纸。我以为这个分层设计是加分项——先锁定方案再写代码逻辑上没毛病。理想很丰满。然后现实开始教我做人。第一坑多文档并存时Claude 的业务理解串了现象架构文档里对同一个业务概念在不同章节可能有不同角度的描述。比如用户订单状态流转在总纲里是一句话带过在概要设计里是个状态机图在详细设计里是字段级的枚举定义。当我把这些文档同时喂给 Claude 生成详设和开发规约时问题来了Claude 产出的详设里订单状态枚举和概要设计里的状态机对不上——多了两个状态少了一个状态转换路径。更离谱的是开发规约里定义的异常处理方式和详设里接口的错误码设计互相矛盾规约说所有异常统一抛 BusinessException详设里却在某个接口上写了此接口需区分 ValidationException 和 BusinessException。诊断我把架构文档、Claude 生成的总纲、概设、详设、规约全部拿出来横向对比发现冲突集中在跨文档的业务规则一致性上冲突类型出现频率典型案例枚举值不一致高概要设计定义 5 个状态详设定义了 7 个异常策略冲突中规约统一异常详设按接口特化命名不一致高同一个 DTO 在概设叫OrderInfo详设叫OrderDetailDTO接口参数遗漏中概设定义了分页参数详设接口签名里丢了根因Claude 不是真正理解业务它是在做跨文档的模式匹配。当同一个概念在多份文档中以不同粒度、不同角度出现时Claude 没有这是同一件事的强约束意识。它只是分别处理每份文档然后拼凑输出。换句话说人类看文档会建立同一个概念的心智模型Claude 不会。它对每份文档的 attention 是均等的不会自动识别总纲里的订单状态和概设里的订单状态机是同一个东西。人类的理解路径 总纲订单状态 → 概设订单状态机 → 详设OrderStatus枚举 ↓ ↓ ↓ 三者是同一个概念必须一致 ← 这是人类的直觉 Claude 的处理路径 总纲订单状态 → 独立理解 → 输出涉及订单状态的描述 概设订单状态机 → 独立理解 → 输出涉及状态机的描述 详设OrderStatus枚举 → 独立理解 → 输出枚举定义 ↓ 三者之间没有强制一致性约束 ← 冲突的源头第二坑上下文长了Claude 开始忘记参考文档现象按模块开发时我的流程是先让 Claude 生成该模块的 PRD接口清单、数据模型、异常处理约定审阅通过后再让它写代码。总纲 概设 详设 开发规约全部作为上下文持续存在。开发第二个模块时也不错。但到第三个模块问题来了——不仅是代码偏了连模块 PRD 本身都开始偏了模块 3 的 PRD 里接口路径风格从/api/v1/order变成了/order/api/v1异常处理方式退化成了 Claude 自己的默认习惯完全忽略了规约里统一抛 BusinessException的约定我需要在每次对话开头反复说请参考之前提供的《开发规约》它才能勉强回到正轨PRD 偏了代码必然偏。这个问题比代码写歪更致命——因为 PRD 在我眼里是审阅过的施工图我默认它是正确的。结果代码写出来跑不通才往回追发现 PRD 本身就和规约冲突了。诊断统计了一下开发 5 个模块的过程中我明确提醒 Claude 参考之前文档的次数模块 10 次文档刚喂新鲜 模块 21 次开始出现小偏离 模块 33 次大量偏离需要反复强调 模块 44 次几乎每次输出后都要纠正 模块 5放弃治疗手动修改根因这背后是两个问题叠加问题一上下文窗口的稀释效应Claude 的上下文窗口虽然大但不是所有内容的权重都一样。当对话轮数增加早期的参考文档逐渐被推到上下文深处Claude 对这些内容的注意力自然降低。对话开始时 [架构文档][总纲][概设][详设][规约][用户指令1] ← Claude 注意力均匀 对话进行中第 5 轮 [架构文档]...[总纲]...[概设]...[详设]...[规约][指令1][代码1][指令2][代码2][指令3]... ↑ 距离当前轮次越来越远注意力越来越弱问题二Claude 的渐进式漂移每次生成代码时Claude 会参考最近生成的代码风格。当它生成的代码和规约有微小偏差时下一轮它会把自己的偏差当作正确示例继续放大——这是一个自我强化的漂移过程。轮次 1生成代码95% 符合规约 ✅ 轮次 2参考轮次 1 的代码 部分规约 → 90% 符合规约 ⚠️ 轮次 3参考轮次 2 的代码 少量规约 → 80% 符合规约 ⚠️ 轮次 4参考轮次 3 的代码 几乎忘记规约 → 60% 符合规约 ❌问题三更深也更隐蔽核心业务逻辑偏差前面说的主要是格式、风格层面的偏离——这类问题肉眼看得出来。但更让我头疼的是业务逻辑层面的偏差——代码编译通过、风格符合规约、接口签名全对但跑起来的行为是错的。这类问题很难举一个漂亮的代码例子因为它本质上不是某一行写错了而是Claude 对整个业务场景的理解停留在文档的文本层面缺少业务方脑子里的隐含知识。举个例子PRD 里写了下单时校验库存并扣减Claude 生成的代码确实做了这两件事——先查库存、再扣库存代码结构没问题。但实际跑起来发现高并发下会出现超卖。因为业务方默认的期望是校验和扣减是原子的——这个对业务方来说是常识PRD 里不需要写。但对 Claude 来说先查再扣和原子扣减是两种不同的实现方式它只会选它见过更多的那个。再比如订单状态流转——PRD 里写了标准路径 PENDING → PAID → SHIPPED。Claude 按这个写了状态机没问题。但业务方后来提到已支付但超时未发货的订单客服可以介入取消这是个隐藏分支不在 PRD 里。Claude 不可能知道生成的代码就没处理这个场景。核心矛盾PRD 写的是显式规则但真实业务里存在大量隐式规则——业务方的默认假设、历史遗留逻辑、口头交代的边界条件。这些东西不会出现在任何文档里但对 Claude 来说文档之外的世界不存在。这类问题比格式偏离危险太多——风格偏了肉眼看得到业务逻辑偏了要跑完整测试、看真实数据才能发现。对于复杂业务场景Claude 写出看起来完全正确但逻辑错误的代码是比语法错误更隐蔽的坑。第三坑你以为增量开发Claude 在重新发明现象完成模块 1 后我想让 Claude 开发模块 2并期望它复用模块 1 的基础设施代码如公共工具类、BaseController、统一异常处理器等。结果 Claude 在模块 2 里重新写了一套异常处理逻辑和模块 1 里已经写好的完全重复实现方式还不一样。诊断我对比了两个模块的代码模块 1手动定义的基础设施 ├── BaseController.java ├── GlobalExceptionHandler.java ← 统一异常处理 ├── BusinessException.java └── Result.java ← 统一返回体 模块 2Claude 生成的代码 ├── OrderController.java ← 没继承 BaseController ├── OrderExceptionHandler.java ← 又写了一套异常处理 └── OrderResult.java ← 又定义了一套返回体模块 2 不仅没有复用模块 1 的基础设施还重复发明了功能等价但实现不同的组件。根因Claude 没有项目已经有什么的全局视图。每次交互它只能看到你喂给它的上下文。我没把模块 1 的代码结构喂给它它自然不知道基础设施已经存在。这不是 Claude 的错是我的 prompt 策略没跟上。我以为按模块开发是自然而然的增量过程但对 Claude 来说每次都是重新开始。改进方案我是怎么把这件事做对的复盘之后我调整了策略重新走了一遍流程。以下是实测有效的改进方案改进一建立单一事实来源——文档合并 显式约束核心思路不让 Claude 同时读多份文档而是由我先把文档合并成一份结构化的事实来源消除多文档之间的歧义。# 项目事实来源喂给 Claude 的 unified spec ## 业务实体定义 - 订单状态PENDING / CONFIRMED / PROCESSING / SHIPPED / COMPLETED / CANCELLED共6个不可增减 - 支付状态UNPAID / PAID / REFUNDING / REFUNDED - ... ## 统一异常策略强制 - 所有 Controller 抛出的异常统一使用 BusinessException - 参数校验失败使用 ValidationExceptionExceptionHandler 中统一处理 - **禁止**在业务代码中 catch 后 return null必须抛异常 ## 命名规范强制 - DTO 命名{Entity}{Action}DTO如 OrderCreateDTO - Service 接口命名I{Entity}Service - Controller 路径/api/v1/{entity}效果多文档冲突问题基本消除。因为冲突的源头同一个概念在不同文档中有不同描述被我在预处理阶段消除了。改进二分层 Prompt 策略——每轮强制注入锚点核心思路不在对话开头一次性喂完所有文档。而是每轮对话都强注入当前模块需要的最小规则集。改进前一次性注入 [总纲 概设 详设 规约] → 对话 1 → 对话 2 → 对话 3 → ... ↑ 锚点逐渐丢失 改进后每轮注入 对话 1[当前模块详设 规约摘要] → 生成模块 1 代码 对话 2[当前模块详设 规约摘要 模块 1 接口清单] → 生成模块 2 代码 对话 3[当前模块详设 规约摘要 模块 1/2 接口清单] → 生成模块 3 代码每轮注入的规约摘要控制在 200 行以内只包含和当前模块相关的规则。宁可多花 30 秒整理上下文也不让 Claude 在 5000 行的上下文里自己找规则。效果偏离率从模块 3 开始就回升的曲线变成了始终保持 90% 的一致性。改进三基础设施锁定——先让 Claude 知道有什么再让它写核心思路在开发每个模块之前显式告诉 Claude 项目已有的基础设施。# 每个模块开发前的 prompt 模板 ## 已有基础设施直接使用不要重新发明 - 异常处理GlobalExceptionHandler路径com.xxx.exception.GlobalExceptionHandler - 统一返回体ResultT路径com.xxx.common.Result - 基础 ControllerBaseController路径com.xxx.controller.BaseController → 所有新 Controller 必须继承 BaseController ## 已有模块接口清单如需调用 - 用户模块UserService.getById(Long id) - 权限模块AuthService.checkPermission(Long userId, String resource)效果重复造轮子的问题彻底消失。而且因为 Claude 知道了已有的接口模块间的调用代码也是一次生成对的。改进四加入校验节点——不要让 Claude 的产出直接进代码库这是最关键的一步。改进后的流程中我在三个节点设了人工校验1. 详设产出校验逐项对比概设检查枚举值、接口签名、异常策略的一致性 2. 规约产出校验和详设交叉验证重点看异常处理是否自相矛盾 3. 模块代码校验CheckStyle / ArchUnit 自动检查 核心业务逻辑走查 → 重点走查金额计算、状态流转、权限判断、优惠券/积分等敏感规则 → Claude 最容易在这些地方写出看起来对、逻辑错的代码效果校验成本远低于修复成本。花 10 分钟校验比花 2 小时修 BUG 划算得多。改进后的完整流程架构设计文档 ↓ ┌─ 人工整理为统一事实来源 ─┐ │ 消除多文档冲突 │ └─────────────────────────┘ ↓ ┌──────────────────────────────┐ │ Claude 生成总纲 │ │ Claude 生成概设 │ │ Claude 生成详设 ──→ 人工校验节点① │ Claude 生成开发规约 ──→ 人工校验节点② └──────────────────────────────┘ ↓ ┌──────────────────────────────┐ │ 按模块生成 PRD 开发 │ │ 分层 prompt 策略 │ │ │ │ 模块 1: [规约摘要] → PRD → 代码 │ │ 模块 2: [规约摘要模块1接口] → │ │ PRD → 代码 │ │ 模块 3: [规约摘要模块1/2接口] → │ │ PRD → 代码 │ │ 每个模块 PRD 代码 → 校验节点③ │ └──────────────────────────────┘核心认知Claude 是高级执行者不是架构师做完这次实战我最深的体会是环节Claude 能做的Claude 做不好的人必须做的理解业务从文档中提取描述跨文档保持一致性定义唯一事实来源产出设计基于模板大量产出保证设计之间的约束不冲突校验跨文档一致性写代码单模块内高质量产出结构代码核心业务规则容易遗漏或写错定义业务规则 关键路径走查复用代码给了接口清单就能用不知道已有什么维护已有组件清单业务逻辑能生成看起来对的代码金额/状态/权限等敏感逻辑易出错重点走查 单元测试覆盖一句话总结Claude 能高质量地执行一个被明确定义的任务但无法在没有人类约束框架的情况下自主保证大型工程的一致性。你的工作不是让 Claude 替代你写代码而是为 Claude 搭建一个它不会跑偏的执行环境。
