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

> Discover how SWE-Agent architect prompts transform LLM research into structured JSON implementation plans. Learn about conduct_research_plan_prompt and extract_implementation_plan.

- Repository: [LangTalks/swe-agent](https://github.com/langtalks/swe-agent)
- Tags: internals
- Published: 2026-03-05

---

**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`](https://github.com/langtalks/swe-agent/blob/main/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`](https://github.com/langtalks/swe-agent/blob/main/agent/architect/prompts/conduct_research_plan_prompt.md) and is loaded via the `markdown_to_prompt_template` utility from [`helpers/prompts.py`](https://github.com/langtalks/swe-agent/blob/main/helpers/prompts.py) (referenced in [`graph.py`](https://github.com/langtalks/swe-agent/blob/main/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`](https://github.com/langtalks/swe-agent/blob/main/graph.py) line 38):

```python
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.

```python
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`](https://github.com/langtalks/swe-agent/blob/main/agent/architect/prompts/extract_implementation_plan.md) and is loaded similarly via `markdown_to_prompt_template` (referenced in [`graph.py`](https://github.com/langtalks/swe-agent/blob/main/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`](https://github.com/langtalks/swe-agent/blob/main/graph.py) line 39):

```python
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`](https://github.com/langtalks/swe-agent/blob/main/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).

```python
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`](https://github.com/langtalks/swe-agent/blob/main/agent/architect/graph.py), the workflow wires these runnables into a state machine defined by [`agent/architect/state.py`](https://github.com/langtalks/swe-agent/blob/main/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`](https://github.com/langtalks/swe-agent/blob/main/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`](https://github.com/langtalks/swe-agent/blob/main/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`](https://github.com/langtalks/swe-agent/blob/main/helpers/prompts.py) and integrated into a LangGraph workflow in [`agent/architect/graph.py`](https://github.com/langtalks/swe-agent/blob/main/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`](https://github.com/langtalks/swe-agent/blob/main/helpers/prompts.py). This function reads the markdown files from [`agent/architect/prompts/conduct_research_plan_prompt.md`](https://github.com/langtalks/swe-agent/blob/main/agent/architect/prompts/conduct_research_plan_prompt.md) and [`agent/architect/prompts/extract_implementation_plan.md`](https://github.com/langtalks/swe-agent/blob/main/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`](https://github.com/langtalks/swe-agent/blob/main/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`](https://github.com/langtalks/swe-agent/blob/main/agent/tools/search.py) and [`agent/tools/codemap.py`](https://github.com/langtalks/swe-agent/blob/main/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`](https://github.com/langtalks/swe-agent/blob/main/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`](https://github.com/langtalks/swe-agent/blob/main/conduct_research_plan_prompt.md) to adjust research strategies or edit [`extract_implementation_plan.md`](https://github.com/langtalks/swe-agent/blob/main/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`](https://github.com/langtalks/swe-agent/blob/main/agent/architect/graph.py).