プロジェクト開発方法論
このスキルは、LLM処理に適したタスクを特定し、効果的なプロジェクトアーキテクチャを設計し、エージェント支援による開発を活用して迅速に反復するための原則をカバーします。この方法論は、バッチ処理パイプライン、マルチエージェント研究システム、インタラクティブエージェントアプリケーションのいずれを構築する場合にも適用されます。
このスキルの作業単位は、プロジェクト全体またはマルチステージパイプラインです。個別のツール設計（説明、スキーマ、エラーメッセージ）は tool-design に属します。スキルごとのアクティベーションルーティングは、対応するスキルとコーパスインデックスに属します。このスキルは、プロジェクトレベルの以下の質問を担当します：このタスクをLLMで構築すべきか、パイプラインの形状はどうあるべきか、コストはいくらか、どのように反復すべきか。
アクティベーション条件
作業単位がプロジェクト全体またはパイプラインである場合に、このスキルをアクティベートします。
- タスクにLLMが適切なプリミティブであるかどうかの判断（コードを書く前のタスク-モデル適合性評価）。
- マルチステージバッチまたはエージェントパイプラインの形成（取得/準備/処理/解析/レンダリング）。
- LLM主体のプロジェクトにおけるトークン、ドルコスト、タイムラインの見積もり。
- プロジェクトレベルでの単一エージェントとマルチエージェントの選択。
- エージェント支援による開発反復の構造化（エージェントがプロジェクト自体の構築を支援する場合）。
- パイプライン契約レベルでの構造化出力の設計（ステージ間のハンドオフフォーマット）。
他のスキルが担当する隣接作業では、このスキルをアクティベートしないでください。
- ツールごとの説明、スキーマ、命名、応答形式、エラーメッセージ：
tool-design。 - 軌道ごとのトークン効率戦術（マスキング、分割、キャッシュ）：
context-optimization。 - エージェントトポロジーレベルでのサブエージェントへの作業分割の判断：
multi-agent-patterns。 - 自律制御ループの設計（ロックされたメトリクス、新規性ゲート、人間の承認境界）：
harness-engineering。
中核概念
タスク-モデル適合性認識
コードを書く前にタスク-モデル適合性を評価します。根本的にミスマッチなタスクに自動化を構築すると、数日分の努力が無駄になるからです。すべての提案されたタスクを以下の2つの表に照らして、続行か中止かを判断します。
以下の特性がある場合は続行：
| 特性 | 根拠 |
|---|---|
| 複数ソースにわたる統合 | LLMはルールベースの代替手段よりも複数の入力からの情報統合に優れている |
| ルーブリックを用いた主観的判断 | 採点、評価、基準に基づく分類は言語推論に自然にマッピングされる |
| 自然言語出力 | 目標が人間が読めるテキストである場合、LLMはそれをネイティブに提供する |
| エラー耐性 | 個々の障害がシステム全体を壊さないため、LLMの非決定性が許容される |
| バッチ処理 | アイテム間で会話状態が不要なため、コンテキストがクリーンに保たれる |
| トレーニングデータに含まれるドメイン知識 | モデルがすでに関連コンテキストを持っているため、プロンプトエンジニアリングのオーバーヘッドが削減される |
以下の特性がある場合は中止：
| 特性 | 根拠 |
|---|---|
| 精密な計算 | 数学、カウント、正確なアルゴリズムは言語モデルでは信頼できない |
| リアルタイム要件 | LLMのレイテンシはサブ秒応答には高すぎる |
| 完全な精度要件 | 幻覚リスクにより100%の精度は不可能 |
| 独自データへの依存 | モデルに必要なコンテキストがなく、プロンプトだけでは取得できない |
| 逐次的な依存関係 | 各ステップが前の結果に大きく依存するため、エラーが連鎖する |
| 決定論的な出力要件 | 同じ入力から同一の出力が求められるが、LLMはそれを保証できない |
手動プロトタイプ手順
自動化に投資する前に、常に手動テストでタスク-モデル適合性を検証します。代表的な入力1つをモデルインターフェースにコピーし、出力品質を評価し、その結果を使用して以下の質問に回答します。
- モデルはこのタスクに必要な知識を持っていますか？
- モデルは必要な形式で出力を生成できますか？
- スケール時にはどのレベルの品質が期待できますか？
- 対処すべき明らかな障害モードはありますか？
これを実行するのは、失敗した手動プロトタイプは失敗した自動化システムを予測し、成功したものは品質ベースラインとプロンプト設計テンプレートの両方を提供するからです。テストには数分しかかからず、何時間もの開発の無駄を防ぎます。
パイプラインアーキテクチャ
LLMプロジェクトはステージ化されたパイプラインとして構成します。決定論的ステージと非決定論的ステージを分離することで、迅速な反復とコスト制御が可能になるからです。各ステージは以下のように設計します。
- 離散的: ステージ間に明確な境界があり、それぞれを独立してデバッグできる
- べき等: 再実行しても同じ結果が得られ、重複作業を防ぐ
- キャッシュ可能: 中間結果がディスクに保持され、高価な再計算を回避する
- 独立: 各ステージを個別に実行でき、選択的な再実行が可能
この標準的なパイプライン構造を使用します：
取得 -> 準備 -> 処理 -> 解析 -> レンダリング
- 取得: ソース（API、ファイル、データベース）から生データを取得
- 準備: データをプロンプト形式に変換
- 処理: LLM呼び出しを実行（高価で非決定論的なステップ）
- 解析: LLM出力から構造化データを抽出
- レンダリング: 最終出力（レポート、ファイル、可視化）を生成
ステージ1、2、4、5は決定論的です。ステージ3は非決定論的で高コストです。この分離を維持するのは、高価なLLMステージを必要な場合にのみ再実行し、解析とレンダリングを迅速に反復できるようにするためです。
ファイルシステムによる状態管理
データベースやインメモリ構造ではなく、ファイルシステムを使用してパイプラインの状態を追跡します。ファイルの存在が自然なべき等性を提供し、人間が読み取れるデバッグが可能になるからです。
data/{id}/
raw.json # 取得ステージ完了
prompt.md # 準備ステージ完了
response.md # 処理ステージ完了
parsed.json # 解析ステージ完了
アイテムの処理が必要かどうかは、出力ファイルが存在するかどうかを確認することで判断します。出力ファイルとそれより下流のファイルを削除することで、ステージを再実行します。中間ファイルを直接読み取ることでデバッグします。このパターンは、各ディレクトリが独立しているため、シンプルな並列化と簡単なキャッシュが可能になります。
構造化出力の設計
構造化され解析可能な出力を生成するようにプロンプトを設計します。プロンプト設計が解析の信頼性を直接決定するからです。すべての構造化プロンプトに以下の要素を含めます。
- セクションマーカー: パーサーが照合できる明示的なヘッダーまたはプレフィックス
- フォーマット例: 出力がどのようになるべきかを正確に示す
- 根拠の開示: 「これをプログラムで解析します」と明記し、モデルがフォーマット準拠を優先するようにする
- 制約付き値: 列挙されたオプション、スコア範囲、固定フォーマット
LLMの出力バリエーションを適切に処理できるパーサーを構築します。LLMは指示を完璧に守るわけではないからです。軽微なフォーマットのバリエーションに対応できる柔軟な正規表現パターンを使用し、セクションが欠落している場合には適切なデフォルト値を提供し、パース失敗時にはクラッシュするのではなくログに記録してレビューできるようにします。
エージェント支援による開発
エージェント対応モデルを使用して、迅速な反復を通じて開発を加速します。プロジェクトの目標と制約を説明し、エージェントに初期実装を生成させ、特定の失敗に対してテストと反復を行い、結果に基づいてプロンプトとアーキテクチャを洗練します。
エージェントの出力を集中させ高品質に保つために、以下のプラクティスを採用します。
- 事前に明確で具体的な要件を提供し、修正サイクルを削減する
- 大規模プロジェクトを個別のコンポーネントに分割し、それぞれを独立して検証できるようにする
- 次のコンポーネントに進む前に各コンポーネントをテストし、早期に障害を発見する
- コンテキストの劣化を防ぐため、エージェントを一度に1つのタスクに集中させる
コストと規模の見積もり
開始前にLLM処理コストを見積もります。トークンコストは規模が大きくなると急速に増大し、予算超過の遅ればせの発見はコストのかかるやり直しを強いるからです。以下の式を使用します。
総コスト = (アイテム数 x アイテムあたりトークン数 x トークンあたり価格) + APIオーバーヘッド
バッチ処理の場合、アイテムあたりの入力トークン数（プロンプト+コンテキスト）を見積もり、アイテムあたりの出力トークン数（通常の応答長）を見積もり、アイテム数で乗算し、リトライと失敗のために20〜30%のバッファを追加します。
開発中は実際のコストを追跡します。コストが推定値を大幅に超える場合は、トランケーションによるコンテキスト長の削減、単純なアイテムへの小規模モデルの使用、部分結果のキャッシュと再利用、または並列処理の追加によるウォールクロック時間の短縮を検討します。
詳細トピック
単一エージェント vs マルチエージェントアーキテクチャの選択
独立したアイテムをバッチ処理する場合は、デフォルトで単一エージェントパイプラインを選択します。管理が簡単で、実行コストが低く、デバッグが容易だからです。以下の条件のいずれかが成立する場合にのみ、マルチエージェントアーキテクチャに移行します。
- 異なる側面の並行探索が必要な場合
- タスクが単一のコンテキストウィンドウの容量を超える場合
- 専門化されたサブエージェントがベンチマークで品質を明らかに向上させる場合
ロールの擬人化ではなく、コンテキスト分離のためにマルチエージェントを選択します。サブエージェントは、焦点を絞ったサブタスクのために新しいコンテキストウィンドウを取得し、長時間実行タスクでのコンテキスト劣化を防ぎます。
詳細なアーキテクチャガイダンスについては multi-agent-patterns スキルを参照してください。
アーキテクチャ削減
最小限のアーキテクチャから開始し、本番環境の証拠によって必要性が証明された場合にのみ複雑性を追加します。過剰に設計された足場は、モデルのパフォーマンスを可能にするよりも制約することが多いからです。
Vercelのd0ケーススタディでは、多数の特殊化されたツールを2つのプリミティブ（コマンド実行とSQL）に削減した後、成功率が向上したことが報告されています（claim-project-development-vercel-d0-reduction）。ファイルシステムエージェントパターンは、カスタム探索ツールの代わりに標準的なUnixユーティリティを使用します。
削減すべき場合：
- データ層が十分に文書化され、一貫して構造化されている
- モデルが十分な推論能力を持っている
- 特殊化されたツールが可能にするのではなく制約している
- 結果の改善よりも足場の維持により多くの時間を費やしている
複雑性を追加すべき場合：
- 基礎となるデータが乱雑で、一貫性がなく、文書化が不十分である
- ドメインがモデルに欠けている専門知識を必要とする
- 安全性の制約によりエージェントの機能を制限する必要がある
- 操作が真に複雑で、構造化されたワークフローの恩恵を受ける
詳細なツールアーキテクチャガイダンスについては tool-design スキルを参照してください。
反復とリファクタリング
最初から複数回のアーキテクチャ反復を計画します。規模の大きな本番エージェントシステムは常にリファクタリングを必要とするからです。Manus社はローンチ以来、エージェントフレームワークを5回リファクタリングしました。Bitter Lessonは、現在のモデルの制限に対応して追加された構造が、モデルの改善に伴って制約になることを示唆しています。
以下のプラクティスに従って変更に対応できるように構築します。
- アーキテクチャをシンプルで偏りのない状態に保ち、リファクタリングを安価にする
- 複数のモデル世代にわたってテストし、ハーネスがパフォーマンスを制限していないことを確認する
- 制限を固定化するのではなく、モデルの改善から恩恵を受けるシステムを設計する
実践的ガイダンス
プロジェクト計画テンプレート
以下のテンプレートを順に従います。各ステップで前提条件を検証してから次のステップに進むためです。
-
タスク分析
- 入力と期待される出力を明示的に定義する
- 分類：統合、生成、分類、または分析
- ビジネスインパクトに基づいて許容エラー率を設定する
- コストを正当化するために、成功あたりの価値を見積もる
-
手動検証
- 対象モデルで代表的な例を1つテストする
- 出力品質と形式を要件に照らして評価する
- パーサーの強化やプロンプトの修正が必要な障害モードを特定する
- コスト見積もりのためにアイテムあたりのトークン数を見積もる
-
アーキテクチャ選択
- 上記の基準に基づいて、単一パイプラインとマルチエージェントのどちらかを選択する
- 必要なツールとデータソースを特定する
- ファイルシステム状態を使用したストレージとキャッシュ戦略を設計する
- 処理ステージの並列化アプローチを計画する
-
コスト見積もり
- アイテム数 x トークン数 x 価格を20〜30%のバッファ付きで計算する
- 各パイプラインステージの開発時間を見積もる
- インフラ要件（APIキー、ストレージ、計算リソース）を特定する
- 本番実行のための継続的な運用コストを見積もる
-
開発計画
- ステージごとに実装し、次に進む前に各ステージをテストする
- 期待される出力とともに、ステージごとのテスト戦略を定義する
- 品質メトリクスに紐づいた反復マイルストーンを設定する
- ロールバック機能を備えたデプロイアプローチを計画する
例
例1：バッチ分析パイプライン（KarpathyのHNタイムカプセル）
タスク：10年前の930件のHN議論を後知恵採点で分析する。
アーキテクチャ：
- 5ステージパイプライン：取得 -> プロンプト -> 分析 -> 解析 -> レンダリング
- ファイルシステム状態：data/{date}/{item_id}/、各ステージの出力ファイル
- 構造化出力：明示的な形式要件を持つ6つのセクション
- 並列実行：LLM呼び出しに15ワーカー
結果：総コスト58ドル、実行時間約1時間、静的HTML出力。
例2：アーキテクチャ削減（Vercel d0）
タスク：内部分析用のテキスト-to-SQLエージェント。
改善前：多数の特殊化されたツール、測定された成功率が低く、平均実行時間が長い。
改善後：2つのツール（bash + SQL）、測定された成功率が高く、平均実行時間が短い（claim-project-development-vercel-d0-reduction）。
重要な洞察：セマンティックレイヤーはすでに優れたドキュメントだった。Claudeはファイルを直接読み取るアクセス権を必要としていただけだった。
詳細な分析についてはケーススタディを参照してください。
ガイドライン
- 自動化を構築する前に、手動プロトタイピングでタスク-モデル適合性を検証する
- パイプラインを離散的、べき等、キャッシュ可能なステージとして構成する
- 状態管理とデバッグにファイルシステムを使用する
- 明示的なフォーマット例を含む、構造化され解析可能な出力を生成するようにプロンプトを設計する
- 最小限のアーキテクチャから開始し、必要性が証明された場合にのみ複雑性を追加する
- コストを早期に見積もり、開発全体を通じて追跡する
- LLM出力のバリエーションを適切に処理する堅牢なパーサーを構築する
- エージェントに一度に1つのタスクを集中させるために、具体的な要件を提供する
- 独立して検証できるように、大規模プロジェクトを個別のコンポーネントに分割する
- 各コンポーネントを次に進む前にテストし、早期に障害を発見する