Openspec Proposal Creation Cn

规范提案创建

遵循规范驱动开发方法，生成完整的变更提案。

快速开始

创建规范提案包含三类输出： 1. proposal.md - 为什么、做什么、影响摘要 2. tasks.json - 编号的实施清单 3. spec-delta.md - 正式的需求变更（ADDED/MODIFIED/REMOVED）

基本流程：生成变更 ID → 脚手架目录 → 起草提案 → 编写规范差异 → 验证结构

工作流

复制此清单并跟踪进度：

规划进度:
- [ ] 第 1 步：审阅现有规范
- [ ] 第 2 步：生成唯一的变更 ID
- [ ] 第 3 步：生成目录结构
- [ ] 第 4 步：起草 proposal.md（为什么、做什么、影响摘要）
- [ ] 第 5 步：创建 tasks.json 实施清单
- [ ] 第 6 步：编写 spec-delta.md 规范差异（ADDED/MODIFIED/REMOVED）
- [ ] 第 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-<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 步：生成目录结构

按标准结构创建变更目录：

# 将 {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 为起点。

必需章节：

• Why：驱动变更的问题或机会
• What Changes：修改项清单
• Impact：受影响的规范、代码、API、用户

语气：清晰、简洁、面向决策。避免不必要背景。

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

将实现拆分为具体、可测试的任务。使用 templates/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

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

这是最关键步骤。规范差异使用 **EARS 格式**（易于需求语法）。

**完整 EARS 指南**见 [reference/EARS_FORMAT.md](reference/EARS_FORMAT.md)

**差异操作**：
- `## ADDED Requirements` - 新增能力
- `## MODIFIED Requirements` - 行为变更（包含完整更新文本）
- `## REMOVED Requirements` - 弃用功能

**基本需求结构**：

ADDED Requirements

Requirement: 用户登录

WHEN 用户提交有效凭据, 系统 SHALL 认证用户并创建会话。

Scenario: 登录成功

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

**用于验证的模式**见 [reference/VALIDATION_PATTERNS.md](reference/VALIDATION_PATTERNS.md)

### 第 7 步：验证提案结构

在展示给用户前运行以下检查：

结构清单：

• [ ] 目录存在：spec/changes/{change-id}/
• [ ] proposal.md 包含 Why/What/Impact
• [ ] tasks.json 含编号任务列表（5-15 项）
• [ ] 规范差异包含操作标题（ADDED/MODIFIED/REMOVED）
• [ ] 需求遵循 ### Requirement: <name> 格式
• [ ] 场景使用 #### Scenario: 格式（四个井号）

**自动化检查**：

统计差异操作（应 > 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 步：提交用户评审

清晰总结提案：

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开发" 或 "按顺序完成任务" 开始实施。

## 进阶主题

**EARS 格式细节**：见 [reference/EARS_FORMAT.md](reference/EARS_FORMAT.md)
**验证模式**：见 [reference/VALIDATION_PATTERNS.md](reference/VALIDATION_PATTERNS.md)
**完整示例**：见 [reference/EXAMPLES.md](reference/EXAMPLES.md)

## 常见模式

### 模式 1：新增功能提案

新增能力时：
- 使用 `ADDED Requirements` 差异
- 同时包含正向场景与错误处理
- 在场景中考虑边界情况

### 模式 2：破坏性变更提案

修改既有行为时：
- 使用 `MODIFIED Requirements` 差异
- 包含完整更新后的需求文本
- 在 proposal.md 中说明变更内容与原因
- 在 tasks.json 中考虑迁移任务

### 模式 3：弃用提案

移除功能时：
- 使用 `REMOVED Requirements` 差异
- 在 proposal.md 中记录移除理由
- 在 tasks.json 中包含清理任务
- 在影响部分考虑用户迁移

## 反模式避免

**不要**：
- 跳过验证检查（务必运行 grep 模式）
- 未先审阅现有规范就创建提案
- 使用含糊的任务描述（如"修一下"）
- 编写不含场景的需求
- 忽略错误处理场景
- 在一个提案中混合多个无关变更

