deepagents-code-review

Deep Agents のコードレビュー

Deep Agents のコードをレビューする際は、以下のカテゴリの問題を確認してください。

幻覚の防止（ゲート 0 — ほかのすべてのゲートより先に実行）

どのような指摘を行う場合でも（バグ、アンチパターン、改善点を指摘する場合）、まず、このターンで読んだソースから引用して、評価対象のアーティファクトを正確に示す必要があります。

• コードに関する指摘：file:line と、今あらためて読み込んだ該当コード。
• レビュー対象のエージェントコード：指摘の根拠となる create_deep_agent、バックエンド、サブエージェント、またはミドルウェアのスニペット。直前に読み込んだファイルから引用してください。

アーティファクトだけが信頼できる情報源です。ブランチ名、作業ディレクトリ、周辺ファイル、記憶からレビュー対象を決して推測しないでください。頭の中のモデルと、あらためて読み込んだソースの内容が異なる場合は、ソースを優先してください。 同じターンに対象を引用せずに行った指摘は無効です。先に引用するか、指摘しないでください。

このゲートは、文脈によるプライミングを受けた LLM が、ファイルに存在しないコードを自信満々に問題として指摘するのを防ぐためのものです。以下のゲートより先に実行してください。

レビューゲート（根拠に基づく）

指摘を書く前、および指摘を書いている間に、以下の手順を順番に実行してください。手順を飛ばした場合、レビューは不合格です。

1. 特定 — 対象範囲内の呼び出し箇所（create_deep_agent、CompiledSubAgent、CompositeBackend、カスタムの backend=、interrupt_on、checkpointer、store）を列挙します。合格条件： 関連する各ファイルパスと行番号を挙げるか、コードの場所を示す grep／検索結果を提示します。
2. 根拠付け — 疑わしい問題ごとに、インポートや名前だけでなく、該当ファイルの引用または行番号付きコードに結び付けます。合格条件： 各指摘に根拠（path:line と短い引用、または欠落を示す「パラメーターなし」の注記）が含まれています。
3. 分類 — 根拠を示した各問題を、以下のカテゴリのいずれかと重大度に対応付けます。合格条件： カテゴリのラベルが、引用したコードの実際の動作または欠落内容と一致しています。
4. 実行時の主張 — エラーが発生する、実行時に失敗する、またはデータが漏えいすると述べる場合、合格条件： 引用したスニペットに、正確な API の組み合わせが示されています（例：同じ構築経路で interrupt_on が設定されているのに checkpointer がない）。そうでない場合は、不確実であることと、何を確認すれば確定できるかを述べてください。

手順 1 を満たせない場合は、推測で問題を指摘せずに停止し、どのファイルまたは検索結果が不足しているかを伝えてください。

重大な問題

1. interrupt_on に Checkpointer がない

# BAD - interrupt_on without checkpointer
agent = create_deep_agent(
    tools=[send_email],
    interrupt_on={"send_email": True},
    # No checkpointer! Interrupts will fail
)

# GOOD - checkpointer required for interrupts
from langgraph.checkpoint.memory import InMemorySaver

agent = create_deep_agent(
    tools=[send_email],
    interrupt_on={"send_email": True},
    checkpointer=InMemorySaver(),
)

2. StoreBackend に Store がない

# BAD - StoreBackend without store
from deepagents.backends import StoreBackend

agent = create_deep_agent(
    backend=lambda rt: StoreBackend(rt),
    # No store! Will raise ValueError at runtime
)

# GOOD - provide store
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()
agent = create_deep_agent(
    backend=lambda rt: StoreBackend(rt),
    store=store,
)

3. Checkpointer があるのに thread_id がない

# BAD - no thread_id when using checkpointer
agent = create_deep_agent(checkpointer=InMemorySaver())
agent.invoke({"messages": [...]})  # Error!

# GOOD - always provide thread_id
config = {"configurable": {"thread_id": "user-123"}}
agent.invoke({"messages": [...]}, config)

4. ファイルシステムツールでの相対パス

# BAD - relative paths not supported
read_file(path="src/main.py")
read_file(path="./config.json")

# GOOD - absolute paths required
read_file(path="/workspace/src/main.py")
read_file(path="/config.json")

5. 仮想ファイルシステムでの Windows パス

# BAD - Windows paths rejected
read_file(path="C:\\Users\\file.txt")
write_file(path="D:/projects/code.py", content="...")

# GOOD - Unix-style virtual paths
read_file(path="/workspace/file.txt")
write_file(path="/projects/code.py", content="...")

バックエンドの問題

6. StateBackend に永続化を期待している

# BAD - expecting files to persist across threads
agent = create_deep_agent()  # Uses StateBackend by default

