Notes7 min read

Write your taste down: a DESIGN.md your agents follow

Pick three to five examples you admire, have the agent pull out the patterns, decide which are rules and which are preferences, and save them in DESIGN.md at the root of your project. Then point CLAUDE.md at it so every session reads it, and review new screens against it.

From the course · lesson 2.1

Every Claude Code session starts with a fresh memory. Whatever you told the agent yesterday about your fonts, your colors and the tone of your buttons is gone today unless it's written in a file the agent reads. Without that file, the agent falls back on its defaults, which Anthropic describes as drifting toward the safe middle of everything it has seen.

So you end up repeating yourself, or you stop noticing the drift. The way to get AI to follow your design taste is to write it down once.

In this course that place is a file called DESIGN.md. It's a plain Markdown file in the root of your project that describes how your product should look, read and feel, written as rules an agent can follow and you can check.

Pick model examples

Start with three to five examples of work you admire, and mix them on purpose. If all five come from the same kind of app, the patterns will describe that genre, not your taste. In a well-known study, people who saw artists' paintings mixed together learned the styles far better than people who saw one artist at a time (the taste gap covers it).

Include at least one thing that isn't software. For Kudos, a made-up testimonial app, the set includes a handwritten thank-you card, a magazine pull quote and a museum wall label. You'll see them again in the template below.

For each one, write a line about what you admire, in words you could point at. "The quote is set three times larger than anything else" is useful. "It feels premium" is not.

Have the agent pull out the patterns

Next, ask the agent to do the close reading. Give it screenshots or links and a prompt like this:

Here are four examples I admire, with a note on each. Find the
patterns they share across type, color, spacing, layout, motion and
tone of voice. For each pattern, name which examples show it and how
confident you are. Don't suggest anything that isn't in the examples.

Katie Parrott at Every did a version of this when she wrote her publication's editorial standards down for Claude. She gathered the pieces everyone pointed to as the house style and asked the model what they had in common. The model came back with structural patterns, such as how the strongest pieces open and how they end. Her summary of the experience is worth keeping: "When you can teach taste to a machine, you're forced to make it legible for yourself."

Rules or preferences?

The agent will return a long list. Most of the value comes from sorting it.

Parrott describes the same step. To make the editor work for a whole team, she had to separate her own preferences from the publication's values, and decide which instincts deserved to become rules for everyone. You're doing the same thing for your product.

  • A rule is a must. Breaking it is a bug. It's specific enough that someone could check it.
  • A preference is a default. An agent may break it if it says which one and why.

One test sorts most items: would I reject a screen for breaking this? If yes, it's a rule. If you'd only sigh, it's a preference.

InstinctRule or preferenceWhy
Body text at least 16pxRuleEasy to check; smaller hurts reading
Customer's words come before stars or logosRuleIt's the point of the product
Corners rounded at 8pxPreferenceNice, but a sharp corner wouldn't make you reject a screen
Motion kept to short fadesPreferenceFine to break for a moment that earns it

Then cut. Claude Code's own docs suggest keeping its instruction file under about 200 lines, because longer files take up more of the agent's attention and get followed less reliably. They also advise writing instructions concrete enough to verify, such as an exact indentation width instead of a request for tidy formatting. The design version is "Body text at least 16px" rather than "Readable type."

A starter DESIGN.md

Here's a complete starter file, filled in for Kudos. Copy it, then replace every line with your own.

# Kudos design rules

## What Kudos is
Kudos helps freelancers, coaches and small businesses collect
testimonials from their customers and show them on their own sites.

## The feeling
A thank-you card, not a review site. Calm, warm and personal.
The customer's words are always the hero.

## Rules (must follow)

### Type
- Quotes: Fraunces, at least 24px on the testimonial wall.
- Interface text: IBM Plex Sans. No other font families.
- Body text at least 16px, line height at least 1.5.

