implementation-plan-best-practices

実装計画のベストプラクティス

プロジェクトの標準との整合性を保ち、逸脱を防ぐ実装計画の確立されたベストプラクティスです。

基本原則

モデルは局所的に最適化するため、階層的な検証（プロンプト → IDE → コミット → CI → ランタイム）によって全体的な制約を適用します。

1. スタイルの基準例

• プロンプトには、テンプレートとして優れたファイルを必ず2〜3個含めます
• 正確なパスと行番号を参照します（例：src/auth/login.ts:45-78）
• コード、テスト、README がそろった具体的なリポジトリの例を優先します
• 例：examples/style-anchor/pkg/greeter/greeter.go（コード）、greeter_test.go（テスト）、README.md（ドキュメント）
• アーキテクチャの逸脱を防ぐため、タスク指示の早い段階で基準例を示します

テンプレート：

Style Anchors:
- src/auth/login.ts:45-78 (authentication pattern with proper error handling)
- src/auth/login.test.ts:12-34 (test structure for auth flows)
- src/middleware/validation.ts:15-30 (input validation pattern)

2. タスクの規模

• **目標所要時間：**30〜150分（0.5〜2.5時間）
• **対象ファイル数：**タスクあたり1〜3ファイル（正当な理由がある場合は最大5ファイル）
• **分割方法：**テスト＋スキャフォールディング → 最小限の実装 → リファクタリングと仕上げ
• 小さなタスクごとにコミットし、逸脱があれば直ちに元に戻します
• タスクが30分未満の場合は、理由を記録するか、分割します

例：

• 小規模：src/utils/parse.ts のバグを修正 — 30〜60分
• 中規模：テスト付きで API エンドポイント src/server/user.ts を追加 — 90〜150分
• 大規模：認証システムを移行 — 設計と3〜5個の段階的なタスクに分割

3. 肯定形の指示

• 許可する操作を明示します（例：ONLY use: cobra, go-playground/validator, sqlite）
• 否定形の表現（「Xを使わないでください」）を避け、「ONLY use: Y, Z」のように指定します
• 対象ファイルを正確に指定します：Touch ONLY: src/api/handlers/user.ts, user.test.ts

4. 階層化されたルール

• **全般：**ユーザーの設定（形式、言語、長さ）
• プロジェクト：CLAUDE.md または .cursor/rules/ に記述する永続的なルール（各セッションで読み込まれます）
• **コンテキスト対応：**ディレクトリまたはファイルパターンごとに自動で適用されるルール

5. TDDを基準にする

• TDD チェックリストを必須にします：テスト → 最小限のコード → 追加テスト → リファクタリング
• テストが失敗した場合：「以前に合格したすべてのテストを維持したまま、このテストに合格するよう実装を修正してください。テストは変更しないでください。依存関係を追加しないでください。」
• 検証コマンドを明示します：

npm test src/auth/login.test.ts
go test ./pkg/auth -v
pytest tests/test_auth.py -v

6. プロンプト内の配置

• 重要な仕様、スタイルの基準例、厳守すべきルールは冒頭に置きます
• プロンプトの末尾でも繰り返します
• 要件を途中に埋もれさせないようにします

7. モデルの使い分け

• **Claude：**限定的で最小限の差分による編集に使用します。research → plan → implement、minimal diff, no renames, explain each edit を指定し、思考を促すトリガー（think、think hard、ultrathink）を使います
• **GPT：**探索的な作業や新規開発、コードレビューに使用します。実践的な計画と副作用の確認を依頼します

8. 自己整合性とAIによる相互レビュー

• 3つ以上の実装案を生成してから（温度を高めに設定）、最も一貫性のある案を選ぶようモデルに依頼します
• 複数モデルでレビューします（例：Claude が作成し、GPT/Gemini がレビュー）。これにより、見落としやすい問題を発見できます

9. 逸脱への対処

次の場合は直ちに停止して元に戻します：

• 許可リストにない新しい依存関係が追加された
• 指定した対象外のファイルが変更された（予期しないファイルが3つを超える）
• タスクの範囲内でリンティング／型エラーを解決できない
• テストが失敗し、モデルが実装ではなくテストの変更を提案する

直ちに実施すること：

1. セッションを停止します
2. タスク開始前の状態に戻します（このセッションでエージェントが作成した変更に限ります）
3. docs/drift-incidents/ にインシデントメモを作成し、次の内容を記載します：
   • 発生したこと
   • 予期せず変更されたファイル
   • 提案された新しい依存関係
   • 是正手順

許容される逸脱：

• 軽微なフォーマット変更（editorconfig）
• 空白文字のみの編集
• 対象範囲内で、型チェック済みの1行リファクタリング

学びの記録：

• 各セッション後に、新しいルールを .cursor/rules/ または CLAUDE.md に追加します
• 新しいパターンを発見した場合は、スタイルの基準例に追加します

10. 品質ゲート

コミット前：

• make lint で警告がゼロであること
• make test ですべてのテストが成功すること
• make typecheck でエラーがゼロであること

CI ゲート：

• 違反（gofmt、lint、typecheck）の数を数え、しきい値を超えた場合は失敗させる
• レース検出を有効にしてテストを実行する（例：go test -race）

タスクごとの検証：

validation:
  commands:
    - npm run lint
    - npm test src/[module].test.ts
    - npm run typecheck
  expected_output: "All tests passing, 0 lint errors"
  failure_handling: "STOP and report. Do not continue to next task."

