openspec-implementation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Specification Implementation

规范实现

Systematically implements approved spec proposals by executing tasks sequentially with proper testing and validation.

通过按顺序执行任务并配合恰当的测试与验证，系统性地实现已获批的规范提案。

Quick Start

快速开始

Implementation follows a read → execute → test → validate cycle for each task:

Read the full proposal and task list
Execute tasks one at a time, in order
Test each completed task
Mark complete only after verification

Critical rule: Use TodoWrite to track progress. Never skip tasks or mark incomplete work as done.

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

完整阅读提案和任务列表
按顺序逐个执行任务
测试每个已完成的任务
仅在验证通过后标记任务完成

核心规则：使用TodoWrite跟踪进度。绝不能跳过任务或把未完成的工作标记为已完成。

Workflow

工作流程

Copy this checklist and track progress:

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

复制以下检查清单并跟踪进度：

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

Step 1: Load and understand the proposal

步骤1：加载并理解提案

Before starting, read all context:

bash

undefined

开始工作前，阅读所有相关内容：

bash

undefined

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 {} ;


**Understand**:
- Why this change is needed (from proposal.md)
- What the expected outcomes are
- Which specs will be affected
- What the acceptance criteria are (from scenarios)

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


**需要理解的内容**：
- 为什么需要此变更（来自proposal.md）
- 预期成果是什么
- 哪些规范会受到影响
- 验收标准是什么（来自场景说明）

Step 2: Set up TodoWrite task tracking

步骤2：设置TodoWrite任务跟踪

Load tasks from tasks.md into TodoWrite before starting work:

markdown

**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"

Why this matters: TodoWrite gives the user visibility into progress and ensures nothing gets skipped.

在开始工作前，将tasks.md中的任务导入TodoWrite：

markdown

**模式**:
读取tasks.md → 提取编号列表 → 创建TodoWrite条目

**示例**:
如果tasks.md包含：
1. Create database migration
2. Implement API endpoint
3. Add tests
4. Update documentation

则在TodoWrite中创建：
- content: "Create database migration", status: "in_progress"
- content: "Implement API endpoint", status: "pending"
- content: "Add tests", status: "pending"
- content: "Update documentation", status: "pending"

重要性：TodoWrite能让用户清晰看到进度，确保没有任务被遗漏。

Step 3: Execute tasks sequentially

步骤3：按顺序执行任务

Work through tasks one at a time, in order:

markdown

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 execution pattern:

markdown

undefined

按顺序逐个处理任务：

markdown

对于每个任务：
1. 在TodoWrite中标记为"in_progress"
2. 执行任务工作
3. 测试工作成果
4. 仅在验证通过后标记为"completed"

绝对不能提前跳过任务，也不能在测试前批量执行多个任务。

任务执行模板:

markdown

undefined

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

undefined

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

undefined

Step 4: Test and validate each task

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

After each task, verify it works:

For code tasks:

bash

undefined

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

针对代码任务:

bash

undefined

Run relevant tests

npm test # or pytest, cargo test, etc.

Run linter

npm run lint

Check types (if applicable)

npm run type-check


**For database tasks**:
```bash

npm run type-check


**针对数据库任务**:
```bash

Verify migration runs

npm run db:migrate

Check schema matches expected

npm run db:schema


**For API tasks**:
```bash

npm run db:schema


**针对API任务**:
```bash

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


**Only mark task complete after all verifications pass**.

npm run test:integration


**仅在所有验证通过后，才能标记任务完成**。

Step 5: Update living specifications (if applicable)

步骤5：更新动态规范（如适用）

During implementation, if you discover the spec deltas need updates:

Document the discovery in proposal.md or a notes file
Do NOT modify spec deltas during implementation
After implementation completes, consider whether spec needs adjustment

Note: Spec deltas are merged during archiving (Step 6), not during implementation.

在实施过程中，如果发现规范增量需要更新：

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

注意：规范增量会在归档阶段（步骤6）合并，而非实施期间。

Step 6: Mark proposal as implementation-complete

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

After all tasks are complete:

bash

undefined

所有任务完成后：

