Abhay Pratap Mishra

@abhay • 3 weeks ago

Generate a CLAUDE.md or AGENTS.md file for your repository

Write a short, specific CLAUDE.md or AGENTS.md from your repo facts, turning the mistakes agents keep making into concrete rules with reasons.

At a glance

Best for: Teams using Claude Code, Codex or Cursor who are tired of correcting the same agent mistakes in every session.
Tested on: Claude · Opus 5.5
You fill in: file_namerepo_factsmistakes
You get: bash pnpm install never npm/yarn pnpm dev web + api pnpm vitest run path/to/file.test.ts one unit test file pnpm test all unit tests pnpm lint &&… (full result below)

Prompt

Write a {{file_name}} for this repository. Coding agents (Claude Code, Codex, Cursor) read it at the start of every session, so every line costs context on every task.

Repo facts:
{{repo_facts}}

Things agents keep getting wrong here:
{{mistakes}}

Rules for the file:

• Under 60 lines. Commands go in code blocks, exactly as they are run.

• Sections: Overview (3 lines max), Commands (install, dev, run one test file, lint, typecheck), Where things live (one line per area), Conventions (only ones that differ from the language or framework defaults), Don't, Definition of done.

• Turn every mistake I listed into a concrete rule with its reason in a few words, e.g. "Use pnpm, not npm: the lockfile is pnpm-lock.yaml."

• No generic advice an agent already follows ("write clean code", "add comments", "follow best practices").

• If a fact you'd need is missing, write TODO(owner): instead of guessing.

After the file, list in 2–4 bullets anything you deliberately left out and why.

Fill in

{{file_name}}: Which file you're writinge.g. CLAUDE.md
{{repo_facts}}: Stack, layout, commands and conventions, as rough notese.g. pnpm monorepo: apps/web (Next.js 15), apps/api (Hono), packages/db (Drizzle)...
{{mistakes}}: Things agents keep getting wrong in this repoe.g. Runs npm install; hand-edits generated migrations; runs the whole e2e suite...

Example input

file_name: CLAUDE.md
repo_facts:
- pnpm workspaces. apps/web = Next.js 15 App Router. apps/api = Hono on Node 22. packages/db = Drizzle ORM + Postgres. packages/ui = shadcn/ui components.
- Unit tests: Vitest (`pnpm test`, or `pnpm vitest run path/to/file`). E2E: Playwright in apps/web/e2e, slow, needs `pnpm dev` running.
- Lint/format: Biome (`pnpm lint`, `pnpm format`). Typecheck: `pnpm typecheck` (tsc -b).
- Migrations: edit packages/db/src/schema.ts, then `pnpm --filter db generate` and `pnpm --filter db migrate`.
- Env vars in .env.local (never committed), template in .env.example.
mistakes:
- runs npm install, which creates package-lock.json
- hand-edits generated SQL files in packages/db/migrations
- runs the whole Playwright suite to check a one-line change
- copies shadcn component code by hand instead of using the CLI in packages/ui
- imports packages/db inside client components

4880

Generated Outputs (1)

3 hours ago

Claude

Opus 5.5

3 hours ago

Generated Output

markdown

CLAUDE.md

Overview

pnpm monorepo: Next.js 15 web app (App Router), Hono API on Node 22,
shared Drizzle/Postgres schema and shadcn/ui component package.

Commands

`bash
pnpm install # never npm/yarn
pnpm dev # web + api
pnpm vitest run path/to/file.test.ts # one unit test file
pnpm test # all unit tests
pnpm lint && pnpm typecheck # Biome + tsc -b
pnpm --filter db generate # after editing schema.ts
pnpm --filter db migrate
`

Where things live

• apps/web: Next.js pages, layouts, server actions

• apps/web/e2e: Playwright tests (slow, need pnpm dev running)

• apps/api: Hono routes and middleware

• packages/db/src/schema.ts: the only place schema changes are made

• packages/ui: shared shadcn/ui components

Conventions

• Env vars: add new ones to .env.example with a placeholder value.

• New UI primitives: pnpm dlx shadcn@latest add run inside packages/ui.

• TODO(owner): which file is the source of truth for API types shared with web?

Don't

• Don't use npm or yarn: it creates package-lock.json next to pnpm-lock.yaml.

• Don't edit files in packages/db/migrations: they are generated. Change schema.ts and regenerate.

• Don't run the full Playwright suite for small changes. Run one spec:

pnpm --filter web exec playwright test e2e/.spec.ts

• Don't copy shadcn component code by hand: use the CLI so imports and styles stay consistent.

• Don't import packages/db in files marked "use client": it pulls server code into the browser bundle.

• Don't commit .env.local.

Definition of done

• pnpm lint && pnpm typecheck pass.

• Unit tests for touched packages pass. Run the relevant e2e spec if UI flows changed.

• New env vars are documented in .env.example.

• Schema changes include the generated migration.

Left out, and why

• Code style rules: Biome already enforces them, and the agent runs pnpm lint.

• Architecture history and the reasons for choosing Hono: useful to humans, but spending that context on every task isn't worth it. Put it in docs/ and link it if needed.

• Deployment steps: agents shouldn't deploy from this repo. Add a line forbidding it if they've ever tried.

• The exact shadcn CLI package name: check that shadcn@latest matches the version your packages/ui was set up with.

Why it works

The opening line, "every line costs context on every task", is what keeps the file short. It pushes the model to cut generic advice, which agents ignore anyway. Asking for each mistake as a rule with its reason matters because agents follow rules better when they know why ("it pulls server code into the browser bundle"). Commands exactly as they're run, including how to run one test file, save the agent from guessing and running the whole suite. The TODO(owner) convention stops the model inventing facts about your repo.

When not to use it

It won't discover facts for you. If you only paste "it's a Next.js app", you'll get a thin file. When an agent can read the repo, it's often better to have it draft the file itself (Claude Code's /init, for example) and then apply these rules to trim it. Revisit the file when your tooling changes. A stale command in CLAUDE.md is worse than none.

Comments (0)

No comments yet. Be the first to share your thoughts!