**要**：
- 在创建变更 ID 前检查冲突
- 编写具体、可测试的任务
- 同时包含正向与负向场景
- 一个提案只处理一个关注点
- 在展示前验证结构

## 文件模板

所有模板位于 `templates/` 目录：
- [proposal.md](templates/proposal.md) - 提案结构
- [tasks.json](templates/tasks.json) - 任务清单格式
- [spec-delta.md](templates/spec-delta.md) - 规范差异模板

## 参考资料

- [EARS_FORMAT.md](reference/EARS_FORMAT.md) - 完整 EARS 语法指南
- [VALIDATION_PATTERNS.md](reference/VALIDATION_PATTERNS.md) - Grep/bash 验证
- [EXAMPLES.md](reference/EXAMPLES.md) - 真实提案示例

---

**Token 预算**：此 SKILL.md 约 250 行，低于建议的 500 行上限。引用文件按需加载以逐步呈现。

EARS 格式指南

EARS（Easy Approach to Requirements Syntax）提供了一种结构化格式，用于编写清晰、可测试的需求。

目录

• 需求结构与关键字
• 场景格式（Given/When/Then）
• 需求类型与模式
• 示例与反模式

需求结构

基本格式

### Requirement: {描述性名称}
{TRIGGER 子句},
系统 SHALL {动作与结果}。

触发类型

WHEN（事件驱动）：

### Requirement: 保存用户资料
WHEN 用户点击“保存”按钮,
系统 SHALL 将资料变更持久化到数据库。

IF（状态驱动）：

### Requirement: 免运费
IF 购物车总额超过 $50,
系统 SHALL 免除运费。

WHERE（特定范围）：

### Requirement: 管理员访问
WHERE 用户具有管理员权限,
系统 SHALL 显示管理面板。

WHILE（持续进行）：

### Requirement: 实时同步
WHILE 文档处于打开状态,
系统 SHALL 每 5 秒同步一次更改。

SHALL / SHOULD / MAY

• SHALL：具约束性的需求（必须实现）
• SHOULD：推荐但非强制
• MAY：可选能力

生产环境需求优先使用 SHALL。谨慎使用 SHOULD/MAY。

场景格式

每条需求必须包含展示预期行为的场景。

结构

#### Scenario: {描述性名称}
GIVEN {前置条件}
AND {附加前置条件}
WHEN {动作或触发}
THEN {期望结果}
AND {附加结果}

示例：完整的需求与场景

### Requirement: 用户登录
WHEN 用户提交有效凭据,
系统 SHALL 认证用户并创建会话。

#### Scenario: 登录成功
GIVEN 一个已注册用户，邮箱为 "user@example.com"
AND 用户拥有正确密码 "SecurePass123"
WHEN 用户提交登录表单
THEN 系统创建已认证会话
AND 重定向用户至仪表盘
AND 设置 24 小时过期的会话 Cookie

#### Scenario: 密码错误
GIVEN 一个已注册用户，邮箱为 "user@example.com"
AND 用户提供错误密码 "WrongPass"
WHEN 用户提交登录表单
THEN 系统拒绝登录尝试
AND 显示错误信息 "Invalid email or password"
AND 不创建会话

#### Scenario: 账户被锁定
GIVEN 该账户因失败尝试而被锁定
WHEN 用户提交任意凭据
THEN 系统拒绝登录尝试
AND 显示错误信息 "Account locked. Contact support."

需求模式

模式 1：数据校验

### Requirement: 邮箱格式校验
WHEN 用户输入邮箱地址,
系统 SHALL 验证其格式符合 RFC 5322 标准。

#### Scenario: 合法邮箱
GIVEN 用户输入邮箱 "test@example.com"
WHEN 表单提交
THEN 系统接受该邮箱

#### Scenario: 格式非法
GIVEN 用户输入 "not-an-email"
WHEN 表单提交
THEN 系统显示错误 "Invalid email format"

模式 2：授权

### Requirement: 删除权限
WHERE 用户尝试删除资源,
系统 SHALL 验证用户拥有资源或具备管理员权限。

