学习指南: 附录A. 通往第一卷的桥梁

模块「附录A. 通往第一卷的桥梁」中第 3 / 5 节课

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

主题：附录A。通往第一卷的桥梁

难度级别：中级

预计学习时间：4-6小时主动学习 + 2-3小时实践练习

前置条件：完成第一卷主要部分（第6、7、9、10、12、13、15、16、17、20、22部分）

理解SDD工件结构：mission.md、tech-stack.md、roadmap.md、requirements.md、plan.md、validation.md

对第一卷中的AgentClinic项目有基本了解

理解EARS和Given/When/Then格式用于需求规范

熟悉Qwen Code钩子（PreToolUse、PostToolUse）

理解智能体可替换性概念以及对ACP/AGENTS.md的引用

学习目标：成功将第二卷全部12个生产场景与第一卷中相应的AgentClinic学习组件对应起来

在三种SDD方言（作者方言、Spec Kit、Kiro）之间完成工件迁移而不丢失语义

形成第二卷的最小学习路径，区分必要工件与完整实施路径

识别并解释第一卷中哪8个主题是阅读第二卷的关键前置条件

应用AgentClinic领域图来解释生产症状（node_not_ready、appointment_latency、high_memory_usage等）在具体章节中的含义

概述：附录A作为课程中SDD（规范驱动开发）学习第一卷与应用第二卷之间的架构桥梁。它系统化地整理了三个关键关联：第一卷中的前置条件（没有这些第二卷无法阅读）、SDD方言对应关系（作者方言、GitHub Spec Kit、AWS Kiro），以及将学习项目AgentClinic转换为生产场景的领域图。附录不包含新方法论——其目的是防止读者认知过载，明确展示第二卷中每个"生产术语"如何从已熟悉的学习代码发展而来。第二卷在第一卷基础上构建了14个新层次：从规范考古学、分层预算到生产SDD反模式和最终生产考核。

关键概念：桥梁（bridge）：第一卷中的工件/概念与其在第二卷中的生产解释之间的明确关联。桥梁以表格形式收集，便于在阅读第二卷任何章节时快速交叉查找。

最小路径：精简的第二卷学习路径，其中部分工件手动填写，部分示例在本地运行，部分模块仅属于完整实施路径。在第0部分（part-00-production-lab.md）中描述。

sdd方言：规范驱动开发方法论的具体实现，具有固定的工件集合和命名规则。教材作者方言使用.md文件；Spec Kit使用/speckit.*命令；Kiro使用自己的工件结构。

agentclinic领域图：第一卷学习实体（Hono路由、SQLite迁移、反馈表单）与第二卷生产症状（node_not_ready、appointment_latency_spike、rate_limit_breach等）之间的对应表。

生产症状：在生产环境中观察到的异常迹象（例如high_memory_usage），在第二卷中通过SDD循环的视角进行分析：规范 → 计划 → 验证 → 升级/修复。

考核路径：获得应用卷考核通过的必修最低要求。对于AgentClinic领域图，考核案例是high_memory_usage（部署后SQLite读取峰值）；其他症状用于理解本地示例。

规范考古学：从没有原始文档的遗留系统痕迹中恢复规范的过程。第二卷发展了第一卷第13部分中的这一主题。

影子规范：未记录在明确工件中但影响决策的非正式启发式和隐性需求。第二卷通过筛选程序将其形式化。

分层预算：按任务复杂度级别（层）分配LLM模型调用成本的系统，防止简单操作上的预算流失。

反古德哈特定量指标：成对的守护指标，设计用于防止针对单一指标的优化导致另一指标退化（防止古德哈特效应）。

练习：标题：练习1：诊断前置条件缺口

问题：以下是第一卷的8个主题列表。对于每个主题，确定：(a) 它产生哪个SDD工件，(b) 在第二卷哪一章使用该工件，(c) 不了解前置条件的情况下阅读该章会发生什么。主题：mission.md/tech-stack.md/roadmap.md的结构；requirements.md/plan.md/validation.md的格式；合并准入事实和EARS；重新计划和路线图更新；支持遗留代码库；智能体可替换性；团队评审和证据包；Qwen Code钩子。

解答：步骤1：制作3×8表格。步骤2：对于"mission.md的结构"——工件：项目宪法；第二卷章节：第3部分（生产宪法）；跳过后果：不理解不可变层与可变层的分离。步骤3：对于"requirements.md/plan.md/validation.md的格式"——工件：功能规范；章节：第7部分（规范CI）；后果：无法将规范网关配置为强制关卡。步骤4：对于"准入事实和EARS"——工件：验证事实；章节：第4部分（LLM对决）；后果：无法组织角色间的对抗性验证。步骤5：对于"重新计划"——工件：更新的roadmap；章节：第9部分（分层预算）；后果：不理解预算约束如何影响重新计划。步骤6：对于"规范考古学"——工件：恢复的规范；章节：第1部分；后果：无法应用从遗留系统中恢复的技术。步骤7：对于"智能体可替换性"——工件：ACP/AGENTS.md；章节：第8部分（文件仲裁）；后果：不理解多智能体法庭如何保持角色独立性。步骤8：对于"团队评审"——工件：证据包；章节：第13部分（实践考核）；后果：无法形成最终生产考核。步骤9：对于"Qwen Code钩子"——工件：PreToolUse/PostToolUse；章节：第11部分（生产API）；后果：无法通过钩子实现自动修复。

