Writing Your First CLAUDE.md

The fastest path to a working CLAUDE.md isn’t writing one from a blank page — it’s letting Claude Code draft an initial version by reading your codebase, and then editing that draft into something genuinely useful.

Step 1: Bootstrap From the Codebase

Claude Code can scan your project — package.json scripts, config files, directory structure, existing README — and draft a starting CLAUDE.md covering the commands and structure it can infer directly.

> /init

This produces a reasonable first pass: detected test/build/lint commands, an outline of the directory structure, and whatever conventions are visible from the code itself (a linter config, a formatter config, a consistent import style). It will not capture the things that live only in your head — architectural decisions, “why,” and the non-obvious gotchas — that part is on you.

Step 2: Prune the Generic

The generated draft will often include advice that’s true of nearly any codebase (“write clear, maintainable code,” “follow best practices”) — delete this. It costs context budget and tells the agent nothing it doesn’t already default to. Keep only what’s actually specific to this project.

Write clean, well-documented code following best practices.
Ensure good test coverage for all new features.
Run `npm test -- --coverage` before opening a PR — CI fails under 80% coverage.
Test files live next to the source file they test (`foo.ts` → `foo.test.ts`), not in a separate `__tests__/` tree.

The rewritten version is actionable and specific; the original was true of every codebase in existence and therefore added nothing.

Step 3: Add What Only You Know

This is the part scanning code can’t produce: architectural reasoning, historical context, and warnings.

## Architecture Notes

- `services/billing/` talks directly to Stripe's API — `services/payments/` is a
  legacy wrapper kept only for backward compatibility with the mobile app's old
  API contract. Do not add new functionality to `services/payments/`.
- The `utils/legacy-date-parser.ts` function has a known timezone bug that several
  downstream reports depend on for consistency — do not "fix" it without checking
  with the analytics team first.

This is the highest-value content in any CLAUDE.md: information that’s genuinely not recoverable from reading the code, because it lives in a decision someone made, a conversation that happened, or a tradeoff that isn’t visible in the diff.

Step 4: Add Commands You Actually Run

## Commands

- Dev server: `npm run dev`
- Run all tests: `npm test`
- Run one test file: `npm test -- path/to/file.test.ts`
- Type-check without building: `npm run typecheck`
- Format: `npm run format`

Precision matters here more than it might seem — an agent that knows the exact single-test-file command will iterate far faster than one that has to guess at flags or re-discover them by trial and error each session.

Step 5: Iterate Like You Would a Frequently-Used Prompt

Treat the first version as a draft, not a final artifact. After a session where the agent misunderstood something or made an assumption you had to correct, that’s a signal worth adding to CLAUDE.md — a quick way to do this mid-session is a shorthand note-taking convention some teams use (typing a note prefixed for later inclusion), reviewed and folded into the file afterward rather than edited live mid-task.

A Reasonably-Sized First Version

# Project: Acme Checkout Service

## Commands
- Dev: `npm run dev`
- Test: `npm test` (single file: `npm test -- path/to/file.test.ts`)
- Lint: `npm run lint`
- Type-check: `npm run typecheck`

## Conventions
- TypeScript strict mode — no `any`
- Named exports only, no default exports
- Early returns over nested conditionals

## Architecture Notes
- `legacy/` is scheduled for removal — do not add new code there
- Payment webhooks are idempotent by design; never assume single delivery

## Testing
- Test files live next to source (`foo.ts` → `foo.test.ts`)
- CI requires 80%+ coverage on changed files

Short, specific, and actionable — this is a far more useful file than a much longer one padded with generic advice.

Common Mistakes

Accepting the /init-generated draft without editing it. The auto-generated version captures what’s mechanically inferable, not what actually matters most — the architectural notes and gotchas you’d add manually are usually the highest-value part of the whole file.

Writing an exhaustive file on day one instead of letting it grow. A CLAUDE.md that tries to anticipate every future need up front is guessing — it’s more effective to start lean and add specific, concrete guidance as real friction surfaces in actual sessions.

Forgetting to commit it. A CLAUDE.md that only exists on one person’s machine doesn’t help the rest of the team — check it into git at the project root so every session, from everyone, benefits.

Frequently Asked Questions

How long should a first CLAUDE.md be? Shorter than you’d expect — a tight, high-signal file of a few dozen lines usually outperforms a sprawling one, since every line costs context budget on every session regardless of relevance to the current task.

Should I write it alone or with the team? Both work, but a file reviewed by the team (the same way a README or CONTRIBUTING.md would be) tends to capture more genuinely shared conventions than one person’s individual assumptions about “how we do things.”

What if /init isn’t available or I want to start from scratch? Nothing about CLAUDE.md requires the bootstrap step — a hand-written file following the same structure (Commands, Conventions, Architecture Notes) works identically; /init is a convenience, not a requirement.

Summary

Bootstrap with /init, aggressively prune anything generic, then add the architectural context and gotchas that only exist in your team’s collective memory — that combination, kept lean, is what separates a CLAUDE.md that actually improves every session from one that’s just noise the agent has to read past.