📒 学霸笔记：07｜上下文的艺术（下）：用 constitution.md 为 AI 注入项目“宪法”

Top Student Notes: 07 | The Art of Context (Part 2): Injecting a Project Constitution with constitution.md

课程 / Course: AI 原生开发工作流实战 / AI-Native Development Workflow in Practice
讲师 / Instructor: Tony Bai
章节 / Chapter: 07
主题 / Topic: constitution.md、项目“宪法”、AI 的顶层约束、原则治理、合宪性审查

一、这一讲在回答什么问题？

What Problem Does This Lecture Solve?

上一讲我们学了：

• CLAUDE.md
• AGENTS.md
• 如何给 AI 注入项目长期记忆
• 如何把“开发规范”和“协作流程”沉淀成 AI 的背景知识

但是，只靠这些还不够。

因为 CLAUDE.md 更擅长回答的是：

• 用什么命令？
• 代码风格是什么？
• 测试怎么跑？
• Commit 怎么写？

可是在更高一级的决策上，新的问题就出现了：

• 两种方案都能做，AI 应该优先选哪个？
• 为了快，能不能引入一个新依赖？
• 测试过了，但设计明显过度抽象，算不算合格？
• 符合局部任务，但违背长期架构哲学，怎么办？

这些已经不是“操作问题”，而是：

原则问题、价值观问题、架构哲学问题

所以这一讲要解决的是：

如何给 AI 一个高于操作手册的“最高原则系统”，用来约束它在复杂工程决策中的行为。

这个东西就是：

constitution.md —— 项目宪法

二、本讲核心结论

Core Conclusion of This Lecture

一句话总结

CLAUDE.md 告诉 AI“怎么做”，constitution.md 告诉 AI“什么绝不能做、什么必须优先做”。

三、从“工作手册”到“根本大法”

From an Operating Manual to a Fundamental Law

这是本讲最重要的认知跃迁。

1. CLAUDE.md 的定位

它像：

团队工作手册 / 操作指南

主要内容是：

• 技术栈
• 命令
• 规范
• 工作流
• 工程偏好

它解决的是：

执行层问题

2. constitution.md 的定位

它像：

项目的根本大法 / 最高原则契约

主要内容是：

• 核心价值观
• 架构哲学
• 不可协商原则
• 优先级判断标准
• AI 在复杂选择中的裁决依据

它解决的是：

决策层问题

3. 一个非常好的类比

• CLAUDE.md：像公司员工手册
• constitution.md：像国家宪法

员工手册可以告诉你：

• 上班几点打卡
• 请假怎么走流程
• 报销怎么填单

但宪法决定的是：

• 什么是不可触碰的底线
• 什么原则高于一切
• 出现冲突时谁优先

四、CLAUDE.md 与 constitution.md 的三大差异

Three Key Differences Between CLAUDE.md and constitution.md

Tony 把这两者的差异讲得非常清楚，核心有三点。

1. 抽象层级不同

Different Levels of Abstraction

CLAUDE.md

低层级、具体、操作性强

例如：

• 用 go test ./...
• 提交信息遵循 Conventional Commits
• 使用 gofmt

constitution.md

高层级、抽象、原则性强

例如：

• 测试必须先于代码
• 简单性优先于过度抽象
• 优先标准库，避免非必要依赖

一句话

CLAUDE.md 规定动作，constitution.md 规定价值取向。

2. 强制力不同

Different Levels of Enforceability

CLAUDE.md

更偏指导性 / operational guidance

AI 会参考它，但有时会变通。

constitution.md

具有绝对优先级和否决权

如果某个方案虽然“能做”，但违反了宪法原则，那么它应被视为：

违宪

应该被驳回，或者至少要求充分说明理由。

一句话

constitution.md 不是“建议”，而是“门禁”。

3. 可变性不同

Different Stability

CLAUDE.md

相对易变：

• 工具变了
• 命令变了
• 依赖升级了
• 工作流微调了

都可能修改它。

constitution.md

应高度稳定：

• 代表项目长期架构哲学
• 不应因短期方便频繁改动
• 除非项目战略方向变化，否则不轻易动

一句话

CLAUDE.md 是操作层配置，constitution.md 是长期治理层制度。

五、为什么 AI 需要“宪法”？

Why Does AI Need a Constitution?

