CLAUDE.md for designers: turn Claude Code into a design partner

Most product designers using Claude Code spend the first ten minutes of every session re-explaining the same things: who the product is for, which components already exist, what the brand actually sounds like, and which patterns are explicitly off-limits. That repetition is not just expensive in tokens—it is the reason AI output keeps drifting toward generic SaaS templates instead of the product you are actually trying to ship. I open-sourced a CLAUDE.md template for product designers to fix that. It turns Claude Code from a clever autocomplete into a design partner that loads your taste, your rules, and your anti-patterns before the first prompt is ever typed.

What CLAUDE.md actually is, and why designers should care

CLAUDE.md is the persistent context file Claude Code reads at the start of every session. It sits at the root of your project, gets loaded automatically, and stays in scope for the entire conversation. Think of it as the agent’s onboarding doc—except instead of being read once and forgotten, it gets re-read every time the agent boots. The equivalent in other tools is AGENTS.md for Cursor and Codex; the file name varies, the function is identical: structured, opinionated context that the agent does not have to be reminded of.

For engineers, the pattern is familiar. CLAUDE.md files in the wild are dense with build commands, deploy hooks, test runners, and folder conventions. That works for engineering because the work product is mostly verifiable code. Product design is different. The signal is taste, hierarchy, interaction quality, content tone, and judgment about when to break a pattern. None of that lives in a package.json. If you want AI to ship work that looks designed, you have to encode the design layer in the same place engineering encodes its layer—and most designers have not done that yet.

This is the same lens I covered in AI agent infrastructure beyond prompt engineering: individual prompts are the smallest unit of leverage. The infrastructure around the prompt—skills, scripts, persistent memory—is where the compounding returns live. CLAUDE.md is the persistent-memory slot for design judgment.

Why most CLAUDE.md files fail product design work

Walk into any AI-first codebase and you will find a CLAUDE.md. Read it carefully and you will notice what is missing: visual hierarchy, density rules, layout intent, content voice, accessibility floors, brand-safe color usage, and the specific patterns this product avoids on purpose. The file was written by engineers, for engineers. It produces code that lints, tests, and deploys—and looks like every other AI-generated SaaS app on the internet.

That visual sameness is not a model problem. It is a context problem. When an agent is asked to “build a settings screen” without design context, it pattern-matches against the most common shape of a settings screen in its training data: card, header, toggles, save bar. The output is technically correct and visually anonymous. The only way to push it toward your product is to give it the design decisions up front—what density, what typography scale, what the empty state looks like, which interaction patterns you have explicitly rejected, and what “good” actually means for this surface.

The failure mode I see most often is designers treating CLAUDE.md as optional documentation. It is not documentation. It is the operating contract between you and the agent. If you do not write it, the agent writes one for itself based on whatever it has seen most. That default is almost never what your product needs.

CLAUDE.md is not documentation. It is the operating contract between you and the agent — and if you do not write it, the agent writes one for itself.

What does a designer’s CLAUDE.md actually need to contain?

Seven blocks. Each one maps to a specific failure mode in AI-assisted design output. The template ships with all of them; the work is filling them in with answers that are true for your product, not generic ones.

1. Project context. Product type, audience, primary user tasks, and the non-negotiable principles that shape every decision. This is the section that tells the agent what kind of product it is working on. “B2B SaaS for finance teams—density matters, data legibility is non-negotiable, marketing-style hero patterns are wrong here” is infinitely more useful than “a web app.” The first 30 lines of the file shape behavior the most; do not waste them on platitudes.

2. Hard rules. Things the agent must never do. “Never use arbitrary Tailwind values—always reference theme tokens.” “Never add a hover state without a focus-visible equivalent.” “Never invent a new component when an existing one can be composed.” Hard rules are the floor. They prevent the worst categories of drift without requiring you to police every interaction.

3. Preferences. Things the agent should default to when there is no explicit instruction. Spacing scale, type ramp, motion easing, copy voice, error tone, empty-state pattern. Preferences are softer than rules—they bend when context demands it—but they keep output inside your visual grammar by default.

