Why AI Coding Feels Faster (While Your Sprints Slow Down)

If you work on a mature codebase, you have probably felt the weird disconnect around AI coding tools over the past year. In the moment, sitting in your IDE, you feel noticeably faster. You ask an agent for a new endpoint or a state machine refactor, and 200 lines of clean-looking TypeScript or Java appear in ten seconds.

Then you look at your team's sprint board on Friday. Cycle times haven't moved. Pull request review queues are backed up worse than before, and subtle regression bugs keep slipping into staging.

In a landmark randomized controlled trial conducted by METR (Model Evaluation & Threat Research), researchers put a stopwatch on experienced open-source developers working across mature codebases. Before starting, developers predicted that frontier AI tools would speed them up by 24%. Even after completing the tasks, they believed they had moved 20% faster.

When researchers checked the stopwatch, tasks done with AI took 19% longer than tasks done without it.

While tooling and base models have improved since that initial trial, newer industry data from DORA and developer productivity studies confirms that the core paradox has only intensified: teams are generating 30% to 40% more pull requests, but PR review turnaround times have doubled, and change failure rates remain elevated.

Writing syntax was never the real bottleneck in software engineering. When we prompt an LLM in an ungrounded chat window, we save twenty minutes of typing and spend the next two hours untangling hallucinated contracts, reviewing plausible-looking edge-case failures, and playing detective in integration tests.

To turn AI from a noisy typing assistant into a dependable team multiplier, we have to confront an uncomfortable truth about a rule most of us have treated as sacred for twenty-five years.

1. The 180-Degree Inversion: When Code Becomes a Cheap Commodity

For twenty-five years, software engineering culture has been anchored to one foundational line from the 2001 Agile Manifesto:

"Working software over comprehensive documentation."

Every developer, tech lead, and engineering manager has had this mantra drilled into their instincts: Code is reality. Writing documentation is waste. If it isn't running in production, it doesn't matter.

In 2001, that was pure economic sanity. Human keystrokes were the scarcest resource on a software team. Translating business requirements into working C++ or Java took weeks of manual labor, while 50-page Word documents rotted the afternoon the first production patch was deployed. The source code was the only truth you could afford to trust.

With AI agents, that economic reality has flipped 180 degrees.

Today, syntax generation is practically free. An agent will happily emit 500 lines of syntactically valid code in thirty seconds for pennies.

What is scarce and expensive now is unambiguous intent, domain invariants, and cross-service alignment. When an agent breaks a downstream service, it rarely fails because the model forgot how to write a loop. It fails because the edge cases, business rules, and contract boundaries lived inside someone's head, an informal Slack message, or a vague two-sentence Jira ticket.

Here is the radical shift most teams haven't internalized yet: application code is still something you commit and maintain, but it is no longer where primary intent lives. Code is now a generated artifact; the living specification is the actual source of truth.

