GitHub Spec Kit 实战（三）：写一份能管住所有 spec 的 /speckit.constitution
前两篇讲了 specify 怎么写才不偏。但还有个问题没解决------
你写完 P1 故事，准备进 /speckit.plan。AI 给你规划了一个"用 MongoDB 存文档、用 Redis 做缓存、用 Kafka 做异步"的方案。你不想用 MongoDB，但 spec 里只字未提"我们项目不能用 MongoDB"，AI 自然就规划了。
这种"项目级硬约束"散落在 README、wiki、老员工的脑子里，AI 看不到。/speckit.constitution 就是把这些约束收拢到一份文件------它是所有 spec、所有 plan、所有 tasks 的"宪法"。
我前前后后重写了 6 次 constitution，越改越短。写得越多越不管用，写得越精越管用。这篇文章把血泪经验总结成 6 条最佳实践。
constitution 长什么样
仓库的 constitution-template.md 给的骨架：
markdown
# [PROJECT_NAME] Constitution
## Core Principles
### [PRINCIPLE_1_NAME]
[PRINCIPLE_1_DESCRIPTION]
### [PRINCIPLE_2_NAME]
...
### [PRINCIPLE_5_NAME]
## [SECTION_2_NAME]
[SECTION_2_CONTENT]
## [SECTION_3_NAME]
[SECTION_3_CONTENT]
## Governance
[GOVERNANCE_RULES]三段式：
- Core Principles（5 条左右）------不可违反的硬规则
- Additional Constraints（Section 2）------技术栈、合规、安全
- Development Workflow（Section 3）------review 流程、测试门槛
最后是 Governance（治理）------宪法怎么改、版本怎么升、违规怎么处理。
模板尾部还要求带一行 metadata：
markdown
**Version**: 2.1.1 | **Ratified**: 2025-06-13 | **Last Amended**: 2025-07-16这行不要省。AI 看到版本号才知道哪条原则是新的、哪条是过时的。
实践 1：每条原则只回答"非黑即白"的问题
宪法和 spec 的 Success Criteria 一样------用 MUST 不用 should 。constitution.md 命令源码里明文规定：
Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate)
判断一条原则合格的标准：PR 阶段能不能用一句 yes/no 来验收？ 能→好；要看情况→改。
反例：
我们鼓励编写单元测试
正例：
所有 PR 必须保持单元测试覆盖率 ≥ 80%，新代码块不允许覆盖率下降
反例：
尽量减少外部依赖
正例：
任何新增外部依赖必须有 ADR（Architecture Decision Record）记录原因，且 PR 必须至少 2 个 maintainer 批准
每条原则都得能塞进一个 PR 模板的 checklist。
实践 2：原则不超过 7 条
5 条原则能让 AI 严格执行，10 条就开始"挑着执行"------注意力被稀释了。我自己的实际项目（中等规模 SaaS）宪法长这样：
markdown
## Core Principles
### I. Library-First
每个 feature 起步为独立 library；library 必须自包含、可独立测试、有清晰文档；禁止仅为组织结构而建的空 library。
### II. CLI Interface (NON-NEGOTIABLE)
每个 library 必须暴露 CLI；文本 I/O 协议：stdin/args 进 → stdout 出，错误走 stderr；支持 JSON + 人类可读双格式。
### III. Test-First (NON-NEGOTIABLE)
TDD 强制：测试写完 → 用户 review → 测试失败 → 才写实现；Red-Green-Refactor 严格闭环。
### IV. Integration Testing
必须写集成测试的场景：新 library 契约、契约变更、服务间通信、共享 schema。
### V. Observability
文本 I/O 确保可调试；结构化日志强制；错误必须带 stack trace 和上下文 ID。5 条。每条都是 MUST，每条都能 PR 阶段 yes/no 验。半年下来 AI 写出来的代码没翻过一次车------因为这 5 条就是项目文化的浓缩。
你可能注意到第 III 条带了 (NON-NEGOTIABLE) 后缀。constitution-template.md 注释里专门提到这个标记------表示这条原则修改时需要 Governance 里规定的更高级别批准 （如 2 个 maintainer 一致同意 + 1 周公示期）。用得克制，标多了就通货膨胀了。
实践 3：技术约束放在 Additional Constraints，不放在 Principles
技术栈相关（"我们用 PostgreSQL 不用 MongoDB"）该写在哪？很多人放 Core Principles，错。
Core Principles 是跨项目、跨时间的价值观 ------比如"测试先行"放到哪个项目都成立。而"用 PostgreSQL 不用 MongoDB"是项目现状，可能 3 年后换库。
放到 Additional Constraints（模板的 SECTION_2_NAME）里：
markdown
## Technology Stack Constraints
- **主数据库**：PostgreSQL 15+。禁止引入 MongoDB、Cassandra 等文档型数据库。
Rationale: 团队无 NoSQL 运维经验，事务一致性需求高，PG 已能覆盖 JSON 场景。
- **后端语言**：Go 1.22+ 和 Python 3.12+。新代码默认 Go。
Rationale: Go 用于高并发服务，Python 用于数据脚本和 AI 集成。
- **前端**：TypeScript + React 18。禁止 Vue、Angular、Svelte。
Rationale: 团队技术栈统一，TS 类型安全是项目级要求。
- **基础设施**：必须部署在 K8s，镜像走公司 Harbor，禁止直连公网部署。每条带 Rationale ------constitution.md 源码强调"explicit rationale if not obvious"。AI 看到"禁止 MongoDB"会想"为什么？是不是漏了最新需求？"------Rationale 解释清楚了，AI 就不会反复在 plan 里建议 MongoDB。
实践 4：改宪法必带 Sync Impact Report
这是 constitution 最独特的机制，也是大多数人不用的------改完宪法要把影响范围列清楚。
constitution.md 命令源码里强制要求：
- Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update):
- Version change: old → new
- List of modified principles (old title → new title if renamed)
- Added sections
- Removed sections
- Templates requiring updates (✅ updated / ⚠ pending) with file paths
- Follow-up TODOs if any placeholders intentionally deferred.
这条要求 AI 改完 constitution 后，必须在文件顶部（HTML 注释，不渲染）加一份变更影响报告：
markdown
<!--
Sync Impact Report
- Version change: v1.2.0 → v1.3.0
- Modified principles: V. Observability (重命名为 V. Observability & Tracing)
- Added sections: Compliance（GDPR 实施要求）
- Removed sections: 无
- Templates requiring updates:
✅ plan-template.md (Constitution Check 段已加入 GDPR 引用)
✅ spec-template.md (Assumptions 段已加合规说明)
⚠ tasks-template.md (待补充"privacy-review"任务类型)
- Follow-up TODOs: 通知法务团队在 2 周内 review 新增 Compliance 段
-->为什么这条机制救命？
我以前改 constitution 不带报告，结果改了"主数据库用 PG"这条，半年后发现 plan 阶段 AI 还在按 MySQL 优化------因为 plan-template.md 里的"Constitution Check"段还引用着旧规则。没有 Sync Impact Report，constitution 就是孤岛。
实践 5：版本号遵守 SemVer，但偏向 MINOR
constitution.md 命令给了 SemVer 规则：
- MAJOR: Backward incompatible governance/principle removals or redefinitions.
- MINOR: New principle/section added or materially expanded guidance.
- PATCH: Clarifications, wording, typo fixes, non-semantic refinements.
实践建议：
- 多数情况用 MINOR------加一条新原则、新加一个章节，都算 MINOR
- MAJOR 慎用------删除原则、重新定义核心原则才用
- PATCH 几乎不给------除非真的只是 typo
我项目里 18 个月改了 12 次 constitution，只有 1 次是 MAJOR（重写了 Principle III. Test-First 的范围）。其余全是 MINOR。
实践 6：宪法不超过 2 页
constitution-template.md 注释里没有明文限制页数，但实际经验：超过 2 页，AI 注意力下降，开始选择性遵守。
我自己项目的宪法（含 5 条原则 + 4 条技术约束 + 3 条工作流 + 治理 + Sync Impact Report）共 187 行 Markdown------大概 1.5 页 A4。
判断"是不是写多了"的标准：
- 看一次 PR review 要花多久读完------超过 5 分钟，团队开始跳读
- 看 AI 在 plan 阶段是否完整 引用宪法------如果开始只引用前 3 条，说明后几条太长了
一份反面教材：1000 行的"完美宪法"
我见过一个团队想搞个"超级宪法"------把代码规范、命名约定、commit 消息格式、git branch 策略、PR 模板、code review 清单、部署流程、on-call 轮值......全塞进 constitution。
结果：
- 半年没人改过------改起来太重
- AI 完全无视中间 80%------太长了注意力不到
- 真正的硬约束（"测试覆盖率 80%"）反而被淹没
- 每次 PR review 都要争"这条是宪法还是建议"------宪法失去了权威
正确做法 ：constitution 只放项目级不可妥协的硬规则 。命名约定、commit 格式这种放 CONTRIBUTING.md，PR 模板放 .github/PULL_REQUEST_TEMPLATE.md。让对的文档管对的事。
写完一次后，怎么维护
constitution 不是写一次就完。我自己用的节奏：
- 每季度 review 一次 ------看 plan 阶段 AI 是否经常"无视"某条；如果是，说明那条不写进宪法或者写得太模糊
- 每改一次同步报告------不写 Sync Impact Report 的变更一律退回
- 每删一条原则开 ADR------为什么删、影响哪些 plan、迁移路径是什么
半年下来我项目 constitution 改过 12 次、删过 1 条、加过 3 条、改过 1 次范围。保持进化，但节奏克制。
小结
| 实践 | 一句话 |
|---|---|
| 1. 每条原则 yes/no 可验 | 禁"should"和"鼓励" |
| 2. 不超过 7 条原则 | 5 条左右最好 |
| 3. 技术约束放 Section 2 | 带 Rationale 解释 |
| 4. 改完带 Sync Impact Report | HTML 注释插顶部 |
| 5. 多数改动用 MINOR | SemVer 不滥用 |
| 6. 全文不超过 2 页 | 长了 AI 注意力下降 |
最关键的一条 ：constitution 写完第一周就开始用 。/speckit.specify 跑出来的 spec.md，去看 plan-template.md 的"Constitution Check"段是不是真的检查了这些原则。如果没检查------你的宪法就是挂着好看。改宪法，不如改 plan-template 让它强制检查。
下一篇会写 /speckit.plan 怎么读懂和怎么干预------plan.md 是宪法和 spec 落地的桥梁，AI 在这一步最容易"自由发挥"，也是人最该把关的地方。