Marcus Andrey Study
Ler em português Library

Framework · AI & design · 3 min read

Context files

Files that AI agents read automatically (CLAUDE.md, AGENTS.md, DESIGN.md) that hold your principles, design-system rules and conventions, so every session starts from your standards instead of generic defaults.

1Context file

Stable rules every session reads: users, principles, tokens, components, "never" rules.

Typically: CLAUDE.md, AGENTS.md, DESIGN.md
2Feature spec

What this feature must do: problem, users, flows, states, rules, acceptance criteria.

Typically: a spec in the wiki or repo
3Task prompt

The request for this one iteration, inside the conversation with the tool.

Typically: "Show three options"

Changes rarely → changes per feature → changes per iteration

Three layers of context for AI work; the context file is the layer that sets your standards for every session.

Use it when

  • Designers keep repeating the same instructions ("use our components", "no raw colours") in every prompt.
  • AI-generated prototypes look generic or off-system, even with good feature specs.
  • You are setting up a prototype repository or a shared agent setup for the team.

How to use it

  1. Know which file your tools read. Agents read a project instructions file at the start of every session: CLAUDE.md for Claude Code, AGENTS.md as an open format many agents support, and DESIGN.md (a Google Labs format: tokens plus written rationale) for the design system. As of late 2026 these conventions still change, so check your tool's docs. Output: the file names your team's tools use.
  2. Write only the stable rules. Who the users are, design principles, tokens, the component inventory, tone of voice, the accessibility baseline. Feature details belong in the feature spec, and one-off requests in the prompt. Output: a first draft, ideally under one or two screens long.
  3. Write the "never" rules explicitly. "Never hard-code colours, spacing or font sizes." "Never create lookalike components." "If a component doesn't exist, stop and list it as an open question." Output: a short "never" list.
  4. Point to the source, don't copy it. Reference the token names and the component library instead of pasting values that will go out of date. See Design tokens. Output: links and names instead of duplicated values.
  5. Version and review it like code. Keep the file in the repository, change it through review, and name an owner (often the design-system team). When an agent makes the same mistake twice, add a rule. Output: a versioned file with an owner and a change history.

Worked example

An internal operations platform with 6 product teams. Designers build code prototypes with an agent, and every prototype comes back with custom grey buttons and no empty states. The design-system designer adds a short CLAUDE.md to the prototype repository:

## Design rules
- Users are expert operators; prefer density and keyboard support.
- Use only components from @acme/design-system; never create lookalike components.
- Use design tokens (var(--ds-*)); never hard-code colours, spacing or font sizes.
- Every list view needs empty, loading, error and large-data states.
- Accessibility baseline: WCAG 2.2 AA; visible focus; no colour-only status.
- If a needed component doesn't exist, stop and list it as an open question.

The next prototypes use library components and include all four list states. When an agent later invents a "chip" component, the team adds one more line instead of correcting it by hand each time.

Watch out for

  • A context file that tries to hold everything. Long files bury the rules that matter. Keep feature details in specs and link to deeper docs.
  • Vague rules. "Follow our design system" gives the agent nothing to check. Name the library, the token prefix and the exact rule.
  • Copied values that drift. Hex codes pasted into the file go stale when the tokens change. Reference the token names instead.
  • Nobody owns it. An unowned file slowly fills with conflicting rules. Review changes like code.

Template

Copy this into CLAUDE.md, AGENTS.md or DESIGN.md and fill it in for your product.

# Design context: <product name>

## Users
- Who they are, what they do all day, what they need (e.g. density, keyboard use)

## Principles
- <principle 1>
- <principle 2>

## Design system
- Components: only from <library name>
- Tokens: use <token prefix>, see <link to token docs>
- Patterns: <link to pattern tiers / usage rules>

## Accessibility baseline
- WCAG 2.2 AA; visible focus; no colour-only status

## Never
- Never hard-code colours, spacing or font sizes
- Never create lookalike components
- Never use real customer or personal data in mock data

## When unsure
- Stop and list the open question instead of inventing a solution

Owner:            Last reviewed:
Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close