project-development

プロジェクト開発の方法論

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

有効化するタイミング

次の場合にこのスキルを有効にします。

• LLM による処理が役立つ可能性のある新しいプロジェクトを始めるとき
• タスクが従来のコードよりもエージェントに適しているかどうかを評価するとき
• LLM を活用したアプリケーションのアーキテクチャを設計するとき
• 構造化出力を伴うバッチ処理パイプラインを計画するとき
• 単一エージェントとマルチエージェントのどちらを採用するか選ぶとき
• LLM を多用するプロジェクトのコストや期間を見積もるとき

基本概念

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

すべての問題が LLM による処理に適しているわけではありません。プロジェクトの最初のステップでは、タスクの特性が LLM の強みと一致するかを評価します。この評価は、コードを書く前に行う必要があります。

LLM に適したタスクには、次のような特性があります。

特性	適している理由
複数の情報源を横断した統合	LLM は複数の入力から情報を組み合わせることに優れています
評価基準に基づく主観的判断	LLM は基準に沿った採点、評価、分類に対応できます
自然言語での出力	目的が構造化データではなく、人が読めるテキストである場合
エラー許容性	個々の失敗がシステム全体を壊すことはありません
バッチ処理	項目間で会話状態を維持する必要がありません
学習済みのドメイン知識	モデルがすでに関連するコンテキストを持っています

LLM に適さないタスクには、次のような特性があります。

特性	適さない理由
正確な計算	数学、カウント、厳密なアルゴリズムは信頼性に欠けます
リアルタイム性の要件	LLM のレイテンシーは、1 秒未満の応答には長すぎます
完全な正確性の要件	ハルシネーションのリスクがあるため、100％の正確性は不可能です
独自データへの依存	モデルには必要なコンテキストがありません
逐次的な依存関係	各ステップが直前の結果に大きく依存します
決定的な出力の要件	同じ入力から常に同一の出力が必要です

評価は手動のプロトタイピングで行います。代表的な例を1つ選び、自動化を構築する前に対象モデルで直接テストします。

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

自動化に投資する前に、手動テストでタスクとモデルの適合性を検証します。代表的な入力を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

項目を処理する必要があるかどうかを確認するには、出力ファイルが存在するかどうかを確認します。ステージを再実行するには、その出力ファイルと下流のファイルを削除します。デバッグするには、中間ファイルを直接読み取ります。

このパターンが提供するもの:

• 自然な冪等性（ファイルの存在が実行を制御します）
• 容易なデバッグ（すべての状態が人間可読です）
• 単純な並列化（各ディレクトリが独立しています）
• 自明なキャッシュ（ファイルは実行間で永続化されます）

構造化出力の設計

LLM の出力をプログラムで解析する必要がある場合、プロンプトの設計が解析の信頼性を直接左右します。プロンプトには、正確なフォーマット要件を例を挙げて指定する必要があります。

効果的な構造指定には次が含まれます:

1. セクションマーカー: 解析のための明示的な見出しやプレフィックス
2. フォーマット例: 出力がどのようになるべきかを正確に示します
3. 理由の開示: 「これはプログラムで解析します」
4. 制約された値: 列挙された選択肢、スコア範囲、フォーマット

プロンプト構造の例:

Analyze the following and provide your response in exactly this format:

## Summary
[Your summary here]

## Score
Rating: [1-10]

## Details
- Key point 1
- Key point 2

Follow this format exactly because I will be parsing it programmatically.

解析コードは変動に柔軟に対応しなければなりません。LLM は指示に完全には従いません。次のようなパーサーを構築します:

• 軽微なフォーマットの変動に対応できる十分に柔軟な正規表現パターンを使用する
• セクションが欠けている場合に妥当なデフォルトを提供する
• クラッシュするのではなく、後で確認できるように解析失敗をログに記録する

エージェント支援開発

最新のエージェント対応モデルは、開発を大幅に加速できます。パターンは次のとおりです:

1. プロジェクトの目標と制約を記述する
2. エージェントに初期実装を生成させる
3. 特定の失敗についてテストして反復する
4. 結果に基づいてプロンプトとアーキテクチャを洗練させる

これは迅速な反復、つまり生成、テスト、修正、繰り返しに関するものです。エージェントが定型コードと初期構造を処理し、その間にあなたはドメイン固有の要件とエッジケースに集中します。

効果的なエージェント支援開発のための主要な実践:

• 明確で具体的な要件を事前に提供する
• 大きなプロジェクトを個別のコンポーネントに分割する
• 次に進む前に各コンポーネントをテストする
• エージェントを一度に1つのタスクに集中させる

コストと規模の見積もり

LLM 処理には予測可能なコストがあり、開始前に見積もるべきです。計算式は次のとおりです:

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

バッチ処理の場合:

• 項目ごとの入力トークン数を見積もる（プロンプト + コンテキスト）
• 項目ごとの出力トークン数を見積もる（典型的な応答長）
• 項目数で乗算する
• 再試行と失敗のために20〜30%のバッファを加える

開発中は実際のコストを追跡します。コストが見積もりを大幅に超える場合は、アプローチを再評価します。次を検討します:

• 切り詰めによってコンテキスト長を削減する
• より単純な項目にはより小さなモデルを使用する
• 部分的な結果をキャッシュして再利用する
• 並列処理で実時間を短縮する（トークンコストではありません）

