How to Teach Claude Code Your Test Conventions with CLAUDE.md

Write a project CLAUDE.md so every test, refactor, and fix Claude Code produces matches your team's conventions.

7 minBeginner

Visit Claude Code

If you find yourself correcting Claude Code the same way every session, the fix is a CLAUDE.md file. Claude reads it automatically and follows its instructions, so your test framework, naming rules, and review standards get applied without you repeating them. A good CLAUDE.md turns ad hoc reminders into durable defaults.

What you need

Claude Code in the repository
A clear idea of your test and refactor conventions
Write access to the repo root

Step 1: Create CLAUDE.md at the repo root

Place the file at the top of the project. Claude loads it as context for every session in that repo, so the rules apply to tests, refactors, and reviews alike.

zsh - my-app

$touch CLAUDE.md

$ls CLAUDE.md

CLAUDE.md

Step 2: Write the conventions that matter

Be specific and concrete. State the test runner, where tests live, how they are named, and any rules like no snapshot tests or always assert behavior, not implementation. Short, direct bullets work better than prose.

CLAUDE.md

# Project conventions

## Testing
- Use Vitest. Tests live next to source as *.test.ts.
- Test behavior, not implementation. No snapshot tests.
- Each test file resets shared state in beforeEach.
- Cover the failure path, not just the happy path.

## Refactors
- Show the diff before applying.
- Never change a public signature without flagging it.

## Reviews
- Flag leftover console.log and TODO before commit.

Step 3: Verify Claude follows it

Start a fresh session and ask for tests without restating any rules. The output should already use your framework, location, and naming, which confirms the file is being read.

Claude Code

You

Write tests for formatName in src/lib/name.ts.

Agent

Per CLAUDE.md I'll use Vitest, put the file at src/lib/name.test.ts, add a beforeEach reset, and include a failure-path case alongside the normal ones.

Conventions applied with no reminder in the prompt.

Step 4: Refine as you catch repeated corrections

Whenever you correct Claude twice for the same thing, add a line to CLAUDE.md. Over a few weeks the file becomes a precise spec of how your team writes and reviews code.

CLAUDE.md history

+ Use Vitest, tests as *.test.ts (week 1)

+ No snapshot tests (week 1)

+ Cover the failure path (week 2)

+ Show diff before applying refactors (week 3)

Keep it short and concrete

A focused list of rules Claude can actually follow beats a long document. Prune anything vague or aspirational; keep only rules you would enforce in review.

Result: a living CLAUDE.md that makes every new test and refactor match your conventions on the first try, so you stop repeating the same corrections.