bash

undefined

Create a completion marker

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


**Tell the user**:
```markdown

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


**告知用户**:
```markdown

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.

undefined

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.

undefined

Best Practices

最佳实践

Pattern 1: Blocked Tasks

模式1：阻塞的任务

If a task cannot be completed:

markdown

**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"

如果某个任务无法完成：

markdown

**标记为阻塞**:
- 保持状态为"in_progress"（不要设为"completed"）
- 清晰记录阻塞原因
- 创建一个新任务来解决阻塞问题
- 立即通知用户

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

Pattern 2: Task Dependencies

模式2：任务依赖

If tasks have dependencies, verify prerequisites before starting:

bash

undefined

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

bash

undefined

Example: Database migration must run before API code

Check migration status

npm run db:status

Only proceed with API task if migration succeeded

undefined

undefined

Pattern 3: Incremental Testing

模式3：增量测试

Test incrementally, not at the end:

Good:

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

Bad:

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

逐步测试，而非最后一次性测试：

正确做法:

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

Pattern 4: Living Documentation

模式4：动态文档

Keep README, API docs, and comments up to date as you go:

markdown

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

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

markdown

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

Advanced Topics

进阶话题

Parallel work: If tasks are truly independent (e.g., separate modules), you can work on them in parallel, but each must be tested independently.

Integration points: When task dependencies exist, use integration tests to verify the connection works.

Rollback strategy: For risky changes, create rollback tasks before deploying.

并行工作：如果任务完全独立（例如不同模块），可以并行处理，但每个任务必须独立测试。

集成点：当任务存在依赖时，使用集成测试验证连接是否正常工作。

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

Common Patterns

常见模式

Pattern 1: Database + API + UI

模式1：数据库 + API + UI

Typical order:

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

典型顺序：

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

Pattern 2: Feature Flags

模式2：功能开关

For gradual rollouts:

Implement feature behind flag
Test with flag enabled
Deploy with flag disabled
Enable flag incrementally
Remove flag after full rollout

用于逐步发布：

在开关后实现功能
测试开关开启的状态
部署时保持开关关闭
逐步开启开关
全面发布后移除开关

Pattern 3: Breaking Changes

模式3：破坏性变更

For API breaking changes:

Implement new version (v2)
Keep old version (v1) working
Add deprecation warnings to v1
Migrate users to v2
Remove v1 (separate task/proposal)

针对API的破坏性变更：

实现新版本（v2）
保持旧版本（v1）可用
为v1添加弃用警告
迁移用户到v2
移除v1（单独的任务/提案）

Anti-Patterns to Avoid

需避免的反模式

Don't:

Skip testing individual tasks
Mark tasks complete before verification
Ignore failing tests ("I'll fix it later")
Batch multiple tasks before testing
Modify living specs during implementation
Work out of order (dependencies break)

Do:

Test each task immediately
Fix failing tests before proceeding
Update TodoWrite in real-time
Document blockers clearly
Communicate progress to user
Keep commits atomic and descriptive

不要:

跳过单个任务的测试
验证前标记任务完成
忽略失败的测试（“以后再修复”）
测试前批量执行多个任务
实施期间修改动态规范
不按顺序工作（依赖关系会断裂）

要:

立即测试每个任务
修复失败的测试后再继续
实时更新TodoWrite
清晰记录阻塞问题
向用户同步进度
保持提交的原子性和描述性

Troubleshooting

故障排除

Issue: Tests failing after task completion

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

Solution:

markdown

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

解决方案:

markdown

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

Issue: Task is too large

问题：任务过大

Solution:

markdown

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

解决方案:

markdown

1. 拆分为子任务
2. 在TodoWrite中更新子任务
3. 按顺序完成子任务
4. 所有子任务完成后标记父任务完成

Issue: Dependency not met

问题：依赖未满足

Solution:

markdown

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

解决方案:

markdown

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

Reference Materials

参考资料

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

Token budget: This SKILL.md is approximately 430 lines, under the 500-line recommended limit.

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

Token预算: 此SKILL.md约430行，低于推荐的500行限制。