writing-plans

実装計画の作成

概要

実装者がコードベースについて何も知らず、判断力にも不安があることを前提に、包括的な実装計画を作成します。必要な情報をすべて記載してください。変更するファイル、コード全体、テストコマンド、確認すべきドキュメント、検証方法を盛り込みます。作業は小さなタスクに分割してください。DRY。YAGNI。TDD。こまめにコミットします。

実装者は優れた開発者ですが、ツールセットや問題領域についてほとんど知らないと想定してください。また、適切なテスト設計についても、十分に理解していないと想定してください。

基本原則： 優れた計画を読めば、実装方法が明らかになります。推測が必要なら、その計画は不完全です。

使用するタイミング

以下の前には必ず使用してください：

• 複数ステップからなる機能の実装
• 複雑な要件の細分化
• subagent-driven-development を介したサブエージェントへの委任

以下の場合も省略しないでください：

• 機能が簡単に見える場合（思い込みがバグの原因になります）
• 自分で実装する予定の場合（未来の自分にもガイドが必要です）
• 1人で作業する場合（ドキュメントは重要です）

小さなタスクへの分割

各タスクは、集中して取り組んで2〜5分で終わるものにしてください。

各ステップでは、1つの作業だけを行います。

• 「失敗するテストを書く」— ステップ
• 「失敗することを確認するために実行する」— ステップ
• 「テストを通すための最小限のコードを実装する」— ステップ
• 「テストを実行し、通ることを確認する」— ステップ
• 「コミットする」— ステップ

大きすぎる例：

### Task 1: Build authentication system
[50 lines of code across 5 files]

適切な例：

### Task 1: Create User model with email field
[10 lines, 1 file]

### Task 2: Add password hash field to User
[8 lines, 1 file]

### Task 3: Create password hashing utility
[15 lines, 1 file]

計画書の構成

ヘッダー（必須）

すべての計画は、必ず次の内容から始めてください。

# [Feature Name] Implementation Plan

> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

---

タスクの構成

各タスクは、次の形式に従います。

### Task N: [Descriptive Name]

**Objective:** What this task accomplishes (one sentence)

**Files:**
- Create: `exact/path/to/new_file.py`
- Modify: `exact/path/to/existing.py:45-67` (line numbers if known)
- Test: `tests/path/to/test_file.py`

**Step 1: Write failing test**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

**Step 2: Run test to verify failure**

Run: `pytest tests/path/test.py::test_specific_behavior -v`
Expected: FAIL — "function not defined"

**Step 3: Write minimal implementation**

```python
def function(input):
    return expected
```

**Step 4: Run test to verify pass**

Run: `pytest tests/path/test.py::test_specific_behavior -v`
Expected: PASS

**Step 5: Commit**

```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```

作成手順

ステップ1：要件を理解する

次の内容を読み、理解してください。

• 機能要件
• 設計ドキュメントまたはユーザーの説明
• 受け入れ基準
• 制約

ステップ2：コードベースを調査する

Hermes ツールを使用してプロジェクトを理解します。

# Understand project structure
search_files("*.py", target="files", path="src/")

# Look at similar features
search_files("similar_pattern", path="src/", file_glob="*.py")

# Check existing tests
search_files("*.py", target="files", path="tests/")

# Read key files
read_file("src/app.py")

ステップ3：アプローチを設計する

次の項目を決定します。

• アーキテクチャパターン
• ファイル構成
• 必要な依存関係
• テスト戦略

ステップ4：タスクを記述する

次の順序でタスクを作成します。

1. セットアップ／インフラストラクチャ
2. 中核機能（各機能でTDDを実施）
3. エッジケース
4. 統合
5. クリーンアップ／ドキュメント

ステップ5：詳細をすべて追加する

各タスクには、次の内容を含めてください。

• 正確なファイルパス（「設定ファイル」ではなく、src/config/settings.py）
• 完全なコード例（「バリデーションを追加する」ではなく、実際のコード）
• 期待される出力を含む正確なコマンド
• タスクが機能することを証明する検証手順

ステップ6：計画をレビューする

次の点を確認します。

• タスクが順序どおりで、論理的に並んでいる
• 各タスクが小さく分割されている（2〜5分）
• ファイルパスが正確である
• コード例が完全である（コピーしてそのまま実行できる）
• コマンドが正確で、期待される出力が示されている
• コンテキストに不足がない
• DRY、YAGNI、TDDの原則が適用されている

ステップ7：計画を保存する

mkdir -p docs/plans
# Save plan to docs/plans/YYYY-MM-DD-feature-name.md
git add docs/plans/
git commit -m "docs: add implementation plan for [feature]"

原則

DRY（同じことを繰り返さない）

悪い例： バリデーションを3か所にコピーして貼り付ける
良い例： バリデーション関数を切り出し、すべての場所で使用する

YAGNI（必要になるまで作らない）

悪い例： 将来の要件に備えて「柔軟性」を追加する
良い例： 今必要なものだけを実装する

# Bad — YAGNI violation
class User:
    def __init__(self, name, email):
        self.name = name
        self.email = email
        self.preferences = {}  # Not needed yet!
        self.metadata = {}     # Not needed yet!

# Good — YAGNI
class User:
    def __init__(self, name, email):
        self.name = name
        self.email = email

TDD（テスト駆動開発）

コードを生成する各タスクでは、TDDのサイクルをすべて含めてください。

1. 失敗するテストを書く
2. 実行して失敗を確認する
3. 最小限のコードを書く
4. 実行して成功を確認する

詳しくは test-driven-development スキルを参照してください。

こまめなコミット

各タスクの後にコミットします。

git add [files]
git commit -m "type: description"

よくある間違い

曖昧なタスク

悪い例： 「認証を追加する」
良い例： 「メールアドレスと password_hash フィールドを持つ User モデルを作成する」

不完全なコード

悪い例： 「ステップ1：バリデーション関数を追加する」
良い例： 「ステップ1：バリデーション関数を追加する」に続けて、関数のコード全体を記載する

検証の不足

悪い例： 「ステップ3：動作をテストする」
良い例： 「ステップ3：pytest tests/test_auth.py -v を実行する。期待される結果：3 passed」

ファイルパスの不足

悪い例： 「モデルファイルを作成する」
良い例： 「作成先：src/models/user.py」

実行への引き継ぎ

計画を保存した後、実行方法を提示します。

「計画が完了し、保存されました。subagent-driven-development を使用して実行する準備ができています。各タスクに新しいサブエージェントを割り当て、仕様への準拠、その後にコード品質の二段階レビューを行います。進めてもよろしいですか？」

実行時には、subagent-driven-development スキルを使用します。

• 各タスクで、すべてのコンテキストを含めて新しい delegate_task を使用します
• 各タスクの後に、仕様への準拠をレビューします
• 仕様に合格した後、コード品質をレビューします
• 両方のレビューで承認されてから進めます

忘れないでください

Bite-sized tasks (2-5 min each)
Exact file paths
Complete code (copy-pasteable)
Exact commands with expected output
Verification steps
DRY, YAGNI, TDD
Frequent commits

優れた計画があれば、実装は明確になります。