Back to Details

constitution

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Instructions

操作说明

  1. Identify the operation from 
    $ARGUMENTS
    or user intent: 
    create
    , 
    update
    , 
    check
    , or 
    show
    .
  2. For create: ask which files to create (architecture.md, ontology.md, or both), gather required information via 
    AskUserQuestion
    , then write the files using the templates below.
  3. For update: identify the target file and section, apply the change surgically, update the 
    Last Updated
    date.
  4. For check: read both constitution files, read the target file, validate against architectural rules and ontology terms, output a Constitution Check Report.
  5. For show: read and display both files formatted for readability.
  6. Always confirm with the user before writing or overwriting files.
  1. 从
    $ARGUMENTS
    或用户意图中识别操作类型：
    create
    （创建）、
    update
    （更新）、
    check
    （检查）或
    show
    （展示）。
  2. 若为create：询问要创建哪些文件（architecture.md、ontology.md或两者都创建），通过
    AskUserQuestion
    收集必要信息，然后使用下方模板生成文件。
  3. 若为update：确定目标文件和章节，精准应用更改，更新
    Last Updated
    日期。
  4. 若为check：读取两份架构文档，读取目标文件，验证其是否符合架构规则和Ontology术语，输出架构合规检查报告（Constitution Check Report）。
  5. 若为show：读取两份文件并以易读格式展示。
  6. 在写入或覆盖文件前，务必先与用户确认。

Examples

示例

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
首次头脑风暴前创建架构文档：
/developer-kit-specs:constitution create
验证规格说明是否符合架构和Ontology：
/developer-kit-specs:constitution check --target=docs/specs/001/2024-01-15--user-auth.md
更新安全约束章节：
/developer-kit-specs:constitution update --file=architecture --section=security
展示当前架构文档：
/developer-kit-specs:constitution show

Constitution Skill

Constitution Skill

Overview

概述

The Constitution is the architectural DNA of a project, expressed through two shared documents:
FilePurpose
docs/specs/architecture.md
Technology stack, infrastructure choices, architectural rules, security constraints, AI guardrails
docs/specs/ontology.md
Domain glossary (Ubiquitous Language) — terms, definitions, bounded contexts
These files live at the 
docs/specs/
level and are shared across all specifications.
Key difference from the old constitution.md approach: instead of a single monolithic file, the constitution is split into two focused documents that are also created and enriched by 
brainstorm
(Phase 6.8.6) and 
spec-to-tasks
(Phase 1.5). This skill lets you create or manage them before brainstorm, as a project setup step.
Constitution是项目的架构DNA，通过两份共享文档体现：
文件用途
docs/specs/architecture.md
技术栈、基础设施选择、架构规则、安全约束、AI guardrails
docs/specs/ontology.md
领域术语表（Ubiquitous Language）——术语、定义、限界上下文
这些文件位于
docs/specs/
目录下，所有规格说明共享使用。
与旧版constitution.md方式的主要区别：不再是单一的庞大文件，架构文档被拆分为两份聚焦的文档，且可通过
brainstorm
（第6.8.6阶段）和
spec-to-tasks
（第1.5阶段）进行创建和补充。本技能允许你在头脑风暴前作为项目设置步骤创建或管理这些文档。

When to Use

使用场景

ScenarioOperation
New project — define stack and domain language before first brainstorm
create
Stack or security rules changed
update
Validate a spec, task, or file against architecture and ontology
check
Review current architecture and ontology
show
Trigger phrases:
  • "Create constitution", "Setup project architecture", "Define ontology"
  • "Update constitution", "Update architecture", "Update ontology"
  • "Constitution check", "Validate against constitution"
  • "Show constitution", "Project principles", "Architectural guardrails"
场景操作
新项目——在首次头脑风暴前定义技术栈和领域语言
create
技术栈或安全规则变更
update
验证规格说明、任务或文件是否符合架构和Ontology
check
查看当前架构和Ontology
show
触发短语：
  • "Create constitution"、"Setup project architecture"、"Define ontology"
  • "Update constitution"、"Update architecture"、"Update ontology"
  • "Constitution check"、"Validate against constitution"
  • "Show constitution"、"Project principles"、"Architectural guardrails"

