Repo Health

The switch to LLMs writing code has been a sharp change to which everyone is still adjusting. Producing code through an LLM is so different from hand-writing code that there is an entirely new skill set to learn. However, fundamentally, the result should still be the same: a feature is requested, and a solution is produced. Many of the programming fundamentals are still important, and in the case of the quality of a repository, it may be even more important when using LLMs.

The agent's repository

The repository, to the agent, is a set of external resources. The resources can be split into two categories: static and dynamic. Static resources are the files, the content of the files, and the structure of the app. Dynamic resources are those an agent can access or generate when running the app, for example, logging or JSON responses from an endpoint.

For agents, static resources are important for planning and implementation; they affect how an agent discovers components and related features. For example, an AGENTS.md (or CLAUDE.md) file at the root of the directory will typically be read immediately and can point agents in the correct direction, potentially saving tokens on less accurate operations like grepping file names.

The dynamic resources are important for validation; they affect the ability of the agent to test changes. For example, Claude provides an in-built skill called /verify (docs) which can invoke custom-built skills tailored towards known testing and validation steps for a repo, exercising the app to surface its dynamic resources — logs, endpoint responses, and other runtime output.

Why this matters

Repository health has always been important. Assuming everything else is equal, the ease of navigating and interacting with an app positively correlates with the quality of future code produced. For instance, if an app is runnable locally then it will be easier to verify changes, and a consistent file structure will be cognitively simpler to reason about.

Agents are expected to complete virtually all coding tasks. However, they are amnesiacs: they begin each task without remembering past repository nuances, structures, commands, etc. And they are imitators. Unless directed otherwise, they will copy local styling regardless of quality. Therefore, it is more important than ever to maintain good repository health to enable agents to efficiently gather context and implement high-quality code.

Despite the difference in the developer experience of producing code, the repository fundamentals will remain important and must constantly be curated to maintain high standards. Ultimately good repo health will compound for humans and agents.