project-development

プロジェクト開発手法

このスキルでは、LLM に適したタスクを見極める原則、効果的なプロジェクトアーキテクチャの設計、エージェント支援開発を使った迅速な反復について説明します。この手法は、バッチ処理パイプライン、マルチエージェントのリサーチシステム、インタラクティブなエージェントアプリケーションのいずれを構築する場合にも適用できます。

このスキルの作業単位は、プロジェクト全体または複数段階のパイプラインです。個々のツール設計（説明、スキーマ、エラーメッセージ）は tool-design の対象です。スキルごとの有効化ルーティングは、対応するスキルとコーパスインデックスの対象です。このスキルが扱うのは、プロジェクトレベルの問いです。そもそもこれを LLM で構築すべきか、パイプラインをどのような形にするか、どれくらいのコストがかかるか、どのように反復すべきか、といった問いです。

有効化するタイミング

作業単位がプロジェクト全体またはパイプラインである場合は、このスキルを有効化してください。

• タスクに LLM が適切な基本要素かどうかを判断する（コードを書く前に、タスクとモデルの適合性を確認する）。
• 複数段階のバッチ処理またはエージェントパイプライン（取得／準備／処理／解析／描画）の構成を決める。
• LLM を多用するプロジェクトのトークン数、費用、所要時間を見積もる。
• プロジェクトレベルで、単一エージェントとマルチエージェントのどちらを選ぶか決める。
• エージェント支援による反復の構成を決める（エージェントがプロジェクト自体の構築を支援する場合）。
• パイプラインの契約レベルで構造化出力を設計する（段階間の受け渡し形式）。

他のスキルが担当する関連作業には、このスキルを有効化しないでください。

• ツールごとの説明、スキーマ、命名、応答形式、エラーメッセージ：tool-design。
• 軌跡ごとのトークン効率化の手法（マスキング、分割、キャッシュ）：context-optimization。
• エージェントのトポロジーレベルで、サブエージェントに作業を分担させるかどうかの判断：multi-agent-patterns。
• 自律制御ループの設計（固定された指標、新規性ゲート、人間の承認境界）：harness-engineering。

基本概念

タスクとモデルの適合性の見極め

コードを書く前に、タスクとモデルの適合性を評価してください。根本的に適合しないタスクを自動化すると、何日も労力を無駄にするためです。提案されたタスクを次の2つの表に照らし合わせ、進めるか中止するかを判断してください。

次の特性がある場合は進めてください。

特性	理由
複数の情報源を横断した統合	LLM は、ルールベースの代替手段よりも複数の入力から情報を統合するのが得意です
基準に基づく主観的な判断	採点、評価、分類は、基準を用いて自然に言語推論へと対応付けられます
自然言語による出力	目標が人間に読みやすい文章であれば、LLM はそれをそのまま生成できます
エラー許容度	個々の失敗でシステム全体が破綻しないため、LLM の非決定性を許容できます
バッチ処理	項目間で会話状態を維持する必要がなく、コンテキストを整理された状態に保てます
学習データに含まれるドメイン知識	モデルがすでに関連するコンテキストを持っているため、プロンプトエンジニアリングの負担を軽減できます

次の特性がある場合は中止してください。

特性	理由
厳密な計算	数学、計数、厳密なアルゴリズムは言語モデルでは信頼性に欠けます
リアルタイム要件	LLM のレイテンシーは、1秒未満の応答には高すぎます
完全な正確性の要件	ハルシネーションのリスクがあるため、100% の正確性は実現できません
独自データへの依存	モデルには必要なコンテキストがなく、プロンプトだけでは取得できません
逐次的な依存関係	各ステップが前の結果に大きく依存し、エラーが累積します
決定的な出力の要件	LLM は、同じ入力に対して同一の出力を保証できません

手動プロトタイプのステップ

自動化に投資する前に、必ず手動テストでタスクとモデルの適合性を検証してください。代表的な入力を1つモデルのインターフェースにコピーし、出力品質を評価して、その結果をもとに次の質問に答えます。