Available Operations

可用操作

1. create — Create one or both files interactively 2. update — Update a specific section of one file 3. check — Validate a spec/task/file against both documents 4. show — Display the current state of both documents
1. create —— 交互式创建一个或两个文件 2. update —— 更新单个文件的特定章节 3. check —— 验证规格说明/任务/文件是否符合两份文档的要求 4. show —— 展示两份文档的当前状态

Operation: create

操作：create

  1. Ask the user which files to create (if not specified in 
    $ARGUMENTS
    ):
    • Options: "Both architecture.md and ontology.md" (recommended), "architecture.md only", "ontology.md only"
  2. For each file to create, check if it already exists. If yes, ask: overwrite or skip.
  3. For 
    docs/specs/architecture.md
    , gather via 
    AskUserQuestion
    :
    Q1 — Software Stack:
    • Options: "Java / Spring Boot", "TypeScript / NestJS", "TypeScript / React", "Python / Django or FastAPI", "PHP / Laravel or Symfony", or freeform
    Q2 — Data Architecture:
    • Options: "PostgreSQL", "MySQL", "MongoDB", "Multiple databases", or freeform
    Q3 — Infrastructure:
    • Options: "AWS", "Docker / Docker Compose", "Kubernetes", "Serverless", "Not yet decided", or freeform
    Q4 — Architectural Rules (optional, freeform):
    • Forbidden patterns, required patterns, security constraints, AI guardrails
    Then create 
    docs/specs/architecture.md
    using the Architecture Template below.
  4. For 
    docs/specs/ontology.md
    , gather via 
    AskUserQuestion
    :
    Ask the user to list the main domain terms and their definitions. Explain:
    "The ontology captures the Ubiquitous Language of your project. It is normally enriched during brainstorming when terms emerge from the idea. You can seed it now with known terms, or create an empty scaffold to fill later."
    • Options: "Seed with known terms (I'll provide them)", "Create empty scaffold", "Skip for now"
    Then create 
    docs/specs/ontology.md
    using the Ontology Template below.
  5. Confirm with the user before writing each file.
  1. 询问用户要创建哪些文件（若
    $ARGUMENTS
    中未指定）：
    • 选项："同时创建architecture.md和ontology.md"（推荐）、"仅创建architecture.md"、"仅创建ontology.md"
  2. 对于每个要创建的文件，检查是否已存在。若已存在，询问：覆盖还是跳过。
  3. 创建
    docs/specs/architecture.md
    时    ，通过
    AskUserQuestion
    收集以下信息：
    问题1 —— 软件栈：
    • 选项："Java / Spring Boot"、"TypeScript / NestJS"、"TypeScript / React"、"Python / Django 或 FastAPI"、"PHP / Laravel 或 Symfony"，或自定义输入
    问题2 —— 数据架构：
    • 选项："PostgreSQL"、"MySQL"、"MongoDB"、"多数据库"，或自定义输入
    问题3 —— 基础设施：
    • 选项："AWS"、"Docker / Docker Compose"、"Kubernetes"、"Serverless"、"尚未确定"，或自定义输入
    问题4 —— 架构规则（可选，自定义输入）：
    • 禁用模式、必填模式、安全约束、AI guardrails
    然后使用下方的架构模板创建
    docs/specs/architecture.md
    。
  4. 创建
    docs/specs/ontology.md
    时    ，通过
    AskUserQuestion
    收集以下信息：
    请用户列出主要领域术语及其定义，并说明：
    "Ontology记录了项目的Ubiquitous Language。通常在头脑风暴期间，随着想法中出现新术语时进行补充。你可以现在用已知术语初始化，或者创建一个空框架后续再填充。"
    • 选项："用已知术语初始化（我会提供）"、"创建空框架"、"暂时跳过"
    然后使用下方的Ontology模板创建
    docs/specs/ontology.md
    。
  5. 在写入每个文件前，与用户确认。

