# How SWE-Agent Handles Atomic Tasks vs File-Level Implementation Tasks: A Deep Dive into the Developer Graph

> Explore how SWE-Agent manages atomic tasks vs file-level implementation tasks using its developer graph. Discover its approach to creating and modifying files for efficient development.

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

---

**The SWE-Agent agent breaks down high-level development requests into granular atomic tasks tracked by indices, while using distinct file-level implementation prompts to determine whether to create new files or modify existing ones.**

The SWE-Agent repository (`langtalks/swe-agent`) employs a hierarchical task decomposition strategy where high-level development goals are split into manageable units. Understanding how the agent handles atomic tasks versus file-level implementation tasks reveals the core mechanics of its code generation pipeline and state management system.

## Understanding the Task Hierarchy in SWE-Agent

The agent operates on two distinct levels of task granularity. **High-level tasks** represent major development objectives (such as implementing a feature or fixing a bug), while **atomic tasks** represent the smallest units of work—typically a single edit operation within a specific file. This separation allows the agent to plan broadly while executing precisely.

The state management system tracks these tasks through the `SoftwareDeveloperState` class, which maintains both the current high-level task index and the current atomic task index. This dual-index approach enables the agent to navigate complex multi-file changes methodically.

## How Atomic Tasks Work

Atomic tasks form the execution layer of the SWE-Agent developer graph. Each atomic task corresponds to a concrete code change, and the agent processes them sequentially until a high-level task is complete.

### State Management for Atomic Tasks

