20.4 README that gets people to "hello world" fast

Goal: fastest path to “it works”

A good README optimizes for one thing: a new person can run your project quickly and successfully.

For AI apps, a README must also handle:

• environment variables and secrets,
• run/test commands,
• common failure modes (timeouts, rate limits),
• prompt/schema versioning basics.

A README structure that works

• What it is: 2–4 sentences
• Quickstart: run in minutes
• Configuration: env vars + .env.example
• Usage examples: 3–6 examples
• Testing: one command
• Troubleshooting: common errors and fixes
• Architecture (optional): file map + boundaries

Quickstart section (what to include)

Quickstart should be copy/paste-able:

• install dependencies
• set env vars
• run one command

Include the expected output for one simple example. That gives users a “did it work?” reference.

Examples and troubleshooting

Examples reduce questions. Troubleshooting reduces frustration.

For AI apps, include at least:

• rate limit symptoms and what to do
• auth/credential setup mistakes
• invalid output/schema failures

Keep troubleshooting short and actionable.

Using AI to draft a truthful README

AI can draft a README quickly if you provide:

• file tree
• run/test commands that you’ve verified
• .env.example
• one or two example inputs/outputs

Force “do not invent commands.” Require it to mark unknowns.

Copy-paste README template

# Project Name

One-sentence description.

## Quickstart

```sh
# install
...

# configure
cp .env.example .env
# edit .env

# run
...
```

Expected output:
```text
...
```

## Configuration

- ENV_VAR_NAME: meaning

## Usage

Examples:
```sh
...
```

## Test

```sh
...
```

## Troubleshooting

- Symptom: ...
  Fix: ...

Where to go next

• 20.5 Changelogs and migration notes
• Later: Part XV troubleshooting