Operation: update

操作：update

  1. Identify the target file and section from 
    $ARGUMENTS
    : 
    • --file=architecture
      or 
      --file=ontology
    • --section=<section-name>
      (e.g., 
      --section=security
      , 
      --section=glossary
      )
  2. Read the target file.
  3. Apply the update surgically — do not touch other sections.
  4. Update the 
    Last Updated
    date.
  5. Write the updated file.
  1. 从
    $ARGUMENTS
    中确定目标文件和章节： 
    • --file=architecture
      或 
      --file=ontology
    • --section=<章节名称>
      （例如：
      --section=security
      、
      --section=glossary
      ）
  2. 读取目标文件。
  3. 精准应用更新——不要修改其他章节。
  4. 更新
    Last Updated
    日期。
  5. 写入更新后的文件。

Operation: check

操作：check

  1. Read both 
    docs/specs/architecture.md
    and 
    docs/specs/ontology.md
    . If either is missing, warn the user but continue with the available file(s).
  2. Read the target file from 
    $ARGUMENTS
    (
    --target=<path>
    ).
  3. Check against architecture.md:
    • Forbidden libraries/imports present?
    • Unapproved patterns used?
    • Security constraints violated (raw SQL, hardcoded secrets, etc.)?
    • AI guardrails violated?
  4. Check against ontology.md:
    • Are domain terms used consistently (no synonyms for defined terms)?
    • Are new domain concepts introduced without being added to the glossary?
  5. Output a Constitution Check Report (see format below).
  1. 读取
    docs/specs/architecture.md
    和
    docs/specs/ontology.md
    。若其中任一文件缺失，向用户发出警告，但继续使用可用文件进行检查。
  2. 从
    $ARGUMENTS
    中读取目标文件（
    --target=<路径>
    ）。
  3. 对照architecture.md检查：
    • 是否存在禁用的库/导入？
    • 是否使用了未批准的模式？
    • 是否违反安全约束（如原生SQL拼接、硬编码密钥等）？
    • 是否违反AI guardrails？
  4. 对照ontology.md检查：
    • 领域术语是否使用一致（已定义术语无同义词）？
    • 是否引入了未添加到术语表的新领域概念？
  5. 输出架构合规检查报告（格式见下方）。

Operation: show

操作：show

  1. Read 
    docs/specs/architecture.md
    and 
    docs/specs/ontology.md
    .
  2. Print both files formatted for readability, with a header indicating which file is which.
  1. 读取
    docs/specs/architecture.md
    和
    docs/specs/ontology.md
    。
  2. 以易读格式打印两份文件，每个文件前添加标题标识。

Architecture Template

架构模板

markdown
undefined
markdown
undefined

Project Architecture

项目架构

Created: YYYY-MM-DD Last Updated: YYYY-MM-DD
创建时间：YYYY-MM-DD 最后更新：YYYY-MM-DD

Software Stack

软件栈

ComponentTechnologyNotes
Language[e.g., TypeScript][version if known]
Framework[e.g., NestJS][version if known]
Key Libraries[e.g., Drizzle ORM, Passport]
组件技术备注
编程语言[例如：TypeScript][已知版本]
框架[例如：NestJS][已知版本]
核心库[例如：Drizzle ORM、Passport]

Data Architecture

数据架构

ComponentTechnologyNotes
Primary Database[e.g., PostgreSQL]
Caching[e.g., Redis, none]
ORM / Data Access[e.g., Drizzle, Hibernate]
Migrations[e.g., Flyway, Drizzle Kit]
组件技术备注
主数据库[例如：PostgreSQL]
缓存[例如：Redis、无]
ORM / 数据访问[例如：Drizzle、Hibernate]
迁移工具[例如：Flyway、Drizzle Kit]

Infrastructure

基础设施

ComponentTechnologyNotes
Hosting[e.g., AWS ECS]
CI/CD[e.g., GitHub Actions]
Containerization[e.g., Docker]
Orchestration[e.g., Kubernetes, none]
组件技术备注
托管服务[例如：AWS ECS]
CI/CD[例如：GitHub Actions]
容器化[例如：Docker]
编排工具[例如：Kubernetes、无]

