← Back to the summary

AI Coding Won't Stop Breaking Your Code—Here's the Three-Stage Fix

Article reference sources: Bilibili - AI Lin Zhansheng's video series + online practice supplements + personal exploration and reflection.

This article sorts out several current AI coding practice approaches and where each should be used, providing you with ideas for AI programming governance. I hope it helps you～

Why does AI programming get messier the more you write?

Probabilistic model vs. causal chain model

AI is currently a probabilistic model, not a causal chain model. It generates content based on probability, so it will inevitably make mistakes—not occasionally, but structurally and ineliminably.

This determines the core contradiction of using AI to write code: AI can rapidly produce a large amount of code, but you cannot fully trust it. This document sorts out how to resolve this contradiction—using different means at different project stages to constrain AI's uncertainty within a controllable range. From the "let it run free" of Vibe Coding, to the "write clearly before starting" of Spec, to the "lock it down with processes" of Harness, they are all essentially answering the same question: How to make AI's errors discoverable and catchable when they occur.

AI Coding Overall Framework: Three Stages

From Vibe Coding to Harness Engineering

As a project goes from 0 to 100, governance methods change accordingly:

0→1 (MVP Stage): Vibe Coding, few constraints, let the model freely explore to produce a prototype. Speed and idea validation are most important in the early stage.
1→10 (Initial Operation): Introduce Spec, solidify intentions, boundaries, and decisions into documents, letting AI work within a constrained context.
10→100 (Long-term Stable Operation): Introduce Harness, turning specifications into physical locks that AI cannot bypass.

Stage	Core Method	Constraint Strength	Applicable Scenario	Upgrade Signal
0→1	Vibe Coding	Almost no constraints	Exploration, idea validation	MVP runs through, needs long-term operation
1→10	Spec	Document-guided, relies on AI compliance	Stabilized, needs long-term operation	Documents can't manage, AI doesn't obey
10→100	Harness	Process-enforced, cannot be bypassed	Complex projects, critical functions cannot fail	—

MVP = Minimum Viable Product. Spec = Specification. Harness = Governance framework/guardrail system.

The standard for judging when to upgrade is very direct: When document-based guiding constraints can no longer manage the project, it's time to upgrade. The project has become more complex; merely writing documents to tell AI what to do and what not to do is no longer enough, as AI starts to disobey or fails to execute correctly even when it listens. At this point, more coercive measures are needed. Conversely, rushing to apply Harness before the project is stable will only slow down feedback, like early Waterfall—Thoughtworks specifically warned about this.

Part 1: MVP Stage (0→1) Vibe Coding

Vibe Coding: Let AI Run with the Prototype

For small projects, early project stages, and exploration phases, prioritize Vibe Coding. Don't rush to pile on rules; writing too many constraints too early can limit a smart model's performance. Models often provide more fitting solutions when unconstrained. When Karpathy (former Tesla AI Director, OpenAI founding member) coined the term "vibe coding," the original intent was to let AI run with the prototype.

But "letting go" doesn't mean "neglecting." In the MVP stage, two things are worth doing right at the start. They don't take much time but save a lot of rework later.

First Step at the Start: Discuss the Project's Causal Chain Clearly with AI

Before writing the first line of code, first clarify the entire project's causal chain with AI:

Why does this project exist? What problem does it solve, and what does it not solve?
What is the project? What is it roughly, and what are the core features?
What effect should it achieve? What experience should the user have after using it?
What won't it do? Which features are explicitly out of scope for this version?

This information doesn't necessarily need to be written into a formal document, but it must be clearly communicated in the conversation, allowing AI to build an overall understanding of the project. No matter how AI switches sessions or restarts later, this set of causal chains serves as its "onboarding training material."

Spec writes causal chains

In one sentence: Spec doesn't write an encyclopedia; it writes causal chains. You may not understand code, but you must understand the business and constraints. Clearly explaining "what it is, why, what effect is desired, where the boundaries are, and what is forbidden" is far more useful than writing a pile of technical details.

Define AI Collaboration Norms

Besides the project information itself, another thing is recommended to be set at the very beginning: How your Agent should assist you in your work.

