Skip to content
Klay

A README whose commands actually work

Make the README's setup commands work verbatim on a clean clone, and check that they still do.

EngineersVibe coderspythonnodedockerci-generic

The README is the first thing a new teammate and every coding agent both read, and it is the most reliably stale file in any repository. Commands that no longer work are worse than no commands: they send the reader down a path that fails for reasons unrelated to what they were trying to do, and they teach everyone to distrust the documentation entirely.

What goes wrong: A new hire loses their first day to a setup step that stopped working four months ago and nobody noticed.

What agents change: An agent takes the README literally and at face value — it is the closest thing your repo has to a system prompt.

You are violating it when

  • The README's install command references a file that no longer exists.
  • Setup requires a step that lives only in someone's memory.
  • Nobody has run the README's instructions on a clean machine this year.

The usual objection: That the README is documentation. It is an executable contract that happens to be written in prose.

A repository’s setup section is part of the product surface. It should describe the shortest reliable path from fresh clone to a working local environment, using commands that can be copied exactly rather than interpreted, repaired, or supplemented from memory. The useful standard is not whether the prose sounds right, but whether the commands still succeed in the environment a newcomer actually has.

This works because it turns onboarding into a repeatable interface. Explicit dependencies, package-manager commands, containerized services, and automated checks remove hidden assumptions from a developer’s laptop. When the same path is exercised continuously, broken setup stops being tribal knowledge and becomes an ordinary failing check.

The misconception is that the README is documentation. Treating it as prose makes drift feel harmless: a stale flag, renamed script, or missing service is “just docs.” In practice, those lines are executable instructions. When they fail, the reader cannot tell whether the project is broken, their machine is wrong, or the instructions are obsolete.

Agent-written code raises the stakes because an agent will usually consume the repository’s own instructions before it has any project context. It does not know which command is folklore and which one is current; it will follow the visible path. A stale README therefore becomes bad operational input, not merely a bad first impression.

Install it

npx klay practices add readme-that-runs
  • .klay/practices/readme-that-runs.mdcreate
    # A README that runs

The README is the first thing a new teammate reads and the first thing every
coding agent reads. It is also the most reliably stale file in any repository.

Commands that no longer work are worse than no commands. They send the reader
down a path that fails for reasons unrelated to what they were doing, and they
teach the whole team to stop trusting the documentation.

## The contract

Someone with a clean machine and a fresh clone can copy the commands in order
and end up with a running application. Nothing in between lives in anyone's
memory.

The previews are the first lines of each file; the command writes them in full. Existing files are never overwritten.

How you know it stuck

npx klay practices audit reports this check for this practice:

  • readme-runnable

Where this comes from

  1. Develop with containersDocker Docs · Official docsShows a concrete mechanism for reducing setup drift to reproducible container startup.
  2. About the repository README file - GitHub DocsGitHub Docs · Official docsDefines the README as the project’s front door and includes getting-started expectations.
  3. The Twelve-Factor AppThe Twelve-Factor App · Official docsExplains the dependency isolation needed for clean-clone setup commands to succeed.
  4. Onboarding your AI peer programmer: Setting up GitHub Copilot coding agent for successGitHub Engineering · Engineering blogConnects repository instructions directly to how coding agents bootstrap their work.

Questions

How do I keep it true?
Run it. A CI job on a clean container that executes the setup block is the only version of this that stays honest.