# 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/claude-md-template.md)
- [`../templates/spec-template.md`](../templates/spec-template.md)
- [`../templates/analysis-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 的自由度发生在正确层级。
- 高层只定义目标和边界，低层才决定具体实现细节。
- 这样既防止模型随机发挥，也不把高层误判强行塞进代码。