Spec Kit 中 /speckit.constitution 命令深度解析：项目宪章的创建、版本化治理与同步机制-二趣网

Spec Kit 中 /speckit.constitution 命令深度解析：项目宪章的创建、版本化治理与同步机制

【免费下载链接】spec-kit💫 Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit

本文围绕 Spec Kit 的templates/commands/constitution.md命令模板展开，完整拆解/speckit.constitution命令的输入约定、范围守卫、扩展钩子检查、模板解析、语义化版本规则与同步影响报告等全流程机制。读完后，你将理解项目"宪法"文件（.specify/memory/constitution.md）是如何被规范化生成与演进的，并能结合源码级证据（模板解析脚本、constitution-sync 预设）在实际项目中正确配置和排查该命令的行为。

1. 命令定位：SDD 流程的"地基"

在 Spec Kit 的规格驱动开发（Spec-Driven Development，SDD）流程中，/speckit.constitution是整个工作流的起点：它创建或更新项目的宪法（constitution）——一组后续每个阶段（specify、plan、tasks、implement 等）都会对照评估的指导原则。完整的命令序列为：

/speckit.constitution -> /speckit.specify -> /speckit.clarify -> /speckit.plan -> /speckit.checklist -> /speckit.tasks -> /speckit.analyze -> /speckit.implement -> /speckit.converge

见 docs/reference/agentic-sdd.md。该命令通常在项目开始时运行一次，之后每当原则发生变化时再更新。典型用法是把原则直接作为参数传入，例如 docs/quickstart.md 中的示例：

/speckit.constitution Taskify is a "Security-First" application. All user inputs must be validated. We use a microservices architecture. Code must be fully documented.

需要注意的调用形式差异：命令统一写作/speckit.*形式，但具体调用取决于所用 Agent——部分 skills 型 Agent 使用$speckit-*（如 Codex、ZCode）或/skill:speckit-*（如 Kimi），步骤本身不变。

2. 命令文件结构与 frontmatter 解析

命令的完整指令定义在 templates/commands/constitution.md。其 YAML frontmatter 声明了命令的元信息：

--- description: Create or update the project constitution from interactive or provided principle inputs. handoffs: - label: Build Specification agent: speckit.specify prompt: Implement the feature specification based on the updated constitution. I want to build... scripts: sh: scripts/bash/resolve-template.sh constitution-template --json ps: scripts/powershell/resolve-template.ps1 constitution-template -Json py: scripts/python/resolve_template.py constitution-template --json ---

各字段的作用：

description：命令的一句话说明，用于 Agent 命令目录展示；
handoffs：完成后向speckit.specify的交接（handoff）定义——宪法更新完毕后，Agent 会提示"基于更新后的宪法构建功能规格"，形成/speckit.constitution → /speckit.specify的自然衔接；
scripts：模板解析脚本的三种语言变体（Bash / PowerShell / Python），安装时会根据specify init时选择的--script sh|ps|py将{SCRIPT}占位符替换为对应的一条命令。

正文中还使用了一个用户输入占位符$ARGUMENTS——命令启动时，用户传入的原则文本会注入到该位置，且指令明确要求 Agent "必须先考虑用户输入（若非空）再继续"。

另外，正文中的__SPECKIT_COMMAND_SPECIFY__这类双下划线占位符是安装期替换的跨命令引用（在仓库中可搜索到大量同类用法，如 extensions/assess/commands/speckit.assess.decide.md），保证命令间相互引用时名称随 Agent 形态（点号/连字符/skills）正确适配。

3. Scope Guard：范围守卫

命令正文的 "Scope Guard" 一节是本命令最独特的约束，它把命令的工作范围严格限定在"更新宪法本身"：

每一部分用户输入都要被分类为宪法内容或独立的非治理意图；
若输入中包含功能实现、代码生成、重构、构建或部署请求，严禁执行，只能提取为"延迟意图（deferred intents）"；
不得创建、修改或删除应用源码、路由、组件、测试、部署文件等与宪法流程无关的产物；
无法判断某指令是否属于宪法内容时，先向用户澄清再动手；
宪法更新完成后，为每个延迟意图输出Next Actions小节，列出原意图并建议合适的后续 Spec Kit 命令（如/speckit.specify），但不实际调用。

这一设计确保了宪法命令的"单点写入"性质：整个命令流程中唯一被写入的文件是.specify/memory/constitution.md，正文结尾也再次强调"只写.specify/memory/constitution.md；不得创建或修改模板源文件"。

4. 前置检查：扩展钩子（before_constitution）

在更新宪法之前，命令要求检查项目根目录的.specify/extensions.yml：

