Applying Coding Rules and Design Rules Simultaneously to AI Agents — How to Use CLAUDE.md and DESIGN.md Together for Claude Code Team Setup

When using AI coding agents as a team, you're bound to encounter this situation at least once. An AI whips up a new component in no time — the code style is perfect, but the button color is some completely off-brand blue. Or the reverse: the design looks great, but the code is full of .then() chains instead of async/await. At first, I thought writing longer prompts would fix it. But no matter how detailed I got, fixing one side kept breaking the other.

The solution turned out to be far more structural than I expected. By specifying coding rules in CLAUDE.md and design rules in DESIGN.md separately, then committing both files to Git, the entire team shares the same AI behavior baseline. Since Google open-sourced the DESIGN.md format under Apache 2.0 in April 2026, interest in this approach has been growing rapidly.

This is particularly well-suited for teams using web frontend stacks like Next.js + Tailwind CSS. If you're more backend-focused, you might want to jump straight to Example 2 (Modular Rule Structure).

Core Concepts

CLAUDE.md — The Coding Constitution for AI Agents

CLAUDE.md is a markdown file that Claude Code automatically reads at the start of each session. By capturing coding rules such as architecture decisions, build commands, test patterns, and naming conventions, the AI operates according to those standards with every request. Simply placing it in the project root and committing it to Git means the entire team shares the same AI persona.

For those new to Claude Code — CLAUDE.md is like a "team rulebook" sent to the AI. Every time a session starts, the AI reads this file and operates within those rules.

The configuration files follow a priority hierarchy:

