`/speckit.constitution` 命令学习笔记

主题: speckit-constitution 命令详解
创建日期: 2026-05-05
最后更新日期: 2026-05-05
关联 spec-kit 版本: 0.8.5.dev0
SKILL 路径: .trae/skills/speckit-constitution/SKILL.md
关联文件: .specify/memory/constitution.md、.specify/templates/constitution-template.md

学习目标

完成本篇笔记后，你将能够：

1. 准确描述 /speckit.constitution 命令的核心职责和产出
2. 列举至少两种典型使用场景
3. 按正确顺序描述命令的完整执行流程（至少 5 个关键步骤）
4. 判断不同宪法变更场景对应的版本号递增类型（MAJOR/MINOR/PATCH）
5. 在自己项目中独立执行命令并验证产出

命令概述

是什么

/speckit.constitution 是 GitHub spec-kit 工作流中的核心命令之一，负责创建或更新项目的"宪法"文件（位于 .specify/memory/constitution.md）。

做什么

• 从宪法模板（.specify/templates/constitution-template.md）初始化项目宪法
• 根据用户描述自动填充占位符为具体内容
• 管理宪法版本号的语义化递增
• 校验并同步依赖模板文件的一致性
• 生成变更报告（Sync Impact Report）

产出什么

触发方式

基本命令格式

/speckit.constitution [用户描述]

参数说明

示例

# 首次初始化（无描述，使用默认模板）
/speckit.constitution

# 带描述初始化
/speckit.constitution 本项目是一个学习 jquery 的项目，产出是 jquery demo 代码

# 修改某原则
/speckit.constitution 将原则II改为代码优先

# 新增原则
/speckit.constitution 新增一条关于代码审查的原则

# 更新治理规则
/speckit.constitution 修改版本策略为双周发布

使用场景

执行流程详解

命令从触发到完成共经历以下 8 个步骤：

步骤 1：加载现有宪法

读取 .specify/memory/constitution.md。如果文件不存在，则从 .specify/templates/constitution-template.md 复制模板。

步骤 2：识别占位符

扫描宪法文件中的所有 [ALL_CAPS_IDENTIFIER] 格式占位符，例如：

• [PROJECT_NAME]
• [PRINCIPLE_1_NAME] / [PRINCIPLE_1_DESCRIPTION]
• [CONSTITUTION_VERSION]
• [RATIFICATION_DATE]
• [LAST_AMENDED_DATE]

步骤 3：收集/推导占位符值

• 如果用户对话中提供了值 → 直接使用
• 否则从项目上下文推断（README、已有文档等）
• 对于无法推断的值 → 使用 TODO(FIELD_NAME): explanation 标记
• 批准日期（RATIFICATION_DATE）：首次创建时为今天，未知时标记 TODO

步骤 4：决定版本号递增类型

根据变更内容判断版本递增规则（详见下方「版本递增规则」章节）：

步骤 5：生成宪法内容

• 替换所有占位符为具体值
• 保留标题层级结构
• 移除模板注释（除非仍有指导意义）
• 确保每个原则包含：简洁名称、具体规则描述、非模糊措辞（使用 MUST/SHOULD）

步骤 6：一致性传播检查

校验以下模板是否与更新后的宪法保持一致：