#### Scenario: 所有者删除
GIVEN 用户拥有文档 ID 123
WHEN 用户请求删除文档 123
THEN 系统删除该文档

#### Scenario: 非所有者被阻止
GIVEN 用户不拥有文档 ID 456
AND 用户不具备管理员权限
WHEN 用户请求删除文档 456
THEN 系统返回 HTTP 403 Forbidden

模式 3：状态流转

### Requirement: 订单处理
WHEN 订单被创建,
系统 SHALL 按状态流转：pending → processing → shipped → delivered。

#### Scenario: 标准流程
GIVEN 新订单处于 "pending" 状态
WHEN 支付确认
THEN 系统流转至 "processing"
WHEN 物品发货
THEN 系统流转至 "shipped"
WHEN 确认送达
THEN 系统流转至 "delivered"

反模式避免

❌ 需求含糊

坏示例：

### Requirement: 高性能
系统应该很快。

好示例：

### Requirement: API 响应时间
WHEN 发起 API 请求,
系统 SHALL 在 95% 的请求中于 200 毫秒内响应。

#### Scenario: 正常负载
GIVEN 系统处于正常负载（< 100 请求/秒）
WHEN 发起 API 请求
THEN 响应时间小于 200ms

❌ 缺少场景

坏示例：

### Requirement: 文件上传
WHEN 用户上传文件,
系统 SHALL 存储它。

好示例：

### Requirement: 文件上传
WHEN 用户上传小于 10MB 的文件,
系统 SHALL 将其存储到 S3 并返回 URL。

#### Scenario: 上传成功
GIVEN 用户选择一个 5MB 的 PDF 文件
WHEN 上传完成
THEN 系统将文件存储到 S3
AND 返回 1 小时有效的签名 URL

#### Scenario: 文件过大
GIVEN 用户选择一个 15MB 的视频文件
WHEN 尝试上传
THEN 系统拒绝该文件
AND 显示错误 "File size exceeds 10MB limit"

❌ 在需求中写实现细节

坏示例：

### Requirement: 密码存储
系统 SHALL 使用 bcrypt，工作因子为 12，并将哈希存储在用户表。

好示例：

### Requirement: 安全的密码存储
WHEN 用户设置密码,
系统 SHALL 在存储前使用业界标准的不可逆哈希进行处理。

#### Scenario: 创建密码
GIVEN 用户设置密码 "SecurePass123"
WHEN 系统处理该密码
THEN 系统仅存储密码的加密哈希
AND 丢弃明文密码
AND 为每位用户使用唯一盐值

（关于 bcrypt/工作因子的实现选择应写在设计文档，而非需求中）

完整示例：用户注册

## ADDED Requirements

### Requirement: 账户创建
WHEN 用户提交包含有效数据的注册表单,
系统 SHALL 创建新账户并发送验证邮件。

#### Scenario: 注册成功
GIVEN 用户提供邮箱 "new@example.com"
AND 提供密码 "SecurePass123"
AND 提供姓名 "John Doe"
AND 该邮箱尚未被注册
WHEN 用户提交注册表单
THEN 系统创建新用户账户
AND 向 "new@example.com" 发送验证邮件
AND 显示信息 "Check your email to verify your account"
AND 重定向至登录页

#### Scenario: 邮箱重复
GIVEN 用户提供邮箱 "existing@example.com"
AND 该邮箱已被注册
WHEN 用户提交注册表单
THEN 系统拒绝注册
AND 显示错误 "This email is already registered"
AND 不发送邮件

#### Scenario: 密码过弱
GIVEN 用户提供密码 "123"
WHEN 用户提交注册表单
THEN 系统拒绝注册
AND 显示错误 "Password must be at least 8 characters"

### Requirement: 邮件验证
WHEN 用户点击验证链接,
系统 SHALL 在令牌有效且未过期时激活账户。

#### Scenario: 令牌有效
GIVEN 用户收到验证邮件
AND 验证令牌未超过 24 小时
WHEN 用户点击验证链接
THEN 系统激活账户
AND 显示信息 "Account verified successfully"
AND 重定向至登录页