# Thread 1
agent.invoke({"messages": [...]}, {"configurable": {"thread_id": "a"}})
# Agent writes to /data/report.txt

# Thread 2 - file won't exist!
agent.invoke({"messages": [...]}, {"configurable": {"thread_id": "b"}})
# Agent tries to read /data/report.txt - NOT FOUND

# GOOD - use StoreBackend or CompositeBackend for cross-thread persistence
agent = create_deep_agent(
    backend=CompositeBackend(
        default=StateBackend(),
        routes={"/data/": StoreBackend(store=store)},
    ),
    store=store,
)

7. root_dir による制限のない FilesystemBackend

# BAD - unrestricted filesystem access
agent = create_deep_agent(
    backend=FilesystemBackend(root_dir="/"),  # Full system access!
)

# GOOD - scope to project directory
agent = create_deep_agent(
    backend=FilesystemBackend(root_dir="/home/user/project"),
)

8. CompositeBackend のルート順序の取り違え

# BAD - shorter prefix shadows longer prefix
agent = create_deep_agent(
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/mem/": backend_a,        # This catches /mem/long-term/ too!
            "/mem/long-term/": backend_b,  # Never reached
        },
    ),
)

# GOOD - CompositeBackend sorts by length automatically
# But be explicit about your intent:
agent = create_deep_agent(
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": persistent_backend,
            "/workspace/": ephemeral_backend,
        },
    ),
)

9. SandboxBackend がないのに execute ツールを期待している

# BAD - execute tool won't work with StateBackend
agent = create_deep_agent()  # Default StateBackend
# Agent calls execute("ls -la") → Error: not supported

# GOOD - use FilesystemBackend for shell execution
agent = create_deep_agent(
    backend=FilesystemBackend(root_dir="/project"),
)
# Agent calls execute("ls -la") → Works

サブエージェントの問題

10. サブエージェントに必須フィールドがない

# BAD - missing required fields
agent = create_deep_agent(
    subagents=[{
        "name": "helper",
        # Missing: description, system_prompt, tools
    }]
)

# GOOD - all required fields present
agent = create_deep_agent(
    subagents=[{
        "name": "helper",
        "description": "General helper for misc tasks",
        "system_prompt": "You are a helpful assistant.",
        "tools": [],  # Can be empty but must be present
    }]
)

11. サブエージェント名の衝突

# BAD - duplicate subagent names
agent = create_deep_agent(
    subagents=[
        {"name": "research", "description": "A", ...},
        {"name": "research", "description": "B", ...},  # Collision!
    ]
)

# GOOD - unique names
agent = create_deep_agent(
    subagents=[
        {"name": "web-research", "description": "Web-based research", ...},
        {"name": "doc-research", "description": "Document research", ...},
    ]
)

12. 単純なタスクでサブエージェントを過剰に使用する

# BAD - subagent overhead for trivial task
# In system prompt or agent behavior:
"Use the task tool to check the current time"
"Delegate file reading to a subagent"

# GOOD - use subagents for complex, isolated work
"Use the task tool for multi-step research that requires many searches"
"Delegate the full analysis workflow to a subagent"

13. CompiledSubAgent に適切な State がない

# BAD - subgraph with incompatible state schema
from langgraph.graph import StateGraph

class CustomState(TypedDict):
    custom_field: str  # No messages field!

sub_builder = StateGraph(CustomState)
# ... build graph
subgraph = sub_builder.compile()

agent = create_deep_agent(
    subagents=[CompiledSubAgent(
        name="custom",
        description="Custom workflow",
        runnable=subgraph,  # State mismatch!
    )]
)

# GOOD - ensure compatible state or use message-based interface
class CompatibleState(TypedDict):
    messages: Annotated[list, add_messages]
    custom_field: str

ミドルウェアの問題

14. ミドルウェアの順序に関する誤解

# BAD - expecting custom middleware to run first
class PreProcessMiddleware(AgentMiddleware):
    def transform_request(self, request):
        # Expecting this runs before built-in middleware
        return request

agent = create_deep_agent(middleware=[PreProcessMiddleware()])
# Actually runs AFTER TodoList, Filesystem, SubAgent, etc.

# GOOD - understand middleware runs after built-in stack
# Built-in order:
# 1. TodoListMiddleware
# 2. FilesystemMiddleware
# 3. SubAgentMiddleware
# 4. SummarizationMiddleware
# 5. AnthropicPromptCachingMiddleware
# 6. PatchToolCallsMiddleware
# 7. YOUR MIDDLEWARE HERE
# 8. HumanInTheLoopMiddleware (if interrupt_on set)

15. ミドルウェアによるリクエスト／レスポンスの変更

