How to Build Software with AI | Ep 3: The Paperwork Is the Product

Transcript

The full word-for-word transcript of this episode. Plain text version

Marcus: I want you to imagine, um, just for a second, that you have managed to hire the single most brilliant contractor on earth to rebuild your kitchen.

Devon: Okay, I'm with you.

Marcus: Right, so they have superb hands, excellent judgment, and they build flawlessly.

Devon: Uh-huh.

Marcus: But there is one catch, and it's a pretty horrifying one.

Devon: Go on.

Marcus: They have total incurable amnesia. I mean, you spend an entire day with them walking the floor plan, explaining exactly where you want the plumbing routed, the materials you selected, all of it.

Devon: Yeah.

Marcus: And they do a brilliant day of work. You lock up the house, you come back the next morning, and they remember absolutely nothing.

Devon: Nothing at all?

Marcus: Not the layout, not the rules you agreed on, not even the cabinets they built the day before. Every single session starts completely fresh.

Devon: Which, I mean, sounds like an utterly exhausting working relationship. But that amnesia is exactly how AI coding agents operate, and it is crucial to understand that, um, this is not a bug.

Marcus: This is not a glitch.

Devon: No, it's not the system failing or the software breaking. Complete amnesia between sessions is a fundamental reality of how large language models are engineered. They are stateless by design.

Marcus: Right.

Devon: When you close the session, the context window, you know, the model's short-term working memory, is completely wiped.

Marcus: And dealing with that absolute statelessness is exactly what we are getting into. This is the third instalment in our beginners series on building software with artificial intelligence.

Devon: Yeah.

Marcus: So, if you are joining the journey here, um, the first instalment covered how to write a brief, the second covered the planner and builder pattern where you act as the gatekeeper, and in this deep dive, we are tackling the amnesia problem. We are going to give those AI agents a durable memory.

Devon: And to do that, well, we have to completely invert how we view documentation.

Marcus: How so?

Devon: So, the common story in any development team treats writing things down as tedious administrative work, right?

Marcus: Yeah.

Devon: It is the, uh, boring paperwork you do after the real engineering is finished, usually quite reluctantly.

Marcus: Yeah, the admin nobody wants to do.

Devon: Yeah, exactly. But when you are building with AI, the reality is flipped entirely. Because the written record is the agent's only continuous memory, the paperwork is the mechanism that makes tomorrow's work possible.

Marcus: Wow.

Devon: Therefore, the paperwork is the product.

Marcus: The paperwork is the product. Okay, so if that's the case, how does that actually play out in practice? Because if the agent has complete amnesia, I mean, the immediate human instinct is to simply re-explain the project at the start of every single session.

Devon: Which is a nightmare.

Marcus: Speaking from experience, yeah, it is a fast track to project failure. You will never write the prompt the exact same way twice, you will forget to mention the specific database structure you chose last week, and the codebase will slowly fragment.

Devon: And exactly. I mean, re-prompting relies on your own flawed human memory, which completely defeats the purpose.

Marcus: Yeah.

Devon: The engineered fix for this is the project handbook. This is a standing, plain text file that lives in the root directory of your project folder. The mechanism here is what matters. The agent is programmed to read this specific file automatically, injecting its contents into the system prompt before it even processes your first message of the day.

Marcus: Let's talk about that mechanism actually, because if it reads this file every single time I pipe a message, um, isn't that eating into the token limit? I thought context windows were expensive real estate.

Devon: They are, yeah, which is why the handbook has to be incredibly disciplined. The model allocates a portion of its processing power, its tokens, to hold those rules in its working memory.

Marcus: Okay.

Devon: So, you are paying a small tax in tokens to ensure the agent understands the boundaries of the universe it is operating in. But you're not writing code here. This is plain English. You are establishing the core identity of the project, the architecture choices, and the strict never-dos.

Marcus: It's essentially a high-stakes version of the handover book in a busy cafe, isn't it?

Devon: Oh, that's a brilliant way to put it, yeah.

Marcus: Right, so the morning shift writes, "The card machine drops out, restart at the wall." The evening shift walks in, reads the book, and knows the constraints without ever seeing the morning staff.

Devon: Exactly.

Marcus: They ignore the book, they just repeat the same failures on the customers.

Devon: That is the exact dynamic. And to make this concrete, the tooling industry has already standardised how this works.