若文件存在，读取hooks.before_constitution键下的条目；YAML 无法解析时静默跳过钩子检查并继续正常流程；
过滤掉enabled: false的钩子；未声明enabled字段的钩子默认视为启用；
不解释、不评估钩子的condition表达式：无condition（或为空）的钩子视为可执行；定义了非空condition的钩子跳过，把条件求值留给 HookExecutor 实现；
对每个可执行钩子，按optional标志输出不同块：
- 可选钩子（optional: true）：输出**Optional Pre-Hook**: {extension}块，给出/{command}、描述和Prompt，由用户决定是否执行；
- 强制钩子（optional: false）：输出**Automatic Pre-Hook**: {extension}块并附带EXECUTE_COMMAND: {command}，且必须真正调用该钩子并等待其完成后才能进入大纲（Outline）阶段。指令特别强调："仅输出块并不等于运行了钩子"——调用方式可能与字面{command}id 不同（例如 skills 模式 Agent 会以/skill:speckit-...或$speckit-...形式执行）。

5. 核心执行流程（Outline 七步法）

宪法文件位于.specify/memory/constitution.md。当前生效的宪法骨架（scaffold）在命令执行时通过模板解析栈从constitution-template动态解析而来。完整流程共七步：

5.1 解析模板（第 1 步）

从仓库根目录运行{SCRIPT}（即 frontmatter 中的解析脚本）并将TEMPLATE_CONTENT解析为当前生效模板：

共享解析器按"项目覆盖 → 预设层 → 扩展层 → 核心模板兜底"的顺序组合（composing）各层；该步骤必须成功才能继续；
失败时停止并报告解析错误，不得只依赖单一模板层继续；
若.specify/memory/constitution.md已存在，加载它作为当前项目特定值与修订记录的来源，应用新解析骨架时保留仍然适用的信息；
若不存在，则以解析出的模板作为初始文档；
不得写回任何版本化的模板层；
识别所有[ALL_CAPS_IDENTIFIER]形式的占位符 token。指令同时提示：用户要求的原则数量可能多于或少于模板中的 5 条——若用户指定了数量，应遵循该数量并相应调整文档结构。

5.2 收集与推导占位符值（第 2 步）

用户输入（对话）提供了值则优先使用；
否则从既有仓库上下文推断（README、docs、内嵌的宪法历史版本）；
治理日期规则：RATIFICATION_DATE是最初通过日期（未知时询问或标记 TODO）；LAST_AMENDED_DATE在有变更时取今天，否则保持原值；
CONSTITUTION_VERSION必须按语义化版本规则递增：
- MAJOR：不向后兼容的治理/原则删除或重新定义；
- MINOR：新增原则/章节，或对指导做了实质性扩充；
- PATCH：澄清、措辞修正、错别字、非语义性润色；
- 版本号升级类型有歧义时，先给出推理再定稿。

5.3 起草更新后的宪法（第 3 步）

以解析出的模板为强制结构起草内容：

每个占位符替换为具体文本——不得残留方括号 token（项目刻意保留、暂不定义的模板槽位除外，但必须明确说明保留理由）；
保持标题层级与模板一致；注释在被替换后可以删除，除非仍有澄清价值；
每个原则（Principle）章节须包含：简洁的标题行、记录"不可协商规则"的段落（或要点列表）、非显而易见的理由说明；
Governance 章节必须列出修订程序、版本策略与合规评审预期。

5.4 同步影响报告（第 4 步）

更新后，在宪法文件顶部以HTML 注释形式前置一份 Sync Impact Report，内容包括：

版本变化：旧版本 → 新版本；
修改的原则列表（重命名时写"旧标题 → 新标题"）；
新增章节；
删除章节；
有意推迟的占位符对应的后续 TODO。

5.5 最终校验（第 5 步）

无未解释的方括号 token 残留；
版本行与报告一致；
日期为 ISO 格式YYYY-MM-DD；
原则须是陈述式、可测试的，避免模糊措辞（例如把 "should" 替换为带理由的 MUST/SHOULD）。

5.6 写回与最终总结（第 6、7 步）

覆盖写回.specify/memory/constitution.md，然后向用户输出最终总结：

新版本号与升级理由；
需要人工跟进的 TODO 占位符或延迟项；
建议的 commit message，例如docs: amend constitution to vX.Y.Z (principle additions + governance update)；
针对任何延迟的非治理意图的Next Actions小节。

此外还有格式与风格要求：标题级别严格沿用模板（不得升降级）；长理由行控制在 100 字符内以保持可读性（但不做僵硬换行）；章节之间保持单一空行；避免行尾空白。用户只提交部分更新（如仅修改一条原则）时，校验与版本决策步骤仍须完整执行；关键信息确实缺失（如无法确认通过日期）时，插入TODO(<FIELD_NAME>): explanation并计入 Sync Impact Report 的延迟项。

6. 后置检查：after_constitution 钩子

宪法写入完成后执行对称的钩子检查：读取.specify/extensions.yml中hooks.after_constitution下的条目，过滤与condition处理规则与前置检查完全一致，按optional标志输出**Optional Hook**或**Automatic Hook**块，强制钩子同样必须实际执行并等待完成。

