制定胶囊系统的项目宪章HERMES & AGENT ENGINEERING · 课时 05

5.1 先决定第一版宪章写什么

项目初始化以后，.specify/memory/constitution.md 已经存在，但里面暂时只有 Spec Kit 提供的模板和占位符。$speckit-constitution 可以把自然语言整理成正式宪章，却不能替我们决定这个项目应该坚持什么原则。

结合前面对胶囊系统的规划，第一版宪章原本可以考虑下面五条原则：

1. 所有加工后的知识都能回到原始资料。
2. 新资料要参与已有知识的演化，不能只是增加一条记录。
3. Hermes 负责理解和判断，飞书负责保存和展示。
4. 系统的重要判断需要留下依据。
5. 未经用户确认，系统不能永久删除原始证据。

不建议在第一版就草率地加入这么多原则，我们第一版只保留第 2 条和第 5 条，其他内容暂时不作为项目级的长期原则。宪章以后仍然可以修订，但每一次增加或修改原则，都应该是一次明确的决定。

5.2 使用 $speckit-constitution 生成宪章

现在进入从胶囊系统目录启动的 Codex 会话，在输入框中引用 $speckit-constitution，并写下这次已经确定的两条原则：

$speckit-constitution

请为胶囊系统制定第一版项目宪章，只保留两条核心原则。

第一条：新资料进入系统后，不能只是增加一条记录。系统需要判断它与已有主题的关系，并把有价值的内容融入现有主题；重复内容不应被反复堆积，冲突内容需要被识别和处理。

第二条：系统可以建议某份资料不被采纳或需要删除，但未经用户确认，不能永久删除原始证据。

不要增加其他核心原则，也不要写具体功能、字段、接口或技术实现。请根据这两条原则完成第一版项目宪章。

如下图所示：

$speckit-constitution 会读取现有模板，把这两条自然语言原则整理成正式条款，并补充宪章的治理规则、版本号和日期。完成后，它会把结果写回 .specify/memory/constitution.md。这一步只更新宪章，不会生成业务代码，也不会开始编写功能 SPEC。

5.3 检查最终写入的内容

在看生成结果之前，先回到项目刚刚初始化完成的状态。此时 .specify/memory/constitution.md 里还没有胶囊系统的规则，只有下面这份默认模板：

尚未填写的默认模板

# [PROJECT_NAME] Constitution
<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->

## Core Principles

### [PRINCIPLE_1_NAME]
<!-- Example: I. Library-First -->
[PRINCIPLE_1_DESCRIPTION]
<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->

### [PRINCIPLE_2_NAME]
<!-- Example: II. CLI Interface -->
[PRINCIPLE_2_DESCRIPTION]
<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->

### [PRINCIPLE_3_NAME]
<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
[PRINCIPLE_3_DESCRIPTION]
<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->

### [PRINCIPLE_4_NAME]
<!-- Example: IV. Integration Testing -->
[PRINCIPLE_4_DESCRIPTION]
<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->

### [PRINCIPLE_5_NAME]
<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
[PRINCIPLE_5_DESCRIPTION]
<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->

## [SECTION_2_NAME]
<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->

[SECTION_2_CONTENT]
<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->

## [SECTION_3_NAME]
<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->

[SECTION_3_CONTENT]
<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->

## Governance
<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->

[GOVERNANCE_RULES]
<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->

**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->

模板中用方括号包围的内容都是占位符，等待 $speckit-constitution 根据项目情况填写。没有方括号的 Core Principles 和 Governance 则是固定的结构标题。把模板中的各个位置拆开来看，会更容易理解它是怎样变成一份正式宪章的。

先抓住 PRINCIPLE

PRINCIPLE 表示一条核心原则，回答的是“这个项目无论怎样设计和开发，都必须遵守什么”。它不是一个独立的大章节，而是放在 Core Principles 章节下面的一条具体规则。因此，模板用 ## Core Principles 建立核心原则章节，再用 ### [PRINCIPLE_1_NAME]、### [PRINCIPLE_2_NAME] 等三级标题依次放入各条原则。

对于个人项目和大多数小团队项目，先把真正不能违背的 PRINCIPLE 想清楚，通常已经足够。胶囊系统的第一版就是如此：我们只保留“新资料必须参与主题演化”和“原始证据由用户最终处置”两条原则，不再额外设计复杂的安全规范、审核流程或质量门槛。

SECTION 是留给进阶需求的扩展位置。它与 Core Principles 处在同一层级，可以容纳一整组相关规则。大型团队或管理要求严格的项目，可能需要单独写安全与合规要求、发布审批流程或统一质量标准，这时才有必要使用 [SECTION_2_NAME] 和 [SECTION_2_CONTENT]。这些内容牵涉组织分工和治理方式，适合以后放到大型项目的进阶场景中单独讨论，本次实战只需要知道模板预留了这个能力。