• .specify/templates/plan-template.md — "Constitution Check" 部分
• .specify/templates/spec-template.md — 范围/需求对齐
• .specify/templates/tasks-template.md — 任务分类是否反映新原则
• .specify/templates/commands/*.md — 命令引用是否过时

步骤 7：写入宪法文件

将完整的宪法内容写回 .specify/memory/constitution.md（覆盖写入），并在文件顶部注入 Sync Impact Report（HTML 注释格式）。

步骤 8：输出摘要

向用户报告：

• 新版本号及递增原因
• 需要手动跟进的文件
• 建议的 commit message

核心概念解析

宪法模板 (Constitution Template)

位于 .specify/templates/constitution-template.md，是宪法文件的初始骨架。包含以下占位区域：

# [PROJECT_NAME] Constitution

## Core Principles
### [PRINCIPLE_1_NAME]
[PRINCIPLE_1_DESCRIPTION]

### [PRINCIPLE_2_NAME]
[PRINCIPLE_2_DESCRIPTION]

...

## Governance
[GOVERNANCE_RULES]

**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]

占位符推断规则

AI 在填充占位符时遵循以下策略：

1. 用户优先：用户在命令描述中明确提供的值优先使用
2. 上下文推断：从 README、已有文件、项目结构中推断
3. 合理默认：对日期使用当天，对版本号首次使用 1.0.0
4. 降级处理：无法推断时使用 TODO(FIELD_NAME): explanation 并在变更报告中记录

TODO 降级策略

当某些占位符确实无法推断时：

• 保留 TODO(FIELD_NAME): 原因说明 格式
• 在 Sync Impact Report 的"Deferred Items"中列出
• 用户后续可再次运行命令补充

宪法文件结构

一份完整的宪法文件包含以下部分：

# [项目名称] 宪法

## 核心原则

### I. [原则1名称]
   [原则1描述 — 明确、可测试的规则]

### II. [原则2名称]
   [原则2描述]

### III. [原则3名称]
   [原则3描述]

### ...（更多原则）

## [附加约束章节]
   [如：文档组织约束、安全要求、性能标准等]

## [开发流程/质量门槛章节]
   [如：审查流程、测试门槛、发布审批等]

## 治理
   [治理规则、版本策略、修订流程]

**Version**: X.Y.Z | **Ratified**: YYYY-MM-DD | **Last Amended**: YYYY-MM-DD

标题层级规范

版本递增规则

宪法版本号采用语义化版本格式 MAJOR.MINOR.PATCH。

版本递增示例

Sync Impact Report

每次宪法更新时，命令会在文件顶部自动生成一份变更报告（HTML 注释格式）。

格式

<!--
Sync Impact Report
==================
Version change: 1.0.0 → 1.1.0

Modified principles:
- [PRINCIPLE_2_NAME]: "II. Code-First" → "II. Documentation-First"

Added sections:
- "VI. Security Requirements"

Removed sections:
- (none)

Templates requiring updates:
- plan-template.md: ✅ updated
- spec-template.md: ✅ updated
- tasks-template.md: ⚠ pending

Follow-up TODOs:
- TODO(RATIFICATION_DATE): 首次批准日期待确认
-->

内容组成

实际操作示例

场景：首次为本项目初始化宪法

步骤 1：在 Trae IDE 聊天框中执行命令

/speckit.constitution 本项目是一个学习 github spec-kit 的"项目"。项目的产出并非代码，而是学习笔记（markdown）文档

步骤 2：命令自动完成以下操作

1. 检查 .specify/memory/constitution.md 是否存在
2. 如不存在，从 .specify/templates/constitution-template.md 复制模板
3. 识别所有占位符：[PROJECT_NAME]、[PRINCIPLE_1_NAME] 等
4. 根据用户描述推导值：
   • PROJECT_NAME → "Spec-Kit 学习笔记项目"
   • 5 条核心原则（根据"学习笔记"上下文生成）
   • 版本号 → 1.0.0（首次）
   • 日期 → 当天（2026-05-05）
5. 生成宪法内容
6. 校验模板一致性
7. 写回 .specify/memory/constitution.md
8. 输出版本摘要

步骤 3：查看产出

打开 .specify/memory/constitution.md，你将看到：

• 宪法名称："Spec-Kit 学习笔记项目宪法"
• 5 条核心原则（结构化学习路径、Markdown 优先、实践驱动等）
• 文档组织约束
• 质量要求
• 治理规则
• 版本行：**Version**: 1.0.0 | **Ratified**: 2026-05-05 | **Last Amended**: 2026-05-05

场景：更新宪法（新增原则）

步骤 1：执行命令

/speckit.constitution 新增一条关于代码审查的原则：所有学习笔记在归档前需经过同行审查

步骤 2：命令自动完成

1. 读取现有宪法（版本 1.0.0）
2. 识别变更类型为 MINOR（新增原则）
3. 在核心原则末尾添加新原则
4. 版本号递增为 1.1.0
5. 更新 Last Amended 日期
6. 生成 Sync Impact Report
7. 写回文件

边界情况与注意事项

宪法模板不存在

行为：命令会尝试从 .specify/templates/constitution-template.md 复制模板。如果模板也不存在，命令将报错并提示用户先运行项目初始化。

解决：确保 .specify/ 目录已正确初始化，模板文件存在。

宪法文件已存在且仅提供部分更新

行为：命令仅更新用户描述中涉及的部分，其余内容保持不变。版本号根据实际变更类型递增。

注意：部分更新仍需执行完整的校验流程。

占位符无法推断

行为：使用 TODO(FIELD_NAME): 原因说明 格式保留占位符，并在 Sync Impact Report 中记录为待办事项。

解决：用户可再次运行命令，提供缺失信息。

模板依赖文件损坏或缺失

行为：一致性传播检查会跳过无法读取的文件，并在 Sync Impact Report 中标记为 ⚠ pending。

解决：手动检查并修复缺失的模板文件。

其他注意事项

• 宪法文件的标题层级不可随意修改，必须保持 H1 → H2 → H3 的层级
• 原则描述应避免模糊措辞（"应该" → 替换为"必须 MUST"或"建议 SHOULD"并附理由）
• 日期必须使用 ISO 8601 格式（YYYY-MM-DD）
• 版本号行格式固定，不可更改

关键要点总结

• /speckit.constitution 负责创建和更新项目宪法文件
• 宪法是 spec-kit 工作流的"最高准则"，定义核心原则、约束和治理规则
• 命令执行流程：加载模板 → 识别占位符 → 推导值 → 决定版本递增 → 生成内容 → 一致性检查 → 写回文件 → 输出摘要
• 版本号采用语义化格式：MAJOR（不兼容变更）、MINOR（新增内容）、PATCH（文字修订）
• 每次更新自动生成 Sync Impact Report（HTML 注释格式）
• 无法推断的占位符使用 TODO(FIELD_NAME): 原因 降级处理
• 宪法文件位于 .specify/memory/constitution.md，模板位于 .specify/templates/constitution-template.md

参考链接