Requirement Completeness

Requirement Completeness

• [ ] No [NEEDS CLARIFICATION] markers remain
• [ ] Requirements are testable and unambiguous
• [ ] Success criteria are measurable

[specify.md](https://gitcode.com/GitHub_Trending/sp/spec-kit/blob/9f19be9cad6e83d8b293041d8dbb1b7787c3ed54/templates/commands/specify.md?utm_source=gitcode_repo_files) 生成的 `checklists/requirements.md` 包含 Content Quality / Requirement Completeness / Feature Readiness 三组共 15 项校验，例如"Success criteria are technology-agnostic"、"Scope is clearly bounded"。这些清单逼着 LLM 系统化地自审输出。文档对此的比喻很准确：相当于给了 LLM 一个质量保证框架。

**4. 通过门禁实现宪法合规。** 实现计划模板通过阶段门禁强制执行架构原则：

```markdown
### Phase -1: Pre-Implementation Gates

#### Simplicity Gate (Article VII)

- [ ] Using ≤3 projects?
- [ ] No future-proofing?

#### Anti-Abstraction Gate (Article VIII)

- [ ] Using framework directly?
- [ ] Single model representation?

这些门禁阻止过度工程化，迫使 LLM 为任何复杂度显式辩护。若门禁未过，必须在 "Complexity Tracking" 段落中记录理由——plan-template.md 中的 Complexity Tracking 表格正为此设计：| Violation | Why Needed | Simpler Alternative Rejected Because |，对架构决策形成问责。

5. 分层细节管理。 模板要求实现计划保持高层可读，任何代码样例、详细算法、扩展的技术规格都必须放入对应的 implementation-details/ 文件。这防止规格沦为"读不了的代码倾倒场"，LLM 学会把复杂度抽到独立文件，保持主文档可导航。

6. 测试优先思维。 实现模板强制测试优先的文件创建顺序：先建 contracts/ API 规格，再按 contract → integration → e2e → unit 的顺序建测试文件，最后才写让测试通过的源码。这一顺序约束确保 LLM 在实现之前先思考可测性与契约。tasks-template.md 中同样体现："Tests (if included) MUST be written and FAIL before implementation"。

7. 阻止投机性功能。 模板显式抵制猜测式功能：

- [ ] No speculative or "might need" features
- [ ] All phases have clear prerequisites and deliverables

这阻止 LLM 加入"锦上添花"功能来复杂化实现，每个功能都必须能追溯到有明确验收标准的具体用户故事。

复合效应

这些约束共同作用，产出这样一类规格：完整（清单保证无遗漏）、无歧义（强制澄清标记暴露不确定性）、可测试（测试优先内建于流程）、可维护（恰当的抽象层级与信息分层）、可实现（清晰阶段与具体交付物）。模板把 LLM 从"有创造力的写作者"转变为"有纪律的规格工程师"，引导其能力稳定地产出高质量、可执行的规格。

六、宪法基础：用九条原则强制架构纪律

SDD 的核心是一份宪法（constitution）——一组治理"规格如何变成代码"的不可变原则。spec-driven.md 中称其位于 memory/constitution.md；在当前仓库实现中，constitution.md 命令定义 明确宪法落在项目根的 .specify/memory/constitution.md（specify/plan 等命令读取时以 /memory/constitution.md 相对约定指代同一位置）。宪法是系统的"架构 DNA"，确保每个生成的实现都保持一致性、简洁性与质量。

九条开发原则

宪法定义九条原则，塑造开发过程的每个方面：

第一条：库优先（Library-First）。 每个功能必须以独立库起步，没有例外：

Every feature in Specify MUST begin its existence as a standalone library.
No feature shall be implemented directly within application code without
first being abstracted into a reusable library component.

这迫使规格从第一天就生成模块化、可复用的代码而非单体应用。LLM 生成实现计划时必须把功能组织成边界清晰、依赖最小化的库。

第二条：CLI 接口强制（CLI Interface Mandate）。 每个库必须通过命令行接口暴露功能：

All CLI interfaces MUST:
- Accept text as input (via stdin, arguments, or files)
- Produce text as output (via stdout)
- Support JSON format for structured data exchange

这强制了可观测性与可测试性：LLM 不能把功能藏在不透明的类里，一切必须能通过文本接口访问和验证。

第三条：测试优先的强制令（Test-First Imperative）。 最具变革性的一条——没有测试就没有代码：

This is NON-NEGOTIABLE: All implementation MUST follow strict Test-Driven Development.
No implementation code shall be written before:
1. Unit tests are written
2. Tests are validated and approved by the user
3. Tests are confirmed to FAIL (Red phase)

这彻底反转了传统的 AI 代码生成：不是先生成代码祈祷它能工作，而是 LLM 必须先生成定义行为的全面测试、获得批准、确认失败（Red 阶段），然后才生成实现。

第四、五、六条：项目自定的治理。 文档明确指出，第 IV、V、VI 条由每个项目自己的宪法定义，而非由 Spec Kit 规定。宪法模板 constitution-template.md 提供占位槽与示例关切（集成测试、可观测性、版本化、破坏性变更等），团队把它们替换成匹配自身系统与组织的原则。这保持了九条结构的稳定，同时允许每个项目编码自己的不可协商标准：某项目的第 IV 条可能治理安全与访问边界，另一个项目可能定义集成测试要求。由于 /speckit.analyze 命令评估的是项目中的具体宪法，这些项目自定条款与内建示例一样参与合规检查。

第七、八条：简洁与反抽象。 这对组合条款对抗过度工程：

Section 7.3: Minimal Project Structure
- Maximum 3 projects for initial implementation
- Additional projects require documented justification

Section 8.1: Framework Trust
- Use framework features directly rather than wrapping them

当 LLM 可能自然地创建华丽抽象时，这两条迫使它为每一层复杂度辩护。实现计划模板的 "Phase -1 Gates" 直接执行这些原则。

第九条：集成优先的测试（Integration-First Testing）。 优先于孤立单元测试的真实环境测试：

Tests MUST use realistic environments:
- Prefer real databases over mocks
- Use actual service instances over stubs
- Contract tests mandatory before implementation

这确保生成的代码在实践中有效，而不只是理论上成立。

宪法如何通过模板被执行

实现计划模板通过具体检查点把这些条款操作化：

### Phase -1: Pre-Implementation Gates

#### Simplicity Gate (Article VII)

- [ ] Using ≤3 projects?
- [ ] No future-proofing?

#### Anti-Abstraction Gate (Article VIII)

- [ ] Using framework directly?
- [ ] Single model representation?

#### Integration-First Gate (Article IX)

- [ ] Contracts defined?
- [ ] Contract tests written?

这些门禁是架构原则的"编译期检查"：LLM 要么通过门禁，要么在 Complexity Tracking 段落中记录经论证的例外，否则无法推进。plan-template.md 把 Constitution Check 标注为 GATE，并在 plan.md 命令 中规定"gate violations unjustified 即 ERROR"。此外，analyze.md 命令 在 tasks 生成之后对 spec.md、plan.md、tasks.md 做非破坏性的跨工件一致性分析，其中宪法冲突被自动定为 CRITICAL 级别——"宪法冲突需要调整规格/计划/任务，而不是稀释、重新解释或静默无视原则"。这正是"持续精化"原则的工具化。

不可变原则的力量

宪法的威力在于其不可变性：实现细节可以演化，核心原则保持恒定。这提供了：

1. 跨时间一致性：今天生成的代码与明年生成的代码遵循同一原则；
2. 跨 LLM 一致性：不同 AI 模型产出架构上兼容的代码；
3. 架构完整性：每个功能强化而非破坏系统设计；
4. 质量保障：测试优先、库优先与简洁性原则保证代码可维护。

宪法的演化

原则不可变，但其应用可以演化：

Section 4.2: Amendment Process
Modifications to this constitution require:
- Explicit documentation of the rationale for change
- Review and approval by project maintainers
- Backwards compatibility assessment