Back to Details

openspec-proposal-creation-cn

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

规范提案创建

Specification Proposal Creation

遵循规范驱动开发方法，生成完整的变更提案。
Follow the specification-driven development approach to generate complete change proposals.

快速开始

Quick Start

创建规范提案包含三类输出：
  1. proposal.md - 为什么、做什么、影响摘要
  2. tasks.json - 编号的实施清单
  3. spec-delta.md - 正式的需求变更（ADDED/MODIFIED/REMOVED）
基本流程：生成变更 ID → 脚手架目录 → 起草提案 → 编写规范差异 → 验证结构
Creating a specification proposal includes three types of outputs:
  1. proposal.md - Summary of why, what, and impact
  2. tasks.json - Numbered implementation checklist
  3. spec-delta.md - Formal requirement changes (ADDED/MODIFIED/REMOVED)
Basic Process: Generate change ID → Scaffold directory → Draft proposal → Write specification delta → Validate structure

工作流

Workflow

复制此清单并跟踪进度：
规划进度:
- [ ] 第 1 步：审阅现有规范
- [ ] 第 2 步：生成唯一的变更 ID
- [ ] 第 3 步：生成目录结构
- [ ] 第 4 步：起草 proposal.md（为什么、做什么、影响摘要）
- [ ] 第 5 步：创建 tasks.json 实施清单
- [ ] 第 6 步：编写 spec-delta.md 规范差异（ADDED/MODIFIED/REMOVED）
- [ ] 第 7 步：验证提案结构
- [ ] 第 8 步：向用户展示并请求审批
Copy this checklist to track progress:
Planning Progress:
- [ ] Step 1: Review existing specifications
- [ ] Step 2: Generate unique change ID
- [ ] Step 3: Generate directory structure
- [ ] Step 4: Draft proposal.md (why, what, impact summary)
- [ ] Step 5: Create tasks.json implementation checklist
- [ ] Step 6: Write spec-delta.md specification differences (ADDED/MODIFIED/REMOVED)
- [ ] Step 7: Validate proposal structure
- [ ] Step 8: Present to user and request approval

第 1 步：审阅现有规范

Step 1: Review Existing Specifications

在创建提案前，了解当前状态：
bash
undefined
Understand the current state before creating a proposal:
bash
undefined

列出所有现有规范

List all existing specifications

find spec/specs -name "spec.md" -type f
find spec/specs -name "spec.md" -type f

列出进行中的变更以避免冲突

List ongoing changes to avoid conflicts

find spec/changes -maxdepth 1 -type d -not -path "*/archive"
find spec/changes -maxdepth 1 -type d -not -path "*/archive"

搜索相关需求

Search related requirements

grep -r "### Requirement:" spec/specs/
undefined
grep -r "### Requirement:" spec/specs/
undefined

第 2 步：生成唯一的变更 ID

Step 2: Generate Unique Change ID

选择具描述性、URL 安全的标识符：
格式：
add-<feature>
、
fix-<issue>
、
update-<component>
、
remove-<feature>
示例：
  • add-user-authentication
  • fix-payment-validation
  • update-api-rate-limits
  • remove-legacy-endpoints
校验：检查是否冲突：
bash
ls spec/changes/ | grep -i "<proposed-id>"
Choose a descriptive, URL-safe identifier:
Format: 
add-<feature>
, 
fix-<issue>
, 
update-<component>
, 
remove-<feature>
Examples:
  • add-user-authentication
  • fix-payment-validation
  • update-api-rate-limits
  • remove-legacy-endpoints
Validation: Check for conflicts:
bash
ls spec/changes/ | grep -i "<proposed-id>"

第 3 步：生成目录结构

Step 3: Generate Directory Structure

按标准结构创建变更目录：
bash
undefined
Create a change directory following the standard structure:
bash
undefined

将 {change-id} 替换为实际 ID

Replace {change-id} with the actual ID

