plan

計画

必読事項

• スキル：principles
  • principles/SKILL.md を読みます。
  • 計画を立てる前に、リンクされているすべての原則の詳細ドキュメントを読みます。
  • 原則の詳細は、任意の参考情報ではなく、拘束力のある計画上の制約として扱います。

役割

Plan は判断を担います。

スコープ、コンテキストの読み込み、意思決定、タスクの順序付け、検証戦略、および保存する計画成果物を管理します。

判断役は作業を直接行ってもかまいません。API コントラクトの調査、移行リスク、テストの一覧作成、ロールアウトの制約など、範囲を限定した調査を独立して進められる場合にのみ委任します。作業者は生のメモを返します。計画は判断役が作成します。

このスキルは、次の 3 層ワークフローに適しています。

• router：計画、ビルド、レビューをいつ実行するかを選択します
• judge：計画の判断と成果物を管理します
• worker：範囲を限定した計画上の質問に答えます

基本的には直接実行します。

ワークフロー

1. DETERMINE_SCOPE
2. LOAD_CONTEXT
3. DELEGATE_INVESTIGATIONS
4. RESOLVE_DECISIONS
5. DESIGN_TEST_SIGNALS
6. DRAFT_PLAN
7. CHECK_GATES
8. WRITE_ARTIFACT

DETERMINE_SCOPE

• 依頼された変更、影響を受ける製品の動作、計画の詳細度、および計画で意図的に対象外とする、または先送りする可能性のある関連作業を特定します。
• リポジトリのルートと、計画成果物のパスを明記します。 <repository-root>/docs/plans/YYYY-MM-DD_HH:MM_<plan-name>.md
• docs/plans/ が存在しない場合は作成します。

LOAD_CONTEXT

• 関連するソース、テスト、ドキュメント、設定、AGENTS.md、およびローカルのガイダンスを読みます。
• 現在の動作、影響を受けるファイル、不変条件、依存関係、コントラクト、テストの接点、検証コマンドを特定します。
• 外部スキルには、skill: principles のように意味がわかるスキル名を使います。
• ローカルファイルにはパスを使います。実装者が正確なスニペットを必要とする場合を除き、参考資料を計画にコピーしないでください。
• 必読資料の読み込みやリポジトリのコマンド実行が、明白な修正を試した後も失敗する場合は、作業を中断してエスカレーションします。コンテキストが不足していても、見切り発車で計画を立ててよいことにはなりません。

DELEGATE_INVESTIGATIONS

• 直接計画するほうが効率的な場合は省略します。
• 独立して実施できる、範囲を限定した質問のみ委任します。
• 作業者への指示には、質問、正確な対象範囲、読み込むファイルまたはスキル、期待する出力形式、作業者は計画成果物を書いてはならないというルール、およびツールの失敗を黙って出力の質を下げて処理せず、判断役にエスカレーションするというルールを含めます。
• 作業者の出力は証拠として扱います。計画を立てる前に重複を取り除き、内容を照合します。

RESOLVE_DECISIONS

• 可能な場合は、リポジトリのコンテキストから不明点を解決します。
• 未解決の判断事項は「未解決の質問」にのみ記載します。
• 実装タスクの中に選択肢を記載しないでください。
• タスクが未解決の質問に依存する場合、そのタスクをブロック中として示し、依存先を明記します。

DESIGN_TEST_SIGNALS

• テストの変更を計画する前に、tests are code 原則の詳細を再度読みます。
• 重要な動作変更ごとに、タスクを作成する前に、自動回帰テストのシグナルを決めます。
• 計画するテスト変更ごとに、次を明記します。
  • 保護対象となる動作、不変条件、またはコントラクト
  • 検証する公開境界
  • 失敗すべき回帰
• テストを追加しない場合は、既存の自動テストのシグナルを明記するか、永続的なシグナルが存在しない理由を説明します。

DRAFT_PLAN