~/.claude/CLAUDE.md          ← Personal global defaults (applied to all my projects)
./CLAUDE.md                  ← Team-shared project rules (committed to Git)
./CLAUDE.local.md            ← Personal local overrides (.gitignore'd)
./.claude/rules/*.md         ← Modular team rules (files split by domain)

Prompt Drift — The phenomenon where an AI agent gradually forgets its initial instructions or drifts toward different patterns during a long conversation. The longer and more complex the instructions, the harder it becomes for the AI to consistently follow rules near the bottom. Since CLAUDE.md is loaded at the start of every session, it helps structurally suppress this phenomenon.

DESIGN.md — The Design System Specification That AI Agents Read

DESIGN.md is a format specification open-sourced by the Google Stitch team under the Apache 2.0 license in April 2026. It describes a brand's visual identity in a markdown structure that AI agents can directly consume. The key is storing design tokens in machine-readable YAML format while including plain-language explanations of why each value is used.

As of April 2026, this is still an alpha-stage format and the spec is subject to change. The current standard structure consists of 9 sections:

Of the 9 sections, I initially left out Section 9 (Design Guardrails) — and only added it after watching the AI decorate headers with warning colors. Specifying what not to do, like "only use white text on blue-family CTAs," helps the AI recognize its own boundaries, and this turns out to be far more effective than I expected.

Practical Application

Example 1: Basic CLAUDE.md + DESIGN.md Integration

This is the simplest integration approach. In the CLAUDE.md file, you declare that DESIGN.md will be referenced and set the criteria for design-related decisions.

## Design System
- Always reference DESIGN.md when creating components to determine colors, typography, and component styles
- Do not use arbitrary values for design tokens; use only values defined in the tokens section of DESIGN.md
- When creating new components, always check the "Design Guardrails" section of DESIGN.md
- Do not hardcode color values; reference them via CSS variables or Tailwind token class names
 
## Coding Rules
- TypeScript strict mode required
- Use async/await (no Promise.then() chains)
- Components: Server Component by default, Client Component only when interaction is needed
- Testing: Unit tests required for new utility functions
- 2-space indentation
 
## Build Commands
- Build: `pnpm build`
- Test: `pnpm test`
- Lint: `pnpm lint`

With this setup, Claude Code consumes both files simultaneously when generating components. Say "create a button component" and you get code that follows the TypeScript + Server Component rules from CLAUDE.md while directly reflecting the color-primary and typography tokens from DESIGN.md.

If the CLAUDE.md above tells the AI "what not to use," the DESIGN.md below provides the concrete values the AI will actually reference. The two files work as a pair. The Color Palette & Roles section of the DESIGN.md file can be written as follows:

# YAML format — indentation determines structure
 
color_palette:
  tokens:
    color-primary: "#0F62FE"
    color-secondary: "#6929C4"
    color-surface: "#F4F4F4"
    color-text-primary: "#161616"
    color-danger: "#DA1E28"
    color-text-on-primary: "#FFFFFF"
  roles:
    color-primary: "For interactive elements and CTAs only. Do not use for decorative purposes"
    color-danger: "For error messages and delete confirmation UIs only. Do not use for emphasis or decoration"
    color-surface: "Use only as background color for cards, panels, and background containers"
 
design_guardrails:
  - "Do not use arbitrary color values not defined in tokens"
  - "Do not use color-primary and color-secondary together in the same component"
  - "Do not use font sizes smaller than 14px (accessibility standard)"

Example 2: Modular Rule Structure by Team Domain

As a project grows, cramming all rules into a single CLAUDE.md creates problems. The longer and more complex the rules become, the harder it is for the AI to consistently follow rules near the bottom — and when frontend, backend, and security teams all modify the same file, merge conflicts pile up. The .claude/rules/ directory pattern solves this problem.

project root/
├── CLAUDE.md              ← Common architecture rules, build commands (whole team)
├── DESIGN.md              ← Design tokens, UI rules (whole team)
└── .claude/
    └── rules/
        ├── frontend/
        │   ├── react.md       ← Owned and managed by the frontend team
        │   └── styling.md     ← Details on applying the design system
        ├── backend/
        │   ├── api.md         ← Owned and managed by the backend team
        │   └── database.md
        └── security.md        ← Owned and managed by the security team

How files under .claude/rules/ are loaded may vary by Claude Code version, so it's recommended to check the official documentation for the version you're using. The frontend team manages only react.md and styling.md, while the backend team handles only api.md and database.md. This structure allows each team to evolve their domain independently without worrying about merge conflicts.

The .claude/rules/frontend/styling.md file can be structured like this:

## Tailwind CSS Token Mapping
- Color tokens from DESIGN.md are mapped 1:1 to theme.colors in tailwind.config.ts
- Color classes must use semantic names in the format `bg-primary`, `text-primary`
- Arbitrary colors (`bg-[#0F62FE]`) are prohibited — reference via Tailwind token class names
 
## Component Style Rules
- Button variants: only four allowed — primary, secondary, ghost, danger
- Spacing: based on a 4px base grid (4, 8, 12, 16, 24, 32, 48px)
- Responsive: mobile-first, use sm/md/lg/xl breakpoints

Example 3: Enforcing Design Tokens at the CSS Level via tailwind.config.ts

Honestly, this approach gave me the most confidence in practice. Even if the AI forgets the rules due to prompt drift, it gets filtered again at the CSS level. If the DESIGN.md above tells the AI "use only these values," this configuration physically enforces that at the CSS framework level.

// tailwind.config.ts — direct mapping of DESIGN.md tokens
import type { Config } from "tailwindcss";
 
const config: Config = {
  theme: {
    extend: {
      colors: {
        // 1:1 correspondence with DESIGN.md color_palette.tokens
        primary: "#0F62FE",
        secondary: "#6929C4",
        surface: "#F4F4F4",
        "text-primary": "#161616",
        danger: "#DA1E28",
      },
      fontFamily: {
        sans: ["IBM Plex Sans", "sans-serif"],
      },
    },
  },
};
 
export default config;

Of these three layers, the third one had the most noticeable real-world impact. No matter how many mistakes the AI makes, arbitrary colors like bg-[#FF0000] aren't in the Tailwind config, so they get caught at the lint stage. Here's how the three layers each enforce rules at a different point:

• DESIGN.md: Prompt level — the agent recognizes the rules before generating code
• CLAUDE.md: AI coding level — directly instructs against hardcoding arbitrary values
• tailwind.config.ts: CSS framework level — physically blocks any colors outside the tokens

Pros and Cons

Pros

Cons and Caveats

Tribal Knowledge — Know-how and rules shared only implicitly within a team. Knowledge that isn't documented and that new team members can only acquire through experience. CLAUDE.md + DESIGN.md converts this into an explicit form that machines can enforce.

The Most Common Mistakes in Practice

1. Writing abstract color descriptions in DESIGN.md — In a rush, you'll be tempted to type "bright blue." That's the dangerous moment. The agent may choose a different value each time it encounters "bright blue." Always use specific hex codes like "#0F62FE" to get consistent results.

2. Cramming all rules into a single CLAUDE.md file — The longer and more complex the rules become, the harder it is for the AI to trust rules near the bottom. As the team grows, complaints like "why aren't my rules being followed?" tend to surface — and the cause is almost always that the rule file has gotten too long. Distributing by domain into .claude/rules/ helps.

3. Updating DESIGN.md without syncing tailwind.config.ts — The AI writes code based on DESIGN.md, but the actual styles render based on the Tailwind config, creating a mismatch. Getting into the habit of bundling both files in the same commit helps. A single git add DESIGN.md tailwind.config.ts is all it takes.

Closing Thoughts

Once you commit both CLAUDE.md and DESIGN.md to Git together, you'll notice a marked reduction in the style inconsistencies that kept getting flagged in code reviews.

Here are 3 steps you can take right now:

1. Create a CLAUDE.md in your project root. Just three things are enough to get started: build commands (pnpm build, pnpm test), architecture principles (TypeScript strict, Server Component first), and naming conventions. Aim for under 300 lines.

2. For DESIGN.md, go to VoltAgent/awesome-design-md and grab a template from the brand closest to your project (Stripe, Linear, Notion, etc.), then just swap out the color hex codes and font families. With over 55 brand examples available, it's a great reference.

3. Place both files in the root, then commit with the command below — and from the next git pull, the entire team will share the same AI behavior baseline.

git add CLAUDE.md DESIGN.md
git commit -m "chore: initial AI agent coding and design rules setup"

References

• Google Stitch's DESIGN.md Open Source Announcement | Google Labs Blog
• Official DESIGN.md Format Spec | GitHub google-labs-code/design.md
• DESIGN.md Collection by Brand | GitHub VoltAgent/awesome-design-md
• Claude Code Best Practices Official Docs | Anthropic
• Exploring the .claude Directory | Claude Code Official Docs
• DESIGN.md Explained — The Format Reshaping How AI Builds UI | Department of Product
• Google Stitch + Claude Code Integration | MindStudio
• Comparing CLAUDE.md, AGENTS.md & Copilot Instructions | DeployHQ
• Claude Code Agent Teams Official Docs | Anthropic
• CLAUDE.md Best Practices | Builder.io
• Building Shared Coding Guidelines for AI Agents | Stack Overflow Blog
• How to Write a DESIGN.md File | Design Project Blog