难度：中级

标题：练习2：SDD方言之间的翻译

问题：团队使用GitHub Spec Kit工作。将以下教材作者方言的工件翻译为Spec Kit命令：功能"预约登记"的requirements.md，冲刺迭代的plan.md，功能验证的validation.md。然后执行反向翻译：/speckit.analyze → 作者方言。

解答：步骤1：requirements.md → /speckit.specify（创建需求规范）。步骤2：plan.md → /speckit.plan + /speckit.tasks（计划分解为计划结构和具体任务）。步骤3：validation.md → /speckit.analyze + 验收清单（验证包含分析和验收检查清单）。步骤4：反向翻译：/speckit.analyze → validation.md（验证文件，包含准入事实、EARS规范、Given/When/Then场景）。步骤5：检查语义保留：在Spec Kit中命令在聊天界面执行，在作者方言中文件在Git中版本控制；两种方法都应产生相同的可验证事实集合。

难度：中级

标题：练习3：通过领域图解释生产症状

问题：在基于AgentClinic的生产系统中，记录了autoscale_200pct症状（负载突然增长200%）。使用领域图，确定：(a) 该症状基于第一卷的哪个学习组件，(b) 它在项目的哪个阶段（MVP）出现，(c) 哪些第二卷章节适用于分析，(d) 涉及哪些指标和预算。

解答：步骤1：根据领域图表，autoscale_200pct对应第一卷"MVP阶段（第12部分）"。步骤2：MVP阶段的特点是手动部署且缺乏自动扩展——负载突然增长是意外的。步骤3：适用的第二卷章节：第9部分（分层预算——负载增长时按任务复杂度分配模型），第10部分（反古德哈特定量指标——防止以延迟为代价优化自动扩展），第11部分（生产API——与自动扩展系统集成）。步骤4：指标：appointment_latency（响应延迟），high_memory_usage（扩展时的资源消耗）。步骤5：预算：模型分层预算（不在例行检查上耗尽昂贵调用），cdn_error_budget_burn（负载激增时不耗尽CDN错误预算）。

难度：中级

标题：练习4：为特定章节形成最小路径

问题：你准备学习第二卷第5部分（规范的变异测试）。基于第0部分的最小路径结构，确定：哪些工件手动填写，哪些示例在本地运行，哪些模块仅属于完整实施路径。

解答：步骤1：从附录A确定前置条件：第一卷第9部分（准入事实、EARS、Given/When/Then）——绝对必要，否则无法验证规范变异。步骤2：手动填写的工件：EARS格式的功能requirements.md，变异体集合（故意扭曲的规范版本），预期失败的oracle列表。步骤3：本地可运行示例：变异脚本（在规范中引入受控缺陷），针对变异体的验证器运行，变异覆盖率分析。步骤4：完整路径模块：与CI/CD集成实现每个PR的自动变异测试，仪表板中的变异分数指标，与分层预算的关联（第9部分）。步骤5：检查：如果你未通过第一卷第9部分——返回学习，否则变异测试将变成"术语堆砌"。

难度：中级

案例研究：标题：案例：团队在准备生产考核时从Spec Kit迁移到作者方言

场景：4人开发团队18个月使用GitHub Spec Kit聊天界面为内部医生预约系统进行规范。转入SDD课程准备生产考核时，发现规范历史未版本控制，/speckit.*命令未产生可审计的可验证工件，且无法为团队评审形成证据包。

挑战：(1) 翻译中的语义丢失：/speckit.plan包含隐式假设，这些假设在文件plan.md中必须显式化。(2) 缺乏合并准入事实——在Spec Kit中检查手动执行而未形式化EARS。(3) 团队不理解智能体可替换性与ACP/AGENTS.md的关联，因为在Spec Kit中智能体角色在聊天上下文中固定。(4) 需要通过以high_memory_usage为主要案例的考核路径。

解答：步骤1：将所有/speckit.*命令反向工程为.md文件结构，保留时间戳。步骤2：通过影子规范（第二卷第6部分）形式化隐式假设，随后筛选为显式requirements.md。步骤3：为所有关键路径引入EARS和Given/When/Then，以加速复习模式通过第一卷第9部分。步骤4：创建带明确角色分离的ACP/AGENTS.md，配置Qwen Code钩子自动固定上下文。步骤5：应用领域图：high_memory_usage解释为部署后SQLite读取峰值（第一卷第12部分），从而能够为考核制定指标和预算。

结果：3周后，团队为第13部分（生产考核）形成了完整证据包。规范的变异分数从0%增长到73%。分层预算在保持延迟的同时将LLM调用成本降低34%。关键结论：卷间桥梁并非形式化手续，而是防止从聊天导向规范转向生产就绪SDD时发生认知崩溃的工具。

经验教训： SDD方言之间的翻译需要明确的语义等价性验证，而不仅仅是文件名和命令的语法对应

聊天格式中积累的影子规范在扩展时成为关键风险；其形式化必须先于生产实施，而非随后

考核路径（high_memory_usage）作为整个团队的锚点：它通过已学习过的代码将第二卷的抽象概念具体化

跳过前置条件（本例中为第一卷第15和16部分）会因需要返回而使迁移时间增加2-3倍