mkdir -p spec/changes/{change-id}/specs/{capability-name}

**示例**：
```bash
mkdir -p spec/changes/add-user-auth/specs/authentication
mkdir -p spec/changes/{change-id}/specs/{capability-name}

**Example**:
```bash
mkdir -p spec/changes/add-user-auth/specs/authentication

第 4 步：起草 proposal.md

Step 4: Draft proposal.md

以 templates/proposal.md 为起点。
必需章节：
  • Why：驱动变更的问题或机会
  • What Changes：修改项清单
  • Impact：受影响的规范、代码、API、用户
语气：清晰、简洁、面向决策。避免不必要背景。
Start with templates/proposal.md.
Required Sections:
  • Why: The problem or opportunity driving the change
  • What Changes: List of modifications
  • Impact: Affected specifications, code, APIs, users
Tone: Clear, concise, and decision-oriented. Avoid unnecessary background.

第 5 步：创建 tasks.json 实施清单

Step 5: Create tasks.json Implementation Checklist

将实现拆分为具体、可测试的任务。使用 templates/tasks.json。
格式：
markdown
undefined
Break down implementation into specific, testable tasks. Use templates/tasks.json.
Format:
markdown
undefined

实施任务

Implementation Tasks

json
[
  {
    "number": 1,
    "category": "阶段 1：基础设施",
    "task": "环境搭建任务 - 数据库架构、依赖等",
    "steps": [
      { "step": "初始化 Git 仓库并配置 .gitignore", "completed": false },
      { "step": "创建并激活 Python 虚拟环境", "completed": false },
      { "step": "创建 requirements.txt 或 pyproject.toml 并安装依赖 (FastAPI, SQLAlchemy, Pydantic, Alembic 等)", "completed": false },
      { "step": "设计初始数据库 ER 图", "completed": false },
      { "step": "配置数据库连接字符串和环境变量 (.env)", "completed": false },
      { "step": "初始化 Alembic 迁移环境", "completed": false }
    ],
    "passes": false
  }
]


**最佳实践**：
- 每个任务可独立完成
- 为每个主要组件添加测试任务
- 为每个主要组件添加测试任务
- 包含测试与验证任务
- 按依赖排序（数据库先于 API 等）
- 通常 5-15 个任务；更多时应拆分
- 每次仅处理1个step
json
[
  {
    "number": 1,
    "category": "Phase 1: Infrastructure",
    "task": "Environment setup tasks - database schema, dependencies, etc.",
    "steps": [
      { "step": "Initialize Git repository and configure .gitignore", "completed": false },
      { "step": "Create and activate Python virtual environment", "completed": false },
      { "step": "Create requirements.txt or pyproject.toml and install dependencies (FastAPI, SQLAlchemy, Pydantic, Alembic, etc.)", "completed": false },
      { "step": "Design initial database ER diagram", "completed": false },
      { "step": "Configure database connection string and environment variables (.env)", "completed": false },
      { "step": "Initialize Alembic migration environment", "completed": false }
    ],
    "passes": false
  }
]


**Best Practices**:
- Each task can be completed independently
- Add test tasks for each major component
- Add test tasks for each major component
- Include testing and validation tasks
- Sort by dependency (database before API, etc.)
- Typically 5-15 tasks; split if more
- Process only 1 step at a time

第 6 步：以 EARS 格式编写规范差异

Step 6: Write Specification Delta in EARS Format

这是最关键步骤。规范差异使用 EARS 格式（易于需求语法）。
完整 EARS 指南见 reference/EARS_FORMAT.md
差异操作：
  • ## ADDED Requirements
    - 新增能力
  • ## MODIFIED Requirements
    - 行为变更（包含完整更新文本）
  • ## REMOVED Requirements
    - 弃用功能
