Writing Implementation Guidance with CLAUDE.md

1.What implementation guidance should contain

When Claude Code helps build a solution, the implementation guidance has two readers: the engineering team and Claude itself. In Claude Code, that guidance lives in CLAUDE.md, a plain markdown file that Claude reads automatically at the start of every session in its directory. This lesson covers that one mechanism. Guidance written for human engineering teams in other forms is a separate concern. The support documentation calls CLAUDE.md the briefing you would give a capable new teammate on their first morning: how the team works, what to avoid, and where the important pieces are.

The support article's content guidance is specific. Include commands for building, testing, linting and running locally, because Claude will run them and they have to be accurate. Include conventions, hard constraints such as "do not edit generated/", and the known gotchas that every new engineer runs into. The architecture itself should be described in three sentences: what the major pieces are and how they communicate. Leave out full API documentation, changelogs, anything obvious from the file tree, and aspirational rules the team doesn't actually follow. The table below is a separate list, taken from the Claude Code best-practices page, and the two lists overlap but are not identical.

Each instruction should be specific enough to check. "Run npm test before committing" works; "Test your changes" doesn't. Group related instructions under markdown headers and bullets, because organized sections are easier to follow than dense paragraphs. Keep each file under about 200 lines. Longer files use more context and reduce adherence, and importing other files doesn't help, since imported files also load at launch.

# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')

# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance

Sources12

2.Putting guidance at the right scope

Guidance works better when each piece sits at the level where it applies. Claude merges instructions from several locations, from broadest to most specific. Most teams only need the project-root file, committed to git so that the whole team benefits.

In larger systems, divide the guidance the way the architecture is divided. The root CLAUDE.md holds instructions that apply everywhere, such as coding standards and commit conventions. A per-subdirectory CLAUDE.md holds conventions for that area's stack: one per package in a monorepo, or one per subsystem such as src/db/ or src/api/ in a large single tree. With this layout, directory owners maintain their own conventions, and the instructions are versioned alongside the code they describe. The alternative is a path-scoped rule in the central .claude/rules/ directory, which loads when Claude works with a file matching the rule's paths: glob. Choose it when you want all conventions in one place, or when the same rule applies to many scattered paths.

Run package scripts from the package directory, not the monorepo root.
Prefix commit subjects with the package name, for example `api: add rate limiting`.
Never edit files under packages/*/generated/. Run `npm run codegen` in the package instead.

Sources32

3.Keeping guidance accurate over time

Implementation guidance goes out of date as the code changes, and stale guidance does active harm. The support article says outdated instructions are worse than none. Upkeep starts with the first draft. Run /init and Claude explores the codebase and drafts a CLAUDE.md covering build commands, test commands, a structure overview and the conventions it detects. You then review the draft, remove anything inaccurate, and commit it.

After the first draft, update the file when something specific happens. If Claude gets something wrong twice, a rule is missing, so add one line. When conventions change, for example a new framework, test runner or set of lint rules, update the file to match. Do a quarterly skim to delete stale content. Watch for contradictions as well: when two instructions conflict, Claude may pick one arbitrarily, so periodically review the root file, nested files and .claude/rules/ together.

The large-codebase guide adds team-level habits. Review CLAUDE.md edits in pull requests like any other documentation change, so the conventions keep pace with the code. Revisit the file after major model releases, because a rule written to work around an older model's limitation can become overhead once a newer model handles the case on its own. A Stop hook can also review the session transcript and propose CLAUDE.md updates while the gap it found is still fresh.

Sources123

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Splitting a long CLAUDE.md into imported files reduces how much context it uses.Why is that wrong?

   Imports make a long file easier to organize, but imported files also load at launch. To load part of the guidance only when it's needed, move it into path-scoped rules or subdirectory files.

   Covered in What implementation guidance should contain

2. 2.Every CLAUDE.md in the repository is read at session start, so subdirectory guidance is always in context.Why is that wrong?

   Subdirectory CLAUDE.md files load on demand, when Claude reads files in that directory, not at session start.

   Covered in Putting guidance at the right scope

3. 3.Outdated guidance is harmless, so stale rules can stay until someone gets around to cleaning up.Why is that wrong?

   Stale instructions actively mislead, and the vendor says they are worse than having none. Delete them during regular reviews.

   Covered in Keeping guidance accurate over time