How SWE-Agent Architect Prompts Work: From Research to Implementation Plans

The architect prompts in SWE-Agent are LangChain prompt templates that orchestrate a research phase using tool-bound LLM calls and a structured extraction phase that outputs JSON implementation plans.

The SWE-Agent repository employs a specialized architect component to bridge high-level planning and concrete code changes. Understanding how the architect prompts work reveals how the system transforms research hypotheses into executable implementation plans through structured LLM interactions.

Overview of the Architect Component in SWE-Agent

The architect is implemented as a LangGraph workflow defined in agent/architect/graph.py. It orchestrates three distinct phases:

• Generate a research hypothesis – determining what to investigate next.
• Conduct the research – executing tools to collect evidence.
• Extract an implementation plan – converting evidence into a concrete JSON description of required code changes.

Two critical prompt templates drive the second and third phases: conduct_research_plan_prompt and extract_implementation_plan.

Conduct Research Plan Prompt: Tool-Augmented Investigation

The conduct research plan prompt drives the evidence-gathering phase. It lives at agent/architect/prompts/conduct_research_plan_prompt.md and is loaded via the markdown_to_prompt_template utility from helpers/prompts.py (referenced in graph.py line 30).

Creating the Research Runnable

The prompt is combined with a tool-bound LLM to create conduct_research_runnable (defined in graph.py line 38):

from langchain_anthropic import ChatAnthropic
from helpers.prompts import markdown_to_prompt_template
from agent.tools.search import search_tools
from agent.tools.codemap import codemap_tools

conduct_research_prompt = markdown_to_prompt_template(
    "agent/architect/prompts/conduct_research_plan_prompt.md"
)

conduct_research_runnable = (
    conduct_research_prompt
    | ChatAnthropic(model="claude-sonnet-4-20250514")
        .bind_tools(search_tools + codemap_tools)
)

Executing the Research Phase

When invoked, the runnable receives the current implementation_research_scratchpad and codebase_structure. Because the model is bound to the search and codemap tools, any tool calls are automatically routed through the ToolNode (tool_node), which appends results back to the scratchpad.

def conduct_research(state):
    response = conduct_research_runnable.invoke({
        "implementation_research_scratchpad": state.implementation_research_scratchpad,
        "codebase_structure": get_files_structure.invoke(
            {"directory": "./workspace_repo"}
        ),
    })
    return {"implementation_research_scratchpad": [response]}

Extract Implementation Plan Prompt: Structured JSON Output

After research completes, the extract implementation plan prompt converts the gathered evidence into a machine-readable plan. This prompt resides at agent/architect/prompts/extract_implementation_plan.md and is loaded similarly via markdown_to_prompt_template (referenced in graph.py line 33).

Creating the Extraction Runnable

The runnable chains the prompt with an LLM and a JSON output parser (defined in graph.py line 39):

from langchain_core.output_parsers import JsonOutputParser
from agent.common.entities import ImplementationPlan

extract_implementation_prompt = markdown_to_prompt_template(
    "agent/architect/prompts/extract_implementation_plan.md"
)

extract_implementation_runnable = (
    extract_implementation_prompt
    | ChatAnthropic(model="claude-sonnet-4-20250514")
    | JsonOutputParser(pydantic_object=ImplementationPlan)
)

Normalizing Research Findings

Before extraction, the scratchpad containing tool results must be normalized. The helper convert_tools_messages_to_ai_and_human (lines 88-102 in graph.py) flattens the tool messages into a plain list of AI and Human messages suitable for the prompt.

Generating the Implementation Plan

The model receives the normalized research_findings, codebase_structure, and explicit output_format instructions from the JsonOutputParser. The prompt instructs the model to "break the research finding into atomic tasks and output valid JSON" (referencing the Rules section in the markdown file, lines 21-36).

def extract_implementation_plan(state):
    response = extract_implementation_runnable.invoke({
        "research_findings": convert_tools_messages_to_ai_and_human(
            state.implementation_research_scratchpad
        ),
        "codebase_structure": get_files_structure.invoke(
            {"directory": "./workspace_repo"}
        ),
        "output_format": JsonOutputParser(
            pydantic_object=ImplementationPlan
        ).get_format_instructions(),
    })
    return {"implementation_plan": ImplementationPlan(**response)}

Integrating Prompts into the LangGraph Workflow

The architect prompts function as contracts between the agent's internal state and the LLM. In agent/architect/graph.py, the workflow wires these runnables into a state machine defined by agent/architect/state.py.

The state tracks:

• implementation_research_scratchpad: The conversation history and tool results
• implementation_plan: The final structured output

The graph transitions from hypothesis generation to conduct_research (using the first prompt) and finally to extract_implementation_plan (using the second prompt), ensuring each phase receives the precise context and instructions required.

Summary

• Conduct Research Plan Prompt (agent/architect/prompts/conduct_research_plan_prompt.md) drives the evidence-gathering phase by binding a Claude model to search and codemap tools, allowing autonomous tool execution while maintaining a scratchpad of findings.

• Extract Implementation Plan Prompt (agent/architect/prompts/extract_implementation_plan.md) converts the research scratchpad into a structured JSON output matching the ImplementationPlan Pydantic model, using a JsonOutputParser to enforce schema compliance.

• Both prompts are loaded via markdown_to_prompt_template from helpers/prompts.py and integrated into a LangGraph workflow in agent/architect/graph.py, creating a deterministic pipeline from research hypothesis to machine-readable implementation plan.

Frequently Asked Questions

How are the architect prompts loaded into the SWE-Agent system?

The architect prompts are loaded using the markdown_to_prompt_template utility defined in helpers/prompts.py. This function reads the markdown files from agent/architect/prompts/conduct_research_plan_prompt.md and agent/architect/prompts/extract_implementation_plan.md, then wraps them into LangChain PromptTemplate objects that can be chained with LLMs in agent/architect/graph.py.

What tools does the conduct_research_plan_prompt bind to the LLM?

The conduct_research_plan_prompt binds the Claude model to the search and codemap tools defined in agent/tools/search.py and agent/tools/codemap.py. This binding allows the LLM to autonomously invoke these tools during the research phase, with results automatically routed back to the implementation_research_scratchpad via the LangGraph ToolNode.

How does the extract_implementation_plan prompt enforce JSON output structure?

The extract_implementation_plan prompt enforces JSON structure by chaining the prompt with a JsonOutputParser from LangChain, configured with the ImplementationPlan Pydantic model from agent/common/entities.py. The parser provides explicit format instructions to the prompt, and the markdown instructions explicitly direct the model to "break the research finding into atomic tasks and output valid JSON," ensuring the output matches the required schema.

Can the architect prompts be customized for different codebases?

Yes, the architect prompts can be customized because they are stored as standalone markdown files in agent/architect/prompts/. You can modify the instructions in conduct_research_plan_prompt.md to adjust research strategies or edit extract_implementation_plan.md to change the implementation plan format. Since the prompts are loaded dynamically via markdown_to_prompt_template, changes to these files take effect immediately without modifying the Python source code in agent/architect/graph.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}