This is not a project specification, but a collaboration specification—defining not "how this project should be done," but "how AI and humans cooperate." For example:

When encountering uncertainty, should it directly provide a solution or ask you first?
Before modifying code, should it explain what was changed and why?
After completing a feature, should it proactively run tests and tell you the results?
Which operations require your confirmation before execution?

These things can be written in AGENTS.md or a collaboration document in the project root directory. Once clearly defined, AI's behavioral style stabilizes, and you don't need to re-teach it every time you start a session.

Engineering Governance After MVP: Refactor First to Lay the Foundation

It's fine to use Vibe Coding to quickly build MVP features in the early stage, but when you decide to enter the engineering governance stage, don't forcefully patch specifications onto a mess. First, refactor the project—clarify the structure, separate boundaries, and add a testing skeleton. Once the foundation is solid, the subsequent Spec and Harness can be attached. Writing specifications on a pile of messy code will still lead AI astray.

Another dimension for judging whether to enter engineering governance: Does this project need to run stably and long-term? One-off scripts and demo demonstrations just need to run; for production code that requires long-term maintenance, multi-person collaboration, and user-facing features, the investment in governance is worthwhile. BCMS states that mature engineers do "vibe coding" for prototypes and "spec-driven development" for any code going live.

Refactor first, then establish specifications

Part 2: Initial Operation (1→10) + Spec Coding

The project is running, the MVP has validated the idea, and the next step is to make it run stably. The signal at this stage is very clear: changing A breaks B, logic conflicts, and modifications trigger new problems. When AI collaboration starts to drag down efficiency, it's time to introduce Spec. Thoughtworks listed SDD (Spec-Driven Development) as the most critical engineering practice for 2025, reasoning that AI makes prototyping too easy, causing people to neglect engineering standards and produce piles of unmaintainable throwaway code.

Three layers of information piece together a clear path

The diagram above summarizes the core of the Spec stage—piecing together three layers of information: intent, context, and process, to form a clear path, letting AI know where to go.

1. Accurately Express Intent and Document It

From the start, use language to clearly express intent: what was changed and why. Vague intent is the root cause of AI going off track. The industry's most extreme practice of this is "spec as prompt"—write the specification before writing code; the code is merely a product of the specification (BCMS). Microsoft expresses it as "align first, then let AI accelerate execution," with spec running through the entire lifecycle.

One more layer needs to be added here: Intent is not just "what to do," but also includes "explicitly what not to do" and "why this decision was made."

Points explicitly to do and points explicitly not to do should both be written into the project specification. If the boundaries of what not to do are not clearly drawn, AI will arbitrarily expand outward and stuff in features you didn't ask for.
Major decisions and their reasons should also be documented. For example, if you make an architectural choice that might affect the direction of subsequent features, write this decision and the reasoning behind it into the document to inform AI. Otherwise, during later iterations, AI won't understand the trade-offs made at the time and might "optimize" away a design you deliberately preserved.

This layer is called "project long-term memory" in the industry—AGENTS.md, knowledge graphs, and ADR (Architecture Decision Record) are all carriers. The experience is: knowledge must be deposited into version-controlled documents or code comments for AI to "see"; verbal agreements are useless (CSDN Practice Summary).

2. Control Context

Enable AI to quickly locate where to make changes and where the changes might ripple, following the project structure and framework. This corresponds to the first decision node in the flowchart "Location clear?":

Location clear → Directly start modifying.
Location unclear → First locate (debug, analyze parameters), don't let AI confidently spout nonsense in the wrong context.

Implementation methods:

Don't feed the entire repository to AI. Use @Files or a dedicated docs/ directory to provide only necessary "knowledge slices," avoiding attention dispersion caused by long texts.
Use MCP (Model Context Protocol) to eliminate information gaps. Dewu Team connected two MCPs: one directly linked to API documentation, and one directly reading Feishu cloud documents, allowing AI to obtain real context without relying on human relay.
AGENTS.md as a directory, not an encyclopedia. It only tells AI where to find deeper information—where the architecture docs are, where the design principles are, where the execution plan is. About a hundred lines is enough; it's not packed with knowledge (36Kr).
Spec itself is a context management tool, allowing AI to work within a "constrained context" rather than freely playing globally.

