skills/cc-switch-dev-workflow/references/knowledge-base/foundations/spec-driven-development.md

Foundation: Spec-Driven Development

Purpose

定义本知识库的第一原则：先有设计哲学、再有调研、再有 Spec、最后才有代码。代码不是起点，Spec 才是起点。

When to Use

• 新项目初始化时
• 老项目要补 SPECS/ 时
• 团队对“为什么不直接让 AI 写代码”存在分歧时

Inputs

• 会议清洗结果
• .references/ 调研材料
• 业务需求或问题陈述

Outputs

• CLAUDE.md
• .research/*.md
• SPECS/*.md
• 面向实施的 TODO.yaml

Primary Agent/Model

GPT-5.4 Pro xhigh

Secondary Agent/Model

Claude Opus 4.6

Required Skills

• ralphy-initializing
• spec-tasking
• spec-reviewing

Steps

1. 先清洗会议纪要，只留下当前项目相关决策。
2. 建立项目哲学和执行边界，写入 CLAUDE.md。
3. 基于参考仓库形成调研结论，而不是凭训练记忆直接拍板。
4. 把调研结论固化为 SPECS/*.md，让 Spec 成为实施前的单一真相源。
5. 只在 Spec 通过自动审查和人工审核后，才进入实施。

Exit Criteria

• 项目有清晰的设计哲学和边界
• SPECS/ 已覆盖系统契约，而不是散落在聊天和提示词里
• 代码任务都能指向明确的 Spec 条款和参考源

Failure Recovery

• 若 Spec 过于抽象无法实施，补写接口契约和验收标准
• 若 Spec 过于具体锁死实现，删去实现细节，只保留系统契约
• 若文档重复定义同一概念，回到 SSOT 原则合并

Related Templates

• ../templates/claude-md-template.md
• ../templates/spec-template.md
• ../templates/analysis-template.md

Non-Negotiables

• Spec 是代码前的单一真相源，不接受“边写边想”的主路径。
• CLAUDE.md 必须存在，并明确设计哲学、技能索引、边界和质量标准。
• 会议纪要不是执行输入，会议纪要的清洗结果才是。
• SPECS/ 只描述系统契约，不混入教程、背景散文和变更历史。

What Belongs In Spec

• 架构边界
• 命名约束
• 数据模型与接口契约
• 生命周期、处理流程和行为约束
• 禁止模式和决策理由

What Does Not Belong In Spec

• 教程式用法说明
• 会议背景
• 提示词技巧
• 技能内部实现说明
• Git 变更历史

Why This Matters For AI Agents

• 规范先行时，AI 的自由度发生在正确层级。
• 高层只定义目标和边界，低层才决定具体实现细节。
• 这样既防止模型随机发挥，也不把高层误判强行塞进代码。