# DESIGN.md vs AGENTS.md: what goes in each file

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

AGENTS.md carries a short block that points the agent to your design guide, and DESIGN.md holds the guide itself and its versions. Briefatto Board writes the block into AGENTS.md for you and keeps DESIGN.md as a separate, frozen file.

## What each file is for

|  | AGENTS.md | DESIGN.md |
| --- | --- | --- |
| Role | Instructions that coding agents read | Your project's design guide |
| Briefatto Board's part | A marked block with the pointer, written by `board install` and updated by `board freeze` | Authored prose plus a generated block of exact styles, stamped with a version by `board freeze` |
| Read by | The agents that read AGENTS.md, which [agents.md](https://agents.md) lists | Your agent, because the AGENTS.md block tells it to |

The same block is also written to CLAUDE.md.

## Questions and answers

### Can I put the design guide inside AGENTS.md?

Keep them apart. The AGENTS.md block is a pointer; the guide lives in DESIGN.md so that `board freeze` can version and validate it.

### Does Briefatto Board overwrite my AGENTS.md?

No. It writes a marked block between start and end comments and edits only that block.

### 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

- [CLAUDE.md vs DESIGN.md: what to put in each for Claude Code](https://briefatto.com/guides/claude-md-vs-design-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/)
- [Is DESIGN.md about architecture or visual design?](https://briefatto.com/guides/is-design-md-architecture-or-visual-design/)
- [What is DESIGN.md, and how do coding agents use it?](https://briefatto.com/guides/what-is-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://agents.md (checked 2026-11-21)
- https://code.claude.com/docs/en/memory (checked 2026-11-21)
- https://github.com/Briefatto/briefatto-board/blob/main/LICENSE
