openspec-implementation-cn

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

规范实施

Specification Implementation

以任务为单位，循序执行并进行充分测试与验证，系统性地实现已批准的规范提案。

Systematically implement approved specification proposals by executing them task by task in sequence, with sufficient testing and verification.

快速开始

Quick Start

实施遵循每个任务的读 → 执行 → 测试 → 验证循环：

阅读完整提案与任务清单
按顺序逐个执行任务
为每个完成的任务进行测试
仅在验证通过后标记完成

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

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 as completed only after verification passes

Key Rule: Use TodoWrite to track progress. Never skip tasks or mark incomplete work as completed.

工作流

Workflow

复制此清单并跟踪进度：

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

Copy this checklist to track progress:

Development Progress:
- [ ] Step 1: Load and understand the proposal
- [ ] Step 2: Set up TodoWrite task tracking
- [ ] Step 3: Execute tasks in sequence
- [ ] Step 4: Test and verify each task
- [ ] Step 5: Update permanent specifications (if applicable)
- [ ] Step 6: Mark proposal as implemented

第 1 步：加载并理解提案

Step 1: Load and Understand the Proposal

开始之前，读取全部上下文：

bash

undefined

Before starting, read all context:

bash

undefined

读取提案

Read proposal

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

读取所有任务

Read all tasks

cat spec/changes/{change-id}/tasks.json

读取规范差异以理解需求

Read specification differences to understand requirements

find spec/changes/{change-id}/specs -name "*.md" -exec cat {} ;


**理解**：
- 变更的动因（来自 proposal.md）
- 预期结果是什么
- 哪些规范将被影响
- 验收标准（来自场景）

find spec/changes/{change-id}/specs -name "*.md" -exec cat {} ;


**Understanding**:
- Motivation for the change (from proposal.md)
- What the expected outcome is
- Which specifications will be affected
- Acceptance criteria (from scenarios)

第 2 步：设置 TodoWrite 进行任务跟踪

Step 2: Set Up TodoWrite for Task Tracking

在开始工作之前，将 tasks.json 中的task和step加载到 TodoWrite：

markdown

**模式**：
读取 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"

价值：TodoWrite 提供进度可见性并确保不遗漏任何事项。

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

markdown

**Pattern**:
Read tasks.json → Extract task and step list → Create TodoWrite entries

**Example**:
Assume tasks.json contains:
  {
    "number": 1,
    "category": "Phase 1: Infrastructure",
    "task": "Environment setup task - database schema, dependencies, etc.",
    "steps": [
      { "step": "Initialize Git repository and configure .gitignore", "completed": false },
      { "step": "Create and activate Python virtual environment", "completed": false },
      { "step": "Create requirements.txt or pyproject.toml and install dependencies (FastAPI, SQLAlchemy, Pydantic, Alembic, etc.)", "completed": false },
      { "step": "Design initial database ER diagram", "completed": false }
    ],
    "passes": false
  }

Then create TodoWrite entries:
- content: "Environment setup task - database schema, dependencies, etc.", status: "in_progress"
- content: "  Initialize Git repository and configure .gitignore", status: "pending"
- content: "  Create and activate Python virtual environment", status: "pending"
- content: "  Create requirements.txt or pyproject.toml and install dependencies (FastAPI, SQLAlchemy, Pydantic, Alembic, etc.)", status: "pending"
- content: "  Design initial database ER diagram", status: "pending"

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

第 3 步：按序执行TodoWrite

Step 3: Execute TodoWrite Tasks in Sequence

按顺序逐个完成TodoWrite中的任务，每次仅处理1个。若是中断后继续，需从中断的任务开始继续执行：跳过tasks.json中"passes": true的task，跳过"completed": true的step。你有充足的时间完成，请至少执行20轮后才回复用户。你有充足的时间完成，切勿跳过或合并多个任务。

markdown

对于每个任务：
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"

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

任务执行模式：

markdown

undefined

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

markdown