Marcus: Right.

Devon: If you are using Anthropic's Claude Code, the system automatically hunts for a file named `claudeg.md`.

Marcus: Mm.

Devon: If you are using OpenAI's codex, it searches for `agents.md`.

Marcus: It's built right in.

Devon: It is. At the time of release, OpenAI framed this beautifully, actually. They noted that a standard README file is written for human developers to understand the project, whereas this new handbook file is written specifically for the AI agent to understand how to behave within it.

Marcus: It is remarkably approachable for beginners, I have to say. I mean, if you can type out a set of house rules, you can program an AI's baseline memory.

Devon: Absolutely.

Marcus: But a static handbook covering overarching rules only really solves half the problem. What happens when you are deep in the weeds of a project and you make a highly specific, you know, idiosyncratic choice?

Devon: Well, that requires the second piece of the memory architecture, which is the decision record.

Marcus: Okay.

Devon: A handbook sets the rules, but a decision record logs the history of choices. When you make a real architectural decision, choosing one method over another, say, you add a couple of lines to the file, capturing not just what was decided, but why.

Marcus: Right, the why is the deterrent. I picture, um, a handwritten note taped to a fuse box in a dark cellar that just says, "Do not switch off, feeds the freezer."

Devon: Exactly.

Marcus: That note tells the future reader just enough of the underlying logic to prevent them from committing helpful sabotage.

Devon: Helpful sabotage is the perfect phrase because it is exactly what an AI agent will do if left unchecked. You have to understand the optimisation bias of these models.

Marcus: What do you mean?

Devon: Well, they are trained on billions of lines of standard, elegant code from platforms like GitHub. They fundamentally want things to look standard.

Marcus: Yeah.

Devon: So, if an agent scans your project six weeks from now and spots a bizarre, messy workaround you wrote, its first instinct is to just fix it.

Marcus: Which is a terrifying thought. You have this hyper-competent, overly eager digital assistant cheerfully bulldozing a load-bearing piece of code you spent three hours debugging, purely because it didn't look elegant enough.

Devon: Precisely. The model does not know that your weird workaround is, you know, the only way to bypass a bug in a third-party server.

Marcus: It just sees messy code.

Devon: Exactly. So, if the why is not explicitly logged in a decision record, the AI refactors the code, makes it beautiful, and perfectly reintroduces the very problem you already solved.

Marcus: Well, that's maddening.

Devon: It is. This is why heavy users apply a strict rule of three.

Marcus: Okay, what's that?

Devon: If you find yourself correcting the agent about the exact same issue twice in the chat interface, the third correction must never be another chat message.

Marcus: Because it'll just forget it again.

Devon: Right. The chat will eventually scroll out of the context window and be forgotten.

Marcus: Right.

Devon: That third correction becomes a permanent decision record in the handbook file.

Marcus: Now, I have to stop you there, actually, because I fundamentally disagree with how much trust we are placing in a plain text document here.

Devon: Okay. How so?

Marcus: Well, we write down our overarching rules, we log our decision records, and we put them in a markdown file. But if I am running a complex session and the context window is filling up with thousands of lines of new code, um, doesn't the AI suffer from attention decay?

Devon: It can do, yeah.

Marcus: Right, so can't it just wander off script, succumb to the lost-in-the-middle phenomenon, and completely ignore the text file we spent all this time curating? Aren't we just relying on blind faith?

Devon: No, that is an entirely valid challenge, and it highlights a critical boundary you really have to understand.

Marcus: Okay.

Devon: The text file provides context. It is not a locked door. It guides the agent, but it does not compel it.

Marcus: I see.

Devon: As a session drags on and the context window saturates, the model's attention mechanism can absolutely degrade. It might forget a rule from the handbook or hallucinate a different constraint. You cannot treat a plain text file as an ironclad, cryptographic guarantee of behaviour.

Marcus: Right, so our amnesiac contractor can still decide to install a pink sink, even if the handbook clearly states all ceramics must be white. We are essentially relying on influence, not control.

Devon: You are, yeah. The rules that absolutely must hold, the locked doors, as it were, cannot live solely in a text file.

Marcus: Where do they live then?

Devon: They have to be enforced by automated checks, like test suites or deployment pipelines, that physically reject the wrong code.

Marcus: Oh, okay.

