工程宪章模板

用这份模板定义所有规格、设计、任务计划和 AI 编码请求都要遵守的规则。它是一层很轻的团队工作协议。

constitution.md

# Engineering Constitution

Owner:
Applies to:
Last reviewed:

## Principles
- 高风险实现前必须先有规格。
- 验收标准必须可观察。
- 高风险变更合并前必须有证据。
- AI 生成代码必须留在批准范围内。

## Required Gates
- Spec review:
- Design review:
- Test evidence:
- Release stop signal:

## AI Coding Rules
- Allowed context:
- Allowed files:
- Non-goal handling:
- Evidence summary:

## Exceptions
- Allowed exception:
- Required approver:
- Follow-up review date:

什么时候使用这份模板

团队希望 SDD 成为工作约定，而不只是模板集合。
多人使用 AI 编码工具，需要一致护栏。
评审质量不稳定，因为证据标准不统一。
负责人需要一份能放进仓库的轻量政策。

填好后应该是什么样

模板只有在写入真实决策、负责人和证据后才有价值。下面是一个可评审的片段。

## Required Gates
- 支付、认证、迁移和公开 API 变更必须经过规格评审。
- AI 生成代码必须包含证据总结和测试命令。
- evidence.md 中的指标超过阈值时停止发布。

场景笔记：把团队习惯写成可执行规则

团队在多个仓库使用 AI 编码工具，但每个人给的上下文、评审要求和证据标准都不同。工程宪章把这些规则变成可重复的工作协议。

容易出错的地方：如果规则只停留在口头文化里，第一次紧急发布就可能跳过规格评审，接受过宽的生成 diff，并且不给下一位评审者留下证据。

评审动作：负责人需要先确认哪些变更必须规格评审，哪些证据门禁不可跳过，以及谁能批准例外。
证据要求：真正生效的宪章会出现在 PR 模板、AI 代理指令和发布门禁里，而不只是团队手册里的政策页。

怎样把模板改成真实项目内容

不要只替换标题和日期。真正有价值的版本，应该把每个占位字段都变成一个可评审决定：谁负责、什么行为必须成立、哪些范围明确不做、合并前需要看到什么证据。如果某个字段暂时无法填写，就把它保留为开放问题，而不是用含糊段落盖过去。

使用这份 constitution.md 时，先写当前最可能导致返工的部分。对很多团队来说，那不是实现步骤，而是边界、例外、兼容性或发布证据。模板越早暴露这些问题，AI 编码或人工实现时越不容易顺手扩大范围。

推荐场景：团队希望 SDD 成为工作约定，而不只是模板集合。
评审重点：原则具体到能影响评审行为。
强写法参考：支付、认证、迁移和公开 API 变更必须有评审过的规格、链接的证据日志和上线停止信号。AI 生成 diff 必须列出允许文件、实际修改文件和覆盖的验收标准。

建议的评审路径

第一轮只看范围：目标是否单一，非目标是否能阻止常见扩张，影响系统是否被点名。第二轮看可验证性：验收标准是否描述了状态、触发和可观察结果，而不是“应该更好用”这类愿望句。第三轮看证据：测试、截图、日志、指标或手工检查是否能证明每条标准。

把这份模板交给 AI 编码工具前，应该先让人类评审者确认允许修改的文件、不可改动的接口、迁移顺序和停止信号。这样 AI 得到的是一份可执行规格，而不是一段看起来很完整但仍然模糊的提示词。

实现前：确认开放问题没有阻塞行为判断。
实现中：每个任务都回到这份模板里的标准或约束。
合并前：用证据证明结果，而不是只写“测试通过”。

实现前先检查这些点

原则具体到能影响评审行为。
门禁区分低风险和高风险工作。
AI 规则写明允许上下文、文件和证据。
例外必须有批准人和复盘日期。

弱写法 vs 强写法

弱写法

写好规格，负责任地使用 AI。

强写法

支付、认证、迁移和公开 API 变更必须有评审过的规格、链接的证据日志和上线停止信号。AI 生成 diff 必须列出允许文件、实际修改文件和覆盖的验收标准。

什么时候可以认为它不是空模板

这类页面最容易变薄的地方，是只提供一个漂亮骨架，却没有说明如何判断填写质量。一个合格版本至少要能回答三件事：这个变更为什么需要现在做；哪些范围被明确排除；合并前用什么证据证明行为没有偏离。

如果你把模板用于真实工作，建议在 PR 描述里附上最终文件，并标出哪些段落在实现中发生过变化。规格不是一次性文档，它应该随着实现证据一起更新。读者复制这份模板时，也应该复制这种习惯：所有看起来像决定的内容，都要能被评审和追踪。

最低证据：至少一条自动化测试或契约 fixture。
高风险证据：补截图、日志查询、指标或回滚信号。
后续证据：对已知缺口写负责人和复查日期。

它在完整 SDD 包里负责什么

不要把所有内容都塞进同一个文件。constitution.md 只负责它最擅长的那一层：把某一类决定写到可以评审、可以引用、可以更新的地方。范围、设计、任务和证据应该彼此连接，但不应该互相吞掉。这样做的好处是，当实现过程中发现新事实时，团队能准确知道应该更新哪一个文件。

实际使用时，可以把这份模板和相关资源串成一条很短的链路：先写规格或提案，再补设计或任务，最后把证据回填到 PR。读者复制模板时，也应该复制这条链路。单独一个漂亮模板不会提高交付质量；可追溯的文件链路才会。

如果页面被拿来做团队规范，建议在仓库里保留一个填好后的样例，而不是只放空模板。样例能告诉新成员什么算“足够具体”，也能让 AI 编码工具学习团队真正接受的边界和证据格式。

上游输入：明确的用户问题、系统约束和已知失败模式。
下游输出：可执行任务、评审问题、测试证据或发布门禁。
维护方式：每次实现改变决定时，同步更新对应规格文件。

FAQ

小团队会不会太正式？

可以很短。一页以内也能有用，前提是写的是团队真正会执行的规则。

它应该放在哪里？

放在仓库或团队手册里，并从模板、PR 描述和 AI 编码说明链接过去。

多久更新一次？

事故、重复评审漏项或工具变化之后更新；不要为了润色文字频繁改。

编辑说明

这份模板面向 spec-driven development 工作流，示例用于展示结构，不代表特定公司的内部流程。

作者: Daniel Marsh
编辑政策: 我们如何审阅和更新内容

建议把它放在仓库的 /docs/specs/ 或 /.specs/ 下，并在实现过程中持续更新。最后更新：2026 年 5 月 19 日。