technical-planning

技術計画

基本原則

「どのように」ではなく「何を」に焦点を当てる：実装の詳細ではなく、提供する成果を定義します。制約と成功基準を明確にしつつ、実装方法の選択には柔軟性を持たせます。

決定を下す最適なタイミング：適切な判断を下すのに十分な情報が得られるまで決定を先延ばしにします。ただし、進行を妨げるほど遅らせてはいけません。後から変更できる決定は速やかに行い、変更が難しい決定は必要になるまで先送りにします。

リスク優先の開発：最もリスクの高い技術的課題に最初に取り組みます。本格的な実装の前に概念実証を作成します。中核となる前提を早期に検証するため、完璧ではなくても動作するソリューションをリリースします。

計画的な先送り：先送りする内容と、いつ対応するのかを明確に記録します。中核的な価値の提供と、仕上げや最適化を区別します。

TodoWriteによる進捗管理

4つのフェーズを通じた計画の進捗管理にTodoWriteを使用します。

1. 開始時：各フェーズのTodoを作成します。

   ☐ Phase 1: Requirements & Risk Analysis
   ☐ Phase 2: Milestone Planning
   ☐ Phase 3: Implementation Strategy
   ☐ Phase 4: Execution Framework
   

2. 計画中：作業を進めながら、フェーズのステータスをin_progress → completedに更新します。主要な成果物のサブTodoを追加します。

   ☐ Extract core requirements (2-3 user journeys)
   ☐ Identify technical risks (high/integration/performance/architecture)
   ☐ Define milestones with success criteria
   ☐ Document deferred items with rationale
   

3. 複雑なプロジェクトの場合：確認事項とその解決内容をTodoとして管理します。これにより、情報が不十分なまま作業を進めることを防げます。

決定のタイミングに関するフレームワーク

早期に決定する（要件フェーズ）：

• 解決するユーザーの課題
• 成功基準と測定方法
• 厳守すべき制約（セキュリティ、コンプライアンス、パフォーマンスのSLA）
• 重要なインテグレーションと依存関係
• アーキテクチャに影響する技術の選択

実装時まで先送りする（実行フェーズ）：

• 具体的なアルゴリズムやデータ構造
• 内部API設計の詳細
• コードの構成パターン
• ライブラリの選択（複数の選択肢がある場合）
• パフォーマンスの最適化（必要性が確認されるまで）
• UI/UXの詳細（ユーザーテストを行うまで）

理由：早期の決定は、詳細を固定せずに作業を進められるようにするためのものです。実装上の決定は、実際に手を動かすことで明確になり、事前の計画から想定されるものより優れた代替案が見つかることもよくあります。

エージェントのガイドライン

作業を進める前に明確にする：不明確な要件、技術的制約、ビジネス上の優先事項を決めつけてはいけません。重要な点について80％以上の確信が得られた場合にのみ作業を進めます。以下について具体的に質問してください。

• 解決するユーザーの課題（依頼された機能だけではありません）
• 成功基準と測定方法
• 技術的制約と既存システムの依存関係
• チームの能力と技術的な好み
• スケジュール上の制約と優先順位のトレードオフ
• パフォーマンスとスケーラビリティの要件

フェーズ1：要件とリスクの分析

前提条件の確認

以下を確認します。

• 解決するユーザーの課題は何ですか？
• 主なユーザーは誰で、どのようなワークフローを利用しますか？
• 成功をどのように測定しますか？
• 技術面およびビジネス面の制約は何ですか？

中核となる要件の抽出

1. 解決する根本的なユーザーの課題を特定します
2. 主なユーザーの利用経路を整理します（重要な経路を2～3個に絞ります）
3. プロジェクトの成功指標を定義します

技術的リスクの特定

1. 影響度の高いリスク：アプローチの妥当性を損なう可能性がある、技術的に不明な点
2. インテグレーションのリスク：外部システムへの依存関係と互換性に関する懸念
3. パフォーマンスのリスク：スケーラビリティのボトルネックとアルゴリズム上の課題
4. アーキテクチャのリスク：広範囲に影響を及ぼす根本的な設計上の決定

