constitution

概述

Constitution 技能通过两份共享文档管理项目的架构基因：

文件	用途
docs/specs/architecture.md	技术栈、基础设施、架构规则、安全约束、AI 防护措施
docs/specs/ontology.md	领域术语表（统一语言）——术语、定义、限界上下文

这些文件位于 docs/specs/，供所有规范共享。与单体的 constitution.md 不同，这些文件由 brainstorm（阶段 6.8.6）和 spec-to-tasks（阶段 1.5）创建/充实。

说明

1. 根据 $ARGUMENTS 或用户意图确定操作：create、update、check 或 show。
2. 对于 create：询问要创建哪些文件（architecture.md、ontology.md 或两者），通过 AskUserQuestion 收集所需信息，然后使用下方模板编写文件。
3. 对于 update：确定目标文件和章节，有针对性地应用更改，并更新 Last Updated 日期。
4. 对于 check：读取两份 constitution 文件，读取目标文件，根据架构规则和本体术语进行验证，并输出 Constitution 检查报告。
5. 对于 show：读取并以易读的格式显示两份文件。
6. 写入或覆盖文件前，始终向用户确认。

示例

# Create constitution before first brainstorm
/developer-kit-specs:constitution create

# Validate a spec against architecture and ontology
/developer-kit-specs:constitution check --target=docs/specs/001/2024-01-15--user-auth.md

# Update the security constraints section
/developer-kit-specs:constitution update --file=architecture --section=security

# Show current constitution
/developer-kit-specs:constitution show

使用场景

场景	操作
新项目——在首次 brainstorm 前定义技术栈和领域语言	create
技术栈或安全规则发生变化	update
根据架构和本体验证规范、任务或文件	check
查看当前架构和本体	show

触发短语：

• “创建 constitution”、“设置项目架构”、“定义本体”
• “更新 constitution”、“更新架构”、“更新本体”
• “constitution 检查”、“根据 constitution 验证”
• “显示 constitution”、“项目原则”、“架构防护措施”

操作

create

1. 询问要创建哪些文件：“Both”（推荐）、“仅 architecture.md”、“仅 ontology.md”
2. 检查文件是否存在 → 询问要覆盖还是跳过
3. 对于 architecture.md：通过 AskUserQuestion 收集信息（领域、基础设施、技术栈、数据、风格、规则）
4. 对于 ontology.md：询问术语，或创建空白框架
5. 写入每个文件前进行确认

模板查找顺序：

• 首选：${CLAUDE_PLUGIN_ROOT}/templates/architecture.md
• 备用：skills/constitution/references/architecture.md

update

1. 解析 --file=architecture|ontology 和 --section=<name>
2. 读取目标文件，有针对性地应用更改
3. 更新 Last Updated 日期
4. 写入文件

check

1. 读取两份 constitution 文件
2. 读取目标文件（--target=<path>）
3. 根据架构规则、安全约束和本体进行验证
4. 输出 Constitution 检查报告

show

1. 读取 docs/specs/architecture.md 和 docs/specs/ontology.md
2. 以易读的格式显示

防止上下文腐化

Constitution 通过基于文件的存储方式避免上下文腐化：

• 在会话开始时读取：docs/specs/architecture.md 和 docs/specs/ontology.md
• 切勿假设内容已在上下文中：实施前 MUST 从文件读取
• 验证工作：对照 constitution 验证，而非依靠记忆

详细场景和恢复流程请参阅 references/context-rot-prevention.md。

约束和警告

• 不会修改源代码——只创建/更新 constitution 文件
• 必须解决 CRITICAL 违规项——WARNING 仅供参考
• 每个项目仅有一份 architecture.md 和一份 ontology.md——供所有规范共享
• 每次更改都要更新 Last Updated 日期
• 重大架构决策应使用 ADR
• 上下文腐化风险：超过 30 天的文件可能已发生偏移

最佳实践

• 先创建再头脑风暴：尽早确立 Constitution，确保一致性
• 库验证：使用任何外部库之前，务必确认它已列入架构的库验证部分
• 规范失效原则：将已完成的规范归档到 archived/——绝不让规范过时
• 本体丰富：由 brainstorm（阶段 6.8.6）和 spec-to-tasks（阶段 1.5）更新
• 报告格式：先写安全部分，然后是 CWE 合规性、架构、库验证和本体

Constitution 检查报告格式

## Constitution Check Report
Target: <file path>
Date: YYYY-MM-DD

### Security Check (CWE/OWASP Compliance)
| Rule | Level | Status | Location | CWE/OWASP |
|------|-------|--------|----------|-----------|
| No SQL injection | CRITICAL | ✅ OK | - | CWE-89 |

### CWE Compliance Report
| CWE | OWASP | Status | Location |
|-----|-------|--------|----------|
| CWE-89 | A03 | ✅ OK | - |

### Architecture Check
| Rule | Status | Detail |
|------|--------|--------|
| Constructor injection | ✅ OK | - |

### Library Verification Check
| Library | Status | Detail |
|---------|--------|--------|
| bcrypt | ✅ OK | Using hash(password, 12) |

### Ontology Check
| Term | Status | Detail |
|------|--------|--------|
| "User" used consistently | ✅ OK | - |

### Summary
- CRITICAL violations: 0
- WARNING violations: 0
- Compliant rules: N

有关详细的安全模式（CWE/OWASP 映射），请参阅 references/security-patterns.md。

与 SDD 工作流集成

[Session Start] → Read Constitution files
        ↓
[Optional] constitution create        ← this skill (pre-brainstorm setup)
        ↓
brainstorm                            ← Constitution loaded before brainstorming
        ↓
spec-to-tasks                         ← Constitution validates spec
        ↓
task-implementation                   ← Constitution guardrails active
        ↓
task-review                           ← Constitution check validates
        ↓
[Session End] → Constitution files updated if needed

必须在以下操作之前加载：

• specs.brainstorm——验证需求是否符合架构
• specs.spec-to-tasks——检查技术栈兼容性
• specs.task-implementation——应用 AI 防护措施
• specs.task-review——检查 Constitution

参考文件

文件	用途
references/architecture.md	完整架构模板
references/ontology.md	完整本体模板
references/security-patterns.md	CWE/OWASP 模式、验证格式
references/context-rot-prevention.md	详细场景和恢复流程
references/constitution-check-report.md	完整报告示例

如需完整模板和详细参考资料，请查阅 references/ 目录。