Write a production-quality README for [PROJECT NAME AND PURPOSE]. The project uses [TECH STACK], runs with these verified commands: [VERIFIED COMMANDS], and has this repository structure or key files: [PROJECT STRUCTURE]. Configuration, dependencies, and operational notes are [CONFIGURATION AND NOTES]. The intended reader is [READER TYPE]. Do not infer commands, endpoints, environment variables, licenses, supported platforms, or deployment behavior that I have not provided. If documentation is incomplete, add a clearly marked “Information needed” item instead of guessing. Return one Markdown README with this order where applicable: title and one-paragraph purpose; features; prerequisites; installation; configuration; quick start; usage examples; project structure; scripts or commands; testing; deployment or release notes; troubleshooting; contributing; license; and support. Use fenced code blocks for commands and configuration examples. Explain what each required environment variable does, whether it is secret, and provide a safe placeholder value where possible. Keep the quick start runnable in order from a clean machine. Include a “Verification” section with the expected successful result after setup and a “Common failures” table with symptom, likely cause, and safe next action. Mention version requirements only when supplied. Before answering, check that every command and code example comes from my inputs, and that setup instructions do not omit a dependency required by a later step. Ask up to 3 clarifying questions only if a required input is missing.
Fill in
| Placeholder | What to enter | Example |
|---|---|---|
| [PROJECT NAME AND PURPOSE] | Give the project name and one or two sentences on what it does. | Shift Notes API, an Express service that stores shift handoff notes for a retail operations team |
| [TECH STACK] | List the language, framework, database, package manager, and other relevant tools. | Node 20, Express 4, PostgreSQL 16, Prisma, npm, Docker Compose |
| [VERIFIED COMMANDS] | Paste commands you have actually run for install, development, test, build, and other key tasks. | npm ci; cp .env.example .env; docker compose up -d db; npx prisma migrate deploy; npm run dev; npm test |
| [PROJECT STRUCTURE] | List the important folders and files with a short note about each. | src/routes for HTTP routes; prisma/schema.prisma for data model; tests for API tests; docker-compose.yml for local database |
| [CONFIGURATION AND NOTES] | Provide environment variables, services, permissions, deployment facts, and known limitations. | DATABASE_URL is required and secret; PORT defaults to 3000; migrations must run before the server; no production deployment process documented |
| [READER TYPE] | State whether the README is for contributors, customers, internal developers, or another audience. | New developers joining the internal platform team |
How to use
- Gather commands from a clean setup or CI run before asking AI to document them.
- Paste the full prompt with your actual file paths and configuration names.
- Run the generated quick start in a fresh environment or ask a teammate to do so.
- Follow up with: “Add a troubleshooting row for this observed error: [ERROR MESSAGE], using only the cause I confirmed: [CAUSE].”
Variations
Open-source README
You need a public-facing README that helps evaluators and contributors assess a repository.
Write a public README for [PROJECT] using these confirmed facts: [FEATURES], [INSTALL COMMANDS], [USAGE EXAMPLE], [CONTRIBUTION PROCESS], and [LICENSE]. The readers are [AUDIENCE]. Produce Markdown with a concise purpose, feature list, install and usage sections, configuration notes, contribution instructions, security reporting route if provided, and license. Do not claim benchmarks, compatibility, maintainer responsiveness, or security properties without evidence. Check that every copied command is complete and that public examples contain no real secrets or internal URLs.
Internal service README
You document a service that another on-call engineer must operate safely.
Create an internal operations README for [SERVICE] from [CONFIRMED SERVICE DETAILS]. Include ownership, purpose, dependencies, access prerequisites, local run steps, deploy procedure, health checks, rollback procedure, dashboards or logs, alerts, and known failure modes. Use [ON-CALL ESCALATION PATH] exactly as provided. Mark missing runbook facts rather than inventing operational steps. Before answering, verify that any rollback action has a stated trigger and that every alert links to a safe first diagnostic action.
README refresh audit
A README exists but may no longer match the codebase.
Compare this current README: [CURRENT README] with these verified project facts: [CURRENT COMMANDS AND CONFIGURATION]. Return a Markdown audit table with section, inaccurate or missing content, evidence from the facts provided, and proposed replacement text. Then provide only the changed README sections. Do not assume code behavior from the old README. Check for outdated package-manager commands, missing required variables, and setup steps that no longer occur in order.
Tips
- A README should optimize for a clean-machine setup, not explain every design decision; link to deeper docs when the project has them.
- Document environment variables with purpose and sensitivity, but never put real credentials or production connection strings in examples.
- Run each code block as written when possible; an untested quick start is often less useful than no quick start.
- Put expected success output beside critical setup steps so readers can tell a configuration failure from a slow command.
FAQ
Can AI inspect my repository and write the README automatically?
It can summarize supplied files, but you should still provide or verify the actual commands and configuration. Repository contents alone often do not show operational requirements.
What belongs in a README versus a wiki?
Put purpose, setup, everyday usage, and essential troubleshooting in the README. Move long architecture decisions and detailed runbooks to linked documentation.
Should I include a deployment section?
Include it when the repository owner is expected to deploy. If deployment is handled elsewhere, say where the approved procedure lives instead of inventing one.