因为 AI 不只是执行器，它还越来越像：

• 方案生成器
• 架构建议者
• 重构推动者
• 自动化工作流参与者

一旦它进入“方案选择”层面，就不能只靠局部任务提示。

没有宪法时，AI 可能会怎样？

• 过度抽象，炫技设计
• 引入不必要的新库
• 为了局部优雅牺牲整体一致性
• 写了能跑的代码，却埋下长期技术债
• 生成复杂但不符合团队哲学的方案

有了宪法后，AI 会被引导成什么样？

• 在多种方案间优先选择长期最优的那种
• 在“快”和“稳”之间有明确偏向
• 在“引依赖”与“用标准库”之间有裁决标准
• 在“复杂模式”与“简单实现”之间有底线
• 在生成计划前先做原则对照

六、constitution.md 从哪里来？

Where Does constitution.md Come From?

这个概念在课程中被明确指向：

GitHub spec-kit 的规范驱动开发思想

Tony 认为这不是一个随意命名的文档，而是：

一种前沿的 AI 工程治理理念

它的目的是：

• 约束 AI 的规划行为
• 限制 AI 的工程冲动
• 把质量、测试、简单性等原则前置
• 将架构哲学转成明确规则

七、解读 spec-kit 的“开发九章”

Understanding the “Nine Articles of Development” in spec-kit

Tony 这里不是要你死记九条，而是要理解其背后的工程哲学。

1. 库先行原则

Library-First Principle

意思是：

功能应先作为独立库设计，而不是直接散落到应用逻辑里

背后思想

• 模块化
• 高内聚
• 低耦合
• 易测试
• 易复用

对 AI 的约束价值

防止 AI 为了快速完成需求，把逻辑直接堆在应用层里，形成“大泥球”。

2. CLI 接口强制

CLI Interface Requirement

意思是：

核心功能最好能通过 CLI 暴露

背后思想

• 可测试
• 可观测
• 可脚本化
• 可集成到自动化流程

对 AI 的约束价值

防止 AI 生成只藏在 UI 背后的“黑盒逻辑”。

3. 测试先行铁律

Test-First Imperative

这可能是整套宪法里最核心的一条：

在写实现之前，先写失败的测试。

背后思想

• 先定义行为，再实现逻辑
• 把“应该做什么”写清楚
• 减少无约束生成代码
• 强制进入 TDD 节奏

对 AI 的约束价值

防止 AI 直接“哗啦啦先写一堆实现”，最后再补测试。

4. 集成、可观测性、版本治理

Integration, Observability, Versioning

这部分强调：

• 集成测试
• 结构化日志
• 版本号纪律
• 工程运行可见性

背后思想

软件不是只要“代码对”就行，还要：

• 可运行
• 可追踪
• 可诊断
• 可演进

5. 简单性与反过度抽象

Simplicity and Anti-Over-Engineering

Tony 特别强调，这是为了防 AI 的一种常见坏习惯：

过度工程 / 过度抽象

AI 很容易：

• 引入多层接口
• 提前抽象未来场景
• 使用复杂设计模式
• 包装框架再包装一层

宪法的作用就是明确告诉它：

简单优先，必要才抽象

6. 集成优先测试

Integration-First Testing

意思是：

优先真实环境测试，而不是全靠 mocks

背后思想

• mock 很方便，但容易造假安全感
• 真实依赖测试更接近真实生产问题
• 真实数据库 / fake server 常比 mock 更有价值

八、九章背后的总哲学

The Overall Philosophy Behind the Nine Articles

如果把这些原则抽象成一句话，就是：

AI 不应只是更快地写代码，而应在原则约束下更可靠地生成可维护的软件。

这也是 constitution.md 的根本意义。

九、如何为自己的 Go 项目写 constitution.md

How to Write a constitution.md for Your Go Project

Tony 给出了一个非常有代表性的 Go 项目宪法样板。
这个样板非常值得学习的不是“字面内容”，而是它的结构。

十、高质量 constitution.md 的四大核心法案

Four Core Articles in a High-Quality constitution.md

第一条：简单性原则

Article 1: Simplicity First

核心精神

• Go 的哲学就是少即是多
• 不做不必要的抽象
• 不引入非必要依赖
• 只实现 spec 要求的内容（YAGNI）

