CLAUDE.md

CLAUDE.md is the markdown file you place in your repo root that acts as a permanent design brief for Claude Code. It gets read first on every session before the model touches a single file. The concept exists because these agents have infinite courage and zero memory of how your team actually ships. Without it they reinvent buttons you already own and ship code that looks like it came from a different company.

You write it once like you are onboarding a ridiculously fast junior designer who asks too many questions. One line for what the repo is. Three adjectives for voice. Three phrases you never say. Exact paths to tokens and components. Forbidden patterns. What clean work looks like. Questions it must ask before proceeding. Review standards that include screenshots for any visual change. Every sentence you add is a sentence you never repeat in prompts again.

It is not a readme for humans. Readmes explain things to people. This file shapes behavior in a machine that codes at lightspeed but has the taste of a blank canvas. It is not a list of npm scripts or test commands although engineers stuff it with those. That misses ninety percent of the value for designers.

Do not confuse it with the system prompt you paste into a chat window. Those evaporate the moment the session ends. CLAUDE.md lives in the git history. It travels with the code. It gets stronger every time you update it with lessons from the last screwup.

Last month a designer shipped a full design system refactor in three days using nothing but a tight CLAUDE.md and the command line. She listed every existing component with one line descriptions. She banned hardcoded hex values and px spacing. She told it to update Storybook stories and keep tests green. The agent found every legacy button variant including the disabled one and swapped the focus ring token without being told twice.

A B2B analytics marketing site saw even bigger gains. The voice section said sharp skeptical numbers first. The clean work paragraph demanded small focused PRs and no new dependencies without asking. When the team requested a new hero section the agent used existing components and tokens on the first pass. Previous attempts without the file took four rounds of feedback and still felt off brand.

The fintech team added a specific rule. If you are about to add a new color stop and ask. Claude Code followed it religiously. It attached before and after screenshots to every visual PR per the review standards section. The file was updated twice in the first week as they learned its failure modes. After that it ran almost autonomously.

Use CLAUDE.md on any codebase you plan to touch for more than a few days especially design systems that span multiple repos or marketing sites that must stay consistent. It earns its keep the moment you stop repeating your rules in every prompt. Skip it on throwaway prototypes or brand new repos where the standards are still changing daily.

The tradeoff is clear. Spend one focused hour writing it well or waste days fixing sloppy outputs later. It will not save you if your codebase is already a mess with no tokens and no naming conventions. The agent will simply accelerate the chaos. Clean the foundation first then hand it the brief.

Your standards become the model's standards. The file compounds over time. What starts as a basic instruction set turns into institutional memory that outlives any single team member.

CLAUDE.md turns the agent from an eager intern into an extension of your own taste.