The agent tracks atomic task progression through two critical state variables in [`agent/developer/state.py`](https://github.com/langtalks/swe-agent/blob/main/agent/developer/state.py):

- **`atomic_tasks`**: A list of `AtomicTask` objects (defined in [`agent/common/entities.py`](https://github.com/langtalks/swe-agent/blob/main/agent/common/entities.py)) representing the individual edit operations required for the current high-level task
- **`current_atomic_task_idx`**: An integer pointer tracking which atomic task is currently being executed

This indexing system allows the agent to pause, resume, and iterate through complex implementation steps without losing context.

### Advancing Through Atomic Tasks

The `proceed_to_next_atomic_task` function in [`agent/developer/graph.py`](https://github.com/langtalks/swe-agent/blob/main/agent/developer/graph.py) handles the transition logic between atomic tasks:

```python
def proceed_to_next_atomic_task(state: SoftwareDeveloperState):
    current_atomic_task_idx = state.current_atomic_task_idx
    atomic_tasks = state.current_task.atomic_tasks

    # If we've finished the current atomic task list, move to the next main task

    if current_atomic_task_idx >= len(atomic_tasks) - 1:
        state.current_task_idx += 1
        state.current_atomic_task_idx = 0
    else:
        # otherwise go to the next atomic task in the same main task

        state.current_atomic_task_idx = current_atomic_task_idx + 1
    return state

```

This function resets the atomic task index when transitioning between high-level tasks, ensuring clean state isolation. When the agent exhausts all atomic tasks for the current main task, it increments `current_task_idx` and begins processing the next development objective.

## File-Level Implementation Strategies

While atomic tasks handle the granularity of changes, **file-level implementation tasks** determine the strategy for applying those changes. The developer graph branches based on whether the current objective requires creating new files or modifying existing ones.

### The New File Creation Path

When the agent determines that a new file is required, it follows the **"Create new file"** path. This branch utilizes the [`implement_new_file.md`](https://github.com/langtalks/swe-agent/blob/main/implement_new_file.md) prompt template located in [`agent/developer/prompts/implement_new_file.md`](https://github.com/langtalks/swe-agent/blob/main/agent/developer/prompts/implement_new_file.md). The graph node `create_new_file` orchestrates this process, generating complete file contents rather than incremental diffs.

### The Diff Modification Path

For changes to existing files, the agent uses the **"Create diff"** strategy. This path employs the [`implement_diff.md`](https://github.com/langtalks/swe-agent/blob/main/implement_diff.md) prompt template from [`agent/developer/prompts/implement_diff.md`](https://github.com/langtalks/swe-agent/blob/main/agent/developer/prompts/implement_diff.md). The `create_diff_for_task` node handles the generation of patch-style modifications, allowing the agent to edit specific lines within existing codebases.

### Selecting the Implementation Strategy

The workflow graph determines which path to take based on the current task requirements:

```python
if current_task.needs_new_file:
    workflow.add_edge("prepare_for_implementation", "create_new_file")
else:
    workflow.add_edge("prepare_for_implementation", "create_diff_for_task")

```

Both paths ultimately produce atomic tasks, but the prompt engineering differs significantly. New file creation prompts focus on comprehensive structure and boilerplate, while diff prompts emphasize precise context and minimal invasive changes.

## The Implementation Workflow

The complete workflow for handling atomic versus file-level tasks follows a deterministic pipeline:

1. **Planning Phase**: The architect component (in [`agent/architect/graph.py`](https://github.com/langtalks/swe-agent/blob/main/agent/architect/graph.py)) generates high-level tasks and decomposes them into atomic units
2. **Decomposition**: Each high-level task is converted into a list of `AtomicTask` objects with specific file targets and change descriptions
3. **Research Phase**: The optional `research_tool_node` gathers context, storing results in `state.atomic_implementation_research`
4. **Implementation Phase**: The `get_clear_implementation_plan_for_atomic_task` function constructs the execution context:

```python
def get_clear_implementation_plan_for_atomic_task(state: SoftwareDeveloperState):
    current_atomic_task = state.current_task.atomic_tasks[state.current_atomic_task_idx]
    return {
        "development_task": current_atomic_task.atomic_task,
        "additional_context": current_atomic_task.additional_context,
        "atomic_implementation_research": state.atomic_implementation_research,
    }

```

5. **Execution Phase**: The LLM generates either a new file or a diff based on the selected strategy
6. **Progression Phase**: `proceed_to_next_atomic_task` advances the state machine, either moving to the next atomic task or the next high-level task

This architecture ensures that file-level decisions (new vs existing) happen at the planning level, while atomic tasks handle the mechanical execution of changes.

## Key Source Files and Architecture

| File | Purpose |
|------|---------|
| [`agent/developer/state.py`](https://github.com/langtalks/swe-agent/blob/main/agent/developer/state.py) | Defines `SoftwareDeveloperState` with `current_atomic_task_idx` and `atomic_tasks` |
| [`agent/developer/graph.py`](https://github.com/langtalks/swe-agent/blob/main/agent/developer/graph.py) | Contains `proceed_to_next_atomic_task` and `get_clear_implementation_plan_for_atomic_task` logic |
| [`agent/developer/prompts/implement_new_file.md`](https://github.com/langtalks/swe-agent/blob/main/agent/developer/prompts/implement_new_file.md) | Prompt template for file creation tasks |
| [`agent/developer/prompts/implement_diff.md`](https://github.com/langtalks/swe-agent/blob/main/agent/developer/prompts/implement_diff.md) | Prompt template for modification tasks |
| [`agent/common/entities.py`](https://github.com/langtalks/swe-agent/blob/main/agent/common/entities.py) | Defines the `AtomicTask` dataclass structure |
| [`agent/architect/graph.py`](https://github.com/langtalks/swe-agent/blob/main/agent/architect/graph.py) | Generates high-level tasks and initial decomposition |

## Summary

- **Atomic tasks** represent single-file edit operations tracked via `current_atomic_task_idx` in [`agent/developer/state.py`](https://github.com/langtalks/swe-agent/blob/main/agent/developer/state.py)
- The `proceed_to_next_atomic_task` function manages transitions between atomic tasks and high-level tasks in [`agent/developer/graph.py`](https://github.com/langtalks/swe-agent/blob/main/agent/developer/graph.py)
- **File-level implementation** bifurcates into new file creation ([`implement_new_file.md`](https://github.com/langtalks/swe-agent/blob/main/implement_new_file.md)) and diff-based modification ([`implement_diff.md`](https://github.com/langtalks/swe-agent/blob/main/implement_diff.md))
- The `get_clear_implementation_plan_for_atomic_task` function assembles context for each atomic execution
- State isolation ensures that completing one high-level task automatically resets the atomic task index for the next objective

## Frequently Asked Questions

### What defines an atomic task in SWE-Agent?

An atomic task is the smallest unit of work in the SWE-Agent system, typically representing a single edit operation within one file. Defined in [`agent/common/entities.py`](https://github.com/langtalks/swe-agent/blob/main/agent/common/entities.py), each `AtomicTask` contains the specific change description, target file information, and additional context needed for implementation.

### How does the agent decide between creating a new file and modifying an existing one?

The decision occurs at the workflow graph level in [`agent/developer/graph.py`](https://github.com/langtalks/swe-agent/blob/main/agent/developer/graph.py). The system checks the current task's properties (such as `needs_new_file`). If true, the graph routes to the `create_new_file` node using the [`implement_new_file.md`](https://github.com/langtalks/swe-agent/blob/main/implement_new_file.md) prompt; otherwise, it routes to `create_diff_for_task` using [`implement_diff.md`](https://github.com/langtalks/swe-agent/blob/main/implement_diff.md).

### What happens when all atomic tasks for a main task are completed?

When `current_atomic_task_idx` exceeds the length of the atomic task list, the `proceed_to_next_atomic_task` function increments `current_task_idx` and resets `current_atomic_task_idx` to zero. This transition moves the agent to the next high-level development task in the queue.

### Where is the atomic task state tracked in the codebase?

The atomic task state is maintained in the `SoftwareDeveloperState` class within [`agent/developer/state.py`](https://github.com/langtalks/swe-agent/blob/main/agent/developer/state.py). This includes the `atomic_tasks` list and the `current_atomic_task_idx` integer, which together form the state machine that drives the developer graph's execution loop.