Writing custom CLAUDE.md rules

CLAUDE.md is the project context file that shapes how x (and Claude Code) behaves in your repository. It's read on every run and injected into the system prompt. There's no strict schema — it's freeform markdown — but some patterns work dramatically better than others.

Template

Start with this structure and customize for your project:

# Project context
This is a TypeScript monorepo using pnpm workspaces.
Main app is in apps/web. Shared packages in packages/.

# Tech stack
- Runtime: Node.js 22, TypeScript 5.4
- Framework: Next.js 14 (App Router)
- Database: PostgreSQL via Prisma
- Testing: Vitest + Playwright

# Conventions
- Use named exports, never default exports
- Prefer composition over inheritance
- All API routes go in src/routes/
- Tests live next to source: foo.ts -> foo.test.ts
- Components use PascalCase filenames

# Commands
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint
- Dev server: pnpm dev (port 3000)

# Rules
- NEVER modify files in /generated/ or /vendor/
- NEVER commit .env files or secrets
- ALWAYS run tests before suggesting a commit
- ALWAYS use server components unless client
  interactivity is explicitly required
- Keep PR descriptions under 500 words

Writing effective rules

Be specific, not aspirational

The model follows concrete instructions better than abstract principles.

• Good: "Use named exports, never default exports"
• Bad: "Follow best practices for module exports"
• Good: "Tests live next to source files: foo.ts → foo.test.ts"
• Bad: "Put tests in a logical location"

Use NEVER and ALWAYS

Absolute directives are unambiguous. "Prefer X" leaves room for interpretation. "ALWAYS use X" doesn't.

# Strong — the model will follow these
NEVER modify files in /generated/
ALWAYS run `npm test` before committing
NEVER use `any` type in TypeScript

# Weak — the model may ignore these
Try to avoid modifying generated files
It would be nice to run tests before committing
Prefer specific types over `any`

Include runnable commands

The agent needs to know how to build, test, lint, and run your project. Without commands, it guesses — and it guesses wrong in monorepos, custom toolchains, and non-standard setups.

Keep it concise

Every line of CLAUDE.md costs tokens. Remove anything the model can infer from the codebase itself. You don't need to explain what TypeScript is — just tell the agent your project's specific conventions.

Advanced patterns

Conditional rules

You can scope rules to specific directories or file types:

# Frontend rules (apps/web/)
- Use React Server Components by default
- Client components must have "use client" directive
- Styles use CSS Modules, never inline styles

# API rules (apps/api/)
- All endpoints return typed responses
- Use Zod for request validation
- Log every 4xx and 5xx response

Anti-patterns to forbid

If the model keeps making the same mistake, add an explicit rule:

# Known anti-patterns — do NOT do these
- NEVER use `fs.writeFileSync` — use the async version
- NEVER add `console.log` for debugging — use the logger
- NEVER import from `@internal/` packages in public API

Maintenance

Stale rules are worse than no rules. Review CLAUDE.md after:

• Major refactors that change project structure
• Dependency upgrades (new framework versions, new tools)
• When the agent repeatedly does something you don't want
• When onboarding new contributors (good time to document conventions)