The Limits of the Compiler Analogy (Why Prompts Aren't Deterministic)

It is tempting to look at this table and say: "Great, so the LLM is just a C compiler."

Every experienced engineer knows the catch: compilers are deterministic, but AI models roll dice. If you feed the exact same C source into gcc twice, you get the exact same binary. But if you give an AI agent the exact same prompt twice, you might get a clean, idiomatic implementation at 10 AM, and an unhandled null pointer or hallucinated dependency at 2 PM.

You cannot treat code as disposable bytecode when you still have to wake up and support it in production at 3 AM.

This non-determinism is precisely why you cannot rely on casual chat prompting. Because the model is probabilistic, you must bound it on both sides. The living specification locks down the intent before the model acts, and deterministic automated verification bounds what is acceptable after it acts.

Tight specifications narrow the model's solution space, while automated verification enforces correctness. That combination is what finally earns trust from the skeptics on your team.

2. Beyond Chat: Demystifying the Harness Rig

When teams first encounter problems with AI code quality, the initial reaction is usually to tweak the prompt: "Be careful with error handling," or "Write production-grade clean code." When that fails, people dump whole folders into massive context windows, only to discover that flooding a model with hundreds of files causes severe distraction and makes the agent miss subtle constraints.

The solution is not more clever chat prompting. It is understanding the core systems formula formalized by Thoughtworks Distinguished Engineer Birgitta Böckeler:

Agent = Model + Harness

The model is the reasoning engine you rent from an AI lab. The Harness Rig is the operational environment your team builds around that model.

In practice, a harness is not just a test runner. A complete harness rig consists of three distinct pillars working together:

• The Context Lake (What the agent knows): Despite the grand name, a team Context Lake does not require an enterprise vector database. It is simply your Git-tracked repository of truth (repo map, API schemas, and active feature specs) fed to the model just-in-time rather than dumped in a prompt.
• The Way of Working (How the agent behaves): The team's conventions, tool access, allowed libraries, and operational boundaries (what the agent can do autonomously vs. when it must ask a human).
• The Verification Rig (How the agent proves correctness): The deterministic compiler checks, linters, and test suites that inspect the output and feed errors back to the model for self-correction.

flowchart TD
    A["Context Lake<br/>AGENTS.md, schemas, living story spec"] -->|"just-in-time context"| B["Coding Agent"]
    B -->|"proposed diff"| C{"Harness Rig: verify.sh<br/>tests, linters, boundary checks"}
    C -->|"fail: stderr fed back"| B
    C -->|"pass"| D["Human review<br/>PR + spec"]

The Two Levels of Intent You Actually Need

Most developers reading about harnesses think: "We don't have custom harness infrastructure. We barely have a generic AGENTS.md file that Cursor or Claude Code generated for us."

You don't need complex internal platforms to start. To get dependable, repeatable output from an agent, you only need to provide two living files:

• Repo-Level Intent (AGENTS.md): This is your team's Way of Working. It doesn't need to be a 1,000-page manual. It simply defines your stack conventions, architectural boundaries (which services can talk to which databases), forbidden dependencies, and how to run tests. It acts as the agent's institutional memory.
• Feature-Level Intent (The Story Spec): This is the contract for the task. It lives in the repository alongside the code, capturing exact endpoints, request/response payloads, and acceptance criteria in unambiguous Given/When/Then terms.

Without written repo intent, every agent session starts like an intern who was hired five minutes ago and never read your codebase. Without written feature intent, the agent is forced to guess your business logic. Providing both is the absolute minimum requirement for consistent AI delivery.

3. Shift-Left Refinement Without Falling Into Waterfall

Whenever you tell experienced engineers that specifications must become the primary source artifact, a red flag immediately goes up:

"Wait. Isn't writing detailed specifications before coding just 1990s Big Design Up Front (Waterfall) dressed up in Markdown?"

This is a valid danger. If a team tries to write 50-page markdown documents for an entire quarter upfront, the LLM will miss half the requirements, and engineers will spend their lives maintaining stale prose.

The difference between modern Spec-Driven Agile and 1990s Waterfall comes down to batch size and collaborative refinement:

• Tiny Batch Size: Waterfall attempted to freeze six months of requirements across an entire release. Spec-Driven Agile bounds the batch size to a single vertical user story (one or two days of execution), demanding crisp completeness on that slice alone before implementation begins.
• The "Four Amigos": In traditional Scrum, refinement often rushes through tickets, slapping points on a two-sentence Jira description because "we'll figure out the details when we start coding." But feeding a two-sentence ticket to an AI agent guarantees hallucinated code. High-leverage squads bring the agent into backlog refinement as the 4th Amigo alongside Product, Dev, and QA.

In refinement, the agent is strictly forbidden from writing implementation code. Instead, it inspects the draft ticket against the Context Lake to surface missing contracts and hidden assumptions:

• "This ticket introduces a partial refund, but billing-service OpenAPI v2 only defines full-void webhooks. Which service versions its schema first?"
• "What is the fallback behavior if the payment gateway times out after 5,000ms?"

The Pragmatic Jira Bridge

Pushing detailed specifications into Git introduces an immediate cultural challenge: Product Managers and Scrum Masters live in Jira, and they will not review Git pull requests.

Expecting non-engineers to maintain Markdown in Git causes process deadlock. Leaving specifications solely in unstructured Jira descriptions blinds your agents. Practical squads bridge this with a clear split:

• Developers maintain the technical spec in Git: During refinement or upon starting a ticket, the developer pairs with the agent to produce the authoritative technical story specification in Git (covering touched repos, contract changes, edge cases, and verification commands).
• Sync a crisp summary to Jira: Once the spec is committed in Git, a short, readable summary is synced back into the Jira ticket (linked directly to the Git spec file). Product managers and stakeholders track status and acceptance criteria on their familiar boards, while the agent executes against the version-controlled specification.

4. The Monorepo Elephant in the Room

Flipping our focus from raw chat prompting to a Git-backed Context Lake, a deterministic Harness Rig, and shift-left story specs provides a predictable foundation for AI development.

Until you try to implement it across your real architecture.

Nearly every tutorial, benchmark, and demo on AGENTS.md and Spec-Driven Development quietly assumes your entire company lives inside a single monorepo. They show an agent running in one root folder, inspecting one directory tree, and executing one test command.

In practice, most enterprise teams I've worked with operate across multi-repo (polyrepo) architectures. A single business feature frequently cuts across a frontend repo, multiple backend microservices, and shared infrastructure definitions—each with its own repository, permissions, and CI pipeline.

When your system spans multiple repositories, where does your Context Lake live? Where do you store cross-repo story specs? And how do you give an agent coherent context across repositories without embarking on a painful monorepo migration?

In Part 2, we will break down the lightweight architecture that solves this: the Sibling Meta-Repo (../team-meta) paired with multi-directory workspace mounting (/add-dir).