4. Anti-patterns. This is the block most designers forget, and it is the one with the highest leverage. AI defaults toward the most common visual idioms in its training data: card-heavy dashboards, gradient hero sections, three-column feature grids, “modern SaaS” type scales. If your product is dense, technical, or deliberately uncomfortable, you have to name those defaults and rule them out explicitly. “We do not use card-based dashboards.” “We do not use hero gradients.” “Do not propose marketing-style layouts inside the product.” The agent will not infer your refusals from your principles—you have to write them down.

5. Success criteria. Outcome-oriented checks the agent applies before declaring work done. Accessibility floor (WCAG AA), responsive behavior, keyboard navigation, content variability (long copy, missing data, error states), and any product-specific gates. Success criteria turn the agent from “generated something plausible” into “verified it meets the bar.”

6. Interactive intake. A short, scripted onboarding the agent runs when you start a project where context is missing. This is what makes the template usable on day one of a new repo: the agent asks five to ten targeted questions—product, audience, stack, primary surfaces, design system status—and writes the answers into CLAUDE.md and supporting docs. No more staring at a blank file wondering what to put in it.

7. Routing to deeper docs. A pointer table that tells the agent where to look when it needs more detail. docs/design-system.md for tokens, components, and spacing. docs/ux-principles.md for flow, hierarchy, and progressive disclosure rules. docs/intake-workflow.md for the interactive setup itself. The root file stays short; the depth lives in the docs.

These seven blocks are the spine of the template. Everything else—the example app and dashboard scoped files, the supporting docs—is there to keep the root prompt focused while still giving the agent a path to deeper context when a task warrants it.

Progressive disclosure: keeping the root prompt short and the docs deep

The single most common failure I see with CLAUDE.md is bloat. Designers who learn the pattern keep adding to the root file until it is 800 lines of mixed rules, preferences, color values, component APIs, and product trivia. At that size, the agent loses the signal in the noise—and you pay the token cost on every single session.

The fix is progressive disclosure. Keep the root CLAUDE.md under 200 lines. Move depth into supporting documents the agent loads only when relevant.

The template ships with three:

• docs/design-system.md — tokens, components, layout density, states, accessibility patterns. Loaded when the agent is building or modifying UI.
• docs/ux-principles.md — flow design, hierarchy, interaction quality, progressive disclosure rules, AI output review checklist. Loaded when the agent is making product decisions, not just rendering them.
• docs/intake-workflow.md — the interactive onboarding script. Loaded once per new project.

You can also scope CLAUDE.md files by directory. The agent respects the nearest relevant CLAUDE.md, so a /app/CLAUDE.md overrides the root for frontend work, and /app/dashboard/CLAUDE.md overrides both inside the dashboard surface. This is how you encode that the marketing site uses one density and type scale and the analytics dashboard uses another—without forcing every rule into one file.

This is the same operating model behind portable design systems for agentic workflows: structured, scoped, versioned context that survives tool changes and team turnover. Your CLAUDE.md is the design-system layer for the AI agent itself.

Interactive intake: a starter prompt that adapts to your product

The other failure I see is the empty-file problem. Designers download a template, open CLAUDE.md, and stare at the headings. Filling it in feels like writing a brand book from scratch.

The template solves this with an interactive intake prompt. Paste the contents into Claude and start with one of two messages:

Use this as an interactive setup prompt. First infer what you can from
this repository, then ask only for missing information that affects the plan.

Or, if there is no repository yet:

Use this as an interactive setup prompt. I want to answer a short guided
intake instead of having you inspect a repository.

The agent then does the work it is best at: reading what it can, asking only about the gaps that change the plan, and producing a draft CLAUDE.md plus a list of files to create or update. You review the plan before any code or content lands. This is the same discipline behind spec-driven development for designers in the age of AI: you specify intent, the agent surfaces gaps, you align before production. CLAUDE.md is just the persistent, project-level version of that contract.

The intake is not a one-time event. As the product matures and patterns drift, you re-run targeted portions of it—“add an anti-patterns block based on the last three reviews where AI output missed the mark”—and the file evolves with the work. The file is alive.

