How Devin plans and executes multi-file code changes

Delegating refactors to an autonomous agent is not as simple as typing a wish into a chat box. For reliable Devin multi-file code changes, you need to treat the agent like a junior engineer who requires a written spec, a clear plan, and a test suite to lean on. This guide lays out the ordered path we use to hand off cross-module work to Devin, from scoping the task to reviewing the resulting pull request.

1. Pin down scope before you create the task

Devin executes against whatever repo and branch you give it, but it cannot infer unstated constraints. A vague prompt like “modernize the auth stack” will send the agent into a grep spiral that touches files you never intended to change. Before opening a task, write a scope block that names the exact files, the desired end state, and explicit non-goals.

{
  "prompt": "Refactor the authentication middleware in api/middleware/auth.py and its callers in api/routes/*.py to use the new JWT library. Do not change session-based routes in api/routes/legacy.py. Write tests for the new flow.",
  "repo": "https://github.com/yourorg/backend",
  "base_branch": "main"
}

If you use the HTTP API directly, the same shape works with a requests call:

import os, requests
resp = requests.post(
    "https://api.devin.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['DEVIN_API_KEY']}"},
    json={"prompt": "Refactor api/middleware/auth.py to JWT per spec in linked issue"}
)
task_id = resp.json()["task_id"]

The pitfall here is ambiguity. Devin multi-file code changes fail most often because the prompt omitted a critical file or assumed the agent would know which tests guard the behavior. Attach the relevant issue link or a short design doc; the agent will read it.

2. Force a written plan before execution

Devin naturally drafts a plan in a markdown file (commonly plan.md) and then starts editing. For anything touching more than five files, split the work into two tasks: first ask for a plan only, review it, then instruct implementation. This adds latency but prevents a 2,000-line diff that violates your architecture.

A typical plan excerpt looks like this:

# Plan: JWT refactor
## Files to modify
- api/middleware/auth.py: replace SessionAuth with JwtAuth class
- api/routes/user.py: update import and decorator usage
- api/routes/admin.py: same decorator update
## New tests
- tests/test_jwt_auth.py: cover expired token, invalid signature, missing header
## Risks
- api/routes/legacy.py must remain untouched (session auth)
- config.py needs new JWT_SECRET env var

The tradeoff is clear: a review gate costs you a round-trip, but it lets you catch a wrong assumption about config.py before Devin rewrites every route. When you approve, send a follow-up prompt: “Execute the plan in plan.md and open a PR when tests pass.”

3. Execution loop: shell, edits, and targeted tests

Once executing, Devin drives a shell. It greps, sed’s, and invokes its own file editor. You should explicitly tell it to run only the affected tests, not the full suite. A repo without a fast targeted test command will waste agent cycles.

Illustrative sequence Devin might run:

grep -rl "SessionAuth" api/ | xargs sed -i 's/SessionAuth/JwtAuth/g'
python -m pytest tests/test_jwt_auth.py -x
git diff --stat

If your project uses poetry or uv, instruct it to use them. The agent respects provided commands but defaults to naive pytest if unspecified. For Devin multi-file code changes, we add a Makefile target test-changed that runs pytest with --cov on the diffed files only.

A common pitfall: Devin may edit a file, run tests, see an import error in a distant module, and “fix” that module too—silently expanding scope. Constrain with: “Only modify files listed in plan.md. If you find a breakage elsewhere, stop and report.”

4. Verification and self-healing

Devin will iterate on red tests, but its context window is finite. After roughly 15–20 file edits, it can lose track of an earlier constraint (e.g., “legacy.py untouched”). Break large refactors into module-sized tasks and merge incrementally.

Give it a single verification script so success is unambiguous:

#!/usr/bin/env bash
# scripts/check.sh
ruff check .
mypy api/
pytest tests/test_jwt_auth.py -q

Tell Devin: “Run ./scripts/check.sh after each file group; do not open PR until it exits 0.” This turns self-healing into a bounded loop instead of open-ended exploration.

Tradeoff: full autonomy overnight vs. interactive correction. We let Devin run unattended on a feature branch, but we require the check script to pass before it attempts a PR. That balances throughput with safety.

5. Pull request and handoff

When done, Devin opens a PR with a summary. Pull the diff locally to review what the agent actually changed across files:

curl -H "Authorization: Bearer $DEVIN_API_KEY" \
  https://api.devin.ai/v1/tasks/$TASK_ID/diff > devin.diff
git apply --check devin.diff && echo "clean"

Review the multi-file diff with git diff --stat to confirm no stray files. Common pitfall: Devin leaves plan.md or debug prints in api/middleware/auth.py. Add a repo convention: “Delete plan.md and remove all print( calls before PR.” Or use a .devinignore if your integration supports it.

For Devin multi-file code changes, we also mandate that the PR description includes the original scope block and the plan link. That makes review trivial.

Common pitfalls with Devin multi-file code changes

• Context fragmentation: Editing 30 files in one task leads to inconsistent imports. Split by module boundary.
• Hidden type propagation: Changing a function signature in core/ without updating dynamic importers. Devin may miss __import__ calls; enforce mypy in the check script.
• Test blind spots: Generated tests often assert happy path only. Demand negative tests in the prompt (“cover expired and malformed tokens”).
• Silent scope creep: Agent “fixes” unrelated lint errors. Forbid with explicit instructions.

Tradeoffs: Devin vs. Claude Code vs. Cursor

In the cluster of autonomous coding agents—Claude Code, Devin, Cursor—each fits a different groove. Devin is the async cloud worker; you hand it a task and return later. Claude Code runs locally and gives a tight feedback loop for smaller multi-file edits where you want to steer each step. Cursor is an interactive IDE copilot best for in-place completions.

For sweeping Devin multi-file code changes across a large repo, Devin wins on unattended throughput, but you sacrifice immediate control. Use it when the change is well-specified and test-covered. For exploratory refactoring, stay in Cursor or Claude Code.

The actionable path is: scope tightly, extract a written plan, bound the execution loop with a check script, and review the diff with the same rigor you’d apply to a human PR. Do that, and Devin becomes a reliable member of your team.