plan

プランモード

ユーザーが実行ではなくプランを求めている場合に、このスキルを使用します。

基本動作

このターンでは、プランニングのみを行います。

• コードを実装しないでください。
• プランの Markdown ファイル以外のプロジェクトファイルを編集しないでください。
• 変更を伴うターミナルコマンドの実行、コミット、プッシュ、外部への操作を行わないでください。
• 必要に応じて、読み取り専用のコマンドやツールでリポジトリなどのコンテキストを調べてもかまいません。
• 成果物として、アクティブなワークスペース内の .hermes/plans/ に Markdown 形式のプランを保存してください。

出力要件

具体的で実行可能な Markdown 形式のプランを作成してください。

関連する場合は、以下を含めてください。

• 目標
• 現在の状況／前提
• 提案するアプローチ
• 手順ごとのプラン
• 変更が見込まれるファイル
• テスト／検証
• リスク、トレードオフ、未解決の質問

タスクがコード関連の場合は、正確なファイルパス、テスト対象の候補、検証手順を記載してください。

保存先

次のパスに write_file を使用してプランを保存してください。

• .hermes/plans/YYYY-MM-DD_HHMMSS-<slug>.md

このパスは、アクティブな作業ディレクトリ／バックエンドのワークスペースからの相対パスとして扱います。Hermes のファイルツールはバックエンドに対応しているため、この相対パスを使えば、ローカル、docker、ssh、modal、daytona の各バックエンドでプランをワークスペース内に保存できます。

ランタイムで特定の保存先パスが指定されている場合は、そのパスをそのまま使用してください。 指定がない場合は、.hermes/plans/ 以下に適切なタイムスタンプ付きファイル名を作成してください。

対話スタイル

• 依頼が十分に明確な場合は、そのままプランを作成してください。
• /plan に明示的な指示がない場合は、現在の会話の文脈からタスクを推測してください。
• 依頼の内容が実際に不明確な場合は、推測せず、簡潔な確認の質問をしてください。
• プランを保存したら、計画した内容と保存先を簡潔に伝えてください。

---

優れたプランの書き方

以下は、上記のプランに含める実装計画を作成するための手引きです。

概要

コードベースの知識がなく、判断力にも不安のある実装者を想定して、具体的で実行可能なプランを作成してください。実装者が必要とするすべての情報（変更対象のファイル、完全なコード、テストコマンド、確認すべきドキュメント、検証方法）を記載してください。作業を細かく分け、DRY、YAGNI、TDD を意識し、こまめにコミットしてください。

実装者は熟練した開発者ですが、ツールセットや問題領域についてほとんど知識がないものとします。適切なテスト設計にも詳しくないものと考えてください。

基本原則： 優れたプランがあれば、実装の手順が明確になります。推測が必要な箇所があるなら、プランは不十分です。

詳細な実装プランが役立つ場面

必ず事前に作成してください：

• 複数段階にわたる機能を実装する場合
• 複雑な要件を細分化する場合
• サブエージェント主導の開発で、サブエージェントに作業を委任する場合

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

• 機能が単純に見える場合（前提によってバグが起こる可能性があります）
• 自分で実装する予定の場合（将来の自分にも指針が必要です）
• ひとりで作業する場合（ドキュメントが大切です）

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. クリーンアップ／ドキュメント作成

Step 5: 詳細をすべて記載する

各タスクには、以下を含めてください。

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

Step 6: 計画をレビューする

確認事項：

• タスクが順序立てて論理的に並んでいる
• 各タスクが小さな単位になっている（2～5分）
• ファイルパスが正確である
• コード例が完全である（コピーしてそのまま使える）
• 期待される出力を含む正確なコマンドが記載されている
• 必要なコンテキストに抜けがない
• DRY、YAGNI、TDD の原則が適用されている

原則

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"

よくある間違い

曖昧なタスク

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

不完全なコード

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

検証の欠落

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

ファイルパスの欠落

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

実行の引き継ぎ

計画を保存した後、実行方法を提案してください。

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

実行時には、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

優れた計画は、実装を明確にします。