うちのチームに新しいメンバーが入ってきて、「LangChainを使えば開発全部自動化できますよね？」と言い出しまして。気持ちはわかるんですが、そこには大きな落とし穴があります。要件定義で使うべき思考と、テストケースを考えるときの思考は、根本的に違う。それを1つのエージェントに丸投げするとどうなるか——自分で試して痛い目を見ました。この記事では、フェーズごとに専門エージェントを分業させるアーキテクチャをLangChainで実装する方法を、実際に動くコードとともに解説します。
注目ポイント
エージェントはステートレスに設計し、フェーズ間の引き渡しは「ドキュメントオブジェクト」で行うのが安定運用の鍵。コンテキストを引き継ぐのではなく、前フェーズの成果物を次フェーズへの入力として渡す。
なぜ「1エージェント・全工程」は破綻するのか
LangChainのReActエージェントやLCELチェーンを使って「ユーザーの要望を入力したら設計書とコードとテストが出てくる」パイプラインを作ろうとした経験がある方は多いと思います。最初の数回は動く。でも少し複雑な要件を入れた途端、出力が崩れ始める。
原因はシンプルで、LLMのコンテキストウィンドウには限界があるからです。要件定義の議論をしながら、同時に実装コードの詳細まで考えさせると、どちらも中途半端になる。さらに問題なのは、エラーになるのではなく「それっぽい何か」が出力されてしまうこと。これが一番タチが悪い。
よくある失敗パターン
「1つの巨大プロンプトに全フェーズの指示を詰め込む」アプローチ。最初は動いて見えるが、要件が複雑になった瞬間に崩壊する。プロンプトエンジニアリングで解決しようとするより、設計を分けるほうが早い。
全体設計と前提環境
今回実装する構成はこうなります。4つの専門エージェントを順番に実行し、各エージェントの出力をPydanticモデルで型定義した「ドキュメントオブジェクト」として次のエージェントに渡します。
# 全体のフロー
ユーザー入力（要件メモ）
↓
RequirementsAgent → RequirementsDoc（曖昧さリスト・確定仕様）
↓
DesignAgent → DesignDoc（アーキテクチャ・API定義・DB設計）
↓
CodingAgent → CodeDoc（実装コード・ファイル構成）
↓
TestAgent → TestDoc（テストケース・テストコード）
前提環境
pip install langchain langchain-community langchain-core
pip install pydantic ollama
# Ollamaでモデルを起動しておく
ollama run gpt-oss:20b
OpenAI APIを使う場合は langchain-openai に差し替えるだけです。今回はローカルLLM（Ollama）ベースで書きますが、モデル部分は差し替え可能な設計にします。
要件定義エージェント：曖昧さを構造化する
要件定義エージェントの仕事は2つ。ひとつは入力テキストから曖昧な箇所を検出して質問リストを生成すること、もうひとつは確定した仕様を構造化されたオブジェクトに変換することです。
from langchain_community.llms import Ollama
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import JsonOutputParser
from pydantic import BaseModel, Field
from typing import List
# 出力の型定義
class RequirementsDoc(BaseModel):
ambiguities: List[str] = Field(description="曖昧な点・確認が必要な事項のリスト")
confirmed_specs: List[str] = Field(description="確定した仕様のリスト")
constraints: List[str] = Field(description="技術的・ビジネス的制約のリスト")
summary: str = Field(description="要件の概要（2〜3文）")
class RequirementsAgent:
def __init__(self, model_name: str = "gpt-oss:20b"):
self.llm = Ollama(model=model_name, temperature=0.1)
self.parser = JsonOutputParser(pydantic_object=RequirementsDoc)
self.prompt = ChatPromptTemplate.from_messages([
("system", """あなたはシニアのシステムアナリストです。
入力された要件テキストを分析し、以下を必ずJSON形式で出力してください。
- 定義が曖昧で確認が必要な項目
- 確定した仕様
- 技術的・ビジネス的制約
- 要件の概要
{format_instructions}"""),
("human", "以下の要件を分析してください:\n\n{requirements_text}")
])
def run(self, requirements_text: str) -> RequirementsDoc:
chain = self.prompt | self.llm | self.parser
result = chain.invoke({
"requirements_text": requirements_text,
"format_instructions": self.parser.get_format_instructions()
})
return RequirementsDoc(**result)
設計のポイント
temperature=0.1 に設定するのがミソ。要件定義は「創造性」より「網羅性・一貫性」が重要なので、低めのtemperatureで安定した出力を得る。
設計エージェント：仕様書からアーキテクチャを生成する
設計エージェントは RequirementsDoc を受け取り、アーキテクチャ案・API定義・DBスキーマを出力します。ここでのポイントは、前フェーズの「曖昧さリスト」も一緒に渡すこと。曖昧なままの仕様を無視した設計を出力させないためです。
class DesignDoc(BaseModel):
architecture: str = Field(description="アーキテクチャの説明（テキスト）")
api_endpoints: List[dict] = Field(description="APIエンドポイント定義リスト")
db_schema: List[dict] = Field(description="DBテーブル定義リスト")
tech_stack: List[str] = Field(description="使用技術スタック")
assumptions: List[str] = Field(description="設計上の前提・仮定（曖昧仕様への対応）")
class DesignAgent:
def __init__(self, model_name: str = "gpt-oss:20b"):
self.llm = Ollama(model=model_name, temperature=0.2)
self.parser = JsonOutputParser(pydantic_object=DesignDoc)
self.prompt = ChatPromptTemplate.from_messages([
("system", """あなたはシニアのソフトウェアアーキテクトです。
確定仕様と制約に基づいてシステム設計を行い、JSON形式で出力してください。
曖昧な仕様については、設計上の前提として assumptions に明記してください。
{format_instructions}"""),
("human", """確定仕様: {confirmed_specs}
制約: {constraints}
曖昧な点（前提として扱う）: {ambiguities}
要件概要: {summary}""")
])
def run(self, req_doc: RequirementsDoc) -> DesignDoc:
chain = self.prompt | self.llm | self.parser
result = chain.invoke({
"confirmed_specs": "\n".join(req_doc.confirmed_specs),
"constraints": "\n".join(req_doc.constraints),
"ambiguities": "\n".join(req_doc.ambiguities),
"summary": req_doc.summary,
"format_instructions": self.parser.get_format_instructions()
})
return DesignDoc(**result)
実装エージェント：設計書をコードに落とす
実装エージェントは DesignDoc のAPIエンドポイント定義とDBスキーマを受け取り、コードを生成します。全体を一度に生成しようとするとコンテキスト超過するので、エンドポイントごとに分割して呼び出す設計にしています。
class CodeDoc(BaseModel):
files: List[dict] = Field(description="生成したファイルのリスト（filename, content）")
setup_instructions: str = Field(description="セットアップ手順")
class CodingAgent:
def __init__(self, model_name: str = "gpt-oss:20b"):
self.llm = Ollama(model=model_name, temperature=0.15)
self.prompt = ChatPromptTemplate.from_messages([
("system", """あなたはシニアのバックエンドエンジニアです。
設計書に基づいてPythonコードを生成してください。
- FastAPIを使用
- 型ヒントを必ず付ける
- docstringは英語で記述
- エラーハンドリングを適切に実装"""),
("human", """以下のAPIエンドポイントを実装してください:
{endpoint}
DBスキーマ: {db_schema}
技術スタック: {tech_stack}""")
])
def run(self, design_doc: DesignDoc) -> CodeDoc:
all_files = []
# エンドポイントごとに分割生成
for endpoint in design_doc.api_endpoints:
chain = self.prompt | self.llm
code = chain.invoke({
"endpoint": str(endpoint),
"db_schema": str(design_doc.db_schema),
"tech_stack": ", ".join(design_doc.tech_stack)
})
all_files.append({
"filename": f"api_{endpoint.get('path','').strip('/').replace('/','_')}.py",
"content": code
})
return CodeDoc(
files=all_files,
setup_instructions=f"Tech stack: {', '.join(design_doc.tech_stack)}"
)
テストエージェント：コードからテストを生成する
テストエージェントは生成されたコードファイルを受け取り、pytestベースのテストコードを生成します。ここでもファイルごとに分割呼び出しです。一度に全コードを渡すとテストの質が落ちる。
class TestDoc(BaseModel):
test_files: List[dict] = Field(description="テストファイルのリスト（filename, content）")
coverage_notes: List[str] = Field(description="カバレッジ上の注意点・未テスト箇所")
class TestAgent:
def __init__(self, model_name: str = "gpt-oss:20b"):
self.llm = Ollama(model=model_name, temperature=0.1)
self.prompt = ChatPromptTemplate.from_messages([
("system", """あなたはQAエンジニアです。pytestを使ったテストコードを生成してください。
- 正常系・異常系・境界値を網羅
- モックは unittest.mock を使用
- テスト関数名は test_[動詞]_[対象]_[条件] の形式で"""),
("human", "以下のコードのテストを生成してください:\n\n{source_code}")
])
def run(self, code_doc: CodeDoc) -> TestDoc:
test_files = []
for file in code_doc.files:
chain = self.prompt | self.llm
test_code = chain.invoke({"source_code": file["content"]})
test_files.append({
"filename": f"test_{file['filename']}",
"content": test_code
})
return TestDoc(
test_files=test_files,
coverage_notes=["境界値テストは手動での確認を推奨"]
)
オーケストレーション：4エージェントをパイプラインで繋ぐ
最後に、4つのエージェントを順番に実行するオーケストレーターを実装します。各フェーズの結果をログに残しておくと、どこで品質が落ちたか後から追跡できます。
import json
from datetime import datetime
from pathlib import Path
class DevPipeline:
def __init__(self, model_name: str = "gpt-oss:20b", output_dir: str = "output"):
self.req_agent = RequirementsAgent(model_name)
self.design_agent = DesignAgent(model_name)
self.coding_agent = CodingAgent(model_name)
self.test_agent = TestAgent(model_name)
self.output_dir = Path(output_dir)
self.output_dir.mkdir(exist_ok=True)
def run(self, requirements_text: str) -> dict:
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
results = {}
print("▶ Phase 1: 要件定義エージェント")
req_doc = self.req_agent.run(requirements_text)
results["requirements"] = req_doc.model_dump()
self._save(f"{timestamp}_requirements.json", results["requirements"])
print(f" 曖昧な点: {len(req_doc.ambiguities)}件 / 確定仕様: {len(req_doc.confirmed_specs)}件")
print("▶ Phase 2: 設計エージェント")
design_doc = self.design_agent.run(req_doc)
results["design"] = design_doc.model_dump()
self._save(f"{timestamp}_design.json", results["design"])
print(f" APIエンドポイント: {len(design_doc.api_endpoints)}件")
print("▶ Phase 3: 実装エージェント")
code_doc = self.coding_agent.run(design_doc)
results["code"] = code_doc.model_dump()
self._save(f"{timestamp}_code.json", results["code"])
print(f" 生成ファイル: {len(code_doc.files)}件")
print("▶ Phase 4: テストエージェント")
test_doc = self.test_agent.run(code_doc)
results["tests"] = test_doc.model_dump()
self._save(f"{timestamp}_tests.json", results["tests"])
print(f" テストファイル: {len(test_doc.test_files)}件")
return results
def _save(self, filename: str, data: dict):
with open(self.output_dir / filename, "w", encoding="utf-8") as f:
json.dump(data, f, ensure_ascii=False, indent=2)
# 実行例
if __name__ == "__main__":
pipeline = DevPipeline(model_name="gpt-oss:20b")
requirements = """
ユーザー管理APIを作りたい。
ユーザーの登録・ログイン・プロフィール更新ができること。
認証はJWTを使う。DBはPostgreSQLを想定。
"""
results = pipeline.run(requirements)
運用Tips
各フェーズの出力をJSONファイルとして保存しておくと、途中のフェーズからやり直せます。要件定義だけ人間がレビューして修正し、設計以降を再実行する、という使い方が現実的です。
実運用での限界と人間の介在ポイント
このパイプラインを実際に使ってみて気づいた限界をいくつか挙げておきます。まず、要件が曖昧なまま進むと雪だるま式に品質が落ちる。RequirementsAgentが出した曖昧さリストを無視してDesignAgentに進むと、設計の前提が崩れ、コードもテストも連鎖的に歪みます。
もうひとつは、テストエージェントのエッジケース認識が甘いこと。正常系は網羅してくれますが、「このAPIに不正なJWTを渡したらどうなるか」といった攻撃的なテストケースは自分で足す必要があります。コストの話をすると、ローカルLLMなのでAPI費用はゼロですが、20Bモデルで全フェーズ回すと5〜10分かかります。小規模プロジェクトなら十分実用的な速度です。
人間が介在すべきポイントは明確で、Phase 1終了後の曖昧さレビューとPhase 3終了後のコードレビューの2点。それ以外はエージェントに任せて、人間は判断に集中する——これがこのアーキテクチャの狙いです。