7. 源码级佐证：模板解析脚本与骨架结构

{SCRIPT}在 Bash 场景下指向 scripts/bash/resolve-template.sh。从源码结构看，其核心逻辑为：解析参数（<template-name> [--json]）→ 通过get_repo_root定位项目根 → 调用resolve_template_content从模板覆盖栈中解析内容 →--json模式时输出{"TEMPLATE_NAME": ..., "TEMPLATE_CONTENT": ...}（有jq则用jq -cn，否则回退到手写 JSON 转义），否则直接输出纯文本；解析失败时向 stderr 报错并以退出码 1 终止——这正对应命令中"解析失败必须停止"的硬约束。Python 版本 scripts/python/resolve_template.py 逻辑等价：同样以TEMPLATE_NAME/TEMPLATE_CONTENT两个键输出 JSON，异常时打印ERROR: Could not resolve required constitution-template from the template override stack并返回 1。

命令所解析的模板源文件是 templates/constitution-template.md，其骨架为：

一级标题[PROJECT_NAME] Constitution；
Core Principles：[PRINCIPLE_1_NAME]至[PRINCIPLE_5_NAME]共 5 个原则槽位，每个配[PRINCIPLE_N_DESCRIPTION]与 HTML 注释示例（如 "I. Library-First"、"III. Test-First (NON-NEGOTIABLE)"）；
两个自由扩展章节[SECTION_2_NAME]/[SECTION_3_NAME]（可放安全要求、性能标准、开发流程等）；
Governance章节与[GOVERNANCE_RULES]；
尾部的元信息行：**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]。

模板内示例值Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16直观演示了第 5.5 节校验要求的 ISO 日期格式。这也解释了为什么命令要求"保留标题层级"——解析结果的结构就是后续所有命令读取宪法时预期的结构。

8. 可选扩展：constitution-sync 预设

默认模型下，/speckit.constitution严格遵守 Scope Guard，只写宪法文件，依赖的模板与命令在运行时读取宪法、不被修改。若团队希望把修订后的原则**物化（materialize）**传播到plan-template.md、spec-template.md、tasks-template.md及项目本地的命令文件，可安装 opt-in 预设 presets/constitution-sync：

# constitution-sync 是内置预设 —— 无需下载 specify preset add constitution-sync

该预设通过wrap策略在核心命令之上叠加一个 "Constitution Template Sync" 小节（见 presets/constitution-sync/commands/speckit.constitution.md）：写入宪法后执行一致性传播——对齐三个模板中的 Constitution Check 与原则相关规则、刷新项目本地命令文件中的过时引用、并把触碰过的文件追加到 Sync Impact Report 中。安装期还会启用受保护的宪法调和（reconciliation）：仅当.specify/memory/constitution.md的内容与其记录的生成哈希一致（即无人手改过）时才允许重新物化。

预设文档明确给出了取舍警告（可作选型依据）：

物化副本可能漂移：修订宪法后若不重跑/constitution，副本就与活文件失步；默认运行时解析模型则每次运行都读活文件，天然无漂移；
组合文件的编辑活不过调和：specify integration use/switch、specify integration upgrade或任何预设/扩展的增删都会重算组合产物，物化进这些文件的指导会被覆盖——因此该预设只写项目自有.specify/templates/脚手架与不受预设/扩展管理的命令文件；
预填的 Constitution Check 可能锚定/plan：把具体门禁文本固化进plan-template.md会替换运行时指针，首轮/plan可能锚在冻结文本上。

若日后想回到默认运行时解析模型，需将.specify/templates/plan-template.md中的## Constitution Check节重置为指针[Gates determined based on constitution file]后再移除预设（详见预设 README 的 "Migrating back to the default" 一节）。

9. 实操要点小结

首次使用：specify init完成初始化后，先运行/speckit.constitution并传入原则文本，让 Agent 生成.specify/memory/constitution.md，再进入/speckit.specify；
原则数量灵活：模板默认 5 条，但按用户指定的数量增删原则，并遵循 MAJOR/MINOR/PATCH 规则递增版本；
只写一个文件：无论输入多么"顺带"，命令绝不触碰源码；非治理意图会被整理进Next Actions供后续命令处理；
钩子故障隔离：.specify/extensions.yml损坏或 YAML 非法时钩子检查静默跳过，不阻塞宪法更新——这是刻意的容错设计；
排查模板问题：若命令报"Could not resolve required constitution-template"，说明模板解析栈中缺少constitution-template贡献层，可参照 scripts/python/resolve_template.py 的报错路径检查项目覆盖、预设与扩展各层配置；
组织级治理：多仓库统一原则的场景下，官方文档建议优先考虑由核心团队维护的版本化预设（runtime resolution 作为单一事实源），而非 constitution-sync 的物化路径。

参考文档：Agentic SDD 命令参考、Quick Start Guide、constitution-sync 预设、核心命令参考。

【免费下载链接】spec-kit💫 Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析