README

Agent Prompt Snippet

Ensure the project has a README covering purpose, installation, quick start usage, configuration, and contribution guidelines.

Purpose

The README is the front door of your project. It is the first thing a developer sees when they land on the repository, the document most likely to be read before any other, and often the document that determines whether a developer uses your project at all.

A README has two jobs. The first is answering the question “Is this what I’m looking for?” within 30 seconds of reading. This requires a clear, one-paragraph description of what the project does, who it is for, and what makes it different. The second job is getting a developer to their first successful outcome—running the project, calling the API, or building from source—with minimal friction.

The README is not exhaustive documentation. It should not try to document every feature, every configuration option, or every API endpoint. Its job is to hook the reader and point them to the right place for more detail. A README that covers everything is a README that covers nothing well.

For open-source projects, the README is a marketing document as much as technical documentation. It creates the first impression of quality, maintainability, and whether the project has an active community. The README signals to potential contributors whether the project is worth their time.

For internal tools, the README’s primary value is reducing the bus factor: the project’s README should allow a new team member to be productive without relying on tribal knowledge held by one specific person.

Who needs this document

Persona	Why they need it	How they use it
Sam (Indie Dev)	Attracts users and contributors; makes the project credible	Writes README before publishing; uses it to verify the project’s value proposition is clear
Claude Code (AI Agent)	Reads README to understand project conventions and development workflow before writing code	Reads README at session start; uses repository structure and command documentation to orient itself
Leo (OSS Maintainer)	First touchpoint for contributors; sets expectations for the project	Keeps README accurate; links from GitHub issues and discussions to README sections
DevOps (CI Operator)	Needs build and deployment instructions; uses README to verify deployment matches documentation	References README for build commands; flags README updates when deployment process changes

What separates a good version from a bad one

Criterion 1: Purpose is stated in the first paragraph without jargon

✓ Strong: “SpecBase tells AI agents and developers which specification documents every software project needs. You specify the type of project (web app, CLI tool, ML model) and the optional features (auth, payments, real-time), and SpecBase returns the precise list of documents required—with rationale, starter templates, and integration with Claude Code via MCP.”

✗ Weak: “SpecBase is a tool that leverages cutting-edge AI and knowledge graph technology to provide developers with a comprehensive, extensible, and highly configurable specification management framework.” (Jargon-heavy. A developer cannot determine in 30 seconds whether this solves their problem.)

Criterion 2: Installation reaches the first running state in under 5 steps

✓ Strong:
brew install specbase
specbase query web_app --features auth --format table
Three lines, including the install command. The developer has running output before reading further.

✗ Weak: A 200-line Prerequisites section that requires manually configuring environment variables, installing multiple language runtimes, and building from source before seeing any output. (The higher the friction to “hello world”, the more developers abandon the project.)

Criterion 3: Configuration shows minimal working example first, full reference later

✓ Strong: “Create config.yaml with:
output: table
That’s the only required configuration. See Configuration Reference for all options.”

✗ Weak: A README that shows a 50-line config file with every possible option as the “example configuration.” New users cannot tell which fields are required vs optional.

Criterion 4: Status indicators reflect current reality

✓ Strong: CI badge shows current build status (green or red, live). Release badge shows the current released version. “Last updated” date in the README header so readers can tell if it’s been maintained.

✗ Weak: CI badge hardcoded to a passing image regardless of actual build status. Version badge showing 0.1.0 when the project is on 2.4.1. (Stale status indicators signal an abandoned project to potential users and contributors.)

Common mistakes

Combining the README with the contributing guide. The README is for users; the contributing guide is for contributors. Mixing them creates a document that serves neither audience well. Keep CONTRIBUTING.md separate; link to it from the README.

No example output. Showing the command is necessary but not sufficient. Show the output. A table, a JSON snippet, or a screenshot of the UI gives the reader confidence that the tool does what it claims before they invest time installing it.

Missing the “why this over alternatives” paragraph. For any non-trivial project, there are alternatives. A developer evaluating your README is also looking at your alternatives. One paragraph naming the alternatives and clearly stating when to choose yours (and when not to) is one of the highest-value sentences in a README.

Documentation rot from missing update ownership. The README is outdated within weeks if no one owns it. Link build commands in the README to Makefile targets (so they’re tested as part of CI) and assign README accuracy as part of the release checklist.

How to use this document

When to create it

Write the README before the first public commit. For new projects: write the README as part of project initialization, before any implementation. Writing the README first forces you to articulate what the project does and how it will be used—a useful forcing function for design decisions.

Who owns it

The project maintainer owns the README. For open-source projects, accept README improvement PRs readily—readers notice problems that authors no longer see. Establish a “README check” item in the release checklist.

How AI agents should reference it

get_standard_docs(type="cli_tool", features=[])
→ readme in documents[]
→ agent reads README to understand project conventions and available commands
→ agent verifies README is accurate for current behavior when making changes
→ agent flags README sections that need updating when behavior changes

The prompt_snippet — “Ensure the project has a README covering purpose, installation, quick start usage, configuration, and contribution guidelines” — tells the agent to check for all five required sections.

How it connects to other documents

The README is the hub that links to other documentation. Installation details live in the Installation Guide; configuration details live in the Configuration Specification; architecture details live in the Architecture Overview. The README’s quick start should be short enough to fit on one screen and should link to each of these documents for depth.