What changes when product designers ship this layer

The behavioral shift is concrete and shows up within the first few sessions.

Four shifts you feel within a week

Output starts on-brand

The agent’s first draft of a screen, component, or content block looks like your product, not a generic template. Review cycles move from color values and spacing to hierarchy and storytelling.

Handoffs get cleaner

Engineering reads the same CLAUDE.md the agent reads. Cross-functional context becomes a shared file, not a Slack thread. Disagreements about “what we said the pattern was” disappear because the pattern is in version control.

Junior collaboration gets safer

A junior designer or PM can ask the agent for a draft and trust that the output respects the system. You stop being the bottleneck for “is this on-brand?” because the system answers most of those questions before the work reaches you.

Anti-patterns stop reappearing

Generic dashboards, gradient heroes, marketing patterns inside the product — the drift categories you used to flag every other review stop landing in the work because the agent rules them out before generating.

This is the practical version of the principle I argued in AI-assisted design workflows that actually work: AI is a multiplier on intent that is well-specified, and CLAUDE.md is where that intent lives across every session. It is also the enablement model from shipping landing pages with Claude Code and GitHub — distributed contribution inside design-led guardrails.

For founders, the visible effect is speed-to-market without brand fragmentation. For VPs, it is delivery consistency across an AI-assisted team. For designers, it is the realization that the agent can finally be trusted with the parts of the job that used to require constant supervision—and that the time saved goes back into the parts of design that still demand human judgment.

How to adapt this template for your team in one afternoon

You do not need a quarterly initiative to ship this. The full adoption fits in a focused afternoon.

1. Clone the template into the root of your project. Drop in CLAUDE.md and the docs/ folder. The example scoped files under examples/ are starting points—copy them into the matching surfaces only where you want different behavior.

2. Rewrite the first 30 lines. Replace the generic project overview with your actual product type, audience, primary user tasks, design constraints, and the three or four non-negotiable principles your work is built on. Be specific. “B2B observability for SRE teams; density and data legibility win over visual polish” beats “we build great products.”

3. Extract hard rules from what you already have. Walk your design system docs, critique notes, and recent PR reviews. Anything you have said more than twice—“never use arbitrary spacing values,” “all components ship with focus states,” “error messages lead with the action, not the apology”—is a hard rule. Pull it into the file verbatim.

4. Add anti-patterns as drift appears. Do not try to predict every failure mode on day one. After the first week of AI-assisted work, log the categories of output you rejected. Those rejections become the anti-patterns block. The list grows fastest in the first month and stabilizes after that.

5. Layer scoped CLAUDE.md files where surfaces diverge. Marketing site, product app, internal dashboard, admin tooling—if the design rules are meaningfully different, give each surface its own scoped file. The root file holds what is shared; the scoped files hold what is local. This is the same architecture that keeps real design systems coherent across multiple products, including the multi-surface work in the Peridio case study.

By the end of an afternoon you will have a CLAUDE.md that is opinionated, project-specific, and ready to load on every session. The compounding starts immediately. The rest is maintenance—prune what stops being true, add what you keep repeating, evolve the file as the product evolves.

The full template, supporting docs, and example scoped files are open-source on GitHub: claude-md-product-design-template. Fork it, rewrite the first 30 lines for your product, and ship the AI operating layer your team has been missing.

Key Takeaways

• CLAUDE.md is the persistent context Claude Code loads every session—if you do not write the design layer into it, the agent fills the gap with generic defaults from its training data.
• A designer’s CLAUDE.md needs seven blocks: project context, hard rules, preferences, anti-patterns, success criteria, interactive intake, and routing to deeper docs.
• Anti-patterns are the highest-leverage section and the one most designers skip—name the visual defaults you reject explicitly so the agent stops proposing them.
• Use progressive disclosure: keep the root file under 200 lines and push depth into docs/ and scoped per-directory CLAUDE.md files for product, marketing, and internal surfaces.
• The full open-source template ships with an interactive intake prompt that turns the empty-file problem into a guided onboarding the agent runs against your repository.