AI Makes Code Work. Engineers Make It Right.

Part 1 of a series.

“AI is the most powerful coding tool I’ve ever used. But a tool is only as good as the craftsman who wields it.”

The Agile Assumption That’s Breaking Down

When a product owner writes a user story like “As a user, I want to save a request to a collection,” they expect the development team to ask questions:

• “How many requests might be in a collection?”
• “Who should have access to these collections?”
• “What happens when the system is under load?”
• “What are the security requirements?”

This back-and-forth — product owners explaining the why, developers digging into the what ifs, testers raising edge cases — is the invisible glue that makes Agile work. Stories are short on purpose because humans naturally fill in the blanks with context, questions, and experience.

But when you hand those same lightweight stories to an AI?

The AI doesn’t pause to ask. It doesn’t challenge the story. It just takes the words literally and fills in the gaps with whatever patterns it has seen in training — which might have nothing to do with your system, your architecture, or your business rules.

The result: code that does exactly what the story says — and quietly fails at everything the story didn’t say.

Why User Stories Work for Humans but Not for AI

For humans, a short story works because the team already carries context in their heads.

Humans bring history to the table:

• They know the business domain and what customers actually need
• They understand how the current system behaves under stress
• They remember painful outages and why certain choices were made
• They’ve seen edge cases crop up before and design to avoid them
• They can smell when a “simple request” hides a deeper complexity

AI tools don’t have that muscle memory:

• No memory of past outages or production war stories
• No awareness of why the architecture looks the way it does
• No sense of compliance rules or business-critical edge cases
• No gut feeling for “this will blow up in production”

That’s why stories that feel perfectly fine for humans become dangerous gaps when an AI takes them at face value.

Human vs. AI: Same Story, Different Worlds

User story: “As a user, I want to save a request to a collection.”

How a human developer responds	How an AI responds
Asks about size limits and performance	Writes code that literally saves a request to a collection
Questions who owns what collections	Assumes the “most common” pattern is correct
Considers concurrency and error handling	Optimizes for what’s written — not what’s implied
Cross-checks with the system’s architecture	Ignores the bigger system around it
Pulls in non-functional requirements that weren’t written down	—

But only the human approach gives you right code — the kind that survives contact with production.

The Critical Gap: Working vs. Right

AI tools are phenomenal at one thing: getting something to work. But there’s a big difference between working code and right code:

• Working code: meets today’s functional requirement
• Right code: meets today’s requirement and tomorrow’s reality

And this isn’t just theory. GitClear analyzed 211 million changed lines of code from 2020–2024 across companies like Google, Microsoft, and Meta. Here’s what they found:

• Refactoring — reusing or moving code instead of copying — dropped from about 25% of changed lines in 2021 to less than 10% in 2024.
• Duplicate code (copy-paste) climbed from 8.3% in 2021 to 12.3% in 2024.
• For the first time, duplication outpaced refactoring.

The takeaway: AI is helping us move faster, but it’s also quietly pushing codebases toward more duplication, less reuse, and less long-term maintainability.

The AI Blind Spots (What It Usually Misses)

• Security: No auth checks, no validation
• Resilience: Crashes on the first failure
• Scalability: Fine at 10 users, falls over at 10k
• Concurrency: Race conditions everywhere
• Observability: Zero logs, zero metrics
• Design principles: Copy-paste code, no refactoring, violating DRY

Real-World Failure: The Missing Context

Take this simple story: “Save user requests to a collection.”

Acceptance criteria:

• User can save a request by clicking “Save to Collection”
• User can select which collection to save to
• System displays confirmation message after successful save
• Saved requests appear in the collection view

What AI built: a clean save feature that met every bullet point.

Where things went wrong:

• Design flaw: No locking mechanism or transactional model for collection operations.
• Requirements gap: Stories captured functionality, but not reliability or concurrency needs.
  • ✅ “Save a request to a collection”
  • ❌ “Save requests reliably, even if a process crashes”
  • ❌ “Allow multiple processes to safely access collections”
• Process trap: Each epic worked in isolation (Save ✅, Run ✅, Manage ✅, Search ✅), but the technical debt accumulated.
• Testing gaps: Happy-path tests all passed, but failure scenarios (simultaneous writes, full disk, real API calls) weren’t covered.

The lesson: AI passed acceptance tests, but missed the system realities any human developer would have flagged.

The Hidden Costs of “Make It Work”

When AI-generated code skips the context, the problems pile up fast:

• Maintenance nightmares: Tangled dependencies and brittle abstractions that developers fear touching.
• Production fire drills: Missing error handling turns small issues into outages.
• Debugging hell: No logs, no metrics, no breadcrumbs to follow.
• Inconsistent patterns: Every feature looks a little different.

Bottom line: “make it work” doesn’t scale.

What We Need: A New Framework

The solution is not to abandon AI tools — they’re too powerful to ignore. Instead, we need to evolve our development practices to bridge the gap between human intent and machine execution.

Agile stories assume humans will fill the gaps. We need a framework that assumes AI will not.

That means:

• Making non-functional requirements explicit
• Drawing clear boundaries for what AI can and can’t decide
• Creating audit trails for AI-assisted decisions
• Ensuring “done” means production-ready, not just functional

“AI accelerates delivery — but without structure, it accelerates technical debt even faster.”

That’s where Refactor Request Cards (RRCs) come in. They turn the implicit into the explicit and make AI-assisted development more predictable, auditable, and sustainable.

“The future of software development isn’t about replacing human judgment — it’s about making that judgment explicit enough for AI to execute reliably.”

In Part 2: how Refactor Request Cards (RRCs) work, and how they help teams move from unpredictable “working” code to reliable “right” code.

---

Originally published on LinkedIn.