3. Context Governance: Switch Sessions When Needed

AI is always on its first day at work

AI is always on its first day at work for this project. Every new session, it starts from scratch.

When a conversation's context has become chaotic, or is particularly long and about to trigger automatic compression, don't force it—switch to a new conversation. In the new clean context, re-inform it through Spec (or other documents):

What the project is — the current project's goals and scope.
What needs to be done now — what the task is this time.
Decision specifications — what key decisions were made previously and why.
Behavioral boundaries — what should be done, what shouldn't.

This is what the diagram above says—Spec is AI's onboarding training. For every new session, use Spec to give it a clean onboarding, and the generation quality will be much higher than struggling through a polluted long conversation.

4. Establish Fixed Processes

Establish fixed processes: judge first, then execute

For processes that are stable and repeatedly executed, don't re-issue prompts each time; instead, write skills/scripts to let AI stably perform the same task, reducing inconsistency and error probability.

The industrialized version is the SDD four-stage cycle, with human checkpoints at each stage:

SDD four-stage cycle

Specify (what to write, why) — the slowest and most important; time spent here yields a 10x return downstream.
Plan (how to do it) — produces plan.md, architecture, data models, technology choices.
Tasks (in what order) — break down into independently deliverable atomic tasks; the list should be detailed enough that "a junior engineer could follow it."
Implement (go do it) — agent executes tasks one by one, each task is accepted upon completion; if it doesn't meet standards, iterate within spec boundaries, don't run free (BCMS).

The key is human review at each stage boundary: spec is reviewed before entering plan, plan is reviewed before breaking down tasks, tasks are reviewed before implementation. This is the source of its "predictability." GitHub Spec Kit solidifies this process into slash commands: /constitution, /specify, /clarify, /plan, /tasks, /implement, /checklist, model-agnostic.

5. Formulate Specifications and Acceptance Criteria

Give AI clear coding standards + acceptance criteria; don't let it define "done" by itself.

Dewu Team implemented a "Constraint + Demonstration + Visual" three-layer specification system:

Layer	Carrier	Function
Constraint	`CLAUDE.md`	Hard rules, cannot be violated
Demonstration	Rules	Provide sample code, follow it
Visual	Visual drafts	Align UI (User Interface), prevent deviation

Just saying "be standardized" is useless; you need to provide samples.

Acceptance criteria must be executable. BCMS recommends EARS notation (Easy Approach to Requirements Syntax), five sentence patterns that turn vague requirements into unambiguous, testable statements that AI can follow to generate code and then generate tests. Paired with AI version TDD (Test-Driven Development): first let AI write test cases according to spec, then write business code. Microsoft calls this acceptance step Validate—verifying whether the output matches the spec.

6. Perform Final Review, Add Regression Tests for Key Functions

Finally, there must be a closing process: run tests + human review of whether AI output meets requirements. Human-in-the-loop is not optional; it's the foundation of SDD (Thoughtworks).

Review focuses on preventing AI failure modes. Dewu Team summarized several categories in their review:

Failure Mode	Manifestation	Defense Means
Intent Drift	Code runs but deviates from requirements	Spec clarifies intent + human review
API Hallucination	Fabricates non-existent interfaces	MCP directly connects to real docs
Scale Decay	Loses control as project grows	Engineering refactoring + Harness

BCMS also warns of two pitfalls: don't let agents run freely without boundaries, and don't skip the clarify stage—time saved on disambiguation far outweighs the cost of rework.

For core, critical, and must-be-stable content in the project, add an extra step: after each modification of related functions, have AI run regression tests. This is not full-scale testing, but targeted regression for critical paths—functions like payment, authentication, and core data flows, where any failure is fatal. Automatically verify they haven't been broken with every change. This saves much more trouble than discovering problems only during final human review.

7. Continuously Iterate, Treat Specifications as Living Documents

Specifications, documents, and engineering systems are not written once and done. During continuous iteration, constantly optimize, deposit, organize, and update them:

