TL;DR
RepoTrace is an add-on layer for a coding agent (the paper calls it a harness). Before every edit, it builds a short mapping of which files actually need to change for the current requirement. The map also flags which previously written code might be affected. This map is attached to the requirement in the agent’s context. The agent gets not just “what to do” but also “where it lives and what’s connected to what.”
The main finding: in multi-round work (each new requirement lands on an already-live project), agents edit the wrong things. Either they rewrite a shared file that holds unrelated functions and lose code that already worked. Or they add a field to the output but forget the code that fills that field. In failed rounds, 55% of edits landed in files outside the ones the human reference solution changed. The agent sees lots of related code and can’t tell “needs changing” from “just sitting nearby.”
The method fixes this in three steps: it builds the repository’s dependency graph, pulls likely edit targets out of the requirement (plus the history of past requirements), and stitches everything into one message for the agent. On a strong model, the average round success rate rose 2.5x, and breakages of previously working code dropped by more than half. But the method requires code: a script, not a chat, builds the graph and the message.
Want this for your own case? Apply this study to your task: AI adapts its method to what you are working on and writes the prompt.
Method Blueprint
Each round t (new requirement r_t), BEFORE the agent starts editing:
STEP 1: Parse the repository with a script → a graph of “which file references which”,
file importance weights (PageRank, fan-in), what changed since the last round
STEP 2: The LLM reads the requirement + the file list ranked by importance + the history
of past requirements → a record: candidate edit targets, behavior constraints,
possibly affected old code, a short summary of the requirement
(no-LLM fallback: match file and symbol names against the requirement text)
STEP 3: Stitch message M_t from four blocks and append it to the requirement:
① links of high-fan-in files and their direct dependents
② overview of existing files + candidates for new ones
③ possibly affected code from past requirements
④ an instruction to build and run the tests (with a command hint)
→ the agent gets “requirement + M_t” and edits and verifies on its own
End of round: the graph and the requirement record are saved for the next round
Steps 1–3 are run by code outside the agent. The agent receives ready-made text.
Example in Practice
The whole method is code, so in chat we reproduce its idea: we ask the agent (or do it ourselves) to build this kind of map before editing. This is a manual version that follows the message structure from the paper, not the authors’ prompt.
Task: You and Claude Code are on day three of polishing the Python backend for an online store, something like Instacart or Amazon. Round 1: the cart. Round 2: promo codes. Round 3: “when an order is canceled, refund the rewards points the customer spent.” The risk: the agent adds the refund to the cancellation handler but misses that points are deducted in a separate module, and that promo codes hinge on the same order status.
Prompt:
Round 3 requirement: when an order is canceled, return the rewards points
the customer spent. If the order was partly paid with a promo code, do not
return the promo code.
Before changing anything, build a requirement-to-code map:
1. EDIT TARGETS: which files and functions need to change directly.
For each one, explain in one sentence why it’s that one.
2. LINKS: which files import or call these targets
(what must not break) and which targets they depend on themselves.
3. AFFECTED OLD CODE: what was implemented in rounds 1–2
(cart, promo codes) that might change because of this requirement.
4. NEW FILES: are any needed, or does everything fit into existing ones.
5. VERIFICATION: what command to run to confirm that the new feature
works and the old stuff didn’t break.
Show me the map and wait for my “ok”. Don’t touch any files that are not
in items 1–3.
Result: The agent returns a five-block map that points to real project files. Before any edits, you’ll see whether it found the points-deduction module and noticed the link to promo codes. If it named only the cancellation handler as a target, you correct it at this step, not after the tests break. After your “ok,” it edits within the set boundaries and runs the tests.
Why It Works
Weakness: in a project, the agent has lots of code “next to” the task. It sees a shared command dispatcher, files with similar names, functions with similar purposes. What it lacks is a signal for which of these is the target and which are just neighbors. So it rewrites a shared file wholesale and loses functions that belong to other features. Or it edits the “output” and never gets to the code that prepares the data. The more rounds, the worse it gets: the context bloats, and the link between old requirements and the code fades.
Strength: once the links are spelled out, the model uses them well. Following a ready-made map is easier than piecing the picture together from dozens of open files. As a bonus, the agent wanders around the repository less: DeepSeek-V4-Pro used 27.6% fewer input tokens.
How the method exploits this: it separates “edit targets” from “related, but hands off” up front and adds memory of past requirements. The agent only has to execute, not guess.
Control levers:
- The “affected old code” block is the main safeguard. Remove it and you lose protection against breaking code that used to work.
- The “verification” block: in the paper, it’s an instruction to build and run the tests. Plug in your own command (pytest, go test ./...).
- Requirement history: the longer the project, the more it matters. You don’t need it for a one-off request.
- The map shows dependencies; it doesn’t order you to change them. The authors stress that a file’s structural importance doesn’t mean it needs editing. Don’t turn the map into a list of mandatory edits.
Prompt Template
The paper doesn’t include full prompt texts (the appendices aren’t in the available version). Below is a message in the authors’ four-block structure. The wording is mine.
{requirement}
Requirement-to-code mapping context for this round:
[CODE LINKS]
Key files that many others reference, and their direct dependents:
{file → who uses it}
[FILE OVERVIEW]
Existing project files: {list of files with a one-line role each}
Possible new files for this requirement: {list or “not needed”}
[POSSIBLY AFFECTED CODE FROM PAST REQUIREMENTS]
{past requirement → files and functions it created or changed}
[VERIFICATION]
After editing, build the project and run the tests: {command}.
Make sure the new requirement works and nothing that worked before is broken.
Note: the links show what depends on what. They do not mean
every listed file has to change. Decide the edit targets yourself.
What to fill in:
- {requirement}: the text of the current task;
- links and overview: a summary of the project structure (you can ask the agent to compile it);
- past requirements: a log like “round 2: promo codes → promo.py, cart.py::apply_promo”;
- {command}: however you run your tests.
🚀 Quick start: paste this into a chat with your agent (Claude Code, Cursor):
Here is a “requirement → code” message template (the RepoTrace method). Adapt it
to my project and my current requirement: {your task}.
Ask me questions to fill in the fields.
[paste the template above]
The agent will ask what files the project has, which requirements are already done, and how the tests run. Those answers fill the template blocks: links, past-round history, and verification. It will survey the repository on its own and assemble a ready-to-use message for your task.
Limitations
⚠️ Code required: in the paper, a script builds the map: parsing imports and calls, PageRank, comparing the graph across rounds. In a regular chat you can only imitate this by hand. The authors didn’t measure how well such a manual version works.
⚠️ Doesn’t help every model: on one of the four models (Qwen3.7-Max) there was no gain. The authors put this down to the weaker model not knowing how to use a ready-made map.
⚠️ Smaller gains on a strong harness: with Claude Code, which already understands repositories well on its own, the improvement is more modest: roughly from 45 to 55 points, versus 14→36 for the simple harness.
⚠️ The map is approximate: links are detected by matching call and import names; this isn’t precise code analysis. Records of past requirements are past analyses, not verified facts about finished work. A wrong map can lead the agent astray.
⚠️ One benchmark and a small sample: 26 tasks, 227 rounds. A preprint, not a reproduced result.
⚠️ Output tokens go up (moderately), and a weaker model can also overspend on input tokens.
How They Tested It
First, the authors analyzed 2,656 agent trajectories from the EvoCode-Bench benchmark. These are multi-round tasks: a single project, requirements arriving one after another, and each round checked against the accumulated tests. That’s how they found a recurring failure: requirement focus misalignment. In failed rounds, 55.16% of source-code edits fell outside the files the human reference changed. The failure has two faces: editing unrelated code and missing a needed update.
Then they tested RepoTrace on 26 tasks and 227 rounds in two harnesses (Terminus-2 and Claude Code) with four models. Each setup was compared with its own version without the method.
Results: - DeepSeek-V4-Pro on Terminus-2: the average share of passed rounds went from 14.1 to 36.4, and the share of fully passed tasks was roughly 4x higher. - GLM-5.2: from 16.2 to 36.2. - Claude Code: from 44.7 to 54.9. - Breakages of previously working code for DeepSeek dropped by 56.78% on average.
The surprise: input tokens went down (−27.6% for DeepSeek). The agent doesn’t burn turns figuring out the project by itself. But on Qwen there’s no gain: the map only works if the model knows how to use it. The practical takeaway: hand the agent an explicit “where to edit” map instead of hoping it will figure things out, and the stronger the model, the better this pays off.
Part of the paper (the per-round analysis and the component ablation) is cut off in the available version, so I rely on the main tables.
Adaptations and Extrapolations
🔧 Technique: a map in the instructions file instead of a script → a permanent agent habit
This is my idea, not from the paper, and it hasn’t been tested. Add a rule to CLAUDE.md or AGENTS.md:
Before every edit for a new requirement, output: (1) the target files,
(2) the files that use them, (3) what earlier work might be
affected, (4) the verification command. Don’t change files outside
this list without my approval. After editing, run the tests.
The agent will do a “manual RepoTrace” every round without any script. The map is rougher than one built from a graph, but you keep the “affected old code” block and the test check.
Extrapolation: a requirements log
Also my idea. Create a file called REQUIREMENTS_LOG.md. After each round, ask the agent to append a line: “requirement → which files and functions it created or changed.” In the next round, point to the log in your prompt.
Read REQUIREMENTS_LOG.md. New requirement: {requirement}.
Match it against the log entries: which past changes might it
affect? Build a target map before editing.
This recreates the method’s history H<t>: a memory of what was done in past rounds and why.
Resources
- Paper: RepoTrace: Improving Requirement Tracing in Multi-Round Agent Interactions (preprint, October 2026).
- Code and trajectories: https://github.com/gtxygyzb/RepoTrace
- Benchmark: EvoCode-Bench (Shen et al., 2026).
- Related work: Regression Accumulation (Huang et al., 2026), SlopCodeBench (Orlanski et al., 2026), Laban et al. (2025), on how agents degrade as the number of rounds grows.
- Authors: Huanyu Liu, Yezheng Cheng, Jinliang You, Tianxiao Huang, Linyu Li, Zheng Fang, Peng Cao, Ge Li.
- Affiliations: Peking University (Key Laboratory of High Confidence Software Technologies), Xidian University, Wuhan University, JD.com.