常见条款

• 只做当前明确需要的功能
• 标准库优先
• 避免复杂模式和抽象层

价值

防止 AI：

• 过度设计
• 提前抽象
• 新库上瘾
• 把简单问题复杂化

第二条：测试先行铁律

Article 2: Test-First Imperative

核心精神

• 先写失败测试，再写实现
• 遵循 Red → Green → Refactor
• 优先表格驱动测试
• 优先集成测试和 fake object，不迷信 mock

价值

这条会从根本上改变 AI 的开发节奏。

以前：

• 先生成代码
• 再补测试

现在：

• 先定义行为
• 再驱动实现

一句话

这条是把“写测试”从质量补丁变成开发起点。

第三条：明确性原则

Article 3: Clarity and Explicitness

核心精神

代码首先是给人读的，其次才是给机器跑的。

常见条款

• 错误必须显式处理
• 禁止丢弃错误
• 错误必须包装保留上下文
• 禁止用全局变量传递状态
• 依赖必须显式注入
• 注释解释“为什么”，不是解释“是什么”

价值

防止 AI 生成：

• 偷懒式错误处理
• 隐式共享状态
• 看似工作正常但难维护的代码

第四条：单一职责原则

Article 4: Single Responsibility

核心精神

• 每个包只做好一件事
• 每个文件、函数、接口都尽量职责单一
• 包间边界清晰、低耦合

常见条款

• GitHub API 包不要混 Markdown 转换逻辑
• 定义小接口而不是“上帝接口”

价值

防止 AI 产出：

• 神对象
• 超大文件
• 混合职责的包结构
• 无边界扩张的模块设计

十一、治理条款为什么重要？

Why Governance Clauses Matter

Tony 在样例最后加了一个“治理（Governance）”章节，这非常关键。

因为前面的条款只是“原则定义”，而治理条款定义的是：

这些原则在工作流中如何生效

例如：

• 宪法高于任何 CLAUDE.md
• 高于单次会话中的临时提示
• 计划生成前必须先做合宪性审查

学霸理解

没有治理条款，宪法就可能只是“挂在墙上的口号”。

有了治理条款，它才真正进入工作流执行链。

十二、AI 如何真正“遵宪”？

How Does AI Actually Follow the Constitution?

Tony 给出的答案很重要：

靠“机制 + 引导”的双重保障

1. 机制保障：把合宪性审查嵌入 plan.md

Mechanism: Embed Constitution Check into plan.md

这是最工程化的做法。

在 plan.md 模板里加入：

## Constitution Check
- [ ] 是否优先使用标准库？
- [ ] 是否避免了不必要的抽象？
- [ ] 是否先规划测试？
- [ ] 是否明确依赖注入方式？

这样 AI 在生成计划时，必须先过一遍“合宪检查”。

学霸理解

这相当于把抽象原则转化为：

可执行 checklist

2. 引导保障：在 CLAUDE.md 中反复提醒

Guidance: Remind Through CLAUDE.md

例如在 CLAUDE.md 中写：

当被要求实现新功能时，先阅读相关代码，并对照 constitution.md 的原则后再提出计划。

这样等于告诉 AI：

• 不只是要看代码
• 还要先对照原则
• 不能直接冲进去写实现

双保险的意义

• constitution.md 给出原则
• plan.md 把原则转成门禁
• CLAUDE.md 把门禁融入执行流程

一句话

原则不是靠“希望 AI 自觉”，而是要靠流程把它卡住。

十三、constitution.md 与 CLAUDE.md 的关系再总结

Final Comparison: constitution.md vs CLAUDE.md

十四、这一讲真正讲的不是“多一个文件”

This Lecture Is Not Really About “One More File”

从表面上看，这讲只是多了一个 constitution.md。
但从方法论上看，它完成的是一个关键升级：

从“给 AI 说明项目细节”升级到“给 AI 立法”。

这是开发者角色进化的重要体现。

你不再只是：

• 给 prompt 的人
• 审批输出的人

而是开始成为：

• 项目原则的制定者
• AI 行为的立法者
• 工程哲学的守护者

十五、如何写出团队自己的“宪法条款”？

How to Write Your Own Team Constitution Clauses?

Tony 的思考题其实特别实用。

你应该从团队里那些“不成文但谁都默认要遵守”的原则下手。

