学习指南: 第20部分。SDD反模式

模块「第20部分。SDD反模式」中第 2 / 5 节课

您正在未登录状态下查看课程。请登录，以保存进度并参加测试。

主题：第20部分。SDD反模式

难度级别：中级

预计学习时间：4-6小时（理论2小时，实践2-4小时）

先决条件： SDD（规范驱动开发）基础——课程第1-5部分

理解git、pull requests和基础CI/CD

使用AI助手进行开发的经验（Claude、GPT、Qwen等）

项目结构的基础知识：package.json、requirements、测试

学习目标：根据第20部分的清单，在实际项目中诊断至少8种SDD反模式

为每种反模式应用具体的修复技术（例如，分离QWEN.md和specs/，在validation.md中引入事实-重现）

审查validation.md并发现测试幻觉（同义反复、镜像、快照欺骗）

创建抗/clear的流程，使新代理无需聊天历史即可继续工作

用自己的话表述PR说明，区分人类和代理的责任

概述：本课程部分是针对变得沉重、嘈杂或无效的SDD流程的诊断图。SDD中的反模式看起来像是正确的流程（文件到位、检查通过、代理工作迅速），但逐渐剥夺了人类对项目的控制。材料涵盖14种具体的反模式：从代码后的规范和巨大的requirements.md到代理代码中的幻觉和测试幻觉。每种反模式都配有症状、危害解释和逐步修复方法。最终的8问题诊断清单可以快速评估流程健康状况：如果有三个否定回答，建议简化而非添加新工具。

核心概念：代码后的规范：代理先实现功能，然后为现有代码补充requirements.md、plan.md和validation.md的反模式。规范变成了报告而非指导工具。修复方法：在实现前提交粗略规范，禁止在创建规范的会话中编写产品代码，在PR中明确显示规范提交在实现提交之前。

巨大的requirements.md：一个需求文件包含数十个项目、多个场景、未来阶段和有争议的决定。代理开始自行选择优先级，人类失去边界。修复方法：分解为阶段，将未来内容移入roadmap.md，只保留当前分支，将有争议的决定标记为问题。

未运行的validation.md：检查中有漂亮的事实，但没有执行痕迹。产生虚假的完成感。修复方法：每个事实旁边存储命令/场景，要求代理提供通过/失败/未检查的事实列表，没有可重现性就不认为事实已确认。

错误后弱化事实：测试失败——代理改变validation.md中的预期结果而非代码。流程保护代理的实现而非产品意图。修复方法：要求展示差异而不修改，特别仔细地审查validation.md的更改，保存更改原因，禁止未经人类决定删除必要事实。

仪式性的/clear：在阶段之间调用/clear命令，但之后代理从聊天中获得长篇解释。在实际上依赖人类记忆的情况下显示可移植性。修复方法：/clear后只提供文件链接，用新会话检查理解，补充规范而非扩展提示词。

技能作为魔法按钮：调用Qwen Code技能，但没人阅读SKILL.md或理解其决定。技能成为隐藏流程。修复方法：将项目技能存储在仓库中，像审查流程代码一样审查SKILL.md，编写限制，在2-3次手动流程重复之前不要创建技能。

Qwen.md作为垃圾场：在QWEN.md中堆放产品需求、技术栈、个人偏好、临时任务和错误笔记。代理无法区分永久规则与临时上下文。修复方法：产品决策放入specs/，行为规则放入QWEN.md，临时结论放入记忆或回顾，定期清理过期内容。

静默修改项目的钩子：钩子格式化、重写或删除文件而不在计划中有明确步骤。变化超出代理和人类的控制。修复方法：默认钩子只检查或记录，格式化仅作为明确的命令规则，所有更改在git diff中，被阻止时解释原因。

记忆作为隐藏的真相来源：代理基于记忆做决定，但specs/、QWEN.md或AGENTS.md中没有记录。新参与者看不到决定依据。修复方法：记忆=提示，非规则；将重复出现的结论移入可审查文件；删除过期记忆；记忆与规范冲突时——选择规范。

无任务的Mcp：为项目连接MCP服务器"以备将来"。代理获得额外权限，团队不理解可能的外部操作。修复方法：只为具体场景连接，限制工具，将配置存储在可审查位置，检查后关闭实验性服务器。

过大的mvp：第一个版本包含授权、角色、分析、界面、迁移、导入、集成。代理快速创建大量文件，人类来不及评估质量。修复方法：第一阶段证明一个风险，限制时间，扩散时回退到最后绿色状态，只在可验证事实后添加功能。

代理代码中的幻觉：代理自信地引用不存在的函数、方法、包。特别危险的是不存在的包名（slopsquatting攻击：攻击者注册相似名称，npm install拉取恶意代码）。修复方法：tech-stack.md中有允许的依赖列表，添加依赖作为单独的审查步骤，首次错误时核对版本，目视检查包名，引用新函数时要求提供定义链接。