Architectural Rules

架构规则

  • [Rule 1, e.g., "Use constructor injection. Never use @Autowired on fields."]
  • [Rule 2, e.g., "Domain entities must not depend on framework annotations."]
  • [规则1，例如："使用构造函数注入。禁止在字段上使用@Autowired。"]
  • [规则2，例如："领域实体不得依赖框架注解。"]

Security Constraints

安全约束

  • Forbidden patterns:
    • No raw SQL string concatenation (SQL injection — CWE-89)
    • No hardcoded secrets or credentials (CWE-798)
    • No deserialization of untrusted data (CWE-502)
  • Required patterns:
    • [e.g., All inputs validated with Bean Validation]
    • [e.g., All secrets via environment variables or Secrets Manager]
  • 禁用模式：
    • 禁止原生SQL字符串拼接（SQL注入——CWE-89）
    • 禁止硬编码密钥或凭证（CWE-798）
    • 禁止反序列化不可信数据（CWE-502）
  • 必填模式：
    • [例如：所有输入需通过Bean Validation验证]
    • [例如：所有密钥通过环境变量或Secrets Manager管理]

AI Guardrails

AI Guardrails

Rules that AI agents MUST follow when generating code for this project:
  • [Guardrail 1, e.g., "Never generate @Transactional on repository methods."]
  • [Guardrail 2, e.g., "Always generate tests alongside implementation code."]
  • [Guardrail 3, e.g., "Do not introduce new dependencies without explicit approval."]
AI Agent为该项目生成代码时必须遵循的规则：
  • [规则1，例如："禁止在仓库方法上生成@Transactional。"]
  • [规则2，例如："生成实现代码时必须同时生成测试代码。"]
  • [规则3，例如："未经明确批准不得引入新依赖。"]

Architecture Decisions

架构决策记录

Significant modifications to this architecture document must be tracked via ADR (Architecture Decision Records) using the 
adr-drafting
skill.
ADR location: 
docs/architecture/adr/

---
对本架构文档的重大修改必须通过
adr-drafting
技能以**ADR（Architecture Decision Records）**形式追踪记录。
ADR存储位置：
docs/architecture/adr/

---

Ontology Template

Ontology模板

markdown
undefined
markdown
undefined

Project Ontology — Ubiquitous Language

项目Ontology——Ubiquitous Language

Created: YYYY-MM-DD Last Updated: YYYY-MM-DD
创建时间：YYYY-MM-DD 最后更新：YYYY-MM-DD

Domain Glossary

领域术语表

TermDefinitionBounded Context
[Term 1][Definition][Context where this term applies]
[Term 2][Definition][Context where this term applies]
术语定义限界上下文
[术语1][定义][该术语适用的上下文]
[术语2][定义][该术语适用的上下文]

Bounded Contexts

限界上下文

ContextDescriptionKey Terms
[Context 1][Description][Key terms]
上下文描述核心术语
[上下文1][描述][核心术语]

Conceptual Mapping

概念映射

[Relationships between key domain entities — to be refined during brainstorming and task generation]

---
[核心领域实体之间的关系——将在头脑风暴和任务生成阶段细化]

---

Constitution Check Report Format

架构合规检查报告格式

undefined
undefined

Constitution Check Report

架构合规检查报告

Target: <file or spec path> Date: YYYY-MM-DD
目标：<文件或规格说明路径> 日期：YYYY-MM-DD

Architecture Check

架构检查

RuleStatusDetail
Constructor injection required✅ OKNo field injection found
No hardcoded secrets❌ CRITICALLine 42: hardcoded password string
JWT authentication⚠️ WARNINGMissing @PreAuthorize on endpoint
规则状态详情
必须使用构造函数注入✅ 合规未发现字段注入
禁止硬编码密钥❌ 严重违规第42行：存在硬编码密码字符串
JWT认证⚠️ 警告端点缺少@PreAuthorize注解

Ontology Check

Ontology检查

