# CLAUDE.md vs DESIGN.md: what to put in each for Claude Code

Updated 2026-11-21 · https://briefatto.com/guides/claude-md-vs-design-md/

CLAUDE.md carries your general instructions and a short pointer, and DESIGN.md holds the design guide. Briefatto Board writes that pointer into CLAUDE.md and AGENTS.md for you and keeps the guide in a versioned DESIGN.md.

## The split

- **CLAUDE.md:** your project's general instructions, plus the Briefatto Board block, which tells Claude Code to read `DESIGN.md` before visual work.
- **DESIGN.md:** the design guide, with authored prose and a generated block of exact styles, stamped with a version by `board freeze`.

With the guide out of CLAUDE.md, a brand change is one frozen, versioned file change, and `board diff v1 v2` shows it.

## Questions and answers

### Should I paste my colours and fonts into CLAUDE.md?

No. `board freeze` records exact styles from a render into DESIGN.md, so nobody copies them by hand.

### Does the pointer go into AGENTS.md as well?

Yes. The installer writes the same block to AGENTS.md and CLAUDE.md.

### Is Briefatto Board free?

Yes. It is open source under the Apache-2.0 licence and installs with `npx briefatto-board install`.

## Try it

```
npx briefatto-board install
```

Briefatto Board is free and open source under Apache-2.0: https://github.com/Briefatto/briefatto-board

## Related guides

- [DESIGN.md vs AGENTS.md: what goes in each file](https://briefatto.com/guides/design-md-vs-agents-md/)
- [Do I need DESIGN.md if I already have AGENTS.md or CLAUDE.md?](https://briefatto.com/guides/do-i-need-design-md-if-i-have-agents-md/)
- [How to make Claude Code follow your brand with DESIGN.md](https://briefatto.com/guides/how-to-use-design-md-in-claude-code/)
- [Does Claude Code read DESIGN.md automatically?](https://briefatto.com/guides/does-claude-code-read-design-md/)

## Sources

- https://github.com/Briefatto/briefatto-board/blob/main/src/board/standing.ts
- https://github.com/Briefatto/briefatto-board/blob/main/skill/briefatto-board/SKILL.md
- https://github.com/Briefatto/briefatto-board/blob/main/README.md
- https://code.claude.com/docs/en/memory (checked 2026-11-21)
- https://github.com/Briefatto/briefatto-board/blob/main/LICENSE
