project-development

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

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

使用する場面

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

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

基本概念

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

すべての問題が LLM 処理のメリットを得られるわけではありません。どのプロジェクトでも、まずタスクの特性が LLM の強みと合致するかを評価します。この評価はコードを書く前に行う必要があります。

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

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

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

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

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

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

自動化に投資する前に、手動テストでタスクとモデルの適合性を検証します。承認済みのモデルインターフェースを使い、使用が許可された合成入力または最小化した入力を使用してください。独自データを未承認のサービスにアップロードしてはいけません。出力の品質を評価します。これには数分しかかからず、開発に何時間も費やした後で無駄だとわかる事態を防げます。

この検証では、次の重要な問いに答えます。

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

プロトタイプの失敗は診断の手がかりであり、すべてのアーキテクチャが失敗することの証明ではありません。成功した例は出発点にすぎず、大規模運用での検証にはなりません。代表的なケースと敵対的なケースを、学習に使っていない評価データでテストしてください。

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

LLM プロジェクトでは、各ステージが次の特性を持つ段階的なパイプラインアーキテクチャが有効です。

• 独立している：ステージ間の境界が明確です
• 冪等性がある：操作を繰り返しても、外部から確認できる効果が重複しません。同一の LLM テキストを生成できることは、別個の決定性の特性です
• キャッシュ可能である：中間結果がディスクに保存されます
• 独立して実行できる：各ステージを個別に実行できます

標準的なパイプライン構造：

acquire → prepare → process → parse → render

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

ファイルの存在だけでは、完了や冪等性を保証できません。一時ファイルに書き込み、検証後にのみアトミックに名前を変更してください。マニフェストには、入力ハッシュ、モデル／プロンプト／ツールのバージョン、スキーマ、ステータス、出力ハッシュ、リクエスト識別子を記録します。不完全な出力や古い出力は未完了として扱い、各項目の変更中はロックし、依存関係が変わった場合は下流のキャッシュを無効化してください。再試行するために、課金対象または外部アクションが不確かな場合の証跡を安易に削除しないでください。保存済みのリクエスト ID を使って照合します。同時書き込みやトランザクション要件がファイルベースの調整では対応できない場合は、データベース／キューを使用してください。

構造化出力の設計

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. 結果に基づいてプロンプトとアーキテクチャを調整します

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

エージェントを活用した開発を効果的に進めるための主な実践事項：

• 明確で具体的な要件を事前に提示します
• 大規模なプロジェクトを独立したコンポーネントに分割します
• 次に進む前に、各コンポーネントをテストします
• エージェントが一度に一つのタスクに集中できるようにします

コストと規模の見積もり

LLM の処理には予測可能なコストがかかるため、開始前に見積もる必要があります。計算式は次のとおりです。

Total cost = input_tokens × input_rate + output_tokens × output_rate + reasoning/tool/media charges + retries + infrastructure

バッチ処理の場合：

• アイテムごとの入力トークン数を見積もります（プロンプト＋コンテキスト）
• アイテムごとの出力トークン数を見積もります（一般的な応答の長さ）
• アイテム数を掛けます
• 再試行や失敗に備えて、20～30％の余裕を加えます

開発中は実際のコストを追跡してください。コストが見積もりを大幅に上回る場合は、アプローチを再評価してください。次の方法を検討してください。

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

詳細なトピック

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

単一エージェントのパイプラインが適しているのは、次のような場合です。

• 独立したアイテムをバッチ処理する
• アイテム同士が相互に作用しないタスク
• コストと複雑さの管理をより簡潔にしたい

マルチエージェントアーキテクチャが適しているのは、次のような場合です。

• 異なる側面を並行して調査する
• 単一のコンテキストウィンドウの容量を超えるタスク
• 専門化されたサブエージェントによって品質が向上する

マルチエージェントを採用する主な理由は、役割を擬人化することではなく、コンテキストを分離することです。サブエージェントは、焦点を絞ったサブタスクごとに新しいコンテキストウィンドウを使います。これにより、長時間実行するタスクでコンテキストが劣化するのを防げます。

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

アーキテクチャの簡素化