• このタスクに必要な知識をモデルは持っていますか？
• モデルは必要な形式で出力を生成できますか？
• 大規模に運用した場合、どの程度の品質が期待できますか？
• 対処すべき明らかな失敗パターンはありますか？

手動プロトタイプで失敗した場合、自動化したシステムも失敗すると予測できる一方、成功すれば品質の基準とプロンプト設計のテンプレートの両方が得られます。このテストは数分で完了し、開発に何時間も費やした末の失敗を防げます。

パイプラインアーキテクチャ

決定論的なステージと非決定論的なステージを分離することで、高速な反復とコスト管理が可能になるため、LLM プロジェクトは段階的なパイプラインとして構成してください。各ステージは次のように設計します。

• 独立性：ステージ間の境界を明確にし、それぞれを個別にデバッグできるようにします
• 冪等性：再実行しても同じ結果になり、作業の重複を防ぎます
• キャッシュ可能性：中間結果をディスクに保存し、コストのかかる再計算を避けます
• 独立実行可能性：各ステージを個別に実行でき、必要な箇所だけ再実行できます

次の標準的なパイプライン構造を使用してください。

acquire -> prepare -> process -> parse -> render

1. 取得：ソース（API、ファイル、データベース）から生データを取得します
2. 準備：データをプロンプト形式に変換します
3. 処理：LLM 呼び出しを実行します（コストが高く、非決定論的なステップです）
4. 解析：LLM の出力から構造化データを抽出します
5. 出力生成：最終的な出力（レポート、ファイル、可視化）を生成します

ステージ1、2、4、5は決定論的です。ステージ3は非決定論的で、コストがかかります。この分離を維持することで、必要な場合にのみコストの高いLLMステージを再実行しながら、解析と出力生成を迅速に反復できます。

ファイルシステムを状態機械として使う

ファイルの存在によって自然に冪等性が得られ、人が読み取ってデバッグできるため、データベースやメモリ内構造ではなく、ファイルシステムを使ってパイプラインの状態を管理してください。

data/{id}/
  raw.json         # acquire stage complete
  prompt.md        # prepare stage complete
  response.md      # process stage complete
  parsed.json      # parse stage complete

出力ファイルが存在するかどうかを確認し、項目の処理が必要か判断します。ステージを再実行するには、その出力ファイルと後続ステージのファイルを削除します。中間ファイルを直接読み取ってデバッグします。各ディレクトリが独立しているため、このパターンでは簡単に並列化でき、キャッシュも容易です。

構造化出力の設計

プロンプト設計が解析の信頼性を直接左右するため、解析可能な構造化出力を得られるようプロンプトを設計してください。構造化プロンプトには、次の要素を必ず含めます。

1. セクションマーカー：パーサーが照合できる明示的な見出しや接頭辞
2. 形式の例：出力がどのような形式になるべきかを正確に示します
3. 解析の明示：「プログラムで解析します」と伝え、形式の遵守を優先するようモデルに促します
4. 値の制約：列挙された選択肢、スコア範囲、固定形式

LLMは指示に完全には従わないため、LLM出力の揺れを柔軟に処理できるパーサーを構築してください。軽微な書式の違いに対応できる柔軟な正規表現パターンを使い、セクションが欠けている場合は妥当な既定値を設定し、クラッシュさせるのではなく、確認用に解析失敗をログに記録します。

エージェントを活用した開発

エージェント対応モデルを活用し、迅速な反復を通じて開発を加速してください。プロジェクトの目標と制約を説明し、エージェントに初期実装を生成させ、特定の失敗をテストして反復し、その結果に基づいてプロンプトとアーキテクチャを改善します。

エージェントの出力に集中力と品質を保たせるため、次の実践方法を取り入れてください。

• 修正の反復回数を減らすため、要件を最初に明確かつ具体的に伝えます
• 大規模なプロジェクトを個別に検証できる小さなコンポーネントに分割します
• 失敗を早期に発見できるよう、次に進む前に各コンポーネントをテストします
• コンテキストの劣化を防ぐため、一度に1つのタスクに集中させます

コストと規模の見積もり

