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

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.

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.

# 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.

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.

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.