Skip to main content

README.md exists with project description

ab-002599 · project-snapshot.code-quality.has-readme
Severity: infoactive

Why it matters

A missing or boilerplate README is a proxy signal for several downstream problems: new contributors (human or AI) can't orient without reading the entire codebase, onboarding instructions drift away from package.json scripts, and the repo becomes difficult to hand off or evaluate for acquisition / due diligence. The standard create-next-app boilerplate is specifically flagged because its presence means "nobody has documented this project" — the file exists but carries zero project-specific content. AI coding tools are often handed a fresh scaffold and asked to build features on top of it without ever being asked to update the README, so the original boilerplate survives indefinitely. This check is informational because it doesn't block functionality, but it's a strong leading indicator of broader documentation and operational-readiness gaps.

Severity rationale

Info because a missing or boilerplate README slows onboarding and hand-off but doesn't create direct security, correctness, or availability risk on its own.

Remediation

Add a project description, setup instructions, and a one-line summary of what the project does:

# Acme

A booking platform for hair salons. Built with Next.js, Supabase, and Stripe.

## Setup
...

Deeper remediation guidance and cross-reference coverage for this check lives in the code-quality-essentials Pro audit — run that after applying this fix for a more exhaustive pass on the same topic.

Detection

  • ID: project-snapshot.code-quality.has-readme
  • Severity: info
  • What to look for: Check for README.md (or README.mdx/README.txt) at the project root. If found, count word count of the body.
  • Pass criteria: README exists at root AND has more than 50 words of actual content (not just a heading).
  • Fail criteria: README missing or contains less than 50 words.
  • Skip (N/A) when: Never.
  • Do NOT pass when: README is the framework's auto-generated boilerplate (e.g., the standard create-next-app README) — count it as fail because it doesn't describe THIS project.
  • Report even on pass: "README.md at root: ~N words; appears to describe the project (not boilerplate)."
  • Detail on fail: "README.md missing" or "README.md contains 18 words and matches create-next-app boilerplate".
  • Remediation: Add a project description, setup instructions, and a one-line summary of what the project does:
    # Acme
    
    A booking platform for hair salons. Built with Next.js, Supabase, and Stripe.
    
    ## Setup
    ...
    

Taxons

History