Why I started writing things down before writing code

The worst project of my early career was a logistics platform. The code was fine, but the system was a ghost. Every week, the definition of a "delivered" package would change. First it was when the driver scanned it at the door. Then it was when the customer signature was uploaded. Then it included a 24-hour grace period for corrections. Each change triggered a cascade of expensive data reprocessing jobs. We were endlessly refactoring a system to solve a problem no one could define.

That experience burned a lesson into me: the keyboard is the last place to formalize your thoughts. Code is a terribly unforgiving medium for ambiguity, and it's expensive to change. I learned to start every project not with an editor, but with a simple, plain-text document.

The High Cost of a Fuzzy Verb

The root problem on that logistics project wasn't technical; it was a failure of language. We had rushed to implement a fuzzy concept—"delivered"—without first nailing down its precise meaning. A one-page document, debated for an hour, would have forced this conversation and saved us months of rework. It taught me that it’s far cheaper to find a flaw in a sentence than in a running service.

This sounds simple, but it often cuts against the grain. The Manifesto for Agile Software Development rightfully values "working software over comprehensive documentation." I agree—I'm not advocating for hundred-page specification documents. But I believe the manifesto's wisdom has been misinterpreted as an excuse to skip the most crucial step: thinking clearly. A one-pager isn't bureaucracy. It's a tool for shared clarity that prevents the very churn that agile methods are meant to fight.

Writing is Thinking, Not Bureaucracy

My solution is a humble one-pager. Its only goal is to turn a vague idea into a concrete, shared plan. This practice is famously used at scale; Amazon's culture of the "six-pager" narrative memo forces teams to crystallize their thinking before a single line of code is approved. For me, it boils down to answering a few critical questions.

Here’s what I put in it:

• The Problem. One sentence describing the pain we are solving, and for whom.
• Core Logic. A plain-English, numbered list of the steps. "1. Ingest daily transaction logs. 2. Filter for completed sales. 3. Aggregate total sales by region."
• Data Contracts. What does the input look like? What will the output look like? Just the key fields, not a full schema.
• Constraints and Non-Goals. What are we explicitly not doing? Stating this up front is the best defense against scope creep.

This document is a focusing lens. It forces the hard questions to the surface when they are cheap to answer. Once it's settled, the team can build with confidence.

A Non-Negotiable for Agentic Systems

This discipline, born from building deterministic automation, becomes a critical safety mechanism when designing systems with LLM agents. A traditional data pipeline is predictable; give it the same input, and you get the same output. Its failure modes are logical.

Agentic systems are different. Their reasoning is probabilistic, and their failure modes can be bizarre and costly. An agent tasked with optimizing cloud infrastructure might misunderstand a constraint and decommission a production database. In this world, the one-pager evolves from a design document into the agent's "constitution."

You aren't just writing down logic; you are codifying intent and boundaries:

• The Objective. Not "improve efficiency," but "reduce p99 latency by 10% without increasing the cloud bill by more than 5%."
• The Guardrails. The unbreakable rules. "Never touch a service tagged 'production-critical'." "Require human confirmation for actions costing over $100."
• The Tools. The specific, limited functions the agent can call, like get_pod_status(), not a generic shell.

This aligns with established best practices for building robust AI. As Martin Zinkevich writes in Google's Rules of Machine Learning, getting the infrastructure and success criteria right from the start is paramount. Without a written charter, you're not building an autonomous system; you're just releasing chaos.

The Reference Architecture

Thinking this way leads to a specific kind of architecture, one designed for durability by separating predictable, deterministic workloads from probabilistic, agentic ones. The two cooperate but are governed by different rules, with clear contracts and observability between them. This is what I aim to build now.

Concrete Takeaways

Writing is thinking. It’s the cheapest, fastest way to iterate on an idea. Before I commit to building anything, I force myself to write down the answers to these questions. It's a pre-flight check that has saved me from countless hours of wasted effort.

• What is the one, single job of this system? This forces clarity of purpose.
• Who consumes its output and what do they depend on? This defines the contract.
• How will I know it’s working correctly at 3 AM? This forces thinking about observability from day one.
• What are the most dangerous ways it could fail? This forces a pre-mortem on reliability.
• If I could only build 10%, what would I ship? This forces ruthless prioritization.

This small, upfront investment in clarity prevents the colossal waste of building the wrong thing beautifully. It ensures the time I spend at the keyboard is aimed squarely at a problem I actually understand.