测试幻觉：npm test通过，但bug仍然存在。子类型：同义反复测试（与相同表达式比较）、镜像测试（检查返回内容而无独立预期）、快照欺骗（错误在快照中被固定为"正确"）、任何错误都不失败的测试。修复方法：validation.md中的事实-重现，审查时阅读测试本身，变异测试（Stryker for Vitest），禁止业务逻辑使用快照。

开发者不理解自己的pr：PR作者无法解释决定，转发代理的回答。责任模糊，未来维护不可能。修复方法：规则——作者用自己的话解释PR，审查者向人类提问，鼓励"结对SDD"，重读git diff并表述"我做了X，因为Y"。

实践练习：标题：按清单诊断仓库

问题：您获得了一个使用SDD 3个月的项目的仓库访问权限。按照第20部分清单的8个问题进行诊断。对每个否定回答：指出具体反模式，在仓库中找到证据（提交、文件、PR），提出修复建议并举例新状态。仓库包含：200行的requirements.md，带有"阶段2"和"讨论"标记，validation.md中的事实无命令，QWEN.md中有产品决策和个人偏好，pre-commit钩子自动格式化代码，配置中有3个MCP服务器，其中2个未在当前任务中使用。

解答：1. 问题1（代码后的规范）：检查git log --oneline -- requirements.md plan.md validation.md —— 文件在实现后提交。反模式："代码后的规范"。修复：git rebase -i重新排序提交，在CONTRIBUTING.md中规定：规范在实现之前。2. 问题3（QWEN.md vs specs/）：在QWEN.md中发现"使用PostgreSQL"（产品性）和"不要在循环中使用await"（行为规则）。反模式："QWEN.md作为垃圾场"。修复：将"PostgreSQL"移入specs/architecture.md，QWEN.md中只保留代理规则。3. 问题4（钩子）：pre-commit在plan.md中无步骤的情况下修改文件。反模式："静默修改项目的钩子"。修复：替换为检查型钩子，通过明确命令npm run format在CI中进行格式化。4. 问题5（MCP）：2个未使用的服务器。反模式："无任务的MCP"。修复：从配置中删除，附带实验日期和决定的注释。5. 问题7（/clear）：检查——创建新会话，只提供文件链接，检查任务理解。如果不理解——补充specs/current-task.md。总计4个否定回答——在添加新工具之前需要简化流程。

难度：中级

标题：审查validation.md发现幻觉

问题：您收到功能"折扣计算"的validation.md和测试。测试通过（覆盖率95%）。找出测试幻觉：(1) test('折扣10%', () => expect(calcDiscount(100, 10)).toBe(100 * 0.9)); (2) test('折扣工作', async () => { const result = await calcDiscount(200, 20); expect(result).toBe(result); }); (3) 价格格式化函数的快照测试； (4) test('不崩溃', () => { expect(() => calcDiscount('abc', 'def')).not.toThrow(); })。对每个：分类幻觉子类型，解释什么bug会被忽略，正确重写测试。

解答：(1) 同义反复测试：100 0.9是函数内部相同的表达式。Bug：如果函数只是返回price (100 - percent) / 100，重命名变量会破坏，但逻辑未被检查。正确：const expected = 90; expect(calcDiscount(100, 10)).toBe(expected); + 单独测试边界值（percent = 0, 100, 101）。(2) 镜像测试：expect(result).toBe(result)永远为true。Bug：任何结果都被认为正确，包括undefined、null、计算错误。正确：严格设定expected = 160; + 类型检查。(3) 快照欺骗：首次运行创建了包含错误的快照。Bug：'1 000,00'与'1 000.00'的格式化被固定为正确且不被检查。正确：明确的expect带locale，禁止业务逻辑使用快照。(4) 任何错误都不失败的测试：唯一断言是不抛出。Bug：函数返回NaN、null、字符串'NaN'——测试都是绿色。正确：单独检查有效输入，检查错误——expect().toThrow()带具体消息。额外：在validation.md中添加事实-重现——修复前失败的命令（例如，calcDiscount(-10, 10)返回负价格）。

难度：中级

标题：将QWEN.md"垃圾场"转换为结构化流程

问题：给定真实项目的QWEN.md（片段）：'# QWEN.md\n\n## 产品\n我们在做牙科CRM。主屏幕——预约日历。\n\n## 技术栈\nReact 18, Node 20, PostgreSQL 15.\n\n## 我的偏好\n我受不了循环中的async/await，用Promise.all写。\n\n## 临时\nBug #234：暂时不修，客户同意。\n\n## 3月15日错误\n代理使用了lodash，虽然我们已弃用。不再使用。\n\n## 代理规则\n- 总是先写测试再写代码\n- 不要擅自更改package.json'。按正确用途转换：按目的分离，指出每个块移至何处，哪些规则已过期应删除，哪些需要定期审查。

