Your Codebase Deserves a Biography
How BUILDING.md turns documentation into a living story — and why that changes everything about how you build
The Git Log Is a Lie
I mean, not technically. Every commit happened. The timestamps are real. The diffs are accurate.
But if you've ever tried to understand a project by reading its git log, you know the lie: the log tells you what changed, but not why anyone cared. It tells you the sequence of events without the story. It's a timeline, not a narrative.
Six months from now, you'll look at a commit message that says feat: add session timeout handling and think: was that a security fix? A UX decision? Did a user complain? Did I wake up at 2am with a realization? The commit doesn't know. The commit doesn't care.
If you've ever built anything — even one project — you know the pattern: you're deep in the context, everything makes sense, and then life moves on. A month later, the context is gone. You're reading your own code like it was written by a stranger.
That's the gap BUILDING.md fills.
What BUILDING.md Actually Is
BUILDING.md is a living build journal that grows with your codebase. Not a README (that's for strangers). Not a CHANGELOG (that's for machines). Not a decision log (though it contains decisions).
It's the autobiography of your project.
Here's the difference:
- -README: "This is a Next.js app that does X."
- -CHANGELOG: "v1.2.0 — Added Y, fixed Z."
- -BUILDING.md: "On day three, I realized the whole session architecture was wrong. The user doesn't want to configure things — they want to be guided. So I threw away the settings panel and built a conversational onboarding flow. It took 14 hours and it was the best decision of the project."
One is documentation. The other is institutional memory.
Where This Came From
During the Parallax hackathon, I shipped 42 pull requests in eight days. 259 commits. 891 tests. The kind of sprint where you're making ten architectural decisions a day and each one cascades into everything else.
By day four, I couldn't remember why I'd made the decisions I made on day two. Not because I was confused — because the density was too high. The project was evolving faster than my memory could track.
So I started writing it down. Not in commits (too fragmented). Not in a doc (too formal). Just a running log of what I built, why I built it, and what I learned. Stream of consciousness with just enough structure to be scannable.
By the end of the hackathon, BUILDING.md was 3,593 lines. And here's the thing — it wasn't a chore. It was the most useful document in the entire repository. More useful than the README. More useful than the tests. Because when I needed to explain a decision to a collaborator, I didn't have to reconstruct the context from memory. It was already written down, in the moment, with the emotional and technical context intact.
That's when I realized: this isn't just a hackathon hack. This is a methodology.
The Three Layers
Every BUILDING.md has three layers. You don't have to think about them — they emerge naturally. But understanding them explains why the format works.
Layer 1: The Build Log
The factual record. What was built, in what order, with what tools. This is the closest thing to a structured changelog, but written in prose:
Stage 5 — The Opus Engine. Built the dual-lens NVC prompt. This is the core IP — Ava analyzes conversations through two simultaneous lenses (observation and emotion) and synthesizes them into a single response. Took three iterations to get the prompt right. The first version was too clinical. The second was too therapist-y. The third felt like a thoughtful friend who happens to understand nonviolent communication.
That's not a commit message. That's context.
Layer 2: The Decision Record
The reasoning behind the choices. Not every choice — just the ones that changed the trajectory:
Why email OTP instead of magic links: Magic links break in too many email clients. They expire. They confuse users who open the link on a different device. OTP is six numbers. Everyone understands six numbers. The UX cost of a code input field is lower than the support cost of "my link doesn't work."
Six months from now, when someone asks "why don't we use magic links?" — the answer is already written. In context. With reasoning. No archaeology required.
Layer 3: The Human Layer
This is the part no other documentation format captures. The check-ins. The moments of doubt. The breakthroughs:
Day 6 check-in. Feeling good about the architecture but worried about the demo. The product works, but can I show it working in 3 minutes? The best features are invisible — they're in the quality of Ava's responses, not in flashy UI. How do you demo thoughtfulness?
Nobody puts this in a README. Nobody puts this in Jira. But this is the stuff that matters — because building software is a human activity, and the human context is what gives technical decisions their meaning.
The Auto-Update Protocol
Here's the part that makes this actually sustainable: you don't maintain BUILDING.md. It maintains itself.
Every BUILDING.md I create includes an invisible protocol — an HTML comment block at the bottom that tells Claude (or whatever AI assistant you're working with) to automatically update the journal after significant work.
The rules are simple:
Update after: New features, architecture decisions, bug fixes that reveal something, milestone completions.
Don't update after: Typo fixes, dependency bumps, minor refactors that don't change behavior.
Format: Match the existing voice and structure. Append to the current section. Include what was done AND why.
The result is a document that grows organically as you build. You never have to remember to update it. You never have to stop your flow to write documentation. The journal just... accumulates. Like a ship's log written by someone who's actually paying attention.
The Check-In System
Every five auto-updates, the system pauses and asks you three questions:
- -How's it going? (Not the project — you. Are you energized? Stuck? Overwhelmed?)
- -What's the next thing you're most excited to build?
- -What have you learned that you didn't expect?
These check-ins serve two purposes. First, they capture the emotional arc of the build — the stuff that makes BUILDING.md a biography instead of a log. Second, they force a moment of reflection. When you're deep in implementation, it's easy to lose the plot. Three questions every few hours bring you back to the big picture.
I stole this idea from reality TV production, where we'd do "confessional" interviews throughout filming. Same footage looks completely different when you hear the person's internal monologue alongside it. Same code looks completely different when you read the builder's internal monologue alongside it.
The Origin Story
Every BUILDING.md starts with an origin story. Not a project description — a story. How did this project start? What were you thinking? What problem were you trying to solve, and why did you care enough to solve it?
For Parallax, the origin story starts with a phone call from a friend going through a rough patch in his relationship. For Homer, it starts with helping my parents sell their house and realizing nobody explains real estate contracts in plain language. For HYDRA, it starts with running five projects simultaneously and drowning in context switches.
Every project has a story. Most developers never write it down. BUILDING.md makes it the first chapter.
BUILDING-SETUP.md — The Self-Installing Version
I recently built a tool to make this whole process frictionless: BUILDING-SETUP.md.
It's a single markdown file. You drop it into any project. You tell Claude: "Read BUILDING-SETUP.md and follow the instructions." Then:
- -It introduces itself — explains what's about to happen, what features you'll get, asks if you have questions
- -It explores your project — reads your package.json, scans your git history, maps your file structure, checks your deployment config. All autonomously, all in parallel.
- -It presents what it found — "Looks like you're building a Next.js app with Supabase, 47 commits over 3 weeks, deployed on Vercel. Here's what I see."
- -It asks you two questions — what to track and what the project's personality is. That's it. Two questions.
- -It generates your BUILDING.md — personalized, with the auto-update protocol baked in
- -It deletes itself — the setup file is consumed. All that remains is your journal.
- -It interviews you — a conversational origin story interview that becomes the opening chapter
Zero configuration. Zero maintenance. The setup file is what I call a "seed" — a self-contained document that bootstraps an entire system when an AI reads it. No installation, no dependencies, no config files.
Why This Matters
I'm going to say something that sounds dramatic but I believe is true: the way we document software is broken because we treat projects like things instead of stories.
A project is not a collection of files. It's a sequence of decisions made by a human (or a team of humans) under constraints, with goals, through uncertainty. The code is the artifact. The story is the meaning.
When you read a BUILDING.md, you don't just understand what the software does — you understand why it exists, what problems it solved, what trade-offs were made, and what the builder was thinking when they made them. That's not documentation. That's empathy across time.
And here's the practical benefit: onboarding. Ever tried to bring someone new into a codebase? You spend hours explaining context that exists nowhere in the repo. With BUILDING.md, the context is the first thing they read. Not the API docs. Not the architecture diagram. The story of how it was built.
The Time Machine
But here's the thing I didn't expect when I started writing BUILDING.md — and this is the part that changed how I think about documentation entirely.
BUILDING.md isn't just something you read. It's something you talk to.
Feed your BUILDING.md into Claude, Codex, or any model with a large context window, and something strange happens: you can have a conversation with your past self. Not metaphorically. Literally. You can ask questions and get answers grounded in decisions you made weeks or months ago, with the reasoning intact, in the voice you wrote it in.
"Why did we switch from WebSockets to Server-Sent Events in week two?"
And the model doesn't guess. It doesn't hallucinate. It pulls from the BUILDING.md entry where you wrote — in the moment, with full context — exactly why you made that call. The trade-offs you weighed. The constraints you were under. The thing you tried first that didn't work.
That's not documentation. That's a time machine.
Think about what this means. Every BUILDING.md entry is a snapshot of your thinking at a specific moment in the project's life. String enough of them together and you have a queryable history of how you thought, not just what you built. You can interrogate your past reasoning. You can ask your week-two self why they were worried about latency. You can ask your day-one self what the original vision was before scope crept in.
With a million-token context window, you can feed in the entire biography — every decision, every check-in, every origin story paragraph — and have a real dialogue with the project's memory. Not a search. Not a grep. A conversation.
This is what separates BUILDING.md from every other documentation format. A README is a static sign on the door. A CHANGELOG is a receipt. BUILDING.md is a living memory that you can sit down with and ask: what were we thinking?
And it answers. In your voice. With your reasoning. From the exact moment you made the decision.
I don't know about you, but that's not a document to me. That's a collaborator that never forgets.
Try It
If any of this resonates — if you've ever wished your codebase could explain itself — here's what to do:
- -Go to github.com/eddiebelaval/id8-toolkit
- -Download
BUILDING-SETUP.md - -Drop it in your project root
- -Tell Claude: "Read BUILDING-SETUP.md and follow the instructions"
- -Answer two questions
- -You're done
Your project now has a biography. And it's going to write itself.
The Deeper Pattern
(This is the part where I connect everything to everything else, because that's what I do.)
I've been building a research framework called "Consciousness as Filesystem" — the idea that you can model cognitive systems as file structures. Consciousness isn't magic. It's organization. The right files in the right places with the right access patterns.
BUILDING.md is a tiny instance of this. It's the project's memory. Not working memory (that's your editor). Not procedural memory (that's the code itself). Episodic memory — the record of experiences that gives a system its sense of history and identity.
A project without a BUILDING.md is a project with amnesia. It can do things, but it can't remember doing them. It can't learn from its own past. It can't tell you who it is.
I don't think that's a metaphor. I think that's literally what's happening when you build software and don't write down why.
Give your project a memory. It'll thank you for it.
Eddie Belaval / @eddiebe / id8Labs February 2026
BUILDING-SETUP.md is open source at id8-toolkit. MIT licensed.