claude-md-project

Generate or audit a project-level ./CLAUDE.md — context specific to this repository.

The project file lives at ./CLAUDE.md (repo root) and applies to THIS project only. Target: ~40 lines maximum.

Analyze the current project Read these files to understand the project (do NOT put discoverable info in the output):

• package.json or pyproject.toml — dependencies, scripts

• README.md — project description

• tsconfig.json or equivalent — language config

• .eslintrc / biome.json / ruff.toml — linting rules

• .claude/settings.json — check for existing hooks (don't duplicate what hooks already enforce)

• Scan top-level directory structure

Identify non-discoverable context For each candidate line, apply the filter: "Can the agent figure this out by reading the code?"

• If YES → do not include

• If NO → include

What typically passes the filter:

• What the project does (1-2 sentences of domain context)

• Non-obvious stack choices (e.g., "Supabase with RLS" — not "uses React")

• Commands with special setup (e.g., pnpm db:migrate — not pnpm dev )

• Architecture decisions the agent would get wrong (e.g., "all DB queries go through /lib/db")

• Implicit patterns not enforced by linters (e.g., "Server Components fetch; Client Components interact")

• Guardrails for common mistakes (e.g., "do not modify /lib/db/client.ts")

What typically fails the filter:

• Directory tree listings (agent runs ls )

• Dependency lists (agent reads package.json)

• Standard commands like npm install , npm test , npm run dev

• README content repeated

• Generic best practices

• Rules already enforced by linters or type system

Think before writing (critical step) Before generating, walk through each section mentally:

• For "What this project does": Is this inferable from the README? If so, what's the ONE thing the README doesn't capture?

• For "Stack": Would the agent guess wrong about any choice? Only include those.

• For "Commands": Is this just pnpm <script-name> ? If so, skip it.

• For "Architecture": What would a new contributor get wrong in their first week?

• For "Do NOT": What mistakes has the agent (or a human) actually made?

Generate the file with these sections

Philosophy (~4 lines)

• This project's design principles — not generic advice

• Quality test: "If I removed this, would the agent make a different (wrong) choice?"

What this project does (~2 lines)

• Domain context, not marketing copy

• What problem it solves, for whom

Stack (~3 lines)

• Only non-obvious choices not discoverable from config files

• Include WHERE things live if the convention is unusual

Commands (~3 lines)

• Only commands with non-standard flags or required setup steps

• Skip anything that's just pnpm <standard-script>

Architecture decisions (~5 lines)

• Decisions the agent would get wrong without guidance

• Where specific things live and WHY

• Patterns that aren't enforced by linters or types

Patterns to follow (~4 lines)

• Project-specific conventions

• Rules the agent tends to violate in this codebase

Do NOT (~3 lines)

• Explicit guardrails for common mistakes — include WHY for each

• Protected files or directories

• Anti-patterns specific to this project

Review and trim (critical step) Read the generated file as if you're paying per token (because the user is). For each line, ask these 3 questions: a) "Would the agent get this wrong without this line?" → if NO, delete b) "Is this already enforced by a linter, type system, hook, or config?" → if YES, delete c) "Can I merge this with another line without losing meaning?" → if YES, merge

Then verify:

• Line count within target (~40 lines, 30-50 acceptable)

• No two lines say the same thing differently

• Every bullet is a COMMAND or CONSTRAINT, not a description

• Every "Do NOT" includes a reason

Write the file

• Write to ./CLAUDE.md at the project root

• Use # headers for sections (no nested headers)

• Use - bullet lists for rules

• Use plain text for commands (no code blocks needed for simple commands)

• No XML tags, no frontmatter — plain markdown only

Suggest .claude/rules/ if appropriate If the project has:

• Multiple distinct domains (frontend + backend + infra)

• File-type-specific rules (different conventions for tests vs source)

• More than 50 lines of context needed

Then suggest splitting into .claude/rules/ files:

• Keep the main CLAUDE.md for cross-cutting concerns (~20 lines)

• Create .claude/rules/[domain].md for specific areas

• Each rules file can use globs in frontmatter: globs: ["src/api/**"]

Also: if rules can be automated (format, lint, test), suggest using hooks in .claude/settings.json instead of CLAUDE.md instructions. Hooks are more reliable than asking.

Philosophy

• API-first: public endpoints are the contract, internals can change freely
• Thin components, thick hooks: UI components are dumb, logic lives in hooks
• Fail loudly: errors bubble to boundaries, never swallowed silently
• Schema-first: Zod defines the contract, types and validation derive from it

What this project does

Internal dashboard for the sales team — tracks pipeline and generates commission reports.

Stack

• Supabase Auth with RLS policies on every table
• Charts use Recharts with the custom theme in /lib/charts/theme.ts

Commands

pnpm db:migrate # applies pending Supabase migrations locally pnpm db:gen # regenerates TypeScript types from DB schema

Architecture decisions

• All DB queries go through /lib/db — never call Supabase client directly
• Zod schemas in /lib/schemas are the single source of truth for validation
• Background jobs use Inngest in /inngest/functions — not cron or setTimeout
• Commission calculations in /lib/commissions are the most complex part — always add tests

Patterns to follow

• Server Components fetch data; Client Components handle interactivity only
• Use server actions for mutations, not API routes
• Let errors bubble to error.tsx boundaries

Do NOT

• Do not create barrel files (index.ts re-exports) — causes circular deps
• Do not add console.log — use /lib/logger for structured output
• Do not modify /lib/db/client.ts — configures connection pooling, changes break prod

BAD — verbose, full of discoverable info (annotated):

Project Overview ← REMOVE: restates README

This is a Next.js application that uses ← REMOVE: narrative, not instruction React for the frontend and Supabase for ← REMOVE: discoverable from package.json the backend database. ← REMOVE: discoverable from package.json

Tech Stack ← REMOVE: entire section is discoverable

• React 18.2 ← REMOVE: in package.json
• Next.js 15 ← REMOVE: in package.json
• TypeScript 5.3 ← REMOVE: in package.json
• Tailwind CSS 3.4 ← REMOVE: in package.json
• Supabase ← REMOVE: in package.json

Directory Structure ← REMOVE: agent runs ls

src/ ├── components/ ├── pages/ ├── utils/ └── lib/

How to run ← REMOVE: standard commands

npm install ← REMOVE: obvious npm run dev ← REMOVE: standard script npm test ← REMOVE: standard script

Code Style ← REMOVE: enforced by tooling

• Use 2-space indentation ← REMOVE: in .prettierrc
• Use single quotes ← REMOVE: in .prettierrc
• Always use semicolons ← REMOVE: in .prettierrc