README Generation

Generate a README from the repo's actual commands, structure, and conventions.

Docs & RefactorIntermediate

Why

GitHub's 2024 survey found 81% of developers expect AI tools to become more integrated in documenting code over the next year, the highest of any workflow. A README that reflects real commands (build, test, deploy) and structure onboards fast; one with stale commands wastes time.

Generating from package.json + the repo layout keeps it accurate.

When

Use when bootstrapping a repo or when the README is stale. Skip if a hand-crafted README is current.

How

1. Feed package.json, the directory tree, and CLAUDE.md/.cursorrules. 2. Prompt: "README: what this is, install, dev, test, build, deploy, structure, conventions". 3. Pull commands from package.json scripts, not memory. 4. Add a contributing section pointing to the rules file. 5. Review and hand-polish the intro; keep commands generated.

Example

Prompt: "@file package.json @file CLAUDE.md generate README; sections: overview, install (npm ci), dev (npm run dev), test (npm test), build (npm run build), structure (src/), conventions (see CLAUDE.md)." Output reflects real scripts; no stale "npm start" if it doesn't exist.

Common Problems

⚠Error: Cannot find module 'xxx' after refactor → re-run `npm install` and `npx tsc --noEmit`; refactors often drop or rename imports.
⚠Error: "Cannot read properties of undefined" after refactor → run the test suite (`npm test`) to catch behavior changes; refactor must be behavior-preserving.
⚠Error: Docs drift: example no longer runs → execute examples in CI (`npm run docs:check`); tested examples never drift.

Best Practices

✓Pull all commands from package.json scripts, not memory.
✓Keep the generated command list; hand-polish only the intro.
✓Measure the outcome with a concrete metric (time saved, defect rate, test coverage) so the practice can be justified and improved.

FAQ

What is README Generation?

Generate a README from the repo's actual commands, structure, and conventions. It helps developers quickly grasp the core value and use cases of README Generation.

How do I get started with README Generation?

To get started with README Generation, focus on these points first: Feed package.json, the directory tree, and CLAUDE.md/.cursorrules.

What are common mistakes with README Generation?

Common mistakes when using README Generation include: Error: Cannot find module 'xxx' after refactor → re-run `npm install` and `npx tsc --noEmit`; refactors often drop or rename imports.; Error: "Cannot read properties of undefined" after refactor → run the test suite (`npm test`) to catch behavior changes; refactor must be behavior-preserving.; Error: Docs drift: example no longer runs → execute examples in CI (`npm run docs:check`); tested examples never drift..

What are the best practices for README Generation?

Best practices for README Generation include: Pull all commands from package.json scripts, not memory.; Keep the generated command list; hand-polish only the intro.; Measure the outcome with a concrete metric (time saved, defect rate, test coverage) so the practice can be justified and improved..

How do I learn more about README Generation?

Start with the official docs, then search real-world examples on GitHub. Validate patterns in a small scratch repo before applying them to production code.