# README exists and is adequately maintained

- **Pattern:** `ab-000672` (`code-maintainability.documentation.readme-exists`)
- **Severity:** high
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-000672
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-000672)

## Why it matters

A missing or boilerplate README means the first developer to clone your project — or you on a new machine six months from now — must read source code to discover how to install dependencies, configure environment variables, and start the server. ISO 25010 maintainability.analysability fails at the project entry point. An unmodified `create-next-app` README is indistinguishable from a project with no documentation at all: it describes Next.js, not your project. Every undocumented setup step is a blocker for every future contributor.

## Severity rationale

High because a missing or boilerplate README blocks every new contributor from setting up and running the project without direct help from the original author.

## Remediation

Write a minimum viable README covering what the project does, how to install it, and how to run it. Reference `src/app/` for the route structure and call out non-obvious setup steps:

```markdown
# Project Name

One paragraph: what this does and who it's for.

## Setup
1. `npm install`
2. Copy `.env.example` to `.env.local` and fill in the values
3. `npm run dev` — runs on http://localhost:3000

## Project Structure
- `src/app/` — routes and pages
- `src/components/` — shared UI components
- `src/lib/` — utilities and third-party wrappers
```

Fifteen minutes of writing now saves hours of onboarding friction later.

## Detection

- **ID:** `readme-exists`
- **Severity:** `high`
- **What to look for:** Check for a `README.md` (or `README.rst`, `README.txt`) in the project root. If found, evaluate its content:
  - Does it describe what the project does?
  - Does it include setup/installation instructions?
  - Does it describe how to run the development server?
  - Is it the default create-next-app/boilerplate README with only the framework's default text (a fail — it contains no project-specific information)?
  - Is it clearly outdated (references to renamed files, missing setup steps the codebase requires)?
- **Pass criteria:** Count all sections in the README (headings at any level). A README exists with at minimum: a description of the project (at least 2 sentences), installation instructions, and a command to start the development server. It is not the unmodified framework boilerplate. The README must contain at least 50 words of project-specific content. Report even on pass: "README.md contains X words of project-specific content across Y sections."
- **Fail criteria:** No README found, OR the README is the unmodified framework boilerplate (e.g., the exact default Next.js README that only says "This is a Next.js project bootstrapped with create-next-app"), OR the README is so outdated it references non-existent files or missing setup steps. Do NOT pass when a README exists but contains fewer than 50 words of non-boilerplate content.
- **Skip (N/A) when:** Never — every project benefits from a README.
- **Detail on fail:** `"README.md is the unmodified Next.js create-next-app boilerplate — contains no project-specific description, setup instructions, or documentation."` or `"No README.md found in project root."` or `"README references .env.local setup but no .env.example exists and no variables are documented."`
- **Remediation:** A README is the first thing any new collaborator (or future you, six months from now) reads. The minimum viable README takes 15 minutes to write:

  ```markdown
  # Project Name

  One paragraph describing what this project does and who it's for.

  ## Setup

  1. Clone the repo
  2. `npm install`
  3. Copy `.env.example` to `.env.local` and fill in the values
  4. `npm run dev` — runs on http://localhost:3000

  ## Key Technologies

  - Next.js 15 (App Router)
  - Supabase (database + auth)
  - Stripe (payments)

  ## Project Structure

  - `src/app/` — routes and pages
  - `src/components/` — shared UI components
  - `src/lib/` — utilities and third-party wrappers
  ```

## External references

- iso-25010 maintainability.analysability

Taxons: code-quality

HTML version: https://auditbuffet.com/patterns/ab-000672