処理を始める前に、LLM の処理コストを見積もってください。トークンコストは規模に応じて急速に積み重なり、予算超過が後から判明すると、コストのかかるやり直しが必要になるためです。次の式を使用してください。

Total cost = (items x tokens_per_item x price_per_token) + API overhead

バッチ処理では、項目あたりの入力トークン数（プロンプト＋コンテキスト）と、項目あたりの出力トークン数（一般的な応答の長さ）を見積もり、項目数を掛け合わせて、再試行や失敗に備えて20～30％の余裕を加えてください。

開発中は実際のコストを追跡してください。コストが見積もりを大幅に超える場合は、切り詰めてコンテキストの長さを減らす、単純な項目にはより小型のモデルを使う、中間結果をキャッシュして再利用する、または並列処理を追加して経過時間を短縮するといった方法を検討してください。

詳細なトピック

シングルエージェントとマルチエージェントのアーキテクチャの選択

独立した項目をバッチ処理する場合は、シングルエージェントのパイプラインを基本としてください。管理が簡単で、実行コストが低く、デバッグもしやすいためです。次のいずれかに該当する場合にのみ、マルチエージェントアーキテクチャを検討してください。

• さまざまな側面を並行して調査する必要がある
• タスクが単一のコンテキストウィンドウの容量を超える
• 専門化されたサブエージェントによって、ベンチマークで品質が明確に向上する

マルチエージェントは役割の擬人化ではなく、コンテキストの分離を目的として選択してください。サブエージェントは、焦点を絞ったサブタスクごとに新しいコンテキストウィンドウを取得するため、長時間実行されるタスクでコンテキストが劣化するのを防ぎます。

アーキテクチャの詳細な指針については、multi-agent-patterns スキルを参照してください。

アーキテクチャの簡素化

最小限のアーキテクチャから始め、本番環境での証拠が必要性を示した場合にのみ複雑さを加えてください。過剰に設計された土台は、モデルの性能を高めるどころか、制約になることが多いためです。

Vercel の d0 事例では、多数の専門化されたツールを、コマンド実行と SQL という2つの基本機能に絞った後、成功率が向上したと報告されています（claim-project-development-vercel-d0-reduction）。ファイルシステムエージェントのパターンでは、独自の調査ツールではなく標準的な Unix ユーティリティを使用します。

簡素化する場合：

• データレイヤーの文書が整備され、一貫した構造になっている
• モデルに十分な推論能力がある
• 専門化されたツールが性能を高めるのではなく、制約になっている
• 成果の向上よりも土台の保守に多くの時間を費やしている

複雑さを加える場合：

• 基盤となるデータが乱雑で、一貫性がない、または文書化が不十分である
• モデルが持たない専門知識をドメインが必要としている
• 安全上の制約により、エージェントの機能を制限する必要がある
• 処理が本当に複雑で、構造化されたワークフローによって効果が得られる

ツールアーキテクチャの詳細な指針については、tool-design スキルを参照してください。

イテレーションとリファクタリング

大規模な本番環境のエージェントシステムでは、必ずリファクタリングが必要になるため、当初から複数回のアーキテクチャ変更を計画してください。Manus は公開以来、エージェントのフレームワークを5回リファクタリングしました。Bitter Lesson が示すように、現在のモデルの制約に合わせて追加された構造は、モデルの改善に伴って制約になります。

次のプラクティスに従い、変更に対応できるようにしてください。

• アーキテクチャをシンプルで特定の設計思想に縛られないものに保ち、リファクタリングを低コストにする
• 複数世代のモデルでテストし、ハーネスが性能を制限していないことを確認する
• 制約を固定化するのではなく、モデルの改善によって恩恵を受けられるシステムを設計する

実践的な指針

プロジェクト計画テンプレート

各ステップでは、次のステップに労力をかける前に前提を検証するため、以下の順序に従ってください。

1. タスク分析

   • 入力と期待する出力を明確に定義します
   • タスクを分類します：統合、生成、分類、分析
   • ビジネスへの影響に基づいて許容できるエラー率を設定します
   • コストを正当化するため、成功時の価値を見積もります