#### Scenario: 令牌过期
GIVEN 验证令牌已超过 24 小时
WHEN 用户点击验证链接
THEN 系统拒绝验证
AND 显示信息 "Verification link expired. Request a new one."

摘要清单

编写需求时：

• [ ] 使用 SHALL 表示具约束性需求
• [ ] 包含触发子句（WHEN/IF/WHERE/WHILE）
• [ ] 写清动作与结果
• [ ] 至少包含一个正向场景
• [ ] 包含错误/边界场景
• [ ] 场景使用 Given/When/Then 格式
• [ ] 避免实现细节
• [ ] 使需求可测试

验证模式

使用 grep 与 bash 的模式，在不依赖外部 CLI 工具的情况下验证提案结构。

目录

• 目录结构验证
• 提案文件验证
• 规范差异验证
• 需求格式验证
• 常用验证工作流

目录结构验证

检查变更目录是否存在

# 验证变更目录是否已创建
test -d spec/changes/{change-id} && echo "✓ 目录存在" || echo "✗ 目录缺失"

列出所有变更

# 显示所有进行中的变更
ls -1 spec/changes/ | grep -v "archive"

检查是否有冲突

# 搜索相似的变更 ID
ls spec/changes/ | grep -i "{search-term}"

提案文件验证

检查必需章节

# 验证 proposal.md 是否包含必需章节
grep -c "## Why" spec/changes/{change-id}/proposal.md
grep -c "## What Changes" spec/changes/{change-id}/proposal.md
grep -c "## Impact" spec/changes/{change-id}/proposal.md

预期：每个 grep 返回 1（如果有子章节则可能大于 1）

验证任务文件

# 统计任务数量
grep -c '"task":' spec/changes/{change-id}/tasks.json

# 显示任务列表
grep '"task":' spec/changes/{change-id}/tasks.json

预期：通常为 5-15 个任务

规范差异验证

检查差异操作是否存在

# 统计差异操作标题数量
grep -c "## ADDED\|MODIFIED\|REMOVED" spec/changes/{change-id}/specs/**/*.md

预期：至少 1 个匹配

列出差异操作

# 以行号显示所有差异操作
grep -n "## ADDED\|MODIFIED\|REMOVED" spec/changes/{change-id}/specs/**/*.md

示例输出：

spec/changes/add-auth/specs/authentication/spec-delta.md:3:## ADDED Requirements
spec/changes/add-auth/specs/authentication/spec-delta.md:45:## MODIFIED Requirements

验证各部分是否有内容

# 检查 ADDED 部分是否包含需求
awk '/## ADDED/,/^## [A-Z]/ {if (/### Requirement:/) count++} END {print count}' \
    spec/changes/{change-id}/specs/**/*.md

需求格式验证

检查需求标题

# 列出所有需求标题
grep -n "### Requirement:" spec/changes/{change-id}/specs/**/*.md

期望格式：### Requirement: 描述性名称

验证场景格式

# 检查场景（必须使用四个井号）
grep -n "#### Scenario:" spec/changes/{change-id}/specs/**/*.md

期望格式：#### Scenario: 描述性名称

统计需求与场景数量

# 统计需求数量
REQS=$(grep -c "### Requirement:" spec/changes/{change-id}/specs/**/*.md)

# 统计场景数量
SCENARIOS=$(grep -c "#### Scenario:" spec/changes/{change-id}/specs/**/*.md)

echo "需求数：$REQS"
echo "场景数：$SCENARIOS"
echo "比率：$(echo "scale=1; $SCENARIOS/$REQS" | bc)"

预期：比率 >= 2.0（每个需求至少 2 个场景）

检查 SHALL 关键字

# 验证需求中是否使用 SHALL（具约束性的要求指示）
grep -c "SHALL" spec/changes/{change-id}/specs/**/*.md

预期：SHALL 的数量至少与需求数量相当

完整验证工作流

预提交验证脚本

#!/bin/bash
# 验证变更提案结构

CHANGE_ID="$1"
BASE_PATH="spec/changes/$CHANGE_ID"

echo "正在验证提案：$CHANGE_ID"
echo "================================"

