openspec-implementation

仕様の実装

承認済みの仕様提案を、適切なテストと検証を行いながら、タスクを順番に実行して体系的に実装します。

クイックスタート

実装では、タスクごとに「読み込む → 実行する → テストする → 検証する」というサイクルを繰り返します。

1. 提案とタスクリストをすべて読む
2. タスクを順番に、1つずつ実行する
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：タスクを順番に実行する

タスクを順番に、1つずつ進めます。

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 行を下回っています。