From Code Navigator to Product Architect
When implementation becomes a conversation, the skill that matters shifts upstream.
Two decades of Agile, trained engineers to live inside the codebase. We navigated functions, debugged logic, traced execution paths. The code was our territory, and we knew every corner.
AI is redrawing the map entirely.
When implementation becomes a conversation, the skill that matters shifts upstream. We are moving from navigating source code to navigating the product itself. And navigation requires a different kind of documentation than we’ve been writing.
The Cost of Vague Requirements
Here’s what happens when you bring loose requirements to an AI agent: you get plausible-looking output that misses your intent in subtle ways. The agent fills gaps with assumptions. You catch some immediately. Others you discover weeks later, buried in edge cases you never specified.
Building https://echo.ink taught me this the hard way. I fed requirements to my AI agent reactively—commenting on implementation as it emerged, adjusting in conversation.
Progressive, I told myself.
Agile.
What I actually built was a trail of context scattered across chat threads. Requirements that existed only in conversation history. Decisions I couldn’t trace back to their source. When I wanted to try a different model, I had to reconstruct everything from memory.
The specification had become invisible. And invisible specifications are worthless to machines.
The Documentation We Abandoned
Rewind to the pre-Agile era. Waterfall demanded exhaustive upfront planning. Every feature documented before a single line of code. The problem wasn’t the documentation, it was the timing. Requirements locked in months before anyone understood what they were building.
Agile’s correction was sensible: tighten the feedback loop, document what matters when it matters, trust the team’s shared understanding. “Working software over comprehensive documentation.”
We took this further than intended. Documentation became synonymous with waste.
Code is the document — I’ve said that many times
Context lives in the team. Requirements exist in the backlog as user stories — brief, intentional, designed to spark conversation rather than specify behaviour.
This worked because humans absorb context continuously. We carry architectural decisions in our heads. We remember why that weird edge case exists.
AI agents have no such continuity. Each conversation starts fresh. Every session requires re-establishing context. Without explicit documentation, you’re explaining the same decisions over and over, or worse, watching the agent reinvent them differently each time.
The New Specification
What does useful documentation look like when machines are building?
It’s not the Waterfall spec. Nobody wants a 200-page requirements document that’s outdated before the ink dries.
Think of it as a blueprint portable enough to hand to any AI system and reproduce consistent results. Detailed enough that the agent doesn’t have to guess. Living enough to evolve as you learn.
The spec becomes your interface with machine implementation. Its quality directly determines how much rework you’ll face, how many cycles you’ll waste, and whether you can compare outputs across different AI models.
Your specification is now your most valuable engineering artifact.
The Three Qualities of AI-Ready Specs
1. REPRODUCIBLE: Same Input, Similar Output (The “Determinism Test”)
If you hand the spec to Claude today and GPT tomorrow, do they build substantially the same thing? If not, your spec has gaps the agents are filling differently.
2. PORTABLE: Model-Agnostic Clarity (The “Translation Test”)
No context assumed. No references to previous conversations. A fresh agent with zero history should understand exactly what to build.
3. VERIFIABLE: Clear Success Criteria (The “Done Test”)
Specific enough that you can check the output against the spec and declare victory or failure. “Fast” isn’t verifiable. “Under 200ms” is.
The Architect’s Role
We are not becoming less technical. We are becoming differently technical.
When code is cheap to produce, the constraint moves upstream. Your leverage comes from defining what to build with precision. From understanding the product deeply enough to specify its behavior completely. From writing documentation clear enough that any agent can execute against it.
The engineers who thrive in this transition will be product architects. They’ll spend less time debugging implementation and more time debugging specifications. Less time in the codebase and more time in the requirements.
Documentation is the new code — You’ll here me say that more often