How to use DESIGN.md with Aider

Aider is a terminal tool, and terminal tools reward being explicit. There is no hidden context here: the model sees the files you add and nothing else.

That is why the setup is slightly different from the IDE tools, and honestly a bit cleaner.

The read-only trick

Aider has a read option that adds files to context without making them editable. It is meant for reference material, which is exactly what a design contract is.

This matters more than it sounds. If you add DESIGN.md as a normal file, Aider can edit it, and an agent that is stuck will sometimes "fix" the constraint instead of following it. Read-only removes that option entirely.

The setup

Put DESIGN.md in your repository root, then create .aider.conf.yml in the same folder:

# Files loaded into every session, never edited
read:
  - DESIGN.md

# Extra instructions appended to the system prompt
chat-language: en

Then add the rules themselves. Aider supports a conventions file that you also load read-only:

read:
  - DESIGN.md
  - CONVENTIONS.md

And in CONVENTIONS.md:

# Conventions

## Design

DESIGN.md is the visual contract for this project and is already in context.

- Use only its color tokens, spacing scale, radius values, and type styles.
- Follow its component rules for states and density.
- Never introduce a font, shadow, or gradient it does not define.
- If a value is missing, stop and ask instead of choosing one.

Two read-only files, loaded automatically on every run. No flags to remember.

Doing it per session instead

If you would rather not commit a config file, the same thing works from the prompt:

aider --read DESIGN.md --read CONVENTIONS.md src/components/Button.tsx

I use the config file, because the one time you forget the flag is the time you get a purple button.

Verify it worked

Start Aider and run /tokens. Your read-only files should appear in the context breakdown with their sizes.

Then ask a question with a checkable answer:

What is the primary accent color in this project?

If the number matches DESIGN.md, you are set.

Common mistakes

• Adding DESIGN.md with `/add` instead of `/read-only`. Editable reference material tends to get edited.
• Loading a huge design document. Aider shows you the token cost of every file in context. A 40 KB design system is real money on every request, so trim to tokens and component rules.
• Forgetting `.aider.conf.yml` is per directory. Aider looks in the current folder and your home directory. Run it from the repo root.

What this means for you

Aider makes the cost of context visible, which is a good discipline. You can see exactly what your design contract costs per session and decide whether it earns its place.

In my experience it does, easily. Grab a documented system from the library, save it as DESIGN.md, and add two lines to a YAML file.