リスク優先度マトリックス

• 重大かつ不明：概念実証を用いてマイルストーン1で対応する必要があります
• 重大かつ既知：確立されたパターンを用いて、早期のマイルストーンで対応します
• 重大ではない：後続のマイルストーンまで先送りするか、対象から除外します

フェーズ2：マイルストーンの計画

前提条件の確認

以下を確認します。

• フェーズ1で特定した技術的リスクの優先順位
• チームの対応能力と利用可能な期間
• 各コンポーネント間の依存関係
• このプロジェクトにおける「動作する機能」の定義

マイルストーンの構成

• 期間：プロジェクトの複雑さに応じて、4～8週間のサイクル
• 成果物：各マイルストーンで、動作しテスト可能な機能を提供する必要があります
• リスク重視：最もリスクの高い項目に最初に取り組むよう、マイルストーンの順序を決めます

各マイルストーンで定義する項目：

目標：マイルストーンの成果を1文で説明します

主要タスク：Last Responsible Moment の原則に沿った、主要な実装タスクを4～6個挙げます：

• 明確な成果と制約を定義する
• 依存関係と統合ポイントを特定する
• 手順を逐一示すのではなく、背景情報と考慮事項を提示する
• 実装の詳細は柔軟にする
• 実行中に解決する必要のある疑問点を明示する

成功基準：

• 最低限の成功（マイルストーンの完了に必須）
• 完全な成功（仕上げを含む理想的な成果）

リスク軽減：このマイルストーンで解決する具体的な不明点

先送りする項目：意図的に対象外とする内容と、取り込む予定のマイルストーン

タスク分解のガイドライン

タスクに分解する際は、指示ではなくガイダンスを提示します：

✓ 良いタスク定義（成果重視）：

• 目標：「ユーザーが安全に認証できるようにする」
• 制約：「既存のセッションミドルウェアと統合する必要がある。応答時間は100ms未満」
• ガイダンス：「セッション認証とトークン認証を検討し、src/middleware/ 内の既存パターンを確認する」
• 検証：「ユーザーがログインでき、セッションが維持され、テストに合格する」

✗ 悪いタスク定義（過度に細かい指示）：

• ステップ1：「bcrypt のインポートを含む auth.js ファイルを作成する」
• ステップ2：「10ラウンドで bcrypt.hash を使う hashPassword 関数を作成する」
• ステップ3：「req.session.userId を確認する Express ミドルウェアを作成する」

理由：良い定義なら、実装者は学んだ内容に基づいて最適な方法を選べます。悪い定義は、背景を理解する前に選択肢を固定してしまい、手戻りにつながることがよくあります。

マイルストーン定義の例

目標：ユーザー認証と、外部 API からの基本的なデータ取得を検証する

主要タスク：

1. プロバイダーとの OAuth フローを実装する
2. ユーザーセッション管理を作成する
3. エラー処理を備えた API クライアントを構築する
4. 基本的なユーザープロフィール表示を追加する

成功基準：

• 最低限：ユーザーがログインしてプロフィールデータを確認できる
• 完全：プロフィール編集とセッション維持を含める

リスク軽減：API のレート制限と、負荷時の応答時間を確認する

先送りする項目：高度なプロフィール機能、パスワードリセットフロー（マイルストーン3）

フェーズ3：実装戦略

開発アプローチ

• まずプロトタイプを作成：リスクの高い想定を検証するため、使い捨てのバージョンを構築する
• 仕上げより中核を優先：UI の改良より先に、機能を実装する
• 早期に統合：最初のマイルストーンで外部システムとの接続をテストする
• 継続的に測定：初日からパフォーマンスとユーザーメトリクスを追跡する

技術選定の基準

