Repo as an Agent

A well-designed repo can itself become an Agent that continuously improves.

Here, a repo is more than a place to store code, and an Agent is more than a model invoked once. The repo preserves goals, knowledge, tools, feedback, and constraints. A model enters it, reads the current state, acts, and writes the results back. Even if a different model takes over next time, the work can continue from where it stopped.

Strictly speaking, a static Git repository cannot act on its own. It still needs a model, Harness, and runtime environment to wake it. The Harness is the system that hosts the Agent, providing the model with context, tools, and execution capabilities. But if those components can be replaced while the repo retains the same way of working and its accumulated capabilities, perhaps the most stable part of the Agent no longer resides in the model, but in the repo.

The Model Is Not the Whole Agent

It is easy to attribute an Agent’s capabilities to the model: a smarter model makes a stronger Agent; if one answer is poor, try again with a larger model.

This view overlooks the environment the model encounters each time it begins work. The same model may perform very differently in two repositories.

One repository contains only source code. It has no architecture documentation, no clear startup procedure, chronically failing tests, key decisions buried in chat history, and no readable logs when something goes wrong. The Agent has to guess again every time it enters. It may complete a local change, but it will struggle to finish work reliably.

Another repository records product goals and technical decisions in searchable documents, uses AGENTS.md to tell the Agent where to start, provides consistent entry points through scripts, and offers clear feedback through tests, type checks, and CI. It can also launch the real page so the Agent can observe the result directly. The model has not changed, but what it can accomplish has clearly expanded.

OpenAI’s account of an agent-first development experiment points in the same direction. The team found that slow early progress was not simply a limitation of Codex; the environment had not been sufficiently defined. Their main work shifted toward designing scaffolding, tools, and feedback loops, with repository knowledge as the single source of truth. Only as testing, validation, review, feedback handling, and failure recovery moved into the repo could the Agent start from a prompt and independently reproduce an issue, make a change, validate it, submit it for review, and repair CI.

Factory calls this difference Agent Readiness: how prepared a repo is for autonomous development. It evaluates not the strength of the model, but whether the repository has reliable builds, tests, documentation, development environments, observability, and security governance, then uses five maturity levels to describe how independently an Agent can work. This framework makes a vague judgment inspectable. When an Agent performs poorly, the model may not be the problem; the repo may not yet provide fast enough feedback, clear enough instructions, or an actionable environment.

The repo, then, is not merely the object an Agent works on. It also defines who that Agent is and what it can do.

A Repo Already Contains the Main Parts of an Agent

Seen this way, familiar files in a mature repo take on another meaning.

AGENTS.md, architecture documents, and decision records are long-term memory. They preserve facts and ways of working specific to the project.
Source code, CLIs, scripts, and Skills are the capacity to act. They do not merely describe what to do; they can be executed directly.
Tests, type checks, lint, CI, logs, and page review provide perception and feedback. They tell the Agent whether its latest action produced the intended result.
Issues, plans, and task files preserve unfinished goals.
Git records what happened and enables comparison, tracing, and rollback.
Human review handles what machine feedback cannot decide: whether a goal is worthwhile, a tradeoff is appropriate, or a result is truly acceptable.

Together, these parts form an actor that persists across multiple model invocations. The model handles reasoning in the moment; the repo provides continuity.

This is also why self-improvement need not mean that a model trains its own weights. The research on a Self-Improving Coding Agent uses a stricter definition: the Agent modifies its own implementation, then uses benchmarks to select the better-performing version. In everyday development, however, a more common and practical form of self-improvement happens outside the model. The model weights remain unchanged, but the Agent’s working environment changes. On its next run, it avoids one mistake already made and gains one capability already validated.

Improvement Begins When Feedback Is Written Back

Completing a task once is not yet self-improvement.

When an Agent fixes a bug, the product is better. But if the Agent will create the same kind of bug next time, only the product improved, not the Agent. The real dividing line is whether this feedback changes future behavior.

A failure can be written back at different levels.

If the Agent simply did not know the command to run, a short repository note may be enough. If a class of tasks always follows the same steps, those steps can become a Skill or script. If a constraint must never be violated, the best approach is usually not another reminder, but encoding it as a test, lint rule, or type rule. Natural language tells the Agent how it should act; automated checks prevent the wrong action from passing unnoticed.

A complete improvement loop therefore looks like this:

A figure with a folded-page head puts a chipped gear back into the repo machine, while an intact gear beside it represents an improved next run — Only when a failure is put back into the repo does it become part of the next action

Eric Ma calls this change operational self-improvement: rather than waiting for a model upgrade, feedback remains in AGENTS.md and reusable Skills. The measure is equally straightforward: whether a human must repeat the same correction, and whether work completed yesterday lowers the cost of similar work today.

This Blog Repo Already Works a Little Like This Agent

This essay itself is an example.

When I ask for “a draft on repo as an agent,” the repository’s rules already define what draft means: first research and polish the Chinese source, do not produce English or Japanese versions early, and do not commit or publish; after writing it into the article system, launch the corresponding page for my review.

I do not need to explain every time where articles belong, when they can be translated, or which checks to run. AGENTS.md preserves the boundaries, the writing Skill preserves reusable writing methods, the Content Collection determines article structure, Markdown smoke checks and build commands detect formatting problems, and the Portal reconnects the real page and human comments to the workflow.

More importantly, this repo also defines how feedback becomes lasting experience. Edits to one essay serve only that essay. Only when the same rationale recurs across multiple reviewed essays and different situations will the Agent propose adding it to the Skill—and human confirmation is still required.

This is a small learning mechanism. It does not train the model, but it distinguishes short-term feedback from long-term rules, deciding what should be forgotten and what deserves to enter the next run. As the number of essays grows, genuinely stable methods can gradually remain, so future production need not start from zero.

Remembering More Does Not Mean Improving More

Turning a repo into an Agent does not mean continually appending text to AGENTS.md.

A 2026 study of repository-level context files found that, in its experimental setting, adding AGENTS.md did not generally improve success rates on coding tasks and increased average reasoning cost by more than 20%. Agents followed nonstandard project instructions, but common repo overviews did not help. The researchers therefore recommend not assuming that more context is always better: any repository guidance claimed to improve performance should be evaluated.

This is a reminder that self-improvement can also degrade into self-contamination.

Incorrect summaries are inherited by the next run. Outdated documentation directs the Agent toward structures that no longer exist. Incidental preferences become permanent restrictions. Ever-longer instructions crowd out the context needed for the actual task. A repo amplifies good patterns, but it also amplifies bad ones.

A self-improving repo therefore also needs mechanisms for forgetting, correction, and promotion. Temporary experience should remain with the current task; only after recurring should it become documentation; rules that can be judged mechanically should move further down into tests and tools. Invalid guidance should be revised or removed. AGENTS.md works better as a map than an encyclopedia.

The Repo Is the Self an Agent Can Keep Rebuilding

To judge whether a repo is becoming this kind of Agent, ask a few concrete questions:

Can a new model instance recover the project’s goals, boundaries, and current state?
Can it run tools directly and observe real results, rather than merely generate plausible-looking code?
Can a failure leave behind an executable correction that makes the same mistake harder to repeat?
Can human judgment enter the system without allowing one-off opinions to permanently contaminate future work?
Can the repo inspect, clean up, and modify the documents, tests, Skills, and scripts that constrain it?

As the answers increasingly become “yes,” the model looks more like reasoning capacity brought in temporarily. What persists through time is the changing code, memory, tools, and feedback loops in the repo.

In the past, we treated a repo as the source code of software. In the future, it may also be the source code of an Agent.

With every run, the Agent modifies the product. When well designed, it also modifies its future self.