2. 手動検証

   • 対象モデルを使って、代表的な例を1つテストします
   • 要件に照らして、出力の品質と形式を評価します
   • パーサーの強化またはプロンプトの修正が必要となる失敗パターンを特定します
   • コスト予測のため、項目あたりのトークン数を見積もります

3. アーキテクチャの選定

   • 前述の基準に基づき、単一パイプラインとマルチエージェントのどちらかを選択します
   • 必要なツールとデータソースを特定します
   • ファイルシステムの状態を利用したストレージおよびキャッシュ戦略を設計します
   • 処理段階の並列化方法を計画します

4. コスト見積もり

   • 項目数 x トークン数 x 価格を計算し、20〜30%の余裕を加えます
   • 各パイプライン段階の開発時間を見積もります
   • インフラ要件（API キー、ストレージ、コンピューティング）を特定します
   • 本番実行にかかる継続的な運用コストを予測します

5. 開発計画

   • 段階ごとに実装し、次に進む前に各段階をテストします
   • 期待する出力を含め、段階ごとのテスト戦略を定義します
   • 品質指標に結び付いた反復開発のマイルストーンを設定します
   • ロールバック機能を備えたデプロイ方法を計画します

例

例 1：バッチ分析パイプライン（Karpathy's HN Time Capsule）

タスク：10年前の HN ディスカッション930件を、後知恵を踏まえて評価しながら分析します。

アーキテクチャ：

• 5段階のパイプライン：fetch -> prompt -> analyze -> parse -> render
• ファイルシステムの状態：data/{date}/{item_id}/ に段階ごとの出力ファイルを保存
• 構造化出力：明示的な形式要件を備えた6つのセクション
• 並列実行：LLM 呼び出し用に15ワーカー

結果：総コスト58ドル、実行時間約1時間、静的 HTML 出力。

例 2：アーキテクチャの縮小（Vercel d0）

タスク：社内分析向けのテキストから SQL を生成するエージェント。

変更前：成功率の測定値が低く、平均実行時間も長い多数の専用ツール。

変更後：成功率の測定値が高く、平均実行時間も短い2つのツール（bash + SQL）（claim-project-development-vercel-d0-reduction）。

重要な知見：セマンティックレイヤーは、すでに優れたドキュメントになっていました。Claude が必要としていたのは、ファイルを直接読み取るアクセスだけでした。

詳しい分析については、ケーススタディを参照してください。

ガイドライン

1. 自動化を構築する前に、手動でプロトタイプを作成してタスクとモデルの適合性を検証します
2. パイプラインを、個別に実行でき、冪等でキャッシュ可能な段階として構成します
3. 状態管理とデバッグにはファイルシステムを使用します
4. 明示的な形式例を含め、構造化され解析可能な出力を生成するプロンプトを設計します
5. 最小限のアーキテクチャから始め、必要性が実証された場合にのみ複雑さを加えます
6. 早い段階でコストを見積もり、開発全体を通して追跡します
7. LLM 出力のばらつきに対応できる堅牢なパーサーを構築します
8. アーキテクチャを何度も見直すことを想定し、計画に含めます
9. 足場となる仕組みがモデルの性能を高めるか、制約するかをテストします
10. 実装をすばやく反復するため、エージェント支援型の開発を活用します

注意点

1. 手動検証を省略する：手法そのものに根本的な問題がある場合、モデルがタスクを実行できるか確認する前に自動化を構築すると、多くの時間を無駄にします。まず、代表的な例を1つモデルのインターフェースで実行してください。
2. モノリシックなパイプライン：すべての段階を1つのスクリプトにまとめると、デバッグや反復が難しくなります。各段階を分け、中間出力を保持して、それぞれを独立して再実行できるようにしてください。
3. モデルを過度に制約する：モデル自身で処理できるガードレール、事前フィルタリング、検証ロジックを追加すると、パフォーマンスが低下します。足場となる仕組みが役立つのか、妨げになるのかをテストしてから、残すかどうかを決めてください。
4. 本番環境までコストを考慮しない：規模が大きくなると、トークンのコストはすぐに積み重なります。予算超過によるアーキテクチャの再設計を避けるため、最初から見積もりと追跡を行ってください。
5. 完璧な解析を求める：LLM が形式の指示に完璧に従うことを期待すると、壊れやすいシステムになります。さまざまな形式に対応できる堅牢なパーサーを構築し、失敗を記録して確認できるようにしてください。
6. 時期尚早な最適化：基本的なパイプラインが正しく動作する前に、キャッシュ、並列化、最適化を追加すると、反復中に破棄される可能性のあるコードに労力を費やすことになります。
7. モデルのバージョン固定：特定のモデルバージョンでしか動作しないパイプラインを構築すると、壊れやすいシステムになります。複数世代のモデルでテストし、LLM 呼び出しレイヤーを抽象化して、パイプラインのロジックを書き直さずにモデルを切り替えられるようにしてください。
8. 評価なしのデプロイ：出力品質を測定せずにエージェントのパイプラインをリリースすると、性能の劣化を検出できません。開発中に品質指標を定義し、モデルやプロンプトを変更するたびに、その前後で評価チェックを実行してください。
9. 出所情報の分散：未加工の入力、中間出力、最終提案が場当たり的なフォルダーに分散すると、監査が不可能になります。ソースの根拠、変換内容、検証レポート、判断をまとめて、各パイプラインの実行結果を1つのディレクトリに保存してください。

統合

プロジェクトの構成とパイプラインに関する判断は、このスキルが担います。隣接する判断は、ほかのスキルが担います。

• tool-design：ツールごとのインターフェース層（説明、スキーマ、レスポンス形式、エラーメッセージ、MCP の名前空間、個々のツールの統合）。「パイプラインをどう設計すべきか」ではなく「この特定のツールをどのような形にすべきか」という質問の場合は、こちらに振り分けてください。
• multi-agent-patterns：エージェントのトポロジーに関する判断（スーパーバイザー型かスウォーム型か階層型か、引き継ぎプロトコル、エージェント間のコンテキスト分離）。このスキルはプロジェクトレベルで単一エージェントか複数エージェントかを選びます。トポロジーの詳細は multi-agent-patterns が担います。
• harness-engineering：プロジェクトを取り巻く自律制御ループ（固定された指標、新規性ゲート、実行状態のステートマシン、人間の承認境界）。「何日間も無人で実行し続けるにはどうすればよいか」という質問の場合は、こちらに振り分けてください。
• context-fundamentals：各段階のプロンプト設計に影響する、コンテキスト制約の概念的な枠組み。
• evaluation：パイプライン実行の成果測定と品質ゲート。
• context-compression：長時間実行されるパイプラインの段階で、要約が必要な軌跡が生成される場合。

参考資料

内部の参考資料：

• 事例研究 - 次の場合に参照してください：アーキテクチャのトレードオフを評価するとき、または実際のパイプライン実装（Karpathy HN Capsule、Vercel d0、Manus のパターン）を確認するとき
• パイプラインのパターン - 次の場合に参照してください：新しいパイプラインのステージ構成を設計するとき、キャッシュ戦略を選ぶとき、またはステージの境界をデバッグするとき

このコレクション内の関連スキル：

• tool-design - ツールのアーキテクチャと削減パターン
• multi-agent-patterns - マルチエージェントアーキテクチャを使用する場面
• evaluation - 出力評価フレームワーク

外部リソース：

• Karpathy の HN Time Capsule プロジェクト：https://github.com/karpathy/hn-time-capsule
• Vercel d0 のアーキテクチャ削減：https://vercel.com/blog/we-removed-80-percent-of-our-agents-tools
• Manus のコンテキストエンジニアリング：コンテキストエンジニアリングの教訓に関する Peak Ji のブログ
• Anthropic のマルチエージェント研究：マルチエージェント研究システムの構築方法

---

スキルのメタデータ

作成日: 2025-12-25 最終更新日: 2026-05-15 作成者: Agent Skills for Context Engineering Contributors バージョン: 1.3.0