主题：附录A. 教材与Spec Kit及Kiro的对应关系
难度级别：中级
预计学习时间：3-4小时主动学习 + 2小时实践
前置知识： 对SDD（规范驱动开发）的基本理解
熟悉Markdown格式
至少使用过一个AI编程助手的经验
项目管理基础概念（路线图、需求、规划）的理解
学习目标： 通过对应表将教材的七个工件与Spec Kit和Kiro中的对应元素进行匹配
根据附录中的标准为具体项目选择格式（教材/Spec Kit/Kiro）并说明理由
将流程从一个系统迁移到另一个系统，保留工件的语义而非仅保留名称
为假设项目用validation.md制定明确的验证事实
识别教材简化格式的缺点，并为大型团队提出额外约定
概述：本SDD教材附录揭示了作者自定义的规范格式（mission.md、tech-stack.md、roadmap.md、requirements.md、plan.md、validation.md、QWEN.md文件）与两个工业级系统Spec Kit和Kiro之间的关系。核心论点——格式不应成为教条；重要的是在可审查的工件中保留意图、计划、验证和决策。教材为教学和与Qwen Code直接协作而有意简化，而Spec Kit和Kiro提供更丰富的团队、模板和集成基础设施。学习本附录将使读者能够在系统间自由切换，根据团队需求调整流程，并就工具选择做出明智决策。
核心概念： 面向Qwen Code的作者自定义sdd方言：七个Markdown文件构成完整的规范周期：从使命到验证。该格式专为AI代理直接阅读而设计，无需特殊CLI工具。每个文件负责一个独立的思考维度：项目为何存在、有哪些约束、按什么顺序构建、具体构建什么、如何分解实现、哪些事实允许合并、以及代理应如何运作。
validation.md作为独立的思考阶段：教材与替代方案的主要架构差异。不将验证标准分散到任务、检查清单或计划分析中，而是用一个明确的文件包含决定分支是否可以合并的事实。这在实现开始前就创建了一个可见的质量思考层。
Spec Kit：具有/speckit.specify、/speckit.clarify、/speckit.plan、/speckit.tasks、/speckit.analyze等命令的规范系统。提供现成模板、扩展、预设和可重复的工作流。面向拥有多个项目、需要统一标准的团队。
Kiro：具有三个层次的平台：steering文件（持久规则）、specs（具体功能）、任务和测试（可验证的实现路径）。与IDE流程深度集成，使用agent hooks和steering管理代理行为。
工件对应表：系统间映射工具。显示mission.md = 项目宪法（Spec Kit）= steering文件（Kiro）；requirements.md = /speckit.specify + /speckit.clarify = requirements；plan.md = /speckit.plan + /speckit.tasks = design + tasks；validation.md = 部分/speckit.analyze + 检查清单 = 任务和测试中的标准。
通过保留语义的流程迁移：适应方法论：不强制文件名，而是迁移原则——明确的宪法、规划前澄清歧义、将架构决策与任务列表分离、实现前可见的验证事实、将实现与工件对比而非与聊天记忆对比。
Kiro迁移的三层：Steering文件（项目持久规则）、specs（具体功能规范）、任务和测试（可验证的实现路径）。从教材迁移到Kiro时需要将内容分配到这些层次。
格式选择标准：教材——用于学习、小型项目、Markdown透明性、平台独立性。Spec Kit——用于成熟团队、澄清歧义、扩展、多个项目。Kiro——用于现有Kiro用户、IDE集成、内置specs和agent hooks。
简化格式的缺点：在大型团队中需要额外约定：合并请求、路线图负责人、规范审查、任务模板。这些主题在教材第16部分展开。
可审查工件作为流程核心：核心元原则：文件名或使用的CLI不重要——重要的是意图、计划、验证和决策存在于可审查、可版本化、可与实现对比的工件中。
练习： 标题：练习1：为假设项目构建对应表
问题：给定一个习惯追踪移动应用项目。教材格式中已创建文件：mission.md（"通过游戏化帮助用户建立稳固习惯"）、tech-stack.md（Flutter、Firebase、Provider）、roadmap.md（MVP → 社交功能 → 分析）、requirements.md（用户场景列表）、plan.md（架构 + 冲刺任务）、validation.md（留存指标、测试覆盖率）。任务：填写对应表，指明教材每个文件在Spec Kit（具体命令）和Kiro（具体层次/文件）中如何映射。对于validation.md，需说明其独立存在为何是架构决策而非仅为便利。
解答：步骤1：mission.md → Spec Kit：项目宪法（通过/speckit.init引入或手动写入规范标题）；Kiro：steering文件project.md或habits-steering.md。步骤2：tech-stack.md → Spec Kit：宪法部分 + 计划（约束在/speckit.clarify中固定，技术计划在/speckit.plan中）；Kiro：steering文件tech-steering.md + design/specs。步骤3：roadmap.md → Spec Kit：通过/speckit.tasks管理的规范顺序和任务；Kiro：specs/中的功能列表及优先级。步骤4：requirements.md → Spec Kit：/speckit.specify用于功能需求，/speckit.clarify用于歧义；Kiro：specs/habit-tracking.md、specs/gamification.md等文件。步骤5：plan.md → Spec Kit：/speckit.plan用于架构决策，/speckit.tasks用于分解；Kiro：design/architecture.md + tasks/中的独立任务。步骤6：validation.md → Spec Kit：部分/speckit.analyze（实现后验证）+ 任务中的检查清单；Kiro：每个任务中的验收标准 + 测试。独立validation.md的论证：它创建了"质量前沿"——必须在实现前可见的事实，而非事后推导。这改变了团队心理：开发者在编写代码前就看到成功标准，防止"为动而动"。在Spec Kit和Kiro中，这一理念"溶解"在流程中，需要额外纪律来维持。步骤7：QWEN.md → Spec Kit：预设中的代理规则；Kiro：agent hooks和steering文件用于行为控制。
难度：中级
标题：练习2：语义保留迁移——从教材到Kiro
问题：一个4人开发团队使用教材格式工作3个月。积累内容：mission.md、tech-stack.md、含12项的roadmap.md、含8个用户故事的requirements.md、含使用Clean Architecture架构决策的plan.md、含5个标准的validation.md。团队转向Kiro。任务：确定哪些内容进入steering文件、specs、任务和测试。特别注意：validation.md包含标准"API响应时间<<200ms（第95百分位）"——它在Kiro中置于何处，如何确保其在实现前的可见性，如同独立文件所做的那样？
解答：步骤1：Steering文件（持久规则）：mission.md → project-steering.md；tech-stack.md → tech-steering.md；QWEN.md中的原则 → agent-steering.md。步骤2：Specs（具体功能）：roadmap.md每项 + 相关需求 → specs/中的独立文件：auth-spec.md、habit-creation-spec.md、gamification-spec.md等。requirements.md拆分并嵌入对应specs。步骤3：plan.md中的架构 → design/clean-architecture.md（系统级独立spec）。步骤4：任务和测试：plan.md分解 → tasks/并关联specs。步骤5：validation.md中的性能标准：在Kiro中进入API相关任务的验收标准。问题：它"溶解"在任务中。为保留实现前可见性：在steering文件中创建performance-steering.md设定全局SLA；添加performance-spec.md作为系统spec；将所有API任务的完成定义纳入该标准；在第一冲刺中创建独立任务"配置负载测试"。如此，"实现前明确验证事实"的语义通过多层冗余和系统规范得以保留，尽管形式已改变。
难度：中级
标题：练习3：为具体场景论证格式选择
问题：三个场景：（A）学习SDD的独立开发者，周末做pet-project。（B）15人产品团队，3个React项目，需要设计师、分析师和开发者间统一规范标准。（C）8人团队已使用Kiro一年，满意IDE集成，但感觉specs"溶解"在任务和聊天中。为每个场景：选择格式，按附录3个标准论证，指出风险及缓解措施。
解答：场景A：教材格式。标准：（1）学习SDD——直接对应；（2）项目小——不需要基础设施；（3）需要平台独立性——pet-project不绑定企业许可。风险：扩展时结构丢失。缓解：若项目增长，提前约定第16部分的规范。场景B：Spec Kit。标准：（1）成熟团队和模板——15人需要统一标准；（2）独立歧义澄清步骤——角色间传递至关重要；（3）多个项目——需要统一标准。风险：过度形式化拖慢启动项目。缓解：为MVP阶段创建"轻量"Spec Kit预设。场景C：Kiro加改进。标准：（1）已使用Kiro——迁移成本最小；（2）需要IDE集成——保留；（3）specs"溶解"问题——通过引入明确steering文件和仿照validation.md的独立spec文件解决。风险：团队将改进视为"又一层官僚"。缓解：开展工作坊，展示明确specs如何节省聊天澄清时间。
难度：中级
标题：练习4：为现有Spec Kit项目创建validation.md
问题：给定Spec Kit上的电商项目。团队使用/speckit.specify处理需求，/speckit.plan处理架构，/speckit.tasks处理分解，/speckit.analyze处理实现后验证。问题：验收标准"分散"在Jira任务中，合并前无统一验证处。任务：按教材精神创建validation.md，提取并整合标准。内容需包括：（1）购物车的功能标准；（2）非功能标准（性能、安全）；（3）合并前"验证审查"流程。
解答：validation.md结构：第1节：上下文——"本文件包含合并到main前必须确认的事实。任何分支未按此清单检查不得合并。"第2节：功能标准（购物车）：[F1]添加商品更新计数器<<100ms且无刷新；[F2]数量变更时客户端重新计算价格并服务端验证；[F3]登录用户跨会话保存购物车；[F4]成功下单后清空购物车并确认。第3节：非功能标准：[N1]购物车API响应时间<<200ms（p95），负载1000 RPS；[N2]所有修改操作需有效JWT；[N3]SQL注入不可能（自动扫描结果）；[N4]日志不含PII（CI正则检查）。第4节：验证审查流程：步骤1——分支作者填写PR中的validation-checklist.md；步骤2——CI自动运行N1-N4检查；步骤3——审查者在staging手动验证F1-F4；步骤4——不符时阻断合并并指明未完成项；步骤5——合并后/speckit.analyze识别隐藏风险。与Spec Kit集成：validation.md不替代/speckit.analyze，而是先于它创建合并"关卡"。团队保留习惯命令，但添加明确质量工件。
难度：高级
案例研究： 标题：案例：初创公司从教材格式迁移到Spec Kit，团队从2人增长到12人
场景：EdTech初创公司"LinguaFlow"由两位创始人使用教材格式开发语言学习平台起步。8个月内项目增长：新增独立设计师、分析师、6名开发者、2名QA。mission.md、roadmap.md等文件存于公共仓库，但流程"稀释"：开发者对requirements.md理解各异，QA不知按何标准检查功能，分析师修改roadmap.md不通知团队。
挑战：三个具体问题：（1）requirements.md变成400行"文字墙"，无人更新；（2）validation.md存在，但开发者凭"记忆"合并分支，不核对文件；（3）新开发者入职需创始人亲自讲解——知识扩展失效。团队考虑过Kiro（一名开发者个人项目用过），但创始人担心失去"简洁"和"控制"。
解决方案：保留语义转向Spec Kit：（1）mission.md和tech-stack.md整合为项目宪法，通过/speckit.init访问；（2）requirements.md拆分为8个独立规范（/speckit.specify），每规范有分析师负责人；（3）规划前强制/speckit.clarify——设计师和分析师必须解决所有需求中的"TBD"；（4）plan.md转为/speckit.plan + /speckit.tasks，明确分离架构和任务；（5）validation.md标准嵌入任务检查清单，/speckit.analyze作为实现后验证；（6）创建"LinguaFlow-Standard"预设，继承QWEN.md的代理规则。关键决策：通过/speckit.tasks中的强制检查清单保留"明确验证事实"理念，而非独立文件。
结果：3个月后：入职时间从2周缩短至3天（新开发者运行/speckit.init即获完整上下文）；QA退回功能减少60%（归功于/speckit.clarify）；分析师和设计师成为规范负责人，开发者成为任务负责人；创始人通过宪法审查和/speckit.analyze保留控制。意外效果："LinguaFlow-Standard"预设非常成功，团队开始向其他EdTech公司销售Spec Kit实施咨询。
经验教训： 教材格式的简洁在团队增长时成为陷阱——扩展需要流程制度化
"明确验证事实"理念可在系统间迁移，但形式必须适应团队文化
迁移阻力常与技术风险无关，而与创始人"控制感"丧失有关——通过其在宪法和/speckit.analyze中的角色解决
成功迁移需要理解双系统的"中介"——本例中为有Kiro经验的开发者，将原则翻译为Spec Kit语言
相关概念： 工件对应表
通过保留语义的流程迁移
简化格式的缺点
格式选择标准
标题：案例：将validation.md集成到企业银行现有Kiro项目
场景：数字银行"FinSecure"团队（20开发者，5产品团队）使用Kiro 2年。结构：steering文件用于合规需求，specs用于各功能，Jira任务含验收标准。监管压力加剧：需证明每项功能进入生产前已通过47个控制点验证。现有任务中的标准碎片化，审计无法还原完整图景。
挑战：Kiro未预设验证事实的"单一真相源"——它们分散在任务、测试、Confluence检查清单中。审计时团队为单个功能花费3-5天收集证据。风险：无法通过监管审计，罚款，牌照限制。因Kiro与银行IDE和安全策略深度集成，排除迁移其他系统。
解决方案：在Kiro内适配validation.md理念：（1）创建独立"validation specs"层——specs/validation/feature-X-validation.md文件，所有涉及资金或客户数据的功能强制要求；（2）validation spec含47个控制点，按风险分组，有明确"确认工件"字段（测试、日志、审查链接）；（3）CI添加"validation gate"——validation spec未经安全官审查则阻断构建；（4）steering文件validation-steering.md定义哪些功能需validation spec；（5）Kiro agent hook在创建关键功能spec时自动建议validation spec模板。如此，"独立质量思考阶段"的语义无损集成到Kiro现有基础设施。
结果：审计准备时间从3-5天缩短至2小时（所有validation specs在同一目录，结构清晰）。首次监管审计流程验证零问题通过。意外效果：开发者更早考虑合规——validation spec在设计阶段创建，而非发布前匆忙补做。团队固化为"Kiro Validation Extension"模式并开源给社区。
经验教训： "简单"教材的理念经适当适配可解决"企业级"问题
分散的质量标准制造"隐性债务"——监管和审计需求必须有单一真相源
新工件集成现有系统需要自动化（CI gate、agent hooks）——否则纪律无法维持
Kiro的steering文件适合定义策略，specs适合具体检查：这契合Kiro初始架构
相关概念： validation.md作为独立思考阶段
Kiro迁移的三层
可审查工件作为流程核心
通过保留语义的流程迁移
学习建议： 制作实体或数字"对应地图"：打印附录对应表，用你自己项目的实例补充——运动记忆和可视化强化记忆
练习"反向翻译"：取Spec Kit格式（/speckit.specify）或Kiro格式（spec文件）的规范，重写为教材格式——这培养深层结构理解，而非仅表面识别名称
对项目进行"审计"：对应表中哪些工件在你项目中明确存在，哪些"溶解"在聊天、记忆、任务中？此练习揭示规范的"隐性债务"
通过三列比较学习：对每个工件提问——"增加了什么？""丢失了什么？""改变了什么思考顺序？"——防止机械迁移名称而不迁移语义
使用"场景法"：构思具体团队（规模、经验、现有工具）并论证格式选择——3个深入场景优于10个浅层场景
聚焦validation.md：这是主要架构差异。尝试向同事解释为何"独立文件"改变开发心理——若解释有说服力，说明你理解了本质
并行阅读教材第16部分：简化格式的缺点在那里展开，理解格式边界对明智选择至关重要
在流程层面练习"翻译"，不仅限于工件：Spec Kit中的/speckit.clarify步骤与教材中"规划前澄清歧义"如何对应？这需要理解工作流，不仅是文件结构
额外资源： 面向Qwen Code的SDD原版教材：完整课程文本，含第16部分关于大型团队流程扩展
Spec Kit文档：/speckit.*命令、预设、扩展和集成的官方指南
Kiro文档：steering文件、specs、agent hooks和IDE集成指南
SDD工具比较分析：Spec Kit、Kiro及较不知名系统（如Aider、Claude Code projects）的综述文章
受监管行业的规范模式：金融科技、健康科技、航空航天案例，"明确验证事实"如何解决合规问题
课程原始材料（知识库）：生成本指南的完整上下文——用于深入研究各章节关联
总结：附录A表明规范格式是工具而非教条。教材作者方言（从mission.md到validation.md的七个Markdown文件）为教学和与Qwen Code直接协作而有意简化，而Spec Kit和Kiro提供工业级团队、模板和集成基础设施。教材的主要架构差异——validation.md作为独立质量思考阶段，在实现前创建验证事实的"前沿"。对应表允许在系统间切换时保留工件语义。格式选择取决于场景：教材用于学习和小型项目，Spec Kit用于有成熟流程和多项目的团队，Kiro用于深度IDE集成和agent hooks。成功适配需要理解不仅"迁移什么"，而且"为何迁移"——意图、计划、验证和决策必须存在于可审查工件中，独立于所选平台。