Back to Details

writing-project-constitution

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Writing Project Constitution

编写项目章程

Create constitution files (CLAUDE.md / AGENTS.md) that are always loaded into the agent's context window on every request. This is the most expensive context layer -- every token here is consumed on every interaction.
Use this skill when initializing a project for spec-driven development, writing CLAUDE.md or AGENTS.md, or defining always-applicable project rules.
Supporting files: CROSS-AGENT.md for agent-specific file placement, EXAMPLES.md for complete examples.
创建章程文件（CLAUDE.md / AGENTS.md），这些文件会在每次请求时始终加载到Agent的上下文窗口中。这是成本最高的上下文层级——此处的每个token都会在每次交互中被消耗。
适用场景：初始化规范驱动开发的项目、编写CLAUDE.md或AGENTS.md，或定义全局适用的项目规则时使用此技能。
支持文件：CROSS-AGENT.md 用于Agent专属文件放置说明，EXAMPLES.md 提供完整示例。

Context Layer: L1 (Always Loaded)

上下文层级：L1（始终加载）

Context Loading Timeline
================================================================
Session Start    Task Start    Implementation    Deep Dive
     |
     +-- CLAUDE.md / AGENTS.md  <-- THIS SKILL
     |   (loaded EVERY request, costs tokens EVERY time)
     |
     +-- Skill descriptions (metadata only)
================================================================
The constitution is the only document that persists across context compression. When the agent's conversation gets too long, older messages are compressed, but the constitution is re-injected. This makes it the right place for information that must NEVER be forgotten.
Context Loading Timeline
================================================================
Session Start    Task Start    Implementation    Deep Dive
     |
     +-- CLAUDE.md / AGENTS.md  <-- 本技能对应的文件
     |   (每次请求都会加载，每次都会消耗token)
     |
     +-- Skill descriptions (metadata only)
================================================================
章程是唯一能在上下文压缩后仍保留的文档。当Agent的对话过长时，旧消息会被压缩，但章程会被重新注入。这使得它成为存放绝对不能遗忘信息的理想位置。

What Belongs Here (and What Does NOT)

哪些内容应放入（以及不应放入）

MUST include (needed every request):

必须包含（每次请求都需要）：

  • Build / test / lint commands
  • Tech stack summary (one line per technology)
  • Core coding conventions (naming, error handling style)
  • Hard constraints ("never commit secrets", "always run tests")
  • Active feature spec references (one line each)
  • Directory structure overview (abbreviated)
  • 构建/测试/代码检查命令
  • 技术栈摘要（每项技术一行）
  • 核心编码规范（命名、错误处理风格）
  • 硬性约束（如“绝不提交密钥”、“始终运行测试”）
  • 活跃功能规范引用（每项一行）
  • 目录结构概述（简化版）

MUST NOT include (move elsewhere):

禁止包含（移至其他位置）：

InformationMove toReason
Detailed requirementsFeature spec (L3/L4)Only needed during implementation
Architecture decisionsTechnical design (L3/L4)Only needed during design
API endpoint detailsPath-conditional rules (L2)Only needed for specific files
Task listsImplementation tasks (L3)Only needed when selecting work
Code examples > 5 linesAgent Skill references (L4)Too expensive for L1
Library documentationMCP or references (L4)Agent can look up on demand
信息类型移至位置原因
详细需求功能规范（L3/L4）仅在实现阶段需要
架构决策技术设计文档（L3/L4）仅在设计阶段需要
API端点详情路径条件规则（L2）仅处理特定文件时需要
任务清单实现任务文档（L3）仅在选择工作内容时需要
超过5行的代码示例Agent Skill引用（L4）对L1来说成本过高
库文档MCP或参考文档（L4）Agent可按需查询

Template

模板

markdown
undefined
markdown
undefined

Project Constitution

Project Constitution

Commands

Commands

  • Build: 
    [command]
  • Test: 
    [command]
  • Test single: 
    [command with placeholder]
  • Lint: 
    [command]
  • Format: 
    [command]
  • Build: 
    [command]
  • Test: 
    [command]
  • Test single: 
    [command with placeholder]
  • Lint: 
    [command]
  • Format: 
    [command]

Tech Stack

Tech Stack

  • Language: [e.g., Go 1.23]
  • Framework: [e.g., Echo v4]
  • Database: [e.g., PostgreSQL 16 via sqlc]
  • Frontend: [e.g., templ + htmx]
  • Language: [e.g., Go 1.23]
  • Framework: [e.g., Echo v4]
  • Database: [e.g., PostgreSQL 16 via sqlc]
  • Frontend: [e.g., templ + htmx]

Project Structure

Project Structure