基本需求结构：
markdown
undefined
This is the most critical step. Specification differences use the EARS format (Easy Approach to Requirements Syntax).
Complete EARS Guide is available at reference/EARS_FORMAT.md
Delta Operations:
  • ## ADDED Requirements
    - New capabilities added
  • ## MODIFIED Requirements
    - Behavior changes (include full updated text)
  • ## REMOVED Requirements
    - Deprecated features
Basic Requirement Structure:
markdown
undefined

ADDED Requirements

ADDED Requirements

Requirement: 用户登录

Requirement: User Login

WHEN 用户提交有效凭据, 系统 SHALL 认证用户并创建会话。
WHEN the user submits valid credentials, the system SHALL authenticate the user and create a session.

Scenario: 登录成功

Scenario: Successful Login

GIVEN 用户邮箱为 "user@example.com" 且密码为 "correct123" WHEN 用户提交登录表单 THEN 系统创建已认证会话 AND 重定向至仪表盘

**用于验证的模式**见 [reference/VALIDATION_PATTERNS.md](reference/VALIDATION_PATTERNS.md)
GIVEN the user's email is "user@example.com" and password is "correct123" WHEN the user submits the login form THEN the system creates an authenticated session AND redirects to the dashboard

**Patterns for Validation** are available at [reference/VALIDATION_PATTERNS.md](reference/VALIDATION_PATTERNS.md)

第 7 步：验证提案结构

Step 7: Validate Proposal Structure

在展示给用户前运行以下检查：
markdown
结构清单：
- [ ] 目录存在：`spec/changes/{change-id}/`
- [ ] proposal.md 包含 Why/What/Impact
- [ ] tasks.json 含编号任务列表（5-15 项）
- [ ] 规范差异包含操作标题（ADDED/MODIFIED/REMOVED）
- [ ] 需求遵循 `### Requirement: <name>` 格式
- [ ] 场景使用 `#### Scenario:` 格式（四个井号）
自动化检查：
bash
undefined
Run the following checks before presenting to the user:
markdown
Structure Checklist:
- [ ] Directory exists: `spec/changes/{change-id}/`
- [ ] proposal.md includes Why/What/Impact
- [ ] tasks.json contains numbered task list (5-15 items)
- [ ] Specification delta includes operation headers (ADDED/MODIFIED/REMOVED)
- [ ] Requirements follow the `### Requirement: <name>` format
- [ ] Scenarios use the `#### Scenario:` format (four hashes)
Automated Checks:
bash
undefined

统计差异操作（应 > 0）

Count delta operations (should be > 0)

grep -c "## ADDED|MODIFIED|REMOVED" spec/changes/{change-id}/specs/**/*.md
grep -c "## ADDED|MODIFIED|REMOVED" spec/changes/{change-id}/specs/**/*.md

验证场景格式（显示行号）

Validate scenario format (show line numbers)

grep -n "#### Scenario:" spec/changes/{change-id}/specs/**/*.md
grep -n "#### Scenario:" spec/changes/{change-id}/specs/**/*.md

检查需求标题

Check requirement titles

grep -n "### Requirement:" spec/changes/{change-id}/specs/**/*.md
undefined
grep -n "### Requirement:" spec/changes/{change-id}/specs/**/*.md
undefined

第 8 步：提交用户评审

Step 8: Submit for User Review

清晰总结提案：
markdown
undefined
Summarize the proposal clearly:
markdown
undefined

Proposal Summary

Proposal Summary

Change ID：{change-id} Scope：{简要描述}
创建的文件：
  • spec/changes/{change-id}/proposal.md
  • spec/changes/{change-id}/tasks.json
  • spec/changes/{change-id}/specs/{capability}/spec-delta.md
下一步： 请评审提案。如认可或修正后，请回复 "openspec开发" 或 "按顺序完成任务" 开始实施。
undefined
Change ID: {change-id} Scope: {brief description}
Files Created:
  • spec/changes/{change-id}/proposal.md
  • spec/changes/{change-id}/tasks.json
  • spec/changes/{change-id}/specs/{capability}/spec-delta.md
Next Steps: Please review the proposal. If approved or revised, reply with "openspec development" or "complete tasks in order" to start implementation.
undefined

进阶主题

Advanced Topics

EARS 格式细节：见 reference/EARS_FORMAT.md 验证模式：见 reference/VALIDATION_PATTERNS.md 完整示例：见 reference/EXAMPLES.md
EARS Format Details: See reference/EARS_FORMAT.md Validation Patterns: See reference/VALIDATION_PATTERNS.md Complete Examples: See reference/EXAMPLES.md

常见模式

Common Patterns

模式 1：新增功能提案

Pattern 1: New Feature Proposal

新增能力时：
  • 使用 
    ADDED Requirements
    差异
  • 同时包含正向场景与错误处理
  • 在场景中考虑边界情况
When adding new capabilities:
  • Use 
    ADDED Requirements
    delta
  • Include both positive scenarios and error handling
  • Consider edge cases in scenarios

模式 2：破坏性变更提案

Pattern 2: Breaking Change Proposal

修改既有行为时：
  • 使用 
    MODIFIED Requirements
    差异
  • 包含完整更新后的需求文本
  • 在 proposal.md 中说明变更内容与原因
  • 在 tasks.json 中考虑迁移任务
When modifying existing behavior:
  • Use 
    MODIFIED Requirements
    delta
  • Include full updated requirement text
  • Explain what changed and why in proposal.md
  • Include migration tasks in tasks.json

模式 3：弃用提案

Pattern 3: Deprecation Proposal

移除功能时：
  • 使用 
    REMOVED Requirements
    差异
  • 在 proposal.md 中记录移除理由
  • 在 tasks.json 中包含清理任务
  • 在影响部分考虑用户迁移
When removing features:
  • Use 
    REMOVED Requirements
    delta
  • Record the reason for removal in proposal.md
  • Include cleanup tasks in tasks.json
  • Consider user migration in the impact section

反模式避免

Anti-Patterns to Avoid

不要：
  • 跳过验证检查（务必运行 grep 模式）
  • 未先审阅现有规范就创建提案
  • 使用含糊的任务描述（如"修一下"）
  • 编写不含场景的需求
  • 忽略错误处理场景
  • 在一个提案中混合多个无关变更
要：
  • 在创建变更 ID 前检查冲突
  • 编写具体、可测试的任务
  • 同时包含正向与负向场景
  • 一个提案只处理一个关注点
  • 在展示前验证结构
Do NOT:
  • Skip validation checks (be sure to run grep patterns)
  • Create proposals without first reviewing existing specifications
  • Use vague task descriptions (e.g., "fix it")
  • Write requirements without scenarios
  • Ignore error handling scenarios
  • Mix multiple unrelated changes in one proposal
DO:
  • Check for conflicts before creating a change ID
  • Write specific, testable tasks
  • Include both positive and negative scenarios
  • Address only one concern per proposal
  • Validate structure before presenting

文件模板

File Templates

所有模板位于 
templates/
目录：
  • proposal.md - 提案结构
  • tasks.json - 任务清单格式
  • spec-delta.md - 规范差异模板
All templates are located in the 
templates/
directory:
  • proposal.md - Proposal structure
  • tasks.json - Task checklist format
  • spec-delta.md - Specification delta template

参考资料

Reference Materials

  • EARS_FORMAT.md - 完整 EARS 语法指南
  • VALIDATION_PATTERNS.md - Grep/bash 验证
  • EXAMPLES.md - 真实提案示例
Token 预算：此 SKILL.md 约 250 行，低于建议的 500 行上限。引用文件按需加载以逐步呈现。
  • EARS_FORMAT.md - Complete EARS syntax guide
  • VALIDATION_PATTERNS.md - Grep/bash validation
  • EXAMPLES.md - Real proposal examples
Token Budget: This SKILL.md is approximately 250 lines, below the recommended 500-line limit. Reference files are loaded on demand for gradual presentation.