Every time you discover a mistake AI repeatedly makes, add a rule or a skill.
Every time you complete a major feature, write back the pitfalls encountered and decisions made into the spec and ADR.
The engineering system (tests, CI (Continuous Integration), lint, hooks) is continuously reinforced as the project evolves.

Specifications are living documents, version-controlled and iterated alongside the code. A spec that is written and then discarded is equivalent to having none.

Spec Stage Tools

Tool	Core Features	Suitable For
Cursor	Plan Mode + `AGENTS.md`, inline diff for fast PR review	Lightweight route, fast iteration
Claude Code	Plan Mode + `claude.md`	Already in the Claude ecosystem
GitHub Spec Kit	Open source, model-agnostic, full set of slash commands	Cross-tool unified process, not locked to a vendor
Superpowers	Series of structured skills, enforces RED-GREEN-REFACTOR (relies on Test-Driven Development TDD)	Using Claude Code, requires strong engineering discipline
OpenSpec	Lightweight, framework-agnostic	Independent developers

Superpowers is an open-source framework created by Jesse Vincent (obra), enforcing "write a failing test first, then write code; code without tests will be deleted by the framework." The core sentence is—"Don't make AI smarter, make AI more disciplined" (Emelia.io, Marc Nuri, Datawhale).

Part 3: Long-term Stable Operation (10→100) + Harness Engineering

When to Introduce Harness

In the 1 to 10 stage of a project, Spec can manage most problems. But as the project continues to grow, complexity reaches a critical point—merely relying on document-based guiding constraints can no longer keep the entire project running well.

The signal is this: Spec is written, AI has read it, but it still makes the same mistakes; documents get longer and longer, but AI becomes less and less obedient; some functional failures are catastrophic, and just "telling AI not to mess up" is no longer enough. What you need is "AI cannot mess up."

This is when Harness should be introduced. The principle is: For some functions in the project that must absolutely be guaranteed error-free, use mandatory specifications and processes to do it, rather than relying on AI's compliance.

What is Harness

Phodal draws the control plane of AI coding as four layers expanding outward:

Layer	Name	Manages	Constraint Strength
Layer 1	Rule	AI's default behavior	Weakest, relies on compliance
Layer 2	Spec	Scope and boundaries of a single change	Medium, document-guided
Layer 3	Loop	Dynamic execution mechanism	Stronger, process constraint
Layer 4	Harness	Organizational governance	Strongest, physical lock

Four-layer control plane expanding outward

Harness is the outermost layer, aggregating the previous three layers into executable governance. Define it in one sentence: Harness answers not "how strong is AI," but "why is this change trustworthy enough."

It is called the "governance operating system" and "guardrail system" for AI programming—through "rules as code" and automated feedback, it encloses AI's creativity within a trustworthy boundary (CSDN).

Core Mechanisms

Specifications alone are "soft constraints"; Harness turns them into "hard enforcement":

	Spec (Soft Constraint)	Harness (Hard Enforcement)
Constraint Method	Document-guided, relies on AI compliance	Process and tool enforced, cannot be bypassed
Can AI ignore it?	Yes	No
Typical Means	`AGENTS.md`, specification docs, ADR	CI, pre-commit hook, agent role isolation
Applicable Stage	1→10	10→100

Soft constraints vs. hard enforcement

Specific mechanisms include these:

Generator-Evaluator Loop. AI writes code → another AI (or validator) reviews → fails, sent back to rewrite → until it passes. Traditional code review is human reviewing human; in Harness, it becomes agent reviewing agent (Tencent Cloud, Runoob).
CI as Harness. In Carlini's practical review, Claude frequently broke existing features in the later stages of the project. The solution was not a stronger model, but stricter CI—"using harness-layer solutions to solve model-layer problems." Checks like lint, typecheck, tests, and pre-commit are moved forward into hooks; violations cannot pass (Phodal).
Role Isolation. The agent responsible for research can only read, not write; the one responsible for planning cannot touch files, only produce plans; the one responsible for coding only writes; the one responsible for verification only checks. Each role's tool permissions are fixed from the factory (36Kr, AI Xiaoquan).
Automated Verification Loop. AI writes → automatic testing → automatic log/monitoring analysis → automatic repair, with humans only intervening at key decision points (CSDN).
Preventing "Fake Completion." Use JSON structures to track feature status (machine-readable, hard for AI to arbitrarily change). The working agent can only mark "pass/fail" and must have genuinely tested before marking passing. Markdown is only used as signposts, not as a strict process (36Kr).