TermStatusDetail
"Reservation" used consistently✅ OKNo synonym "Booking" found
New term "Voucher" introduced⚠️ WARNINGNot defined in ontology.md
术语状态详情
"Reservation"使用一致✅ 合规未发现同义词"Booking"
引入新术语"Voucher"⚠️ 警告未在ontology.md中定义

Summary

总结

  • CRITICAL violations: 1 (must fix before proceeding)
  • WARNING violations: 2 (should fix)
  • Compliant rules: 2

---
  • 严重违规：1项（必须修复后才能继续）
  • 警告：2项（建议修复）
  • 合规规则：2项

---

Relationship with brainstorm and spec-to-tasks

与brainstorm和spec-to-tasks的关系

This skill is the pre-brainstorm setup entry point. The same files are also created/enriched by:
CommandWhenWhat it does
constitution create
Before brainstorm (this skill)Creates architecture.md and/or ontology.md from scratch
brainstorm
Phase 6.8.6		During brainstormingCreates/enriches ontology.md with terms extracted from the idea
spec-to-tasks
Phase 1.5		After brainstormCreates architecture.md if missing; enriches ontology.md with new terms from the spec
If you run 
constitution create
before brainstorm, the brainstorm and spec-to-tasks commands will detect the existing files and load them instead of creating new ones — no duplication.
Note on ontology.md: The ontology is normally most naturally created during brainstorming, because domain terms emerge from the idea description. Using 
constitution create
to seed it beforehand is useful when the team already has a well-defined domain language.
本技能是头脑风暴前的设置入口点。同一批文件也会通过以下命令创建/补充：
命令时机功能
constitution create
头脑风暴前（本技能）从头创建architecture.md和/或ontology.md
brainstorm
第6.8.6阶段		头脑风暴期间从想法中提取术语，创建/补充ontology.md
spec-to-tasks
第1.5阶段		头脑风暴后若缺失则创建architecture.md；从规格说明中提取新术语，补充ontology.md
若你在头脑风暴前运行
constitution create
，brainstorm和spec-to-tasks命令会检测到已存在的文件并加载使用，而非创建新文件——不会重复生成。
关于ontology.md的说明：Ontology通常在头脑风暴期间自然创建，因为领域术语会从想法描述中浮现。当团队已有明确的领域语言时，使用
constitution create
提前初始化会很有用。

Integration with SDD Workflow

与SDD工作流的集成

[Optional] constitution create        ← this skill (pre-brainstorm setup)
        ↓
brainstorm                            ← enriches ontology.md (Phase 6.8.6)
        ↓
spec-to-tasks                         ← loads/creates architecture.md, enriches ontology.md (Phase 1.5)
        ↓
task-implementation                   ← AI guardrails from architecture.md prevent unapproved patterns
        ↓
task-review / ralph-loop              ← constitution check validates implementation
[可选] constitution create        ← 本技能（头脑风暴前设置）
        ↓
brainstorm                            ← 补充ontology.md（第6.8.6阶段）
        ↓
spec-to-tasks                         ← 加载/创建architecture.md，补充ontology.md（第1.5阶段）
        ↓
task-implementation                   ← architecture.md中的AI guardrails防止使用未批准模式
        ↓
task-review / ralph-loop              ← 架构合规检查验证实现是否符合要求

Constraints

约束条件

  • Does NOT modify source code — only creates/updates 
    docs/specs/architecture.md
    and 
    docs/specs/ontology.md
  • Constitution Check is advisory for WARNINGs — CRITICAL violations must be resolved
  • One architecture.md and one ontology.md per project — shared across all specs
  • Version the architecture — update 
    Last Updated
    date on every change; use ADRs for significant decisions
  • 不会修改源代码——仅创建/更新
    docs/specs/architecture.md
    和
    docs/specs/ontology.md
  • 架构合规检查中的警告为建议性——严重违规必须解决
  • 每个项目仅一份architecture.md和ontology.md——所有规格说明共享使用
  • 版本化架构——每次更改时更新
    Last Updated
    日期；重大决策使用ADR记录