解答：按第20部分规则结构化：1. "产品" + "技术栈" → specs/product.md和specs/tech-stack.md（产品决策不在QWEN.md中）。2. "我的偏好" → 删除或转换为客观规则："如果顺序不重要，优先通过Promise.all并行执行独立操作"——作为代理行为规则放入QWEN.md。个人"受不了"不可接受。3. "临时：Bug #234" → 移入回顾或记忆并设过期日期，关闭后2周内从QWEN.md删除。4. "3月15日错误" → 如果规则仍相关（"不使用lodash"），移入specs/dependencies.md并附理由；如果代理不再犯——作为过期删除。5. "代理规则"——保留在QWEN.md中，补充："总是先写测试再写代码" → 明确为"遵循TDD：validation.md中的事实 → 测试 → 实现"。"不要擅自更改package.json" → 强化："添加依赖——带tech-stack.md审查的单独步骤"。审查：QWEN.md每月审查，specs/——架构变更时，记忆——每周清理。

难度：中级

标题：构建抗/clear的流程

问题：您开发"支付系统集成"功能已2周。聊天历史包含50+条消息，有澄清、计划偏离、妥协。明天新开发者（和新代理）加入项目。创建最小文件集，使/clear后无需从聊天重述即可继续工作。注意：当前阶段——测试webhook，已知问题——sandbox返回202而非200，已做决定——指数退避重试（最初不在规范中）。

解答：创建文件：1. specs/payment-integration/current-phase.md："阶段3.3：测试webhook。状态：进行中。阻塞：sandbox返回202而非文档所述200。决定：指数退避重试（最多5次，基础延迟1秒，乘数2）。决定日期2024-01-15，原因：支付系统sandbox环境与文档不兼容，生产不受影响。下一步：负载下验证重试。" 2. specs/payment-integration/decisions.md：带上下文、替代方案（等待支付方修复——拒绝，因期限未知）、签名的决定记录。 3. validation.md：更新事实"Webhook处理sandbox的202"带curl重现命令 + 事实"重试总计不超过30秒"带负载命令。 4. QWEN.md：添加规则"与外部API集成时：将文档差异记录在specs/<integration>/discrepancies.md中"。 5. 检查：新会话只获得这些4个文件的链接 + 任务"继续阶段3.3"。如果代理未阅读decisions.md就提议更改重试——流程不稳定，需要强化规范。

难度：高级

案例研究：标题：MVP崩溃：当代理在48小时内构建过多

场景：EdTech初创公司委托开发在线课程平台。需求："2周MVP——注册、课程浏览、教师基础分析"。代理（Claude Code，访问大上下文）在48小时内生成：带角色的完整授权（管理员、教师、学生、访客）、字段级权限系统、12个widget的分析仪表板、CSV数据迁移、SendGrid和Stripe集成。全部"工作"——npm test通过，150+文件，80%覆盖率。

挑战：创始人无法解释权限系统如何工作："代理说这样更安全"。首次真实负载（20个同时注册）发现：email唯一性检查的竞态条件、关键操作缺少事务、"分析"在客户端按全量计算指标。80%覆盖率是幻觉——测试只检查函数存在，不检查正确性。修复一个错误会破坏另外三个，因隐藏依赖。项目6周后完全重写。

解决方案：应用第20部分反模式：1. "过大的MVP"——第一阶段应证明一个风险。本例：能否快速创建并显示课程？其余——后续阶段。2. "测试幻觉"——引入事实-重现：validation.md中每个事实附带修复前失败的命令。变异测试（Stryker）发现60%"覆盖"测试不捕获变异。3. "开发者不理解自己的PR"——引入规则：创始人必须用自己的话解释PR，否则合并被阻止。4. "代码后的规范"——重写从粗略规范"一个课程，一个用户，一个页面"开始。

结果：重写的MVP（实际上是"nano-MVP"）——邮箱注册、创建文本课程、浏览列表——3天完成，12个文件。创始人理解每个决定。第二阶段（分析）发现最初12个widget不需要：教师只要求"多少学生开始和完成"。到首个付费用户的总时间从10周缩短到4周，维护成本降低8倍。

经验教训：代码覆盖率数字——如果测试不检查行为，就是幻觉指标。变异测试对关键路径是必需的。

代理可以创建"工作"的项目，但人类无法维护。人类控制以解释PR的能力衡量，而非代码生成速度。

MVP是验证风险的实验，不是完整产品的迷你版。每个阶段应有一个可衡量的风险和验证事实。