src/           # Application source
internal/      # Private packages
cmd/           # Entry points
specs/         # Feature specs and designs (see below)
src/           # Application source
internal/      # Private packages
cmd/           # Entry points
specs/         # Feature specs and designs (see below)

Coding Standards

Coding Standards

  • [Convention 1: e.g., Use snake_case for DB columns, camelCase for Go]
  • [Convention 2: e.g., Errors must wrap with fmt.Errorf("context: %w", err)]
  • [Convention 3: e.g., All public functions must have godoc comments]
  • [Convention 1: e.g., Use snake_case for DB columns, camelCase for Go]
  • [Convention 2: e.g., Errors must wrap with fmt.Errorf("context: %w", err)]
  • [Convention 3: e.g., All public functions must have godoc comments]

Boundaries

Boundaries

  • ALWAYS: Run tests before considering implementation complete
  • ALWAYS: Follow existing patterns in the codebase
  • ASK FIRST: Database schema changes, new dependencies
  • NEVER: Commit .env files, modify CI config, use force push
  • ALWAYS: Run tests before considering implementation complete
  • ALWAYS: Follow existing patterns in the codebase
  • ASK FIRST: Database schema changes, new dependencies
  • NEVER: Commit .env files, modify CI config, use force push

Active Specs

Active Specs

Current feature specs (load these when working on related code):
  • specs/prd-notifications.md
    - Push notification system
  • specs/design-notifications.md
    - Notification architecture
  • specs/tasks-notifications.md
    - Implementation tasks
Current feature specs (load these when working on related code):
  • specs/prd-notifications.md
    - Push notification system
  • specs/design-notifications.md
    - Notification architecture
  • specs/tasks-notifications.md
    - Implementation tasks

Conditional Rules

Conditional Rules

Code-area-specific rules are in:
  • .claude/rules/
    (Claude Code)
  • .github/instructions/
    (Copilot CLI)
These load automatically when touching matching files.
undefined
Code-area-specific rules are in:
  • .claude/rules/
    (Claude Code)
  • .github/instructions/
    (Copilot CLI)
These load automatically when touching matching files.
undefined

Size Budget

篇幅预算

Target: under 200 lines / ~2000 tokens.
Every line in the constitution costs tokens on every single request. Measure ruthlessly:
Good constitution (150 lines):
- 10 lines: commands
- 5 lines: tech stack
- 10 lines: project structure
- 15 lines: coding standards
- 10 lines: boundaries
- 10 lines: active specs
- Remaining: breathing room

Bad constitution (500+ lines):
- 50 lines: detailed API documentation  -> move to L4
- 100 lines: code examples              -> move to L4
- 80 lines: architecture decisions       -> move to L3/L4
- 200 lines: task lists                  -> move to L3
目标：少于200行 / ~2000个token。
章程中的每一行都会在每次请求时消耗token，务必严格控制篇幅：
优质章程（150行）：
- 10行：命令
- 5行：技术栈
- 10行：项目结构
- 15行：编码标准
- 10行：约束边界
- 10行：活跃规范
- 剩余：预留空间

劣质章程（500+行）：
- 50行：详细API文档  -> 移至L4
- 100行：代码示例      -> 移至L4
- 80行：架构决策       -> 移至L3/L4
- 200行：任务清单       -> 移至L3

Cross-Agent File Placement

跨Agent文件放置

The same content maps to different files per agent:
AgentPrimary FileLocation
Claude Code
CLAUDE.md
Project root
Codex CLI
AGENTS.md
Project root
Copilot CLI
AGENTS.md
+ 
.github/copilot-instructions.md
Project root
Multi-agentBoth 
CLAUDE.md
and 
AGENTS.md
Project root
For multi-agent projects, create both files. They can share content or reference each other. See CROSS-AGENT.md for detailed patterns.
相同内容对应不同Agent的文件位置不同：
Agent主文件位置
Claude Code
CLAUDE.md
项目根目录
Codex CLI
AGENTS.md
项目根目录
Copilot CLI
AGENTS.md
+ 
.github/copilot-instructions.md
项目根目录
多Agent同时使用
CLAUDE.md
和
AGENTS.md
项目根目录
对于多Agent项目，需创建两个文件。它们可共享内容或互相引用。详见CROSS-AGENT.md中的详细模式。

Path-Conditional Rules (L2 Layer)

路径条件规则（L2层级）

Move area-specific rules out of the constitution into conditional files:
将特定领域的规则从章程中移至条件文件：

Claude Code: 
.claude/rules/

Claude Code：
.claude/rules/

markdown
<!-- .claude/rules/api-handlers.md -->
---
paths:
  - "internal/handler/**/*.go"
  - "internal/api/**/*.go"