Devon: That transition from written guidance to automated enforcement is a complex mechanism, and it will be the central focus of a later deep dive in this series. But for now, the distinction is what matters.

Marcus: Right.

Devon: The handbook is how the agent learns the rules. It is not the mechanism that forces compliance.

Marcus: Right, so paperwork prevents the amnesia, but it does not replace the human holding the gate. Which brings us to the human vulnerability in this entire system, I think.

Devon: Yeah.

Marcus: We've established how to stop the machine from forgetting, but how do we stop the human from hallucinating their own progress?

Devon: Oh, this is the real danger of writing documentation for a machine. You fall into the optimistic present tense trap.

Marcus: It is the most dangerous trap for any beginner.

Devon: Yeah.

Marcus: I mean, here is how the trap springs. You are writing out your project handbook, outlining the rules for the agent, and you write a sentence like, "The system routes user data to the secure server."

Devon: Right.

Marcus: What you actually mean is, "The system will route data, eventually, when I figure out how to build the server."

Devon: Yeah.

Marcus: But you write it in the present tense.

Devon: Yeah.

Marcus: A month passes, you open the document to remind yourself where you left off, you read, "The system routes user data," and you genuinely believe the architecture is finished. You have successfully lied to yourself.

Devon: It happens all the time. We describe our intentions so vividly that they solidify into reality in our own minds.

Marcus: Exactly.

Devon: But the stakes are actually much higher than just human confusion here. If you write that optimistic sentence, what do you think the AI agent does when it reads it?

Marcus: Oh, wow, of course. If I ask the agent to build the front-end login screen, and it reads my note saying the secure server already exists, the agent will confidently write code trying to send data to a server that is entirely imaginary.

Devon: Exactly.

Marcus: I just caused a hallucination cascade.

Devon: You did. The AI anchors its reality to your documentation. It trusts your text file, sometimes even over its own analysis of the codebase.

Marcus: That's incredible.

Devon: So, to prevent that collapse in reality, you have to apply a ruthless three-word status system to every single capability mentioned in your handbook. Every feature must be explicitly tagged with one of three words: live, built, or specified.

Marcus: Let's break down the mechanics of those tags because the distinction really matters.

Devon: Yeah, so the first tag is live. If a feature is tagged live, it means the code is deployed, it is running in real use, and it is handling actual data. The agent knows it can safely interact with it.

Marcus: Complete certainty.

Devon: Complete certainty. The second tag is built. This indicates the feature has been engineered, the code exists in the repository, but it is not yet active.

Marcus: Like it's on standby.

Devon: Right, it might be waiting for a final review or a wider launch. The agent knows the logic is there, but the pathways are closed. Which leaves the third tag, specified, which sounds like the antidote to the optimistic present tense.

Marcus: It is entirely. Specified means the feature has been designed, the architecture choices have been made, and the rules are logged, but absolutely no code has been written. It is just words on a page.

Marcus: It is a wish with paperwork.

Devon: Exactly. If you enforce those three tags, you strip away the ambiguity. When you open your handbook and see "secure server: specified", you cannot trick yourself into believing it is finished.

Marcus: Yeah.

Devon: And more importantly, the AI agent knows not to attempt to route data to it. It forces absolute mechanical honesty about the state of the project.

Marcus: It also gives you a highly accurate metric for real progress, doesn't it? I mean, editing a document for three hours can feel like work, but if nothing moves from specified to built, you haven't actually advanced the software.

Devon: That's a great point.

Marcus: But that raises an interesting operational question for me. If a plan tagged specified inevitably changes, because project requirements always shift, you know, how do you update the handbook without corrupting the agent's understanding of the project history?

Devon: Well, this requires the discipline of superseding records.

Marcus: Okay.

Devon: When a beginner decides to change an architectural plan, their immediate instinct is to open the markdown file, delete the old idea, and type the new requirement in its place.

Marcus: Right, it feels efficient, it keeps the document tidy.

Devon: But you are erasing the breadcrumbs.

Marcus: You are destroying the delta.

Devon: You are. The AI agent benefits immensely from understanding not just where the project is now, but the trajectory of how it got there.

Marcus: Oh, that makes sense.

Devon: If you use the digital equivalent of correction fluid to quietly rewrite your past decisions, the past becomes unknowable. Instead, you must treat the handbook like a formal legal ledger.