• 事前のチャット履歴がない熟練エンジニアを対象に書きます。
• 正確なファイルパスを記載し、役立つ場合は行番号も示して、依存関係の順にタスクを並べます。
• 依存タスクを適用した後、各タスクによってリポジトリの整合性が保たれるようにします。後続タスクで修正するために、先行タスクでインポート、型、テスト、実行時の動作が壊れるようなリファクタリングの分割は避けます。
• 依存タスクを完了する前に正直な検証ができないタスクは、統合します。
• テストは、動作を変更するタスクか、依存するテストタスクに含めます。各テストタスクには、DESIGN_TEST_SIGNALS に記載されたテストシグナルを含めます。
• 意図、不変条件、実施順序には Details を使います。正確な実装方法は Code Changes に記載し、プローズで変更差分を繰り返さないでください。

コードの計画への記載方針：

• 基本的には差分を示します。既存ファイルの小さな変更では、周辺の数行を含むパッチ形式のハンクで、変更行のみを示します。
• 大きなコードブロックは、新規ファイルの場合、または変更内容を理解するために追加のコンテキストが必要な場合に限って使います。新規ファイル、新規関数、新規コンポーネント、新規型、および大幅に書き換える単位には、完全またはほぼ完全なコードを記載します。
• 小さな編集で既存ファイル全体を掲載しないでください。
• 変更対象でない限り、生成された成果物、ロックファイル、スナップショット、ビルド出力は含めないでください。
• 重要なロジックを ... で省略しないでください。
• コメントは、不明瞭な不変条件、エッジケース、エラー処理、並行処理、パフォーマンス、セキュリティ、ドメインルールに関する場合にのみ追加します。

CHECK_GATES

成果物を作成する前に、次の点を確認します。

• 計画が事前のチャット履歴なしで理解できること。
• 重要なタスクすべてに正確なファイルが記載されていること。
• すべてのタスクが具体的で、判断の余地がないこと。
• すべてのタスクの Verify セクションが、そのタスクと依存タスクを適用した直後に有効であること。
• Open Questions に未解決の判断事項のみが記載されていること。
• 任意のセクションは「該当なしなら省略」とされており、内容がない場合は省略されていること。
• すでに回答済みの質問が未解決の質問として残っていないこと。
• ブロックされたタスクには、ブロッカーが明記されていること。
• 検証コマンドと期待される結果が明示されていること。
• すべての検証コマンドで使うツールがこのリポジトリで実行できること。各ツールを no-op（例：--help、ドライラン、バージョン確認、対象なしでの実行）で呼び出し、利用可能であることを確認します。未実装コードを実行するコマンドでは、ツール自体が利用可能であることの確認で十分です。明らかな修正を試してもツールを実行できない場合は、エスカレーションします。
• 重要な動作変更すべてに、自動テストのシグナル、既存のシグナル、または持続的なシグナルが存在しない明示的な理由があること。
• タスクのファイル一覧が、そのタスクのスニペットやハンクと一致していること。
• このスキルや計画作成プロセスに関するメタ的な注記が含まれていないこと。

WRITE_ARTIFACT

• 最終計画を <repository-root>/docs/plans/YYYY-MM-DD_HH:MM_<plan-name>.md に書き込みます。
• 計画を改訂する場合は、最終成果物全体を書き直します。前のドラフトからの差分だけを書かないでください。
• 採用されたフィードバックを該当するセクションに反映します。
• 置き換えられたスコープは、削除されたと説明するのではなく、記述自体を削除します。

成果物テンプレート

# Plan: <Feature Name>

## Summary
<1-3 sentences describing what this builds and why>

## Prerequisites
<Task-specific setup, dependencies, or docs; skip if none>

## Open Questions
<Unresolved decisions only; skip if none>

## Out of Scope
<Nearby work the reader might reasonably expect from this plan, but this plan rejects or defers; skip if none>

## Overview
<1-2 short paragraphs about architecture, approach, constraints, and sequencing>

## Task <n>: <name>
**Files:** `path/to/file.ts:42`, `path/to/test.ts`
**Depends on:** Task <m> or `None`
**Blocked by:** <open question or external dependency; omit if unblocked>

**Details:**
- <Intent, invariant, or sequencing note not obvious from the code>
- <Concrete step only when no code hunk carries it>

**Test Signal:** <For test tasks only: behavior protected, boundary exercised, and regression that should fail; omit otherwise>

**Code Changes:**
```ts
// Patch-style hunk for small edits; full definition only for new/rewritten code.
```

**Verify:**
- `<command>`
- Expected: <observable result>