---

API handler conventions:
- Use echo.Context for HTTP handling
- Return HTTP errors via echo.NewHTTPError()
- Validate request body with validator tags
- Log with structured logger (slog)
markdown
<!-- .claude/rules/api-handlers.md -->
---
paths:
  - "internal/handler/**/*.go"
  - "internal/api/**/*.go"
---

API handler conventions:
- Use echo.Context for HTTP handling
- Return HTTP errors via echo.NewHTTPError()
- Validate request body with validator tags
- Log with structured logger (slog)

Copilot CLI: 
.github/instructions/

Copilot CLI：
.github/instructions/

markdown
<!-- .github/instructions/api-handlers.instructions.md -->
---
applyTo: "internal/handler/**/*.go,internal/api/**/*.go"
---

API handler conventions:
- Use echo.Context for HTTP handling
...
markdown
<!-- .github/instructions/api-handlers.instructions.md -->
---
applyTo: "internal/handler/**/*.go,internal/api/**/*.go"
---

API handler conventions:
- Use echo.Context for HTTP handling
...

Codex CLI: Subdirectory 
AGENTS.md

Codex CLI：子目录
AGENTS.md

markdown
<!-- internal/handler/AGENTS.md -->
API handler conventions:
- Use echo.Context for HTTP handling
...
markdown
<!-- internal/handler/AGENTS.md -->
API handler conventions:
- Use echo.Context for HTTP handling
...

Integration with Other Spec Documents

与其他规范文档的集成

The constitution is the hub that links to other documents. Keep references minimal:
markdown
undefined
章程是链接其他文档的枢纽，应尽量简化引用：
markdown
undefined

Active Specs

Active Specs

  • specs/prd-{feature}.md
    - What to build (load via feature-spec skill)
  • specs/design-{feature}.md
    - How to build (load via technical-design skill)
  • specs/tasks-{feature}.md
    - Implementation order (load via implementation-tasks skill)

Agents use these references to know which files to load when starting work on a feature.
  • specs/prd-{feature}.md
    - 需构建的内容（通过feature-spec技能加载）
  • specs/design-{feature}.md
    - 构建方式（通过technical-design技能加载）
  • specs/tasks-{feature}.md
    - 实现顺序（通过implementation-tasks技能加载）

Agent会利用这些引用，在开始处理某个功能时知道需要加载哪些文件。

Workflow

工作流程

1. Create CLAUDE.md (and/or AGENTS.md) at project root
2. Add build/test commands first (most universally needed)
3. Add tech stack summary (one line per technology)
4. Add coding standards (only project-specific ones)
5. Add boundaries (always/ask-first/never)
6. Extract area-specific rules to L2 conditional files
7. Add active spec references as features are planned
8. Review total line count -- cut anything over 200 lines
9. Validate: read the file and ask "is EVERY line needed on EVERY request?"
1. 在项目根目录创建CLAUDE.md（和/或AGENTS.md）
2. 首先添加构建/测试命令（最通用的需求）
3. 添加技术栈摘要（每项技术一行）
4. 添加编码标准（仅项目特有的规范）
5. 添加约束边界（始终执行/需先询问/禁止操作）
6. 将特定领域规则提取至L2条件文件
7. 随着功能规划推进，添加活跃规范引用
8. 检查总行数——删除超过200行的内容
9. 验证：通读文件并自问“每一行是否在每次请求时都需要？”

Quality Checklist

质量检查清单

Constitution Quality Check:
- [ ] Under 200 lines total
- [ ] Build/test/lint commands are present and correct
- [ ] No detailed requirements (those belong in feature specs)
- [ ] No architecture decisions (those belong in technical designs)
- [ ] No task lists (those belong in implementation tasks)
- [ ] No code examples longer than 5 lines
- [ ] Area-specific rules extracted to L2 conditional files
- [ ] Active spec references are current (no stale links)
- [ ] Every line passes the test: "needed on EVERY request?"
章程质量检查：
- [ ] 总行数少于200行
- [ ] 构建/测试/代码检查命令存在且正确
- [ ] 无详细需求（应放入功能规范）
- [ ] 无架构决策（应放入技术设计文档）
- [ ] 无任务清单（应放入实现任务文档）
- [ ] 无超过5行的代码示例
- [ ] 特定领域规则已提取至L2条件文件
- [ ] 活跃规范引用为最新（无失效链接）
- [ ] 每一行都通过测试：“每次请求都需要吗？”

Detailed Guides

详细指南

Cross-agent file placement: See CROSS-AGENT.md Complete constitution examples: See EXAMPLES.md
跨Agent文件放置：详见CROSS-AGENT.md 完整章程示例：详见EXAMPLES.md