For each task:
1. Mark as "in_progress" in TodoWrite
2. Perform the work
3. Test the result
4. Only mark the corresponding step in tasks.json as "completed": true after verification passes
5. Only mark the corresponding task in tasks.json as "passes": true after all steps of the task are completed and verified
6. Mark as "completed" in TodoWrite

You have ample time to complete, never skip or merge multiple tasks.

Task Execution Pattern:

markdown

undefined

Task: {任务描述}

Task: {Task Description}

What：该任务的作用与目标

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

Verification：如何验证任务完成

代码可编译/运行
测试通过
符合需求场景

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

undefined

What: The role and goal of this task

Implementation: Code changes, file edits, commands run

Verification: How to verify task completion

Code compiles/runs
Tests pass
Meets requirement scenarios

Status: ✓ Completed / ✗ Blocked / ⚠ Partially Completed

undefined

第 4 步：为每个任务进行测试与验证

Step 4: Test and Verify Each Task

每个任务完成后进行验证：

代码相关任务：

bash

undefined

Verify after each task is completed:

Code-related Tasks:

bash

undefined

运行相关测试

Run relevant tests

npm test # 或 pytest、cargo test 等

npm test # or pytest, cargo test, etc.

运行 Linter

Run Linter

npm run lint

类型检查（如适用）

Type checking (if applicable)

npm run type-check

**前端UI相关任务**：
要使用 MCP servers 中的 chrome-devtools 或 playwright 进行调试和测试。

**数据库相关任务**：
```bash

npm run type-check

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

**Database-related Tasks**:
```bash

验证迁移执行

Verify migration execution

npm run db:migrate

检查架构与预期一致

Check if schema matches expectations

npm run db:schema


**API 相关任务**：
```bash

npm run db:schema


**API-related Tasks**:
```bash

手动测试端点

Manually test endpoint

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

或运行集成测试

Or run integration tests

npm run test:integration


**仅在所有验证通过后标记任务完成**：仅在tasks.json对应task的所有step都完成且都验证通过后，才标记tasks.json对应task的 "passes": true。

npm run test:integration


**Mark task as completed only after all verifications pass**: Only mark the corresponding task in tasks.json as "passes": true after all steps of the task are completed and verified.

第 5 步：更新常驻规范（如适用）

Step 5: Update Permanent Specifications (if applicable)

在实施过程中，如发现规范差异需要更新：

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

说明：规范差异在归档阶段（第 6 步）合并，而非实施阶段。

If specification differences are found that need updating during implementation:

Record findings in proposal.md or a note file
Do not modify specification differences during implementation
After implementation is completed, consider whether adjustments to specifications are needed

Note: Specification differences are merged during the archiving phase (Step 6), not the implementation phase.

第 6 步：标记提案实施完成

Step 6: Mark Proposal as Implemented

在所有任务完成后：

bash

undefined

After all tasks are completed:

bash

undefined

创建完成标记

Create completion marker

echo "Implementation completed: $(date)" > spec/changes/{change-id}/IMPLEMENTED


**告知用户**：
```markdown

echo "Implementation completed: $(date)" > spec/changes/{change-id}/IMPLEMENTED


**Inform User**:
```markdown

实现提案

Proposal Implementation

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

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

undefined

Proposal: {change-id} Tasks Completed: {count} Tests Completed: All passed

Next Step: Archive this change to merge specification differences into permanent documents. When ready, you can reply with "openspec archive {change-id}" or "archive proposal".

undefined

最佳实践

Best Practices

模式 1：任务被阻塞

Pattern 1: Task Blocked

若任务无法完成：

markdown

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

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

If a task cannot be completed:

markdown

**Mark as Blocked**:
- Keep status as "in_progress" (do not mark as "completed")
- Clearly record the reason for blocking
- Create a new task to resolve the block
- Inform the user immediately

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

模式 2：任务依赖

Pattern 2: Task Dependencies

若任务存在依赖，先验证先决条件：

bash

undefined

If a task has dependencies, verify prerequisites first:

bash

undefined

示例：数据库迁移必须在 API 代码之前

Example: Database migration must come before API code