最小限のアーキテクチャから始めてください。複雑さを加えるのは、その必要性が明らかになってからにします。ツールを減らすことで実際のタスクが改善するかどうかを評価してください。より汎用的なシェルや SQL のプリミティブは、権限の範囲と障害の影響を拡大する可能性があります。

リンク先の Vercel の事例研究は、特定の環境における一例であり、一般的な成功率を保証するものではありません。

簡素化が複雑化を上回る場合：

• データレイヤーのドキュメントが整っており、一貫した構造になっている
• モデルに十分な推論能力がある
• 特化したツールが能力を高めるのではなく、制約になっていた
• 成果の向上よりも、足場となる仕組みの保守に多くの時間を費やしている

複雑さが必要な場合：

• 基盤となるデータが雑然としていたり、一貫性に欠けていたり、ドキュメントが不十分だったりする
• ドメインに、モデルが持たない専門知識が求められる
• 安全性の制約により、エージェントの機能を制限する必要がある
• 操作が本当に複雑で、構造化されたワークフローによって効果が得られる

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

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

リファクタリングが必要になることを想定してください。大規模な本番エージェントシステムでは、アーキテクチャを複数回にわたって見直す必要があります。リンク先のコンテキストエンジニアリングの経験は、歴史的かつ特定の環境におけるものです。The Bitter Lesson が示すように、現在のモデルの制約に合わせて追加した構造は、モデルの改善に伴って制約になることがあります。

変更に備えて構築しましょう。

• アーキテクチャをシンプルで、特定の方針を押し付けないものに保つ
• モデルの強みを変えてテストし、ハーネスがパフォーマンスを制限していないことを確認する
• 制約を固定化するのではなく、モデルの改善を活かせるシステムを設計する

実践的なガイダンス

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

1. タスク分析

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

2. 手動での検証

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

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

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

4. コストの見積もり

   • アイテム数 × トークン数 × 価格
   • 開発時間
   • インフラ要件
   • 継続的な運用コスト

5. 開発計画

   • 段階ごとの実装
   • 各段階のテスト戦略
   • イテレーションのマイルストーン
   • デプロイ方法

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

手動検証を省略する：アプローチに根本的な問題がある場合、自動化を構築する前にモデルがタスクを実行できることを検証していないと、大幅な時間を無駄にします。

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

モデルを過度に制約する：評価後にのみ、不要なワークフローの複雑さを取り除いてください。決定論的な認可、入出力の検証、安全性の境界はモデルの外部に維持してください。

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

完璧な解析を求める：LLMが形式の指示に完全に従うと期待することです。さまざまな形式の違いに対応できる堅牢なパーサーを構築してください。

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

例

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

タスク：10年前のHNディスカッション930件を、後知恵による評価で分析します。

アーキテクチャ：

• 5段階のパイプライン：取得 → プロンプト → 分析 → 解析 → レンダリング
• ファイルシステムの状態：各段階の出力ファイルを含むdata/{date}/{item_id}/
• 構造化された出力：形式要件を明示した6つのセクション
• 並列実行：LLM呼び出しに15個のワーカーを使用

過去の事例研究の結果は、リンク先の一次資料とその評価条件に照らして検証する必要があります。これらは、新しいプロジェクトのコスト、レイテンシ、成功率の見積もりではありません。Case StudiesまたはPipeline Patternsの補助ファイルは同梱されていません。

ガイドライン

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

統合

このスキルは次のスキルと連携します：

• context-fundamentals - プロンプト設計におけるコンテキストの制約を理解する
• tool-design - パイプライン内のエージェントシステム向けツールを設計する
• multi-agent-patterns - マルチエージェントと単一パイプラインのどちらを使うか判断する
• evaluation - パイプラインの出力とエージェントの性能を評価する
• context-compression - パイプラインが制限を超える場合にコンテキストを管理する

参考資料

内部資料：

• Case Studies - Karpathy HN Capsule、Vercel d0、Manusのパターン
• Pipeline Patterns - パイプラインアーキテクチャに関する詳細な指針

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

• 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

制限事項

• このスキルは、タスクが上記の対象範囲に明確に該当する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全性の境界、または成功基準が不足している場合は、作業を中断して確認を求めてください。