常见可写成宪法的隐性规则示例

1. 不引入新依赖

## 第X条：依赖克制原则
除非标准库或现有依赖无法满足需求，否则禁止引入新的第三方库。任何新增依赖必须在计划阶段说明必要性与替代方案评估。

2. 数据库变更必须可回滚

## 第X条：数据库演进安全原则
所有数据库 schema 变更必须同时提供向前迁移与回滚脚本。没有回滚方案的数据库变更视为不合宪。

3. 前端组件无状态优先

## 第X条：前端组件纯度原则
默认优先实现无状态组件。只有在存在明确交互状态需求时，才允许引入局部状态管理，并需说明理由。

4. 禁止暴露内部 ID

## 第X条：标识暴露安全原则
对外接口中禁止直接暴露数据库自增主键或内部实现型 ID。所有外部标识必须使用经过封装的稳定标识符，例如 UUID 或业务编码。

5. 所有副作用必须显式隔离

## 第X条：副作用隔离原则
涉及外部 I/O、网络调用、数据库写入、消息发送等副作用逻辑，必须与纯计算逻辑分离，不得在核心业务判断中隐式触发。

十六、本讲知识结构图

Knowledge Structure of This Lecture

CLAUDE.md 解决“怎么做”
        ↓
复杂工程决策中仍然不够
        ↓
需要更高层次的原则系统
        ↓
constitution.md 登场
        ↓
它定义：
- 核心价值观
- 架构哲学
- 不可协商底线
- 决策优先级
        ↓
来源于 spec-kit 的前沿实践
        ↓
通过宪法条款约束 AI：
- 简单性
- 测试先行
- 明确性
- 单一职责
        ↓
再通过 plan.md 的 Constitution Check
和 CLAUDE.md 的执行提醒
实现“机制 + 引导”的双重保障

十七、学霸速记表

Quick Revision Table

十八、学霸自检题

Self-Check Questions

基础题

1. CLAUDE.md 与 constitution.md 的根本区别是什么？
2. 为什么说 constitution.md 的强制力高于普通上下文文件？
3. spec-kit 的“测试先行铁律”为什么重要？

进阶题

4. 为什么 AI 特别需要“简单性”和“反过度抽象”的约束？
5. 如何通过 plan.md 让“合宪性审查”真正进入工作流？
6. 为什么治理条款是 constitution.md 中不可缺少的一部分？

思辨题

7. 你当前团队里最值得写进“宪法”的一条架构哲学是什么？
8. 如果 AI 为了速度想引入一个新库，而你们团队一直强调依赖克制，你会如何把这个原则写成法案？
9. 你的项目是否存在某些“虽然能跑、但绝不接受”的代码风格或设计方式？它们是否应该进入 constitution.md？

十九、学霸总结

Top-Student Summary

这一讲完成了“上下文艺术”的最后升维：
从上一讲的 CLAUDE.md / AGENTS.md 的长期记忆机制，进一步上升到更高抽象层级的项目原则治理，即 constitution.md。

CLAUDE.md 更像操作手册，告诉 AI：

• 用什么命令
• 遵循什么格式
• 如何配合项目工作流

而 constitution.md 更像项目宪法，告诉 AI：

• 在多个方案中应该偏向什么
• 什么是不可协商的底线
• 什么行为即使短期有效也绝不允许

Tony 通过解读 spec-kit 的“开发九章”，展示了 constitution.md 的真正价值：
它不是多写一个文件，而是把团队的架构哲学、工程价值观和长期技术利益，前置到 AI 的规划与实现环节中，用来约束 AI 避免：

• 过度抽象
• 依赖泛滥
• 测试后补
• 结构失控
• 只顾眼前、不顾长期

最后，通过“机制 + 引导”的双保险：

• 在 plan.md 中设置 Constitution Check
• 在 CLAUDE.md 中明确要求 AI 先对照宪法再规划

就能把抽象原则变成可执行的工程门禁。

因此，这一讲真正让开发者角色再上了一层楼：

你不再只是 AI 的操作者，而开始成为 AI 的立法者与工程哲学的治理者。

二十、一句话记忆

One-Sentence Memory Hook

CLAUDE.md 训练 AI 按规则做事，constitution.md 约束 AI 按原则做正确的事。