规范提案创建指南：遵循规范驱动开发（SDD）创建全面变更提案

openspec-proposal-creation by forztf/open-skilled-sdd

311 周安装量

7 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/forztf/open-skilled-sdd --skill openspec-proposal-creation

方法论需求分析技术文档

🇨🇳中文介绍

规范提案创建

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

快速开始

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

proposal.md - 原因、内容和影响摘要
tasks.md - 编号的实施清单
spec-delta.md - 正式的需求变更（新增/修改/移除）

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

工作流程

复制此清单并跟踪进度：

提案进度：
- [ ] 步骤 1：审查现有规范
- [ ] 步骤 2：生成唯一变更 ID
- [ ] 步骤 3：搭建目录结构
- [ ] 步骤 4：起草 proposal.md（原因/内容/影响）
- [ ] 步骤 5：创建 tasks.md 实施清单
- [ ] 步骤 6：使用 EARS 格式编写规范差异
- [ ] 步骤 7：验证提案结构
- [ ] 步骤 8：提交给用户审批

步骤 1：审查现有规范

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

# 列出所有现有规范
find spec/specs -name "spec.md" -type f

# 列出活动变更以避免冲突
find spec/changes -maxdepth 1 -type d -not -path "*/archive"

# 搜索相关需求
grep -r "### Requirement:" spec/specs/

步骤 2：生成唯一变更 ID

选择一个描述性的、URL 安全的标识符：

格式：add-<功能>、、、

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

步骤 3：搭建目录结构

使用标准结构创建变更文件夹：

# 将 {change-id} 替换为实际 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 处的模板作为起点。

原因：驱动此变更的问题或机会
变更内容：修改项的要点列表
影响：受影响的规范、代码、API、用户

语气：清晰、简洁、以决策为中心。避免不必要的背景信息。

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

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

# 实施任务

1. [第一个具体任务]
2. [第二个具体任务]
3. [测试任务]
4. [文档任务]

每个任务可独立完成
包含测试和验证任务
按依赖关系排序（例如数据库在 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 "user@example.com" 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：验证提案结构

在提交给用户之前运行这些检查：

结构检查清单：
- [ ] 目录存在：`spec/changes/{change-id}/`
- [ ] proposal.md 包含原因/内容/影响部分
- [ ] tasks.md 包含编号的任务列表（5-15 项）
- [ ] 规范差异具有操作标题（新增/修改/移除）
- [ ] 需求遵循 `### Requirement: <名称>` 格式
- [ ] 场景使用 `#### Scenario:` 格式（4 个井号）

自动化检查：

# 统计差异操作数量（应大于 0）
grep -c "## ADDED\|MODIFIED\|REMOVED" spec/changes/{change-id}/specs/**/*.md

# 验证场景格式（应显示行号）
grep -n "#### Scenario:" spec/changes/{change-id}/specs/**/*.md

# 检查需求标题
grep -n "### Requirement:" spec/changes/{change-id}/specs/**/*.md

步骤 8：提交给用户审批

清晰地总结提案：

## 提案摘要

**变更 ID**：{change-id}
**范围**：{简要描述}

**创建的文件**：
- spec/changes/{change-id}/proposal.md
- spec/changes/{change-id}/tasks.md
- spec/changes/{change-id}/specs/{capability}/spec-delta.md

**后续步骤**：
审查提案。如果批准，请说 "openspec implement" 或 "apply the change" 以开始实施。

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 - 真实世界提案示例

令牌预算：此 SKILL.md 大约 450 行，低于推荐的 500 行限制。参考文件仅在需要时加载，以实现渐进式披露。

🇺🇸English

Specification Proposal Creation

Creates comprehensive change proposals following spec-driven development methodology.

Quick Start

Creating a spec proposal involves three main outputs:

proposal.md - Why, what, and impact summary
tasks.md - Numbered implementation checklist
spec-delta.md - Formal requirement changes (ADDED/MODIFIED/REMOVED)

Basic workflow : Generate change ID → scaffold directories → draft proposal → create spec deltas → validate structure

Workflow

Copy this checklist and track progress:

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

Step 1: Review existing specifications

Before creating a proposal, understand the current state:

# 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/

Step 2: Generate unique change 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:

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

Step 3: Scaffold directory structure

Create the change folder with standard structure:

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

Example :

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

Step 4: Draft proposal.md

Use the template at templates/proposal.md as starting point.

Required sections :

Why : Problem or opportunity driving this change
What Changes : Bullet list of modifications
Impact : Affected specs, code, APIs, users

Tone : Clear, concise, decision-focused. Avoid unnecessary background.

Step 5: Create tasks.md implementation checklist

Break implementation into concrete, testable tasks. Use the template at templates/tasks.md.

Format :

# Implementation Tasks

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

Best practices :

Each task is independently completable
Include testing and validation tasks
Order by dependencies (database before API, etc.)
5-15 tasks is typical; split if more needed

Step 6: Write spec deltas with EARS format

This is the most critical step. Spec deltas use EARS format (Easy Approach to Requirements Syntax).

For complete EARS guidelines , see reference/EARS_FORMAT.md

Delta operations :

## ADDED Requirements - New capabilities
## MODIFIED Requirements - Changed behavior (include full updated text)
## REMOVED Requirements - Deprecated features

Basic requirement structure :

## 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 "user@example.com" and password "correct123"
WHEN the user submits the login form
THEN the system creates an authenticated session
AND redirects to the dashboard

For validation patterns , see reference/VALIDATION_PATTERNS.md

Step 7: Validate proposal structure

Run these checks before presenting to user:

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)

Automated checks :

# 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

Step 8: Present for user approval

Summarize the proposal clearly:

## 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.

Advanced Topics

EARS format details : See reference/EARS_FORMAT.md Validation patterns : See reference/VALIDATION_PATTERNS.md Complete examples : See reference/EXAMPLES.md

Common Patterns

Pattern 1: New feature proposal

When adding net-new capability:

Use ADDED Requirements delta
Include positive scenarios AND error handling
Consider edge cases in scenarios

Pattern 2: Breaking change proposal

When changing existing behavior:

Use MODIFIED Requirements delta
Include complete updated requirement text
Document what changes and why in proposal.md
Consider migration tasks in tasks.md

Pattern 3: Deprecation proposal

When removing features:

Use REMOVED Requirements delta
Document removal rationale in proposal.md
Include cleanup tasks in tasks.md
Consider user migration in impact section

Anti-Patterns to Avoid

Don't :

Skip validation checks (always run grep patterns)
Create proposals without reviewing existing specs first
Use vague task descriptions ("Fix the thing")
Write requirements without scenarios
Forget error handling scenarios
Mix multiple unrelated changes in one proposal

Do :

Check for conflicts before creating change ID
Write concrete, testable tasks
Include positive AND negative scenarios
Keep one concern per proposal
Validate structure before presenting

File Templates

All templates are in the templates/ directory:

proposal.md - Proposal structure
tasks.md - Task checklist format
spec-delta.md - Spec delta template

Reference Materials

EARS_FORMAT.md - Complete EARS syntax guide
VALIDATION_PATTERNS.md - Grep/bash validation
EXAMPLES.md - Real-world proposal examples

Token budget : This SKILL.md is approximately 450 lines, under the 500-line recommended limit. Reference files load only when needed for progressive disclosure.

Weekly Installs

200

Repository

forztf/open-skilled-sdd

GitHub Stars

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode187

codex181

gemini-cli180

github-copilot172

cursor168

kimi-cli152

任务估算指南：敏捷开发故事点、计划扑克、T恤尺码法详解

10,500 周安装