Ship Fast, Break Intent: How a Simple Markdown File Keeps AI from Wrecking Your Feature
Table of Contents
There’s a quote floating around podcasts and conference talks right now that sounds like a dream:
“If you want your developer to be 100x with AI, it’s more like they’ll do a year’s worth of work in three days.”
Sounds incredible. But nobody asks the follow-up question: Are you ready to plan for that?
Because here’s what’s actually happening in most teams I see: the AI velocity is real, but the planning infrastructure around it is not. And when the speed of generation outpaces the clarity of intention, you don’t get a year’s work in three days. You get three days of code that nobody fully understands, plus weeks of rework to undo what the AI confidently got wrong.
The Real Bottleneck Isn’t the Developer
Let’s be honest about what’s driving the current chaos in AI-assisted development. It’s not the models. It’s not even the developers. It’s the organisational reflex to treat AI as a shortcut around communication.
The pattern repeats itself everywhere. The PRD isn’t ready. The stakeholders haven’t aligned. But a manager has seen the demos, heard the 100x claims, and the release date is already on the calendar. So the instruction comes down: start building, we’ll figure out the details as we go.
And here’s the thing — developers go along with it. Not out of laziness, but because waiting for clarity in most organisations means waiting indefinitely. So they open their AI assistant, describe what they think the feature should do, and start generating.
The code comes fast. It looks coherent. And then three sprints later, someone shows the stakeholders a demo, and half of it is wrong because the business logic was never properly captured in the first place.
What follows is rework. Dead code. Orphaned components the AI introduced and never cleaned up. And because the AI generated it all in a confident, structured style, nobody’s quite sure which parts to trust and which to throw away.
The Quality Problem Is Already Here
This isn’t just a process complaint. There’s data behind it now.
A CodeRabbit study analysing 470 real-world open-source pull requests found that AI-generated code produces roughly 1.7x more issues than human-written code — across logic, security, maintainability, and performance. Logic and correctness issues were up 75%. Security vulnerabilities rose between 1.5 and 2x. Performance inefficiencies like excessive I/O appeared nearly 8x more often.
That last number should stop you in your tracks. Eight times.
Worth noting: this is CodeRabbit’s own research, and they sell AI code review tooling — so take the precise numbers with that in mind. But the pattern they’re describing matches what a lot of teams are reporting from their own postmortems. And the reason isn’t hard to understand.
The model doesn’t know your business rules. It doesn’t know that this particular endpoint has a rate limit for a reason, or that this flag exists because of a compliance requirement from three years ago that nobody documented. It fills the gaps with confident-sounding assumptions. And confident-sounding wrong code is harder to catch than obviously broken code.
Spec-Driven Development: Theoretically Right, Practically Limited
Birgitta Böckeler, writing on martinfowler.com, has been exploring Spec-Driven Development (SDD) as a response to exactly this problem. The core idea is sound: write a structured spec before you code, and use that spec as the source of truth for both the human and the AI.
Her breakdown of SDD tools — Kiro, spec-kit, and Tessl — is worth reading. But in her analysis she’s honest about a friction point that I think most practitioners feel but rarely say out loud. Reviewing spec-kit specifically, she found the volume of markdown artifacts it generates to be repetitive and tedious — and admitted she’d rather review the code directly. She’s exploring these tools sympathetically, which makes the observation land harder.
And separately: the tools work best when the problem is clearly defined. When a spec can actually be written upfront.
But what about the cases where you can’t? When the feature request is “we need something like what competitor X launched, but our version,” and the three stakeholders in the room have three different mental models of what that means? When the PRD is a Confluence page with a title, two bullet points, and a note that says “details TBD”?
In my experience, that’s the majority of features in a multi-team, multi-stakeholder environment. SDD, as currently implemented, assumes a level of upfront clarity that most real teams don’t have. It’s a great answer to a question most organisations aren’t asking cleanly enough yet.
What Actually Helps: The Feature MD
Here’s what I think is practical — not as a replacement for good process, but as a survival strategy for the world we’re actually in.
The idea is simple: before you generate a line of code, you create a feature markdown file. Not a spec in the formal SDD sense. Not a PRD. Something lighter — a living document that grows alongside the feature rather than preceding it.
This file is your memory, your AI’s context, and your team’s source of truth, all in one place.
What goes in it?
Every decision you get from a stakeholder, documented immediately. You don’t wait for the final PRD. You treat every Slack message, every meeting note, every “oh by the way” from the product manager as a decision worth capturing. Write it down. Date it. Note who said it.
The business flow as a Mermaid diagram. Not a fancy architecture diagram — just the flow. What triggers this feature? What does the user do? What does the system do in response? What are the edge cases the business cares about? A Mermaid diagram forces you to make the flow explicit in a way that prose never does. And it gives the AI something concrete to reason from rather than making assumptions.
flowchart TD
A[User clicks Approve] --> B{Is user authorised?}
B -- No --> C[Show permission error]
B -- Yes --> D[Send approval event]
D --> E[Notify requester]
D --> F[Update status in DB]
F --> G[Trigger downstream audit log]The code locations that matter. Which service handles this? Which utility functions are relevant? Which existing components does this feature touch? Link them in the markdown. When you hand context to the AI three weeks from now, or when a new developer picks this up, they don’t have to archaeologically excavate the codebase to understand where things live.
Every time the flow changes, update the doc first. This is the discipline that makes it work. Not “I’ll update it later.” Before you generate new code, update the diagram. Update the decision log. This isn’t bureaucracy — it’s the thing that stops the AI from confidently rebuilding something you already built differently last week.
Use tools like grill-me or grill-me-with-doc — prompt-based techniques that use AI to stress-test your own understanding before you write a line of code. Ask the hard questions. Let the AI push back on your assumptions. Better to discover the gaps in the spec before they become gaps in the code.
Who owns this?
Whoever opens the first PR. Ideally the tech lead, but in practice it should live with whoever writes the first line of code and gets updated by anyone who changes the flow — developer, PM, or tech lead. The point isn’t ownership in a formal sense; it’s that someone has to be responsible for keeping it current. Without that, the doc goes stale fast and stops being useful to the AI or anyone else.
Why this works in the real world
The Feature MD approach doesn’t require a final PRD. It works because you don’t have one. It’s designed for incremental clarity — you capture what you know now, flag what’s still uncertain, and update it as decisions arrive. The document is never “done” until the feature is shipped.
It also solves a specific AI problem: context decay. The longer a feature takes to build, the more the AI loses track of early decisions. If you’re three weeks into a feature and you open a new chat to generate the next component, the AI has no memory of the architectural call you made in week one. The Feature MD gives it that memory back, consistently, every time.
And crucially — it creates accountability. When a stakeholder changes direction mid-sprint (and they will), you have a documented history of what was decided and when. That’s not just useful for the AI. It’s useful in the retro when everyone is trying to understand why you built the thing you built.
The Skill Shift Nobody Talks About
The 100x developer conversation focuses almost entirely on generation speed. But generation speed was never the bottleneck. Understanding the problem was.
I wrote about this earlier from a different angle — in The Boolean and the Watcher, I described watching two uses of AI happen within the same pair programming session, an hour apart. One was a developer offloading a trivially solvable problem to the AI out of reflex. The other was the AI surfacing AngularJS internals that had walked out the door with a developer who left years ago. Same tool, completely different relationship to thinking. The cognitive load wasn’t reduced in both cases — in one it was bypassed, in the other it was directed. That distinction matters more than most productivity conversations acknowledge.
What AI actually demands from developers is a higher-order skill: the ability to translate ambiguous organisational intent into precise, structured context. That’s not a skill most developers were hired for. It’s not a skill most managers are even aware they need to cultivate.
The developers who will thrive with AI aren’t the ones who can generate code the fastest. They’re the ones who can ask the right questions before they generate anything, document what they learn as they go, and build a feedback loop between the AI’s output and the business’s actual intent.
The Feature MD is one way to build that discipline. It’s not magic. It won’t fix a broken planning process. But it gives you something concrete to do right now, in the organisation you’re actually in, with the clarity you actually have.
A Note to Managers
If you’re reading this and you’re the one setting the release dates before the PRDs are ready — this isn’t an argument to slow down. It’s an argument to invest in the scaffolding that makes fast actually reliable.
The 100x productivity claim isn’t wrong. But a 100x developer working from bad context doesn’t deliver 100x value. They deliver 100x volume at unknown quality, and somebody else spends 50x the time cleaning it up.
Here’s one concrete thing that changes the dynamic: before the next sprint kicks off, ask the developer — where’s the feature doc? Not the Jira ticket. Not the PRD that’s still being written. The living markdown that captures what’s been decided, what the flow looks like, and where the code lives. If it doesn’t exist, that’s the conversation to have — not after the rework, but before the first prompt.
The constraint isn’t the developer. It’s not even the AI. It’s the clarity of what you’re building and who owns documenting it as that clarity evolves.
Fix that, and the 100x becomes real.
If you’ve built your own version of this workflow — or tried it and found it wanting — I’d love to hear what worked and what didn’t.