模板从 [SECTION_2_NAME] 开始，是因为固定存在的 Core Principles 已经是整份宪章的第一个章节。后面的第一个可选章节自然占据第二个章节位置，因此叫作 SECTION_2；再往后才是 SECTION_3。这里的数字只是模板内部用来区分位置的编号，不代表优先级，也不会作为“第 2 节”“第 3 节”显示在最终标题中。之所以没有 [SECTION_1_NAME]，正是因为第一个章节的名称已经固定为 Core Principles，不需要再留占位符。

因此，默认模板并不是一份可以直接执行的通用宪章。它只规定了宪章应该具备的基本骨架，具体保留几条原则、是否需要额外章节，以及每条规则写什么，仍然要由当前项目决定。

执行 $speckit-constitution 后，Agent 会用我们确定的内容替换这些占位符，删除不需要的原则和可选章节，并补上治理规则、版本和日期。现在再打开 .specify/memory/constitution.md，得到的才是胶囊系统正式使用的宪章：

5.4 生成后的宪章

以下是通过$speckit-constitution生成的宪章。

<!--
Sync Impact Report

- Version change: template -> 1.0.0
- Modified principles:
  - Template Principle 1 -> I. 资料必须融入主题
  - Template Principle 2 -> II. 原始证据由用户最终处置
- Added sections: None
- Removed sections:
  - Template Principles 3-5
  - Template optional Sections 2-3
- Follow-up TODOs: None
  -->

# 胶囊系统宪章

## Core Principles

### I. 资料必须融入主题

新资料进入系统后，系统 MUST 判断其与已有主题的关系，而不能仅新增一条孤立记录。
其中有价值的内容 MUST 融入相关的现有主题；重复内容 MUST 避免反复堆积；与已有内容
冲突的信息 MUST 被识别并得到明确处理。此原则确保系统积累的是持续整合、可辨析的知识，
而不是不断膨胀的资料清单。

### II. 原始证据由用户最终处置

系统 MAY 建议不采纳某份资料或删除某份资料，但在获得用户明确确认之前，MUST NOT
永久删除任何原始证据。此原则保留用户对证据去留的最终决定权，并确保系统的判断不会
造成未经授权且不可逆的信息损失。

## Governance

本宪章是胶囊系统所有规划与决策的最高治理依据。任何修订 MUST 记录变更内容、理由及
影响，并经用户明确批准后生效。版本号遵循语义化版本：删除或重新定义核心原则为 MAJOR，
新增原则或实质扩展治理要求为 MINOR，非语义性的澄清和文字修订为 PATCH。每次规划、
评审及交付前 MUST 检查是否符合两条核心原则；发现不符合时，相关工作 MUST 在继续前
修正，或取得用户对宪章修订的明确批准。

**Version**: 1.0.0 | **Ratified**: 2026-08-08 | **Last Amended**: 2026-08-08

5.5 读懂文件顶部的注释

文件开头的 <!-- 和 --> 是 HTML 注释标记。夹在这两个标记之间的内容会保留在 Markdown 源文件里，但不会出现在正常渲染的页面中。这里之所以能看到，是因为上面的代码块展示了文件的完整源码。

注释中的 Sync Impact Report 可以理解为“同步影响报告”。这里的“同步”不是把文件上传到云端，而是检查这次宪章变更会不会影响项目里的其他内容。这份报告不属于宪章条款，它更像一张随文件保存的修改说明。

这次生成结果中的几个字段分别记录了：

以后再次修订宪章时，这份报告也会跟着更新。这样再打开文件，就能先知道这一版改了什么，而不必逐段比较全文。

5.6 正文中的大写英文

宪章里的 MUST、MUST NOT 和 MAY 不是没有翻译完的英文，而是规范文档常用的约束词。MUST 表示“必须”，MUST NOT 表示“不得”，SHOULD 表示“原则上应当如此，但允许有理由的例外”，MAY 则表示“可以这样做，但不是强制要求”。Spec Kit 使用这些大写单词，是为了让每条规则的约束强度更加明确，也方便后续检查 SPEC、方案和任务是否违反宪章。

5.7 读懂文件末尾的版本信息

最后一行记录的不是胶囊系统或 Spec Kit 的软件版本，而是这份宪章自身的版本和生效时间。

• Version 是宪章版本号。1.0.0 表示这是第一份正式生效的宪章。以后删除或重新定义核心原则，通常升级主版本；增加原则或实质扩展治理要求，升级次版本；只做文字澄清，则升级修订版本。
• Ratified 的意思是“批准生效日期”，记录这份宪章第一次被正式确认的时间。只要仍在修订同一份宪章，这个日期通常不会改变。
• Last Amended 的意思是“最后修订日期”，记录最近一次修改宪章的时间。第一版刚刚生成时，它和批准生效日期相同；以后再次修改，通常只更新这个日期和版本号。

5.8 长期原则发生变化时修订宪章

宪章可以新增或者修改吗？我们来探讨一下。

到这里，胶囊系统的第一版宪章已经生成。但宪章不是项目初始化时填完就不再改动的表格，它保存的是整个项目需要长期遵守的边界。以后无论修改哪一份 SPEC，或者让 Agent 开发哪一项新功能，这些边界都不应该被遗忘。这正是项目需要宪章的原因：需求会变，具体功能会变，但一些不能轻易跨过的原则，需要有一个稳定的位置长期约束后续决策。

