Ask Knox

The Front Door Test

Every codebase has a front door: the first file a new engineer or a coding agent reads. For almost every service, that file is the README. It is opened at project creation, at onboarding, at the start of every agent session where no context file exists or before one is found. It is the most-read file in the repository and, on most projects, the least-maintained.

The test for a README is brutal in its simplicity: can a new engineer — or a coding agent — answer four questions without asking anyone?

What is this service?
How do I run it locally?
Where are the key files?
What will bite me?

If the answer to any of these is "you'd have to ask," the README has failed. Not partially failed — failed. Because the moment "you'd have to ask" is the answer, the documentation is actively transferring work from the doc to a human, on every first contact.

The anatomy diagram shows four required zones and one optional. The optional zone — architecture overview — is included only when the structure is genuinely non-obvious from the key-files table. For most services, it is not needed. For multi-service systems with non-obvious interaction patterns, it earns its place.

Zone 1: The One-Liner

The first three lines of a README are the most-read text in the repository. They are read by engineers evaluating whether to use the project, by new hires trying to understand what they just cloned, and by agents at the start of every session. They are also the zone most frequently wasted on marketing copy.

The rule: one sentence that answers "what is this" with a subject, a verb, and a specific outcome. No adjectives. No performance claims. No philosophy.

Wrong:

announce-lessons is a powerful, developer-friendly pipeline designed to streamline
notification workflows for modern content-driven applications.

Right:

announce-lessons: posts newly-merged academy lessons to Discord #lessons
within 5 minutes of merge.

The right version answers the question before the reader finishes the sentence. It names the input (newly-merged lessons), the output (a Discord post), the channel (#lessons), and the timing guarantee (5 minutes). An agent reading it knows immediately what this service does, who uses it, and what success looks like. The wrong version answers nothing.

Zone 2: The Quick-Start

The Quick-Start section's job is to take a person from "I just cloned this" to "something is running and I can verify it" in the fewest commands possible. The quality standard is the copy-paste test: every command in this section must be copy-pasteable and work on the primary development environment without modification.

The failure modes are well-known:

The install wall — 12 steps including optional dependencies, platform branches, and IDE configuration. Readers abandon it at step 4.
The missing end state — instructions that end without telling you what "working" looks like. You run the commands and stare at a blank terminal.
The implicit assumption — "make sure you have Node 20" buried in step 3, after a step that would have failed on Node 18 with a confusing error.

The discipline: one clean path, exact commands, end state. If the local dev environment requires an .env.local file, the Quick-Start copies the example. If it requires a specific runtime version, the Quick-Start states it. The last line tells you what you should see when it worked.

npm install
cp .env.example .env.local   # fill DISCORD_WEBHOOK_URL
npm run dev
# Expected: "announce-lessons started, polling every 5m" in the console

Four lines. One path. Verifiable end state.

Zone 3: The Key-Files Table

This is the zone most READMEs skip and the one that matters most for agent-assisted development. The key-files table is what separates a README written for humans who will ask questions from one written for agents (and senior engineers) who will read first and ask never.

The format is two columns: File/Dir and Purpose. The purpose column is not a description of what the file contains — it is what a reader would search for in that file. "Master track registry — lesson order, colors, tier mapping" is better than "contains track definitions."

| File / Dir         | Purpose                                                    |
|--------------------|------------------------------------------------------------|
| src/index.ts       | Entry point — starts the polling loop                      |
| src/detect.ts      | Reads git log to find lessons merged since the stored ref  |
| src/discord.ts     | Formats and POSTs embeds to the Discord webhook            |
| src/state.ts       | Persists announced lesson IDs to prevent duplicate posts   |
| data/announced.json| Append-only log of announced IDs — never delete this       |
| tests/             | Vitest unit tests                                          |

An agent reading this table knows in seconds where to look for the entry point, where the business logic lives, where the state is managed, and — critically — that data/announced.json is important enough to call out explicitly. Without this table, the agent spends the first part of its session doing structural discovery. With it, the agent opens the right file first.

The last row of the example (data/announced.json — never delete this) is doing double duty: it is both a key-files entry and a gotcha. When a file or directory is important enough to call out, its row in the table is also the place to put the single most important thing to know about it.

Zone 4: What Will Bite You

The gotchas section documents the things that bit the last three people who worked on this codebase. Not theoretical warnings. Not complete lists of edge cases. The real, specific things that caused real confusion.

The standard for what belongs here: if you would tell a new engineer "before you touch anything, you should know..." — that's a gotcha. The format is a short bullet for each:

## Known Gotchas

- **Never delete `data/announced.json`** — the idempotency check reads this file.
  If it is missing, every lesson in history will be re-announced on next run.
- **LAST_REF_PATH must be writable at runtime** — if the process runs in a
  read-only container, the ref never advances and lessons are re-detected on
  every poll.
- **Discord webhooks rate-limit at 5 requests/2s** — the service introduces a
  500ms delay between posts. Do not remove it.

Each entry names the thing, the constraint, and the consequence. An agent reading these gotchas will not delete the state file, will not run in a read-only container without checking, and will not remove the rate-limiting delay. Three lines that prevent three classes of mistakes.

The Decision Flow in Practice

The flow diagram shows where the test fails. Notice that Q3 (key-files table) has a soft failure — "agent must cold-grep." This is the most common failure mode in READMEs written for human engineers: Q1 and Q2 are excellent, Q4 is present, but Q3 is absent because no human author thought to write it. Humans navigate by intuition; agents navigate by maps.

The agents reading your repositories now are exactly the kind of readers who will notice the missing map on every single session. The 30 minutes you spend writing a key-files table will save that time back across the first ten agent dispatches. After that, it is pure compounding.