# 1. 目录存在
if [ ! -d "$BASE_PATH" ]; then
    echo "✗ 变更目录未找到"
    exit 1
fi
echo "✓ 变更目录存在"

# 2. 必需文件存在
for file in proposal.md tasks.json; do
    if [ ! -f "$BASE_PATH/$file" ]; then
        echo "✗ 缺少 $file"
        exit 1
    fi
    echo "✓ 找到 $file"
done

# 3. 提案包含必需章节
for section in "## Why" "## What Changes" "## Impact"; do
    if ! grep -q "$section" "$BASE_PATH/proposal.md"; then
        echo "✗ proposal.md 缺少章节：$section"
        exit 1
    fi
done
echo "✓ proposal.md 包含所需章节"

# 4. 任务文件包含 'task' 键
TASK_COUNT=$(grep -c '"task":' "$BASE_PATH/tasks.json" || echo "0")
if [ "$TASK_COUNT" -lt 3 ]; then
    echo "✗ tasks.json 任务数量不足（$TASK_COUNT）"
    exit 1
fi
echo "✓ 找到 $TASK_COUNT 个任务"

# 5. 存在规范差异文件
DELTA_COUNT=$(find "$BASE_PATH/specs" -name "*.md" 2>/dev/null | wc -l)
if [ "$DELTA_COUNT" -eq 0 ]; then
    echo "✗ 未找到规范差异文件"
    exit 1
fi
echo "✓ 找到 $DELTA_COUNT 个规范差异文件"

# 6. 存在差异操作
OPERATIONS=$(grep -h "## ADDED\|MODIFIED\|REMOVED" "$BASE_PATH/specs"/**/*.md 2>/dev/null | wc -l)
if [ "$OPERATIONS" -eq 0 ]; then
    echo "✗ 未发现差异操作"
    exit 1
fi
echo "✓ 找到 $OPERATIONS 个差异操作"

# 7. 需求具备场景
REQ_COUNT=$(grep -h "### Requirement:" "$BASE_PATH/specs"/**/*.md 2>/dev/null | wc -l)
SCENARIO_COUNT=$(grep -h "#### Scenario:" "$BASE_PATH/specs"/**/*.md 2>/dev/null | wc -l)

if [ "$REQ_COUNT" -eq 0 ]; then
    echo "✗ 未找到任何需求"
    exit 1
fi

if [ "$SCENARIO_COUNT" -lt "$REQ_COUNT" ]; then
    echo "⚠ 警告：场景数（$SCENARIO_COUNT）少于需求数（$REQ_COUNT）"
    echo "  建议：每个需求至少包含 2 个场景"
else
    echo "✓ 找到 $REQ_COUNT 个需求，包含 $SCENARIO_COUNT 个场景"
fi

echo "================================"
echo "✓ 验证通过"

用法：

bash validate-proposal.sh add-user-auth

常见问题与修复

问题：缺少场景

检测：

# 查找没有场景的需求
awk '/### Requirement:/ {req=$0; getline; if ($0 !~ /#### Scenario:/) print req}' \
    spec/changes/{change-id}/specs/**/*.md

修复：为每个需求添加场景

问题：场景标题层级错误

检测：

# 查找场景标题井号数量错误（不完全等于 4）
grep -n "^###\? Scenario:\|^#####+ Scenario:" spec/changes/{change-id}/specs/**/*.md

修复：场景必须使用恰好 4 个井号：#### Scenario:

问题：缺少差异操作

检测：

# 检查文件存在需求但无差异操作头
for file in spec/changes/{change-id}/specs/**/*.md; do
    if grep -q "### Requirement:" "$file" && \
       ! grep -q "## ADDED\|MODIFIED\|REMOVED" "$file"; then
        echo "缺少差异操作：$file"
    fi
done

修复：添加适当的差异操作标题（ADDED/MODIFIED/REMOVED）

快速验证命令

一行命令：完整结构检查

