Every AI tool I use - Claude, Cursor, GPT - writes copy like a generic SaaS company. "Unlock your potential." "Seamlessly integrate." "Revolutionize your workflow." It sounds like nobody and everybody at the same time.
The reason is simple. These tools have zero brand context. They don't know how your brand sounds, what words you avoid, what your color palette is. So they default to the same bland, safe, corporate tone.
The fix most teams use is pasting brand guidelines into every prompt. A paragraph here, a tone description there. It works until it doesn't - someone forgets, someone pastes the wrong version, someone joins the team and doesn't know the guidelines exist.
I wanted something better. One file. One source of truth. Something that lives in the repo and any tool can read.
What brand guides actually are
A typical brand guide is a 50-page PDF. Strategy section. Voice and tone. Color palette. Typography. Photography direction. Do's and don'ts. Maybe a manifesto.
Most of it is useful exactly once - when the designer presents it to the team. After that, it lives in a Google Drive folder nobody opens. The people writing copy don't check it. The developer building the landing page has never seen it. The AI agent generating social posts definitely hasn't.
The information is good. The format is wrong. A PDF in a shared drive is not accessible to the tools that actually produce brand content.
One file, three layers
brand.md is a markdown file with YAML frontmatter. It lives in your project root next to README.md and CLAUDE.md. Three layers, each building on the previous one:
Strategy - why the brand exists, what it's not, where it stands in the market, the guardrails.
Voice - how the brand speaks. Tonal rules, phrases it owns, a "We Say / We Never Say" table. This is the layer AI tools use most.
Visual - colors with hex codes and usage rules, typography, design direction.
The frontmatter is minimal:
---
name: "Acme"
tagline: "Build faster, break nothing"
version: 1
language: en
---
Each layer extracts independently. Writing a blog post? Read the Voice layer. Building a landing page? Voice + Visual. Preparing a pitch? Strategy + Voice. You don't need all 16 sections for every task.
What it looks like in practice
Here's a trimmed example from a real brand.md:
## Voice
### Tonal Rules
1. Short, declarative sentences. State facts.
2. Show the work, don't describe the ambition.
3. Technical terms are fine. Jargon is not.
4. Understatement over overstatement. Always.
### We Say / We Never Say
| We Say | We Never Say |
|---------------------|-----------------------------|
| "I built" | "I'm passionate about" |
| "This removes friction" | "This is a game-changer" |
| "Here's what I learned" | "Excited to announce" |
That table is directly usable as a system prompt modifier. Any AI tool reading this file now knows what words to use and what words to avoid. No pasting. No context window wasted on a 50-page PDF.
How AI tools consume it
The idea is the same as AGENTS.md for coding instructions or llms.txt for website context. brand.md gives AI tools brand context.
An AI agent encountering a brand.md file should:
- Read frontmatter for name, tagline, language
- Read Strategy for brand context and positioning
- Read Voice > Tonal Rules as system-level instructions for text generation
- Read Voice > Phrases as few-shot examples of brand voice
- Read Visual > Colors + Typography when generating CSS or design specs
The format is markdown because it renders on GitHub, highlights in any editor, and parses with any markdown library. No custom tooling needed. No API. No integration. Just a file in a repo.
I used it on my own site
I built caiopizzol.com entirely from a brand.md file. The process went like this:
First, I researched how other DX leaders position their personal brands - Lee Robinson, Zeno Rocha, Guillermo Rauch. What patterns they follow, what whitespace exists.
Then I generated a brand.md through a structured interview - archetype, tone, what the brand is and isn't, reference brands (Resend, Vercel, Linear), anti-patterns to avoid.
The file became the single source of truth for everything. The website copy came from the Voice layer. The color palette and typography came from the Visual layer. The LinkedIn bio, the X profile, the GitHub README, the dev.to profile - all derived from the same file. Four languages (English, Portuguese, Spanish, Italian) all consistent because the tonal rules were defined once.
When I needed to update the messaging - SuperDoc's positioning changed from "API infrastructure" to "document engine" - I updated brand.md and re-derived everything from it. One change, consistent everywhere.
The file is 300 lines. It replaced what would have been a 50-page brand guide that nobody would maintain. And because it's in the repo, every AI tool I use already has the context.
That's the whole point. Not a platform. Not a service. A file.