1. チームの専門知識：チームがよく知る技術を優先する
2. 実証済みの信頼性：中核システムには、成熟し実績のある選択肢を選ぶ
3. 統合能力：既存のツール／システムとの互換性を確保する
4. スケーラビリティの道筋：想定される成長に技術が対応できること

品質ゲート

• すべてのコードに基本的なテストカバレッジが必要です
• 主要なユーザージャーニーについて、パフォーマンスのベンチマークを満たす必要があります
• 認証とデータ処理について、セキュリティレビューが必要です
• ユーザー向け機能はアクセシビリティ基準を満たす必要があります

フェーズ4：実行フレームワーク

スプリント計画

1. リスク評価：今後の作業における不明点を特定する
2. 調査時間：スプリントの20～30％をプロトタイピング／学習用に確保する
3. 完了の定義：コードの完成だけでなく、機能が動作することを含める
4. 継続的な検証：主要なユーザージャーニーについて、定期的にステークホルダーからフィードバックを得る

保留項目の管理

• 定期的なレビュー：保留項目の妥当性が引き続きあるか、各マイルストーンで評価します
• カテゴリー：技術的負債、UX の洗練、エッジケース、パフォーマンスの最適化、高度な機能
• スケジュール設定：保留項目を適切な今後のマイルストーンに組み込みます
• 削除：保留項目の中には、不要になるものもあります

ドキュメントの要件

• 成果物に焦点を当てた技術仕様書
• 対応策を含むリスク一覧
• 目標スケジュールを記載した保留項目の一覧
• 主要な選択に関するアーキテクチャ決定記録

エージェント向けの判断フレームワーク

IF プロジェクトの技術的な実現可能性が不明 → マイルストーン 1 で概念実証をスケジュールします
IF プロジェクトに外部連携が必要 → 最初のマイルストーンで最小限の連携をテストします
IF プロジェクトにパフォーマンス要件がある → ベンチマークを設定し、コアアルゴリズムを早期にテストします
IF チームに選定した技術の専門知識がない → 初期のマイルストーンに学習・調査の時間を含めます
IF プロジェクトの期限が厳しい → 最低限達成すべき成功基準に集中し、仕上げは保留します
IF プロジェクトがグリーンフィールド → アーキテクチャの決定と基盤のセットアップに、より多くの時間をかけます
IF プロジェクトが機能強化 → 連携ポイントと後方互換性に集中します

不明点がある場合に尋ねる質問

WHEN 要件が曖昧 → 「これはどのような具体的なユーザーの問題を解決しますか？成功をどのように測定しますか？」
WHEN 技術的な範囲が定まっていない → 「技術的な機能のうち、必須のものと、あると望ましいものは何ですか？」
WHEN スケジュールが現実的でない → 「必ず守る必要がある期限はいつですか？どの程度の柔軟性がありますか？」
WHEN チームの能力が不明 → 「チームはどのような技術の経験がありますか？スキルの不足している分野は何ですか？」
WHEN 連携ポイントが不明確 → 「接続が必要な既存システムは何ですか？データ形式や API の制約は何ですか？」
WHEN パフォーマンスのニーズが指定されていない → 「想定されるユーザー負荷と応答時間の要件は何ですか？」
WHEN 成功基準が不足している → 「このマイルストーンの完了と成功を、どのように判断しますか？」

避けるべきよくある落とし穴

• 要件が不明確なときに、確認の質問をせずに仮定で進める
• 必要な詳細を求めず、不完全な情報のまま進める
• 成果に焦点を当てた指針ではなく、手順を逐一示す過度に規範的なタスク定義を作成する
• 実行段階まで保留できる実装上の決定を早すぎる段階で行う
• 重大な不明点を保留したまま、リスクの低い機能に時間をかける
• 中核となる仮定を検証する前に、解決策を過剰に設計する
• 成果物に集中せず、実装の詳細を計画する
• 解決する具体的な問題を理解せず、ユーザーのニーズを推測する
• 保留の決定とその理由を記録しない
• コア機能をまず実証せず、早まった最適化を行う
• 全体像を理解する前に、技術の選択を確定する