openspec-implementation-cn

Spec Implementation

Systematically implement approved spec proposals by executing sequentially task by task with thorough testing and verification.

Quick Start

Implementation follows the Read → Execute → Test → Verify cycle for each task:

Read the complete proposal and task list
Execute tasks one by one in order
Test each completed task
Mark complete only after verification passes

Key Rules: Use TodoWrite to track progress. Never skip tasks or mark unfinished work as complete.

Workflow

Copy this checklist and track progress:

开发进度:
- [ ] 第 1 步：加载并理解提案
- [ ] 第 2 步：设置 TodoWrite 任务跟踪
- [ ] 第 3 步：按序执行任务
- [ ] 第 4 步：为每个任务进行测试与验证
- [ ] 第 5 步：更新常驻规范（如果适用）
- [ ] 第 6 步：标记提案为实施完成

Step 1: Load and Understand the Proposal

Before starting, read all context:

# 读取提案
cat spec/changes/{change-id}/proposal.md

# 读取所有任务
cat spec/changes/{change-id}/tasks.json

# 读取规范差异以理解需求
find spec/changes/{change-id}/specs -name "*.md" -exec cat {} \;

Understand：

The motivation for the change (from proposal.md)
What the expected outcome is
Which specs will be affected
Acceptance criteria (from scenarios)

Step 2: Set Up TodoWrite for Task Tracking

Before starting work, load the tasks and steps from tasks.json into TodoWrite:

**模式**：
读取 tasks.json → 提取task和step列表 → 创建 TodoWrite 条目

**示例**：
假设 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 }
    ],
    "passes": false
  }

则创建 TodoWrite：
- content: "环境搭建任务 - 数据库架构、依赖等", status: "in_progress"
- content: "  初始化 Git 仓库并配置 .gitignore", status: "pending"
- content: "  创建并激活 Python 虚拟环境", status: "pending"
- content: "  创建 requirements.txt 或 pyproject.toml 并安装依赖 (FastAPI, SQLAlchemy, Pydantic, Alembic 等)", status: "pending"
- content: "  设计初始数据库 ER 图", status: "pending"

Value: TodoWrite provides progress visibility and ensures nothing is missed.

Step 3: Execute TodoWrite in Order

Complete the tasks in TodoWrite one by one in order, handling only 1 at a time. If resuming after an interruption, continue from the interrupted task: skip tasks with "passes": true in tasks.json, and skip steps with "completed": true. You have plenty of time to complete this, so please execute at least 20 rounds before replying to the user. You have plenty of time to complete this; never skip or merge multiple tasks.

对于每个任务：
1. 在 TodoWrite 中标记为 "in_progress"
2. 执行工作
3. 测试结果
4. 仅在验证通过后，才标记tasks.json对应task的对应step的 "completed": true
5. 仅在tasks.json对应task的所有step都完成且都验证通过后，才标记tasks.json对应task的 "passes": true
6. 在 TodoWrite 中标记为 "completed"

你有充足的时间完成，切勿跳过或合并多个任务。

Task Execution Patterns：

## Task: {任务描述}

**What**：该任务的作用与目标

**Implementation**：
代码变更、文件编辑、运行的命令

**Verification**：
如何验证任务完成
- [ ] 代码可编译/运行
- [ ] 测试通过
- [ ] 符合需求场景

**Status**：✓ 完成 / ✗ 阻塞 / ⚠ 部分完成

Step 4: Test and Verify Each Task

Verify after each task is completed:

Code-related tasks：

# 运行相关测试
npm test # 或 pytest、cargo test 等

# 运行 Linter
npm run lint

# 类型检查（如适用）
npm run type-check

Frontend UI-related tasks: Use chrome-devtools or playwright in MCP servers for debugging and testing.

Database-related tasks：

# 验证迁移执行
npm run db:migrate

# 检查架构与预期一致
npm run db:schema

API-related tasks：

# 手动测试端点
curl -X POST http://localhost:3000/api/endpoint \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}'

# 或运行集成测试
npm run test:integration

Mark a task complete only after all verification passes: Only after all steps of the corresponding task in tasks.json are completed and all have passed verification should you mark the corresponding task in tasks.json as "passes": true.

Step 5: Update Living Specs (if applicable)

During implementation, if spec discrepancies are found that need updating:

In proposal.md or a notes fileRecord the finding
Do not modify during implementationspec discrepancies
After implementation is complete, then consider whether the spec needs adjustment

Note: Spec discrepancies are merged during the archive phase (Step 6), not during the implementation phase.

Step 6: Mark the Proposal Implementation Complete

After all tasks are complete:

# 创建完成标记
echo "Implementation completed: $(date)" > spec/changes/{change-id}/IMPLEMENTED

Notify the user：

## 实现提案

**提案**：{change-id}
**完成任务**：{数量}
**完成测试**：全部通过

**下一步**：将该变更归档以合并规范差异到常驻文档。
准备好后可回复 "openspec归档 {change-id}" 或 "归档提案"。

Best Practices

Pattern 1: Task Is Blocked

If a task cannot be completed:

**标记为阻塞**：
- 状态保持 "in_progress"（不要标记为 "completed"）
- 清晰记录阻塞原因
- 创建新的任务以解决阻塞
- 立即告知用户

**示例**：
任务："实现支付处理"
阻塞："缺少支付网关 API 凭据"
行动：创建新任务 "获取支付网关凭据"

Pattern 2: Task Dependencies

If tasks have dependencies, verify prerequisites first:

# 示例：数据库迁移必须在 API 代码之前
# 检查迁移状态
npm run db:status

# 仅在迁移成功后继续 API 任务

Pattern 3: Incremental Testing

Do not test all at once at the end; test progressively:

Good：

任务 1：创建模型 → 测试模型 → 标记完成
任务 2：创建 API → 测试 API → 标记完成
任务 3：添加校验 → 测试校验 → 标记完成
任务 4：创建页面 → 测试校验 → 标记完成

Bad：

任务 1、2、3、4 → 全部实现 → 一次性测试 → 调试失败

Pattern 4: Living Documentation

Promptlyupdate README, API docs, and comments:

添加新 API 端点时，同时：
- 更新 API 文档
- 添加请求/响应示例
- 更新 OpenAPI/Swagger 规范
- 添加内联代码注释

Advanced Topics

Parallel Work: If tasks truly do not depend on each other (such as different modules), they can proceed in parallel, but each must be tested independently.

Integration Points: When dependencies exist, use integration tests to verify that connections work.

Rollback Strategy: For high-risk changes, create a rollback task before deployment.

Common Patterns

Pattern 1: Database + API + UI

Typical order:

Database schema/migration
Data access layer (models)
Business logic layer (services)
API endpoints (controllers)
UI integration
End-to-end testing

Pattern 2: Feature Flags

Progressive rollout:

Implement the feature behind a flag
Enable the flag for testing
Keep the flag disabled by default at deployment
Enable the flag gradually
Remove the flag after full release

Pattern 3: Breaking API Changes

For breaking API changes:

Implement the new version (v2)
Keep the old version (v1) running
Add deprecation notices in v1
Migrate users to v2
Propose removal of v1 separately

Anti-Pattern Avoidance

Do not：

Skip testing of individual tasks
Mark tasks complete before verification
Ignore failing tests (do not "fix later")
Batch-merge multiple tasks before testing
Modify living specifications during the implementation phase
Scramble the task order (break dependencies)

Do：

Test each task immediately
Fix failing tests before continuing
Update TodoWrite in real time
Clearly document blockers
Sync progress with the user in a timely manner
Keep commits atomic and descriptive

Troubleshooting

Problem: Tests fail after task completion

Solution：

1. 不要标记任务完成
2. 调试失败原因
3. 修复代码
4. 重新运行测试
5. 仅在通过后标记完成

Problem: Task is too large

Solution：

1. 拆分为子任务
2. 在 TodoWrite 中登记子任务
3. 依序完成子任务
4. 在全部子任务完成后标记父任务完成

Problem: Dependencies are not satisfied

Solution：

1. 暂停当前任务
2. 先完成依赖任务
3. 测试依赖项
4. 恢复原任务

References

TASK_PATTERNS.md - Common task execution patterns
TESTING_STRATEGIES.md - Testing methods by task type

Token Budget: This SKILL.md is about 350 lines, below the recommended 500-line limit.

About this skill

Quick Start

Workflow

Step 1: Load and Understand the Proposal

Step 2: Set Up TodoWrite for Task Tracking

Step 3: Execute TodoWrite in Order

Step 4: Test and Verify Each Task

Step 5: Update Living Specs (if applicable)

Step 6: Mark the Proposal Implementation Complete

Best Practices

Pattern 1: Task Is Blocked

Pattern 2: Task Dependencies

Pattern 3: Incremental Testing

Pattern 4: Living Documentation

Advanced Topics

Common Patterns

Pattern 1: Database + API + UI

Pattern 2: Feature Flags

Pattern 3: Breaking API Changes

Anti-Pattern Avoidance

Troubleshooting

Problem: Tests fail after task completion

Problem: Task is too large

Problem: Dependencies are not satisfied

References