### Color
- Background #FAF7F2, text #1F1B16.
- One accent, #C2410C, only for the main action and active states.
- No gradients.
- Text contrast at least 4.5:1 (WCAG AA).

### Spacing and layout
- Spacing comes from this scale only: 4, 8, 16, 24, 32, 48, 64px.
- One main action per screen.
- On the wall: quote first, then name, then role. Never stars on top.

### Words
- Say "testimonial", never "review".
- Sentence case everywhere. Buttons start with a verb ("Send request").
- AI polish always shows the customer's original next to the edit.
  Nothing is published without the customer's approval.
- Never write sample testimonials that look like real customers.
  Placeholder content is labeled "Example".

## Preferences (defaults; break one only if you say which and why)
- Cards have 8px corners and no shadow.
- Motion: fades of 150 to 200ms, ease-out. No bounce.
- Empty states: one short, warm sentence and one action.
- Show a customer photo only if they agreed to it; otherwise initials.

## Avoid (the average)
- Inter, Roboto, Open Sans or Lato as the default font.
- Purple gradients on white.
- Three-card feature grids with icons.
- Vague claims like "Trusted by thousands".

## Examples we admire
- A handwritten thank-you card: one message, nothing else.
- A magazine pull quote: the quote is the design.
- A museum wall label: quiet text that doesn't compete.
- A plain receipt email: clear order, nothing extra.

## How to check a screen
1. Does it do its job, and is the flow obvious?
2. Does it pass every rule above? Note any that fail.
3. Which preferences did it break, and is the reason good?

Claude Code loads CLAUDE.md on its own, but it won't open DESIGN.md unless you tell it to. So add one line to your CLAUDE.md (the starter file /init creates, as in Claude Code for designers) to pull the design file in:

Design rules: @DESIGN.md
Read the rules before changing any UI. Rules are must-follow.
If you break a preference, say which one and why.

The @ tells Claude Code to load that file at the start of every session, alongside CLAUDE.md itself.

Design reviewStandby
A new screen is marked up against DESIGN.md, so every note points to a written rule instead of a feeling.

Check it's followed

Writing the file is half the job. Claude Code's docs are clear that instruction files are context the agent reads, not settings it's forced to obey. So check.

When the agent builds a new screen, ask for a review against the file, not against vibes:

Review this screen against DESIGN.md. For each rule, say pass or
fail and show the evidence. Then list any preferences you broke
and why.

Do your own pass in a sensible order. Julie Zhuo, who led product design at Facebook, advises critiquing function and flow before visuals and polish, and always pairing a criticism with a suggestion.

If a rule keeps getting broken, it's usually too vague, so rewrite it until a stranger could check it. Fully mechanical rules, like a banned font name, can later become hooks: small scripts that block a change automatically.

The file will never hold all of your taste, only the part you can put into words. That frees your attention for the rest. In lesson 2.1 of Chief of Agents, you write your own DESIGN.md with the Designer agent, sort its rules from its preferences, and then use it to cut a batch of fifty variants down to one.

Sources

Learn this inside Claude Code.

Join the waitlist for Chief of Agents. You'll get the free beginner's handbook and skills right away, and hear first when the course opens.

One email to confirm, then the handbook and skills. Unsubscribe anytime.

Keep reading

  1. 6 min read

    Your first Claude Code skill in 15 minutes

    How to make a Claude Code skill: pick a weekly chore, write it down once as a SKILL.md, and run it any time by typing its name.

  2. 7 min read

    Write the press release before you build

    How to know an idea is worth building: write the press release first. Amazon's PR/FAQ, a skeptic agent and the 11-star exercise.

  3. 6 min read

    Claude Code for designers: what it is, and why it isn't just for engineers

    What a coding agent does, why directing one is a design skill, and a safe first hour for designers new to Claude Code.

All notes →

© 2026 Chief of Agents · Notes · PrivacyIdeate. Build. Sell. You lead, the agents work.