第一版宪章只保留两条原则，是当时经过裁剪后的决定。当时我们关心的是两个最明确的问题：新资料不能只是堆进系统，已保存的原始证据也不能由系统擅自删除。这两条原则没有问题，但它们也不代表我们在第一天就能想全项目的所有长期边界。

后来在整理胶囊系统的需求简报和 SPEC 时，我们开始具体讨论资料识别、知识冲突和证据处置。一个新问题随之出现：如果 Agent 没有找到适用的规则，或者处理结果没有通过检查，它应该怎么做？

这个问题不能简单地用“报错”来回答。Agent 往往仍然能够继续生成看似完整的内容，但它生成的事实表述可能没有证据，它对冲突的处理也可能覆盖用户原来的判断。等错误被写进证据层或知识页，用户很难再分辨哪一部分来自资料，哪一部分只是 Agent 在缺少依据时的推测。因此，只要这类不确定会影响证据、知识内容或不可逆状态，系统就必须停下来，把决定交给用户（人工介入）。

人工介入还暴露了另一个问题。如果用户每次都要处理类似的异常，那么这些审核记录其实已经表明，当前需求或规则还有缺口（简单点说，就是你的系统还有问题）。它们应该被保留下来，用于后续补充 SPEC 和验收条件，或者进行二次开发和迭代。所以，人工介入不只是针对某一种情况，而是一种全局的可以兜底的机制。

但某一次人工选择可能只是一个特例，系统不能把这次选择擅自归纳成全局规则。从发现规则缺口到修改系统行为，仍然需要用户明确批准。

到了这一步，我们要考虑的就不只是“人工应该怎么介入”，而是“对于系统全局来说，如果遇到 Agent 无法处理的情况，应该怎么做“。而这条规则又应该写在哪里？

思考的方向是这条规则的作用范围：如果一条规则只约束当前功能，就写入这项功能的 SPEC；如果它会反复约束资料识别、知识冲突和证据删除等不同功能，并且以后增加的 Agent 流程也必须遵守，它就是项目级的长期原则。人工审核的这两层约束属于后一种，所以需要进入宪章。

宪章和 SPEC 在这里并不重复。宪章固定所有功能都不能跨过的原则：重要不确定必须暂停并交给用户，审核过程要可追溯，单次决定不能自动变成全局规则。SPEC 再针对当前功能规定什么情况进入审核队列、系统向用户展示哪些信息、用户可以作出哪些决定，以及流程怎样恢复。前者管长期边界，后者管可验收的具体行为。

可以再次引用 $speckit-constitution，向 Codex 输入：

$speckit-constitution

请在现有胶囊系统宪章中增加第三条核心原则：

当系统无法依据现有规则作出可靠决定，并且继续执行可能改变证据、
知识内容或产生不可逆后果时，必须暂停受影响的操作，记录触发原因
和当前状态，并把决定交给用户。系统不得静默忽略问题，也不得在
缺少依据时继续猜测。

人工介入的原因、用户决定和后续结果必须保持可追溯，用于发现需求
和规则中尚未覆盖的情况。单次人工决定不得自动成为全局规则；规则
变更必须经过用户明确批准，并同步更新相关 SPEC 和验收条件。

这一次不是重新生成一份互不相关的宪章。$speckit-constitution 会读取当前的 1.0.0，保留原来的批准日期和两条原则，然后把新增原则写入同一份文件。修订后的核心内容如下：

### III. 重要不确定必须交由用户决定

当系统无法依据现有规则作出可靠决定，并且继续执行可能改变证据、知识内容或产生不可逆
后果时，系统 MUST 暂停受影响的操作，MUST 记录触发原因和当前状态，并 MUST 将决定
交给用户。系统 MUST NOT 静默忽略问题，也 MUST NOT 在缺少依据时继续猜测。

人工介入的原因、用户决定和后续结果 MUST 保持可追溯，用于发现需求和规则中尚未覆盖的
情况。单次人工决定 MUST NOT 自动成为全局规则；任何全局规则变更都 MUST 经用户明确
批准，并在生效前同步更新相关 SPEC 和验收条件。

**Version**: 1.1.0 | **Ratified**: 2026-08-08 | **Last Amended**: 2026-08-15

新增一条核心原则属于实质性扩展，所以次版本从 1.0.0 升到 1.1.0。Ratified 仍然是第一份宪章的批准日期，只有 Last Amended 更新为本次修订日期。文件顶部的 Sync Impact Report 也会记录新增了第三条原则，没有删除或重新定义原来的原则。

这样，人工审核就不再是某一份 SPEC 里的临时补丁。后续无论修改哪个功能，Agent 都必须先检查这三条原则。第一版没有想全并不可怕，宪章本来就可以随项目认识的变化而修订。真正需要避免的是，项目已经发现一条跨功能、长期有效的边界，却只把它留在聊天记录或某一份功能 SPEC 中，以至下一次开发时又从头讨论，甚至在不知情的情况下直接违反它。

5.9 ■ 学点英语