# BAD - mutating instead of returning new object
class BadMiddleware(AgentMiddleware):
    def transform_request(self, request):
        request.messages.append(extra_message)  # Mutation!
        return request

# GOOD - return modified copy
class GoodMiddleware(AgentMiddleware):
    def transform_request(self, request):
        return ModelRequest(
            messages=[*request.messages, extra_message],
            **other_fields
        )

16. 説明がないミドルウェアツール

# BAD - tool without docstring
@tool
def my_tool(arg: str) -> str:
    return process(arg)

class MyMiddleware(AgentMiddleware):
    tools = [my_tool]  # LLM won't know how to use it!

# GOOD - descriptive docstring
@tool
def my_tool(arg: str) -> str:
    """Process the input string and return formatted result.

    Args:
        arg: The string to process

    Returns:
        Formatted result string
    """
    return process(arg)

システムプロンプトの問題

17. 組み込みツールの指示を重複させている

# BAD - re-explaining what middleware already covers
agent = create_deep_agent(
    system_prompt="""You have access to these tools:
    - write_todos: Create task lists
    - read_file: Read files from the filesystem
    - task: Delegate to subagents

    When using files, always use absolute paths..."""
)
# This duplicates what FilesystemMiddleware and TodoListMiddleware inject!

# GOOD - focus on domain-specific guidance
agent = create_deep_agent(
    system_prompt="""You are a code review assistant.

    Workflow:
    1. Read the files to review
    2. Create a todo list of issues found
    3. Delegate deep analysis to subagents if needed
    4. Compile findings into a report"""
)

18. 組み込みの指示と矛盾している

# BAD - contradicting default behavior
agent = create_deep_agent(
    system_prompt="""Never use the task tool.
    Always process everything in the main thread.
    Don't use todos, just remember everything."""
)
# Fighting against the framework!

# GOOD - work with the framework
agent = create_deep_agent(
    system_prompt="""For simple tasks, handle directly.
    For complex multi-step research, use subagents.
    Track progress with todos for tasks with 3+ steps."""
)

19. 停止条件がない

# BAD - no guidance on when to stop
agent = create_deep_agent(
    system_prompt="Research everything about the topic thoroughly."
)
# Agent may run indefinitely!

# GOOD - define completion criteria
agent = create_deep_agent(
    system_prompt="""Research the topic with these constraints:
    - Maximum 5 web searches
    - Stop when you have 3 reliable sources
    - Limit subagent delegations to 2 parallel tasks
    - Summarize findings within 500 words"""
)

パフォーマンスの問題

20. 独立したサブエージェントを並列実行していない

# BAD - sequential subagent calls (in agent behavior)
# Agent calls: task(research topic A) → wait → task(research topic B) → wait

# GOOD - parallel subagent calls
# Agent calls in single turn:
#   task(research topic A)
#   task(research topic B)
#   task(research topic C)
# All run concurrently!

# Guide via system prompt:
agent = create_deep_agent(
    system_prompt="""When researching multiple topics,
    launch all research subagents in parallel in a single response."""
)

21. State に大きなファイルを含めている

# BAD - writing large files to StateBackend
# Agent writes 10MB log file to /output/full_log.txt
# This bloats every checkpoint!

# GOOD - use FilesystemBackend for large files or paginate
agent = create_deep_agent(
    backend=CompositeBackend(
        default=StateBackend(),  # Small files
        routes={
            "/large_files/": FilesystemBackend(root_dir="/tmp/agent"),
        },
    ),
)

22. 本番環境で InMemorySaver を使用している

# BAD - ephemeral checkpointer in production
agent = create_deep_agent(
    checkpointer=InMemorySaver(),  # Lost on restart!
)

# GOOD - persistent checkpointer
from langgraph.checkpoint.postgres import PostgresSaver

agent = create_deep_agent(
    checkpointer=PostgresSaver.from_conn_string(DATABASE_URL),
)

23. 再帰への考慮が不足している

# BAD - no guard against long-running loops
agent = create_deep_agent(
    system_prompt="Keep improving the solution until it's perfect."
)
# May hit recursion limit (default 1000)

# GOOD - explicit iteration limits
agent = create_deep_agent(
    system_prompt="""Improve the solution iteratively:
    - Maximum 3 revision cycles
    - Stop if quality score > 90%
    - Stop if no improvement after 2 iterations"""
)

コードレビューチェックリスト

各分野（設定、バックエンド、サブエージェント、ミドルウェア、システムプロンプト、パフォーマンス）の完全なチェックリストは、references/checklist.md を参照してください。「レビューゲート」と上記の番号付き問題一覧を確認した後に実行してください。