Why This Layer Cannot Be Omitted

If the previous three layers (Rule/Spec/Loop) are not built, Harness can at most pick up trash at the end; if the previous three layers are established, Harness has organizational governance significance (Phodal). It does not replace specifications; it turns specifications into physical locks that AI cannot bypass. When summarizing Codex's long-task experience, OpenAI also pointed out: long tasks are more reliable not because of longer prompts, but because of the structured context and clear "done when" routines provided by the harness.

Harness Stage Tools

Tools at this layer only took shape in early 2026. The term "harness engineering" is generally attributed to Mitchell Hashimoto (HashiCorp co-founder, creator of Terraform) in his February 2026 blog post. LangChain subsequently formalized it into a formula: "Agent = Model + Harness"—what determines AI's reliability is not how strong the model is, but the shell you wrap around it (Augment Code).

Tool	Core Features	Suitable For
Claude Agent SDK	The harness behind Claude Code, automatically compresses long sessions; native hooks (PreToolUse intercepts dangerous operations, PostToolUse runs lint/test, Stop prevents fake completion) turn rules from "relying on AI compliance" to "unenforceable bypass" (Official Docs)	Embedding agents in products
Codex CLI	Open-source terminal agent, reliable for long tasks	OpenAI ecosystem, CLI workflows
LangGraph + Deep Agents	Stateful orchestration + sub-agent delegation	Multi-agent pipelines
Composio	250+ SaaS APIs packaged as agent actions	Connecting to many external services
CI/CD	lint/typecheck/tests moved forward to hooks	Every project should have it

CI is the most cost-effective harness. Carlini's practical review proved: when the model frequently breaks features later on, the solution is not a stronger model, but tightening CI.

Summary: Where to Start

Summarize the entire article in one sentence: AI will inevitably make mistakes. Your job is not to eliminate errors, but to ensure that when errors occur, they can be discovered and caught.

Three stages, three sets of methods, progressing with project maturity:

0→1: Vibe Coding, few constraints, get the prototype running. The only thing to do in advance is to clearly explain the project's causal chain to AI—what it is, why, what effect is desired, what not to do. Don't rush to pick tools; use the IDE you are most comfortable with and focus your energy on discussing the project's causal chain clearly with AI. Piling on tools is just creating work for yourself.
1→10: Introduce Spec, solidify intent, context, and process into documents, letting AI work within a constrained track. Spec tool selection is about "how to write clearly." If you want cross-tool compatibility without vendor lock-in, choose GitHub Spec Kit; if using Claude Code and need strong discipline, choose Superpowers; for independent developers starting lightweight, choose OpenSpec; if already deeply invested in a particular IDE, use its native Plan Mode + AGENTS.md. To test the waters, pick a small feature to be implemented this week, spend 30 minutes writing it into a spec with EARS acceptance criteria, run it once, and compare the result with your usual vibe coding—the difference will speak for itself (BCMS).
10→100: Layer on a Harness, turning specifications into physical locks that AI cannot bypass. Continue using Spec tools, and layer Harness on top. Harness selection is about "how to lock"—if you already have CI, first tighten lint/typecheck/tests/pre-commit (zero-cost first step); to embed agents, choose Claude Agent SDK or Codex CLI; for multi-agent pipelines, choose LangGraph + Deep Agents; to connect to many external APIs, choose Composio. Don't build the full set all at once; treat where it hurts (Faros.ai).

The upgrade signal is simple: When the current means can no longer manage AI, upgrade. Don't pile on in advance, and don't delay upgrading.

In short, judge first, then execute. Facing a complex project, don't let AI directly start writing code. First, perform task routing—judge whether this is a simple modification or requires a fixed spec + harness process. If the judgment is correct, you'll get twice the result with half the effort.

Reference Reading

Materials referenced when writing this article: