RepoFit
ProductBest practicesThe rubricPricingScan a repo
Sign inAnalyze your repo
Best practices

How to get a repository ready for agents.

Five practices, in the order that changes the most. Each one says what to do, why it saves tokens and errors, and what we measure to know whether it's done.

What changes when the repository is ready.

It isn't that the agent gets faster. It's that it stops needing you for what it can find out and verify on its own.

  • New sessions without fear

    Opening a clean session stops meaning starting from zero: the context lives in the repository, not in your chat history. No more dragging a hundred-message conversation around just to keep what you already explained.

  • You stop writing the same prompt

    The conventions, the paths and the business rules are written where the agent looks for them. No need to dictate them again, or to remember what they were.

  • The same result, no matter who asks

    Two people, two different agents, the same repository: the written rules are the same for everyone. The result stops depending on who wrote the better prompt.

  • The agent closes the loop and you approve

    With discoverable commands and tests that assert something, it can try, verify itself and correct before asking you to review. You approve the result, not every step.

Why this isn't obvious

Because almost nobody has done it. We measured more than 100 public repositories — live, famous, well-maintained projects — and the median scores 67 out of 100: half have not a single agent instruction, and almost nine in ten hide files that don't sit comfortably in a context window. It isn't carelessness: nobody measured this until now, because until now the one reading the code was a person.

+100public repositories measured

67/ 100 · the median score

Documentation· 25 points

Write the map once, not in every prompt.

Why it pays off

An agent that can't find where a responsibility lives goes looking, and looking means reading. Documentation is the only context you write once and that serves every session, every person and every agent — and unlike a prompt, it gets reviewed in a pull request.

What to do

  • One page per module saying what it does and where it's touched
  • A root README with what the project is and how to run it
  • A navigable index, not loose files
  • Update it when you close the change, not “later”

What we measure

  • Documentation coverage15
  • Documentation freshness5
  • Root README3
  • Navigable documentation2
Agent instructions· 14 points

Leave the instructions where the agent looks.

Why it pays off

Instruction files are the first thing any agent opens. If they're empty, if they contradict each other across tools, or if their links are dead, every session starts by guessing your conventions — and guesses differently each time, which is why the same request gives two results.

What to do

  • One adapter per tool, all pointing at the same documentation
  • Pointers, not copies: duplicated knowledge drifts
  • Live links, because a dead one sends the agent exploring
  • Two or three non-negotiable facts, not a manual

What we measure

  • Agent instructions4
  • Adapter consistency3
  • Live documentation links3
  • Always-on context2
  • How to verify, told to the agent2
Executability· 26 points

Let the agent run and verify on its own.

Why it pays off

If the commands aren't discoverable, the agent guesses them or asks you. If the tests assert nothing, it can't know whether what it did works, and the only verifier available is you, on every change. With tests that assert, the try → verify → fix loop happens without you.

What to do

  • Commands declared where they're looked for: scripts, a Makefile or a README
  • Lockfile and runtime version pinned, so it installs the same twice
  • A `.env.example` with what the code actually reads
  • Strict typing and lint: two more verifiers that don't cost your time

What we measure

  • Test volume3
  • Continuous integration4
  • Test breadth4
  • Reproducible install4
  • Discoverable commands4
  • Declared environment variables4
  • Strict verifier3
History· 20 points

Look after the files that always break.

Why it pays off

The files that concentrate the fixes are the ones an agent will break: the most-changed and the least forgiving. Git history says which they are without anyone having to have an opinion, and it also says which areas only one person knows — which is where the agent has nothing to learn from.

What to do

  • Split the files that accumulate fixes, not just the big ones
  • Document the areas only one person knows
  • Commit messages that say what changed and why
  • Close or mark the areas nobody has touched in a year

What we measure

  • Risk hotspots7
  • Concentrated knowledge5
  • Abandoned areas3
  • Commit traceability2
  • Documentation follows the work3
Structure· 15 points

Make it fit in a context window.

Why it pays off

Changing three lines of a 900-line file means loading all of it, and an 80-file folder means listing it to find one thing. None of that shows up on your bill as “structure”: it shows up as tokens.

What to do

  • No giant code files, least of all a committed bundle
  • No vendored dependencies inside the repo
  • A navigable tree, no drawer folders, no loose code at the root
  • One library per role: two HTTP clients force a guess

What we measure

  • Giant files5
  • Committed dependencies3
  • Tree navigability4
  • Libraries with the same role1
  • Duplicate files2

What we do have measured

Across public repositories of different languages and sizes, a real agent (Claude Opus 5) tried to verify against the code what their documentation claimed. The better documented the repository, the more of what it says held up: 81 out of every 100 claims in the best-documented third, against 51 in the worst. Looking only at applications, 80 against 59.

Documentation coverageWhat the agent could verify
  • The worst-documented third46 · 51
  • The middle third68 · 66
  • The best-documented third95 · 81

Public repositories in several languages, measured with a real judge. It's an observed relationship: a well-documented repository tends to be better maintained in everything else too. Size explains far less than documentation does.

RepoFit

And how RepoFit gets you there

Every practice on this page is a group of checks in the rubric. The diagnosis tells you where you stand, with the evidence next to it and the cost in points of everything that's missing. And a failed check doesn't just return its subtraction: it returns its playbook, adapted to your conventions, for your agent to run and for you to approve.

Analyze your repo, freeScan a public repo
The rubricProduct
Analyze your repo, freeScan a public repo

No card. Your code never leaves your machine.