HUMAN.md
The one file every agent reads before it does anything on your behalf.
HUMAN.md is a single markdown file that describes who you are, how you think, what you're working on, and how you want AI to behave on your behalf. It's the default context every agent loads at session start.
When To Use This
HUMAN.mdis for you if…
- Every AI tool you use asks you the same basic questions about who you are and what you do.
- Your agents produce work that sounds generic — not like you wrote it.
- You switch AI tools often and hate re-bootstrapping context every single time.
- You want one portable, version-controlled identity file that every agent can consume on day one.
The Parts
What's Inside HUMAN.md
Name, role, core beliefs. The non-negotiables that define your default stance.
Domains you operate in at a senior level. Where your judgment can be trusted.
Tone, cadence, words you use, words you don't. So agents sound like you.
Hard rules. Time boundaries. Decisions already made that shouldn't be revisited.
Current mission. The one or two things that should override everything else.
Why A Single File
Context scattered across twenty tools is context that doesn't exist. If an agent needs three logins and a ceremony to figure out who you are, it won't — it'll just guess.
HUMAN.md is one file, one format, one source of truth. Markdown. Version-controlled. Portable. Any agent that can read text can read HUMAN.md. No vendor lock-in. No proprietary schema.
The constraint is the feature.
What Goes In
Five sections, in this order:
Identity — Who you are. Your name, role, the one-liner you'd say at a dinner party.
Expertise — Where your judgment is trustworthy. Agents defer to you in these areas and shouldn't re-derive first principles every turn.
Voice — How you sound. If an agent writes on your behalf, it should read like you wrote it. Include words you use, words you never use, cadence preferences.
Constraints — Hard rules. "Never commit without tests." "Never use first-person on the blog." "Don't call contractors before 10am Pacific."
Goals — What you're building right now. Not a resume. The one or two things agents should optimize for when there's ambiguity.
What Stays Out
HUMAN.md is not a journal. It's not a memoir. It's the identity manifest that agents should load fast and trust deeply.
Keep it tight. ~500 lines is the sweet spot. If it grows past 1,000, you're writing long-form content that belongs in DOTs instead.
Rule of thumb: if it doesn't change how an agent behaves on your behalf, it doesn't go in HUMAN.md.
The Third Leg
Inside the Command Center, HUMAN.md is the third leg of context — alongside the project spec and the codebase itself.
Miss the project spec: the agent doesn't know what to build.
Miss the codebase: the agent doesn't know what's there.
Miss HUMAN.md: the agent doesn't know who it's building for — and quality drops before a single line of code is written.
Every agent, every session, loads HUMAN.md first. That's not a convention. It's a guardrail. Because the default quality of work is bounded by the quality of the identity the agent is operating against.
The Traps
Common Mistakes With HUMAN.md
Turning it into a memoir
HUMAN.md is an identity manifest, not an autobiography. If a line wouldn't change how an agent behaves on your behalf, cut it. The Vault is where your story lives. HUMAN.md is the three-inch summary an agent reads in the first two seconds of every session.
Writing in corporate voice
Agents mirror what they read. If your HUMAN.md sounds like a LinkedIn bio, every email it writes will sound like one too. Write it the way you actually talk — cadence, vocabulary, the mild swearing, the catchphrases. That's the whole point.
Forgetting to update it
Your identity manifest is a living document. The moment a constraint stops being true — a company you no longer work at, a goal you already hit, a voice you've outgrown — it poisons every agent session downstream. Touch HUMAN.md at least monthly. Treat stale entries like stale dependencies.
Objections Answered
But What About…
A prompt is per-request. HUMAN.md is per-identity. Every agent you ever use reads it. You wouldn't rewrite your bio for each tweet — don't rewrite your identity for each chat.