詳細トピック

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

シングルエージェントのパイプラインは次に有効です:

• 独立した項目のバッチ処理
• 項目が相互作用しないタスク
• より単純なコストと複雑さの管理

マルチエージェントアーキテクチャは次に有効です:

• 異なる側面の並列探索
• 単一のコンテキストウィンドウの容量を超えるタスク
• 専門化されたサブエージェントが品質を向上させる場合

マルチエージェントの主な理由はコンテキストの分離であり、役割の擬人化ではありません。サブエージェントは集中したサブタスクのために新しいコンテキストウィンドウを取得します。これにより、長時間実行されるタスクでのコンテキスト劣化を防ぎます。

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

アーキテクチャの削減

最小限のアーキテクチャから始めます。複雑さは、必要であることが証明された場合にのみ追加します。本番環境での証拠は、専門化されたツールを削除することでパフォーマンスが向上することが多いことを示しています。

Vercel の d0 エージェントは、17 個の専門化されたツールから 2 つのプリミティブ（bash コマンド実行と SQL）に削減することで、100% の成功率（80% から向上）を達成しました。ファイルシステムエージェントパターンでは、カスタムの探索ツールの代わりに標準の Unix ユーティリティ（grep、cat、find、ls）を使用します。

削減が複雑さを上回る場合:

• データレイヤーが十分に文書化され、一貫した構造になっている
• モデルに十分な推論能力がある
• 専門化されたツールが、可能にするのではなく制約になっていた
• 成果の改善よりもスキャフォールディングの維持に多くの時間を費やしている

複雑さが必要な場合:

• 基盤となるデータが乱雑、不一致、または十分に文書化されていない
• そのドメインが、モデルに欠けている専門知識を必要とする
• 安全上の制約により、エージェントの機能を制限する必要がある
• 操作が真に複雑で、構造化されたワークフローから恩恵を受ける

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

反復とリファクタリング

リファクタリングを想定してください。大規模な本番エージェントシステムには、複数回のアーキテクチャの反復が必要です。Manus はリリース以来、エージェントフレームワークを 5 回リファクタリングしました。The Bitter Lesson は、現在のモデルの限界のために追加された構造が、モデルの改善に伴って制約になることを示唆しています。

変更に備えて構築する:

• アーキテクチャをシンプルかつ意見を挟まないものに保つ
• モデルの強みを横断してテストし、ハーネスがパフォーマンスを制限していないことを検証する
• 限界を固定するのではなく、モデルの改善から恩恵を受けるシステムを設計する

実践的なガイダンス

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

1. タスク分析

   • 入力は何ですか？ 望ましい出力は何ですか？
   • これは合成、生成、分類、分析のどれですか？
   • 許容できるエラー率はどのくらいですか？
   • 成功した完了 1 件あたりの価値はどのくらいですか？

2. 手動検証

   • 対象モデルで 1 つの例をテストする
   • 出力の品質と形式を評価する
   • 失敗モードを特定する
   • 項目あたりのトークン数を見積もる

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

   • 単一パイプラインかマルチエージェントか
   • 必要なツールとデータソース
   • ストレージとキャッシュの戦略
   • 並列化のアプローチ

4. コスト見積もり

   • 項目数 × トークン数 × 価格
   • 開発時間
   • インフラストラクチャの要件
   • 継続的な運用コスト

5. 開発計画

   • 段階ごとの実装
   • 段階ごとのテスト戦略
   • 反復のマイルストーン
   • デプロイのアプローチ

避けるべきアンチパターン

手動検証の省略: モデルがタスクを実行できることを検証する前に自動化を構築すると、アプローチが根本的に欠陥している場合に多大な時間を浪費します。

モノリシックなパイプライン: すべての段階を 1 つのスクリプトにまとめると、デバッグと反復が困難になります。段階を分離し、中間出力を永続化してください。

モデルの過度な制約: モデル自身で処理できるはずのガードレール、事前フィルタリング、検証ロジックを追加すること。スキャフォールディングが役立つか害になるかをテストしてください。

本番環境までコストを無視する: トークンコストは規模が大きくなるにつれて急速に積み上がります。最初から見積もり、追跡してください。

完璧なパース要件: LLM が形式の指示に完全に従うことを期待すること。ばらつきに対応する堅牢なパーサーを構築してください。

時期尚早な最適化: 基本的なパイプラインが正しく動作する前に、キャッシュ、並列化、最適化を追加すること。

例

例 1：バッチ分析パイプライン（Karpathy の 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 へのエージェント。

変更前：専門ツール 17 個、成功率 80％、平均実行時間 274 秒。

変更後：ツール 2 個（bash + SQL）、成功率 100％、平均実行時間 77 秒。

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

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

ガイドライン

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

統合

このスキルは、以下と連携します：

• context-fundamentals - プロンプト設計におけるコンテキストの制約を理解する
• tool-design - パイプライン内のエージェントシステム向けにツールを設計する
• multi-agent-patterns - マルチエージェントと単一パイプラインのどちらを使うか判断する
• 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 最終更新日：2025-12-25 作成者：Agent Skills for Context Engineering Contributors バージョン：1.0.0