11. 階層的な検証

1. プロンプトレベル： 明示的な制約、スタイルの基準、タスクの規模設定
2. IDE レベル： lint、型チェック、自動フォーマット
3. コミットレベル： コミット前フック、検証スクリプト
4. CI レベル： 品質ゲート、テストスイート、カバレッジのしきい値
5. 実行時レベル： 入力検証、適切なエラー処理、モニタリング

12. マイルストーン 0 から得た主な教訓

• テンプレートは具体的にするのではなく、明示的にする： 検証エラーを避けるため、スキーマで必須の最上位フィールドをすべて含める
• 具体的なスタイルの基準を早い段階で適用する： すべての計画タスクに、具体的な基準を2～3個（コード＋テスト＋README）含める
• 推測による編集には印を付ける： 推測による追加には、理由とともに assumption: true を使用する
• タスク規模の制約を守る： タスクの見積もりを30～150mに収め、短すぎるタスクは理由を添えて分割する
• 検証をインラインで記載する： quality_score、issues、approval を含む validation の概要を追加する
• 具体的な実行コマンドを優先する： instructions に明示的なバリデーターコマンドを追加する
• 実装ルールの適用範囲を限定する： 実装のみを対象とするパターンチェックは when: implementation_phase の範囲内にする
• リポジトリの例を基準として使う： 小さく、適用範囲が明確な例は、効果の高い基準になる

タスクテンプレートの例

task:
  id: t-auth-001
  name: "Add login endpoint with JWT validation"
  estimate_minutes: 90

  files:
    touch_only: [src/api/handlers/auth.ts, src/api/handlers/auth.test.ts]
    modify_only: [src/api/routes.ts]

  style_anchors:
    - {path: src/api/handlers/user.ts, lines: 45-78, pattern: "Handler with proper error handling"}
    - {path: src/api/handlers/user.test.ts, lines: 12-45, pattern: "Test structure for API handlers"}

  constraints:
    dependencies:
      only_use: [jsonwebtoken, express-validator]
    file_scope:
      max_files: 3
      stop_if_exceeded: true

  instructions: |
    ## CRITICAL CONSTRAINTS
    - ONLY modify files listed above
    - ONLY use dependencies: jsonwebtoken, express-validator
    - MUST pass: npm test, npm run lint

    ## Style Anchors
    See src/api/handlers/user.ts:45-78 for handler pattern
    See src/api/handlers/user.test.ts:12-45 for test structure

    ## TDD Checklist
    - [ ] Write failing test for POST /auth/login
    - [ ] Implement minimal handler to pass
    - [ ] Add tests for edge cases
    - [ ] Refactor for clarity

    ## Drift Policy
    STOP if: files touched >3, new dependencies, tests fail

    ## Validation
    npm test src/api/handlers/auth.test.ts && npm run lint && npm run typecheck

  validation:
    commands: [npm test src/api/handlers/auth.test.ts, npm run lint, npm run typecheck]
    expected_output: "All tests passing, 0 errors"
    failure_handling: "STOP. Revise implementation to pass tests."

すぐに使える実践チェックリスト

実装計画を作成する際は、次の点を確認してください。

1. プロンプトレベルのルールを記載した CLAUDE.md または .cursor/rules/ を作成する
2. プロンプトに具体的なスタイルの基準を2～3個追加する（リポジトリの例を優先する）
3. タスクの規模を30分～2.5時間に調整し、タスクごとにコミットする
4. 否定的な制約を肯定的な指示に置き換える
5. 警告ゼロの lint、コミット前フック、CI ゲートを適用する
6. 変更を加える前に、TDD の計画とテストを必須にする
7. 実行時の検証には適切なエラー処理を使う
8. 生成する YAML にスキーマで必須のフィールドをすべて含める
9. 推測による追加には、理由とともに assumption: true の印を付ける
10. 重要な制約はプロンプトの冒頭と末尾の両方に記載する

よくあるアンチパターン

アンチパターン	問題点	対処法
スタイルの基準がない	モデルが一貫性のないパターンを導入する	行番号を付けた具体例を2～3個追加する
タスクが2.5時間を超える	レビューが難しく、方向性がぶれやすい	テスト、実装、リファクタリングに分割する
否定的な表現	「Xを使わない」は従いにくい	「Y、Zのみを使う」とする
ルールが埋もれている	モデルが重要な制約を見落とす	冒頭と末尾の両方に記載する
検証コマンドがない	タスクの完了条件が不明確になる	lint、test、typecheck のコマンドを明示する
テストの変更を許可する	実装を通すためにテストが弱められる	「テストではなく、実装を修正する」とする
ドリフトへの対処方針がない	小さなずれが積み重なる	明確な停止基準と復元手順を定める
コミットの区切りがない	コミットされていない変更が大きいと、デバッグが難しくなる	タスクごとにコミットする

他のスキルとの連携

• implementation-planner： 計画の生成時にこれらのプラクティスを適用する
• implementation-plan-review： これらのプラクティスに照らして計画を検証する
• business-requirements-interview： 要件がこれらのプラクティスに沿っていることを確認する
• technical-requirements-interview： 技術仕様がこれらのプラクティスに従うようにする

例

次の例については、examples/ ディレクトリを参照してください。

• すべてのベストプラクティスを適用した、適切に構成されたタスク
• 改善点を示す修正前・修正後の例
• よくある間違いとその修正方法