Coding agents fail on large repositories for reasons that are different from simple code-generation failures. The model may be able to write a function, but the agent system must also discover relevant files, retain architectural context across many tool calls, execute commands safely, recover from test failures, and avoid losing task state as the context window fills. A production coding agent is therefore not just a prompt around a language model; it is a scaffold that controls memory, tools, iteration, and feedback.
The Confucius Code Agent paper frames this as an industrial-scale software-engineering problem. Its agent is built around a unified orchestrator, hierarchical working memory for long-context reasoning, persistent notes for cross-session learning, modular extensions for tool use, and a meta-agent that searches over agent configurations through a build-test-improve loop. The reported result is a 54.3% Resolve@1 score on SWE-Bench-Pro, but the more transferable lesson is the system design: large-codebase agents need explicit state channels and measurable development loops.
This topic teaches the scaffold pattern behind those systems. It is useful for engineers building repository repair bots, code-review assistants, migration agents, documentation agents, or internal developer tools that must operate over real codebases rather than isolated programming puzzles.
A coding-agent scaffold has three audiences. The agent needs compact, reliable context and tools it can call predictably. The user needs a transparent workflow with plans, diffs, approvals, and failure explanations. The developer of the scaffold needs modular extension points, traces, metrics, and ways to reproduce behavior. Mixing these concerns in one prompt makes the system brittle; separating them lets each layer evolve.
Large repositories exceed the model context window. A practical scaffold splits state into layers: task intent, current plan, active file set, evidence snippets, tool results, test failures, and unresolved assumptions. The orchestrator promotes and demotes information between these layers instead of appending every observation to the conversation transcript.
Long-horizon coding work often spans sessions. Persistent notes capture repository facts that should survive a single run: build commands, ownership boundaries, test conventions, flaky checks, generated-code warnings, and architectural constraints. These notes are not a chat history dump; they are curated memory that can be retrieved into working memory when a future task touches the same area.
Model choice matters, but repository-scale performance often depends on the scaffold: how the system searches, edits, tests, summarizes, stores memory, and terminates. Treat the scaffold as production software with APIs, state machines, and regression tests, not as incidental glue around a model call.
A large-codebase coding agent repeatedly chooses the next action, executes it through a constrained tool interface, records the observation, updates memory, and decides whether to continue. The key difference from a generic ReAct loop is that software engineering has strong external validators: compilers, linters, unit tests, type checkers, and diffs.
class CodingAgentRun:
def __init__(self, objective, repo):
self.objective = objective
self.repo = repo
self.plan = []
self.active_files = set()
self.evidence = []
self.failures = []
self.notes = load_relevant_notes(repo, objective)
def step(self):
prompt_state = {
"objective": self.objective,
"plan": self.plan[-8:],
"active_files": list(self.active_files),
"evidence": self.evidence[-20:],
"failures": self.failures[-5:],
"persistent_notes": self.notes[:10],
}
action = model_choose_action(prompt_state)
observation = execute_tool(action)
self.update_memory(action, observation)
return self.should_stop(observation)The scaffold makes state explicit. The model sees a curated state object, not an unbounded transcript. Tool observations are summarized into durable fields that can be inspected, filtered, and tested independently.
The Confucius paper describes a meta-agent that synthesizes, evaluates, and refines agent configurations. The general pattern is to treat scaffold choices as search parameters: which tools are enabled, how much context is retrieved, when tests run, what prompts are used for planning, and which termination criteria apply. Each candidate configuration is evaluated on a task suite, and failures feed the next configuration proposal.
def improve_scaffold(seed_config, benchmark):
config = seed_config
for round_id in range(10):
results = run_agent_suite(config, benchmark)
failures = cluster_failures(results.traces)
patch = propose_config_change(config, failures)
candidate = apply_patch(config, patch)
if evaluate(candidate, benchmark).score > results.score:
config = candidate
return configBug-fixing agents need issue triage, code search, patch generation, and test execution. Hierarchical memory helps them keep the issue, failing trace, touched files, and constraints visible while discarding irrelevant command output. Persistent notes help future runs remember project-specific commands and known traps.
Large migrations require repeated local decisions under global consistency constraints. A scaffold can store migration rules as notes, maintain a checklist of completed modules, and run targeted tests after each slice. This is safer than asking a model to rewrite a whole repository from a single prompt.
Review agents must inspect diffs, connect changes to tests, and explain residual risk. The same scaffold pattern works: separate evidence collection from judgment, preserve trace links to files and commands, and use validators before producing a final review.
Store task state in typed channels instead of a monolithic scratchpad. Examples include plan, facts, assumptions, active_files, test_failures, and user_constraints. Typed channels make summarization safer because each channel has a different retention policy.
Planning, editing, testing, and finalization need different tools. During planning, read-only search tools reduce accidental edits. During implementation, write tools are enabled but destructive commands remain blocked. During finalization, the agent should focus on validation and reporting rather than broad exploration.
Traces are the raw material for debugging and meta-agent improvement. Store action, tool input, output summary, changed files, validation command, exit code, and failure class. Without structured traces, scaffold changes are anecdotes rather than measurable improvements.