# 快速验证变更结构
CHANGE_ID="add-user-auth" && \
test -f spec/changes/$CHANGE_ID/proposal.md && \
test -f spec/changes/$CHANGE_ID/tasks.json && \
grep -q "## ADDED\|MODIFIED\|REMOVED" spec/changes/$CHANGE_ID/specs/**/*.md && \
grep -q "### Requirement:" spec/changes/$CHANGE_ID/specs/**/*.md && \
grep -q "#### Scenario:" spec/changes/$CHANGE_ID/specs/**/*.md && \
echo "✓ 所有验证通过" || echo "✗ 验证失败"

显示提案摘要

# 展示提案概览
CHANGE_ID="add-user-auth"
echo "提案：$CHANGE_ID"
echo "文件数：$(find spec/changes/$CHANGE_ID -type f | wc -l)"
echo "任务数：$(grep -c '\"task\":' spec/changes/$CHANGE_ID/tasks.json)"
echo "需求数：$(grep -h \"### Requirement:\" spec/changes/$CHANGE_ID/specs/**/*.md | wc -l)"
echo "场景数：$(grep -h \"#### Scenario:\" spec/changes/$CHANGE_ID/specs/**/*.md | wc -l)"

验证清单

在面向用户展示提案之前：

手动检查：
- [ ] 变更 ID 描述性且唯一
- [ ] proposal.md 的 Why 部分解释问题
- [ ] proposal.md 的 What 部分列出具体变更
- [ ] proposal.md 的 Impact 部分标识受影响区域
- [ ] tasks.json 含 5-15 个具体、可测试的任务
- [ ] 任务按依赖顺序排列

自动检查：
- [ ] 目录结构存在
- [ ] 必需文件存在（proposal.md、tasks.json、spec-delta.md）
- [ ] 差异操作存在（ADDED/MODIFIED/REMOVED）
- [ ] 需求遵循格式：`### Requirement: 名称`
- [ ] 场景遵循格式：`#### Scenario: 名称`
- [ ] 每个需求至少包含 2 个场景
- [ ] 需求使用 SHALL 关键字

运行所有自动检查：

# 执行验证脚本
bash validate-proposal.sh {change-id}

提案：{变更标题}

Why

[描述问题或机会]

背景：

• [背景点 1]
• [背景点 2]

当前状态：[当前如何工作]

期望状态：[应该如何工作]

What Changes

• [变更 1]
• [变更 2]
• [变更 3]

Impact

受影响的规范

• spec/specs/{capability}/spec.md - [发生哪些变更]

受影响的代码

• src/{module} - [需要实现的内容]

用户影响

• [如适用，说明对用户的影响]

API 变更

• [是否存在破坏性变更]
• [是否新增端点]

需要迁移

• [ ] 数据库迁移
• [ ] API 版本提升
• [ ] 用户沟通
• [ ] 文档更新

时间线评估

[粗略估计：小/中/大，或具体天数]

风险

• [风险 1 与缓解方案]
• [风险 2 与缓解方案]

规范差异：{能力名称}

本文件包含对 spec/specs/{capability}/spec.md 的规范变更。

ADDED 需求

Requirement: {需求名称}

{WHEN/IF 子句描述触发条件} 系统 SHALL {动作与结果}。

Scenario: {正向场景名称}

GIVEN {前置条件} WHEN {动作} THEN {期望结果} AND {附加结果}

Scenario: {错误场景名称}

GIVEN {错误前置条件} WHEN {动作} THEN {期望的错误处理}

---

MODIFIED 需求

Requirement: {现有需求名称}

Previous：{旧行为的简要说明}

{采用 EARS 格式的完整更新需求文本} WHEN {触发条件}, 系统 SHALL {新的动作与结果}。

Scenario: {更新后的场景名称}

GIVEN {新的前置条件} WHEN {动作} THEN {新的期望结果}

---

REMOVED 需求

Requirement: {弃用的需求名称}

移除原因：{弃用原因}

迁移路径：{用户应如何适配}

---

备注

• 对全新能力使用 ADDED
• 修改既有行为时使用 MODIFIED（包含完整更新文本）
• 对弃用功能使用 REMOVED
• 每条需求都应包含场景
• 同时考虑正向与错误场景