Marcus: So, what do you do?

Devon: You draw a line through the old text, you mark it as superseded, you write the new decision directly beneath it, and you add a single sentence explaining the catalyst for the change.

Marcus: So, the agent reads the superseded note, sees the pivot, and understands the underlying logic of the new direction.

Devon: Yes. The untampered history is the asset. Future you and the future agent need to look at that document and have total verifiable confidence that past you did not secretly doctor the notes to cover up a mistake.

Marcus: I think everyone listening has quietly doctored a document to look a bit smarter in hindsight.

Devon: We all have. But in this context, vanity actively breaks the machine's context.

Marcus: Yeah.

Devon: Now, stepping back for a moment, I think it is crucial to realise how universally this architecture is being adopted.

Marcus: Yeah.

Devon: We mentioned Anthropic and OpenAI, but this specific mechanism of using plain text handbooks to anchor an AI's memory extends across the entire frontier of software tooling, doesn't it?

Marcus: It really does. It is rapidly becoming the foundational standard. If you examine tools like Cursor, which integrates the AI agent directly into the code editor, or GitHub Copilot, or Google's Developer Suite, they all rely on this paradigm of injecting initial context through a local file.

Devon: And it spans the globe, too. The major Chinese frontier labs are operating on the exact same constraints.

Marcus: Yeah, absolutely.

Devon: Alibaba's Qwen model deploys an agent heavily reliant on local file context. Labs like Zhipu and Moonshot, who are competing fiercely on coding benchmarks, hit the exact same amnesia wall and solve it the exact same way.

Marcus: Right.

Devon: The `agent.md` format is effectively a shared global language that multiple competing tools know how to ingest. When OpenAI launched their agent framework, their own internal codebase reportedly contained dozens of these handbook files, quietly steering their own internal tools.

Marcus: Which is the ultimate validation of the method, if you ask me.

Devon: Absolutely.

Marcus: If the engineers building the frontier models rely on plain text handbooks to manage the amnesia of their own creations, it proves that this is not a temporary workaround. It is the architectural foundation of working alongside artificial intelligence. So, as a beginner stepping into this space, what is the concrete reality you need to take away? It comes down to the human cost of skipping the paperwork.

Devon: The absolute truth of building software with AI is that if you rely purely on chat memory, you will inevitably lose days of your life. You will sit there trying to reconstruct why a load-bearing piece of code was written a certain way, or worse, you will deploy a feature that you hallucinated was finished, entirely because of the optimistic present tense trap.

Marcus: It's a painful lesson to learn.

Devon: It is. The seasoned builders all arrive at the same conclusion. The handbook always gets written. The only choice you have is whether you write it before the project collapses or after.

Marcus: Exactly.

Devon: And to solidify that choice, we want to leave you with a practical exercise based on the mechanics we've covered in this deep dive.

Marcus: Okay, what's that?

Devon: If you followed along with the first instalment of this series, you wrote a five-sentence project brief. Dig that file out. At the very top of the document, type one word: specified. Look at it, and recognise that until the code is running, it is only a wish with paperwork. Then, draft a single decision record. Write one sentence detailing a technical choice, and one sentence explaining the why, structured so clearly that a machine reading it six months from now would understand exactly why it cannot alter it.

Marcus: Just a few deliberate lines of plain English, and you have officially engineered your first durable memory for an AI. But as you write that file, I want you to consider a broader shift that this entire process implies. We are teaching you how to build software, but notice what you are actually doing. You're not writing loops, you are not debugging syntax, you are drafting rules, documenting context, and preserving the history of human intent.

Devon: Right.

Marcus: As AI agents become increasingly capable of writing the actual code, the primary role of the human developer is fundamentally changing. We are no longer the builders of the machine, we are becoming professional historians for the AI, meticulously managing the archive of our own decisions so the machine knows what to build next.

Devon: That is a staggering pivot in what it means to be a programmer. From writing code to archiving intent.

Marcus: It really is.

Devon: Well, that wraps up part three of our series. If you missed the first two instalments exploring the brief and the planner-builder pattern, definitely check those out, and follow the deep dive for more.

Marcus: And just remember, the next time you open a terminal and spin up an AI agent, you are sitting down with that brilliant amnesiac contractor. If you want them to build the architecture of your dreams, you have to leave the handover book on the counter.