openspec-proposal-creation

规范提案创建

遵循规范驱动开发方法创建全面的变更提案。

快速开始

创建规范提案涉及三个主要产出：

1. proposal.md - 原因、内容和影响摘要
2. tasks.md - 编号的实施检查清单
3. spec-delta.md - 正式的需求变更（ADDED/MODIFIED/REMOVED）

基本工作流：生成变更 ID → 搭建目录结构 → 起草提案 → 创建规范增量 → 验证结构

工作流

复制此检查清单并跟踪进度：

Proposal Progress:
- [ ] Step 1: Review existing specifications
- [ ] Step 2: Generate unique change ID
- [ ] Step 3: Scaffold directory structure
- [ ] Step 4: Draft proposal.md (Why/What/Impact)
- [ ] Step 5: Create tasks.md implementation checklist
- [ ] Step 6: Write spec deltas with EARS format
- [ ] Step 7: Validate proposal structure
- [ ] Step 8: Present for user approval

步骤 1：审查现有规范

创建提案之前，先了解当前状态：

# List all existing specs
find spec/specs -name "spec.md" -type f

# List active changes to avoid conflicts
find spec/changes -maxdepth 1 -type d -not -path "*/archive"

# Search for related requirements
grep -r "### Requirement:" spec/specs/

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

选择一个描述性强且适合用于 URL 的标识符：

格式：add-<feature>、fix-<issue>、update-<component>、remove-<feature>

示例：

• add-user-authentication
• fix-payment-validation
• update-api-rate-limits
• remove-legacy-endpoints

验证：检查是否存在冲突：

ls spec/changes/ | grep -i "<proposed-id>"

步骤 3：搭建目录结构

创建包含标准结构的变更文件夹：

# Replace {change-id} with actual ID
mkdir -p spec/changes/{change-id}/specs/{capability-name}

示例：

mkdir -p spec/changes/add-user-auth/specs/authentication

步骤 4：起草 proposal.md

使用 templates/proposal.md 中的模板作为起点。

必需章节：

• Why：推动此变更的问题或机会
• What Changes：修改项的项目符号列表
• Impact：受影响的规范、代码、API 和用户

语气：清晰、简洁，聚焦决策。避免不必要的背景信息。

步骤 5：创建 tasks.md 实施检查清单

将实施过程拆分为具体、可测试的任务。使用 templates/tasks.md 中的模板。

格式：

# Implementation Tasks

1. [First concrete task]
2. [Second concrete task]
3. [Test task]
4. [Documentation task]

最佳实践：

• 每项任务都应可独立完成
• 包含测试和验证任务
• 按依赖关系排序（先数据库，再 API 等）
• 通常包含 5-15 项任务；如需更多任务，请拆分

步骤 6：使用 EARS 格式编写规范增量

这是最关键的一步。规范增量使用 EARS 格式（易用的需求语法方法）。

EARS 完整指南，请参阅 reference/EARS_FORMAT.md

增量操作：

• ## ADDED Requirements - 新增功能
• ## MODIFIED Requirements - 变更行为（包含完整的更新后文本）
• ## REMOVED Requirements - 弃用功能

基本需求结构：

## ADDED Requirements

### Requirement: User Login
WHEN a user submits valid credentials,
the system SHALL authenticate the user and create a session.

#### Scenario: Successful Login
GIVEN a user with email "[email protected]" and password "correct123"
WHEN the user submits the login form
THEN the system creates an authenticated session
AND redirects to the dashboard

验证模式，请参阅 reference/VALIDATION_PATTERNS.md

步骤 7：验证提案结构

提交给用户之前，运行以下检查：

Structure Checklist:
- [ ] Directory exists: `spec/changes/{change-id}/`
- [ ] proposal.md has Why/What/Impact sections
- [ ] tasks.md has numbered task list (5-15 items)
- [ ] Spec deltas have operation headers (ADDED/MODIFIED/REMOVED)
- [ ] Requirements follow `### Requirement: <name>` format
- [ ] Scenarios use `#### Scenario:` format (4 hashtags)

自动化检查：

# Count delta operations (should be > 0)
grep -c "## ADDED\|MODIFIED\|REMOVED" spec/changes/{change-id}/specs/**/*.md

# Verify scenario format (should show line numbers)
grep -n "#### Scenario:" spec/changes/{change-id}/specs/**/*.md

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

步骤 8：提交用户审批

清晰地总结提案：

## Proposal Summary

**Change ID**: {change-id}
**Scope**: {brief description}

**Files created**:
- spec/changes/{change-id}/proposal.md
- spec/changes/{change-id}/tasks.md
- spec/changes/{change-id}/specs/{capability}/spec-delta.md

**Next steps**:
Review the proposal. If approved, say "openspec implement" or "apply the change" to begin implementation.

高级主题

EARS 格式详情：请参阅 reference/EARS_FORMAT.md 验证模式：请参阅 reference/VALIDATION_PATTERNS.md 完整示例：请参阅 reference/EXAMPLES.md

常见模式

模式 1：新功能提案

添加全新功能时：

• 使用 ADDED Requirements 增量
• 包含正向场景和错误处理
• 在场景中考虑边缘情况

模式 2：破坏性变更提案

变更现有行为时：

• 使用 MODIFIED Requirements 增量
• 包含完整的更新后需求文本
• 在 proposal.md 中记录变更内容及原因
• 在 tasks.md 中考虑迁移任务

模式 3：弃用提案

移除功能时：

• 使用 REMOVED Requirements 增量
• 在 proposal.md 中记录移除理由
• 在 tasks.md 中包含清理任务
• 在影响部分考虑用户迁移

应避免的反模式

不要：

• 跳过验证检查（始终运行 grep 模式）
• 未先审阅现有规范就创建提案
• 使用含糊的任务描述（“修复那个东西”）
• 编写不含场景的需求
• 忘记错误处理场景
• 在一个提案中混合多个无关更改

应该：

• 在创建变更 ID 前检查冲突
• 编写具体、可测试的任务
• 包含正向和负向场景
• 每个提案只关注一个问题
• 在提交前验证结构

文件模板

所有模板都在 templates/ 目录中：

• proposal.md - 提案结构
• tasks.md - 任务检查清单格式
• spec-delta.md - 规范增量模板

参考资料

• EARS_FORMAT.md - 完整的 EARS 语法指南
• VALIDATION_PATTERNS.md - Grep/bash 验证
• EXAMPLES.md - 真实提案示例

---

Token 预算：此 SKILL.md 约 450 行，低于建议的 500 行上限。参考文件仅在需要渐进式披露时加载。