openspec-implementation

规范实施

通过按顺序执行任务并进行适当的测试和验证，系统地实施已批准的规范提案。

快速开始

每项任务都遵循“阅读 → 执行 → 测试 → 验证”的循环：

1. 阅读完整提案和任务列表
2. 按顺序逐项执行任务
3. 测试每项已完成的任务
4. 只有验证通过后才标记为完成

关键规则：使用 TodoWrite 跟踪进度。切勿跳过任务，也不要将未完成的工作标记为已完成。

工作流

复制此清单并跟踪进度：

Implementation Progress:
- [ ] Step 1: Load and understand the proposal
- [ ] Step 2: Set up TodoWrite task tracking
- [ ] Step 3: Execute tasks sequentially
- [ ] Step 4: Test and validate each task
- [ ] Step 5: Update living specifications (if applicable)
- [ ] Step 6: Mark proposal as implementation-complete

步骤 1：加载并理解提案

开始前，阅读所有背景信息：

# Read the proposal
cat spec/changes/{change-id}/proposal.md

# Read all tasks
cat spec/changes/{change-id}/tasks.md

# Read spec deltas to understand requirements
find spec/changes/{change-id}/specs -name "*.md" -exec cat {} \;

理解以下内容：

• 为什么需要此变更（见 proposal.md）
• 预期结果是什么
• 哪些规范会受到影响
• 验收标准是什么（见场景）

步骤 2：设置 TodoWrite 任务跟踪

开始工作前，将 tasks.md 中的任务加载到 TodoWrite：

**Pattern**:
Read tasks.md → Extract numbered list → Create TodoWrite entries

**Example**:
If tasks.md contains:
1. Create database migration
2. Implement API endpoint
3. Add tests
4. Update documentation

Then create TodoWrite with:
- content: "Create database migration", status: "in_progress"
- content: "Implement API endpoint", status: "pending"
- content: "Add tests", status: "pending"
- content: "Update documentation", status: "pending"

这样做的重要原因：TodoWrite 能让用户了解进度，并确保不会遗漏任何任务。

步骤 3：按顺序执行任务

按顺序逐项处理任务：

For each task:
1. Mark as "in_progress" in TodoWrite
2. Execute the work
3. Test the work
4. Only mark "completed" after verification

NEVER skip ahead or batch multiple tasks before testing.

任务执行模式：

## Task: {Task Description}

**What**: [Brief explanation of what this task does]

**Implementation**:
[Code changes, file edits, commands run]

**Verification**:
[How to verify this task is complete]
- [ ] Code compiles/runs
- [ ] Tests pass
- [ ] Meets requirement scenarios

**Status**: ✓ Complete / ✗ Blocked / ⚠ Partial

步骤 4：测试并验证每项任务

每项任务完成后，都要验证其是否正常工作：

代码任务：

# Run relevant tests
npm test # or pytest, cargo test, etc.

# Run linter
npm run lint

# Check types (if applicable)
npm run type-check

数据库任务：

# Verify migration runs
npm run db:migrate

# Check schema matches expected
npm run db:schema

API 任务：

# Test endpoint manually
curl -X POST http://localhost:3000/api/endpoint \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}'

# Or run integration tests
npm run test:integration

只有通过所有验证后，才能将任务标记为完成。

步骤 5：更新持续维护的规范（如适用）

实施期间，如果发现规范差异需要更新：

1. 记录发现，写入 proposal.md 或备注文件
2. 实施期间不要修改规范差异
3. 实施完成后，再考虑是否需要调整规范

注意：规范差异会在归档期间（步骤 6）合并，而不是在实施期间合并。

步骤 6：将提案标记为实施完成

所有任务完成后：

# Create a completion marker
echo "Implementation completed: $(date)" > spec/changes/{change-id}/IMPLEMENTED

告知用户：

## Implementation Complete

**Change**: {change-id}
**Tasks completed**: {count}
**Tests**: All passing

**Next step**: Archive this change to merge spec deltas into living documentation.
Say "openspec archive {change-id}" or "archive this change" when ready.

最佳实践

模式 1：受阻任务

如果无法完成某项任务：

**Mark as blocked**:
- Keep status as "in_progress" (NOT "completed")
- Document the blocker clearly
- Create a new task for resolving the blocker
- Inform the user immediately

**Example**:
Task: "Implement payment processing"
Blocker: "Missing API credentials for payment gateway"
Action: Create new task "Obtain payment gateway credentials"

模式 2：任务依赖关系

如果任务之间存在依赖关系，开始前请验证前置条件：

# Example: Database migration must run before API code
# Check migration status
npm run db:status

# Only proceed with API task if migration succeeded

模式 3：增量测试

逐步测试，不要等到最后再测试：

正确做法：

Task 1: Create model → Test model → Mark complete
Task 2: Create API → Test API → Mark complete
Task 3: Add validation → Test validation → Mark complete

错误做法：

Task 1, 2, 3 → Implement all → Test everything → Debug failures

模式 4：持续维护文档

随时更新 README、API 文档和注释：

When adding a new API endpoint, also:
- Update API documentation
- Add example request/response
- Update OpenAPI/Swagger spec
- Add inline code comments

进阶主题

并行工作：如果任务确实互不依赖（例如，涉及不同模块），可以并行处理，但必须分别测试每项任务。

集成点：如果任务存在依赖关系，请使用集成测试验证连接是否正常。

回滚策略：对于高风险变更，请在部署前创建回滚任务。

常见模式

模式 1：数据库 + API + UI

典型顺序：

1. 数据库架构/迁移
2. 数据访问层（模型）
3. 业务逻辑层（服务）
4. API 端点（控制器）
5. UI 集成
6. 端到端测试

模式 2：功能开关

逐步推出功能时：

1. 在开关控制下实施功能
2. 在启用开关的情况下测试
3. 在禁用开关的情况下部署
4. 逐步启用开关
5. 全面推出后移除开关

模式 3：破坏性变更

对于会造成破坏性影响的 API 变更：

1. 实施新版本（v2）
2. 确保旧版本（v1）继续正常工作
3. 为 v1 添加弃用警告
4. 将用户迁移到 v2
5. 移除 v1（单独的任务/提案）

应避免的反模式

不要：

• 跳过对单项任务的测试
• 验证前就将任务标记为完成
• 忽略失败的测试（“以后再修”）
• 在测试前累积多个任务
• 在实施期间修改持续维护的规范
• 不按顺序工作（依赖关系会因此出问题）

应该：

• 立即测试每项任务
• 继续之前先修复失败的测试
• 实时更新 TodoWrite
• 清楚记录阻塞问题
• 向用户同步进度
• 保持提交原子化且描述清晰

故障排除

问题：任务完成后测试失败

解决方案：

1. Do NOT mark task complete
2. Debug the failure
3. Fix the code
4. Re-run tests
5. Only mark complete after pass

问题：任务过大

解决方案：

1. Break into subtasks
2. Update TodoWrite with subtasks
3. Complete subtasks sequentially
4. Mark parent task complete after all subtasks done

问题：未满足依赖项

解决方案：

1. Pause current task
2. Complete dependency first
3. Test dependency
4. Resume original task

参考资料

• TASK_PATTERNS.md - 常见任务执行模式
• TESTING_STRATEGIES.md - 按任务类型划分的测试方法

---

令牌预算：此 SKILL.md 约有 430 行，低于建议的 500 行上限。