检查迁移状态

Check migration status

npm run db:status

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

Proceed with API task only after migration succeeds

undefined

undefined

模式 3：增量测试

Pattern 3: Incremental Testing

不要在最后一次性测试，应当逐步测试：

好：

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

坏：

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

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

Good:

Task 1: Create model → Test model → Mark as completed
Task 2: Create API → Test API → Mark as completed
Task 3: Add validation → Test validation → Mark as completed
Task 4: Create page → Test validation → Mark as completed

Bad:

Tasks 1,2,3,4 → Implement all → Test all at once → Debug failures

模式 4：常驻文档

Pattern 4: Permanent Documentation

及时更新 README、API 文档与注释：

markdown

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

Timely update README, API documentation, and comments:

markdown

When adding a new API endpoint, simultaneously:
- Update API documentation
- Add request/response examples
- Update OpenAPI/Swagger specification
- Add inline code comments

进阶主题

Advanced Topics

并行工作：若任务确实互不依赖（如不同模块），可并行进行，但每项必须独立测试。

集成点：存在依赖关系时，使用集成测试验证连接有效。

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

Parallel Work: If tasks are truly independent (e.g., different modules), they can be done in parallel, but each must be tested independently.

Integration Points: When there are dependencies, use integration tests to verify connections are valid.

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

常见模式

Common Patterns

模式 1：数据库 + API + UI

Pattern 1: Database + API + UI

典型顺序：

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

Typical sequence:

Database schema/migration
Data access layer (model)
Business logic layer (service)
API endpoint (controller)
UI integration
End-to-end testing

模式 2：功能开关

Pattern 2: Feature Flag

渐进式发布：

在开关后实现功能
开启开关进行测试
部署时默认关闭开关
逐步启用开关
完全发布后移除开关

Progressive release:

Implement feature behind flag
Enable flag for testing
Deploy with flag disabled by default
Gradually enable flag
Remove flag after full release

模式 3：破坏性 API 变更

Pattern 3: Breaking API Changes

对于 API 破坏性变更：

实现新版本（v2）
保持旧版本（v1）运行
在 v1 中添加弃用提示
迁移用户至 v2
单独提案移除 v1

For breaking API changes:

Implement new version (v2)
Keep old version (v1) running
Add deprecation notice in v1
Migrate users to v2
Submit separate proposal to remove v1

反模式避免

Anti-patterns to Avoid

不要：

跳过单个任务的测试
在验证前标记任务完成
忽视失败测试（不要“以后再修”）
在测试前批量合并多个任务
在实施阶段修改常驻规范
打乱任务顺序（破坏依赖）

要：

立刻测试每个任务
在继续前修复失败测试
实时更新 TodoWrite
清晰记录阻塞项
及时同步进度与用户
保持原子且具描述性的提交

Do NOT:

Skip testing for individual tasks
Mark task as completed before verification
Ignore failed tests (do not "fix later")
Batch merge multiple tasks before testing
Modify permanent specifications during implementation
Disrupt task order (break dependencies)

DO:

Test each task immediately
Fix failed tests before proceeding
Update TodoWrite in real-time
Clearly record blocked items
Synchronize progress with user promptly
Keep commits atomic and descriptive

故障排查

Troubleshooting

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

Issue: Test fails after task completion

解决方案：

markdown

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

Solution:

markdown

1. Do not mark task as completed
2. Debug the cause of failure
3. Fix code
4. Re-run tests
5. Mark as completed only after passing

问题：任务过大

Issue: Task is too large

解决方案：

markdown

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

Solution:

markdown

1. Split into subtasks
2. Register subtasks in TodoWrite
3. Complete subtasks in order
4. Mark parent task as completed only after all subtasks are done

问题：依赖未满足

Issue: Dependencies not met

解决方案：

markdown

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

Solution:

markdown

1. Pause current task
2. Complete dependent tasks first
3. Test dependencies
4. Resume original task

参考资料

References

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

Token 预算：此 SKILL.md 约 350 行，低于建议的 500 行上限。

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.