← Back to the summary

Harness Engineering: The Pre-Development Ritual That Keeps AI-Generated Codebases from Rotting

Core argument: The success or failure of a Vibe Coding project does not depend on how powerful the AI model is, but on whether you have established an engineering process to harness the AI. I call this methodology Harness Engineering.

1. The Problem: Why do Vibe Coding projects always "start fast and then collapse"?

The typical curve of Vibe Coding looks like this: the project advances extremely quickly in the early stages, and a decent prototype can be built in a few days; but as it progresses, the code becomes messier, the cost of changes gets higher and higher, and eventually the entire project turns into a "shit mountain," getting worse with every change until it collapses.

What's the problem?

It's not that AI isn't strong enough. The problem lies in a common misconception—many people think Vibe Coding is just throwing work directly to the AI and then going for a coffee.

The real problem is that you lack a set of engineering processes to harness the AI. It's like a construction site: you have the best workers in the world (AI), but without blueprints, construction standards, or quality inspections, the building you put up will definitely collapse.

2. The Solution: The Three-Layer Pyramid of Harness Engineering

                    ┌─────────────────┐
                    │  Harness         │
                    │  Engineering     │
                    │  Engineering     │
                    │  processes to    │
                    │  harness AI      │
                    └────────┬────────┘
                             │
          ┌──────────────────┼──────────────────┐
          │                  │                  │
    ┌─────▼─────┐     ┌─────▼─────┐     ┌─────▼─────┐
    │ Pre-       │     │ During     │     │ Quality   │
    │ Development│     │ Development│     │ Gate      │
    │ Planning   │     │ 5 Key      │     │ Git as    │
    │ is         │     │ Points     │     │ Gatekeeper│
    │ Everything │     │            │     │           │
    └─────┬─────┘     └─────┬─────┘     └─────┬─────┘
          │                  │                  │
    ┌─────▼─────┐     ┌─────▼─────┐     ┌─────▼─────┐
    │ Set       │     │ Small-step │     │ Version   │
    │ Blueprints│     │ Iteration  │     │ Rollback  │
    │ Lay       │     │ Context    │     │ Change    │
    │ Foundation│     │ Management │     │ Tracking  │
    │ Establish │     │ Acceptance │     │ Code      │
    │ Rules     │     │ Loop       │     │ Review    │
    └───────────┘     └───────────┘     └───────────┘

The entire Harness Engineering system consists of three pillars: 9-step pre-development planning (Set Blueprints → Lay Foundation → Establish Rules), 5 key points during development, and a quality gate centered on Git. Let's unpack them layer by layer.

3. Pillar One: The 9 Steps Before Development—"Planning is Everything"

This is the thickest base of the pyramid. The time invested in the planning phase will be repaid tenfold during the development phase.

Phase One: Set Blueprints (Finalize Requirements and Design)

Before writing a single line of code, thoroughly nail down "what to do."

Step 1: Elicit Requirements—Like Chatting with a Friend

Don't jump straight into writing code. First, chat with Claude and pour out all the ideas in your head:

Pain Points: Is this problem painful enough? Is it still unsolved? Is there a real market?
Target Users: Who will use it? In what scenarios?
Core Features: What should it ideally be able to do?

This step does not pursue rigor; it pursues information volume and coverage. Your goal is to turn vague ideas in your head into language the AI can understand.

Step 2: Output a PRD Document, and You Verify It

Have the AI organize the chat content from the previous step into a structured PRD document (Product Requirements Document), which should at least include:

Feature list
User flows
Page inventory
Acceptance criteria for each feature (boundary definition)

The last item is the most critical. For example—

❌ Unqualified writing: "Users can log in."

✅ Qualified writing: "After a successful login, redirect to the home page (if the user was intercepted from a page requiring login, redirect back to that original page); upon login failure, display the specific error reason (wrong password / account does not exist / network anomaly), with the error message shown below the input field in red text."

Without acceptance criteria, the AI will write more and more divergently. It will keep "optimizing" a feature without knowing when to stop, eventually causing the code to bloat out of control.

Step 3: Pre-determine the Visual and Page Framework

Before the logic code, first lock down the UI style. There are two methods:

Find 2-3 reference websites and tell the AI "follow this vibe"
Let the AI generate several different style proposals for you to choose from

What needs to be finalized in this step: page layout, content partitioning, overall style (minimalist / luxurious / techy).

Why must this step be done before writing features? Because if you don't lock down the UI direction in advance, the AI will constantly tear down and rebuild the UI while writing feature logic—each rebuild is a rework, and it's a chain-reaction rework.

Phase Two: Lay the Foundation (Finalize Constraints and Architecture)

With the blueprints ready, now determine "under what conditions and with what materials to build."

Step 4: Clarify Project Boundaries and Non-Functional Requirements

These are questions the AI won't proactively ask you, but if you don't clarify them, rework is guaranteed:

Dimension	Questions to Clarify
Deployment	Purely local? Or an online public service?
User Scale	A few users? Or thousands of concurrent users?
Data Compliance	Is there user data? Is privacy compliance needed?
Performance Ceiling	Are there hard requirements for page load time?
Cost Constraints	Can paid APIs be used? What is the budget cap?

Security, performance, availability, cost—if these four non-functional requirements are not clearly written down, structural, large-scale rework will inevitably follow.

Step 5: Lock Down the Tech Stack, the More Verifiable the Better

The principle for choosing a tech stack is not "the most advanced," but "the most suitable + the most verifiable."

Suitable: Familiar to the team, active community, mature ecosystem. For example, React + TypeScript + TailwindCSS is a robust combination verified by numerous projects.
Verifiable: Once chosen, you can quickly run it to see the effect, rather than spending three days just setting up the environment.

Write the tech stack into claude.md, making it a global constraint for the AI—the AI will not introduce new dependencies or frameworks without your authorization.

Step 6: Have the AI Produce a Lightweight Architecture Draft

Don't jump straight into drawing UML class diagrams. Have the AI output a lightweight architecture draft covering four dimensions:

How the directory structure is layered (e.g., components/, hooks/, services/, utils/)
What the core modules are (authentication module, data module, UI component library)
What the data models look like (key entities and their relationships)
What the core components are (page-level components, reusable components)

The goal of this step is not to produce a perfect architecture document, but to allow the AI and you to form a consensus on "what the system looks like."

Phase Three: Establish Rules (Solidify Rules and Documentation)

The first two phases produced a large number of decisions. If they are not solidified, the AI will forget 80% of them in the next conversation.

Step 7: Solidify into Documents—The AI's "Permanent Constraints"

Write all decisions into Markdown files in the project root directory. These files serve as the AI's global context:

Project Root Directory/
├── PRD.md          # Product Requirements Document (what to do, acceptance criteria)
├── ARCH.md         # System Architecture Document (how to do it, layered design)
├── Design.md       # Design Specification Document (visual style, component specs)
├── Project.md      # Current Project Phase Document (progress, next steps)
└── claude.md       # Project-level AI Instructions (tech stack, constraints)

Whenever the AI starts a new conversation or a new task, these files are loaded as system prompts, forming permanent constraints for Vibe Coding. The AI won't go off track because the constraints are right in its context.

Step 8: Set Development Standards + Build a Reference Materials Folder

Good code is not written by "AI self-discipline" but by rule constraints. At a minimum, cover:

Coding Standards: Naming conventions, file organization, commenting principles
Error Handling: A unified error handling pattern; don't let the AI improvise everywhere
API Interface Specifications: RESTful conventions, request/response formats, error code conventions
Reference Materials: Give the AI a sample reference (like a well-implemented component) and have it write to that standard

Giving the AI a "standard answer" as a reference is more effective than giving it a hundred rules.

Step 9: Set Up Git and the Quality Gate

Git is not just a backup tool; it is the last gate for quality. Core operations:

Operation	Scenario	Meaning
`git reset --hard`	Code has gone completely off track	Discard all modifications, return to a clean historical node, rewrite the prompt
`git reset --soft`	Some modifications are problematic	Roll back the version but keep working directory changes, adjust locally and recommit
`git restore --staged`	Staging area contains wrong files	Remove files from the staging area but keep working directory changes
`git checkout -- <file>`	A specific file was broken	Discard working directory changes for a single file

Combined with meticulous atomic commits, you can roll back losslessly at any step when you step into a pit, instead of pushing forward with a pile of half-finished code.

4. Pillar Two: 5 Key Points During Development

(The original text did not expand on this section; the following is a supplement of the core points)

Small-step iteration, only change one thing at a time: One prompt should only have the AI complete one clear functional point. If you change too much, you can't review it all, and the AI is prone to losing control.
Context management: Reload context files like PRD.md and ARCH.md at the start of each new conversation to ensure the AI always works within the "rules."
Acceptance closed loop: Every time the AI completes a step, immediately check it against the acceptance criteria in the PRD. If it fails, correct it immediately. Don't let deviations accumulate.
Commit discipline: Immediately commit after each functional point that passes acceptance. Small-step commits = the ability for small-step rollbacks.
Incremental refactoring: After a feature runs through, have the AI do a round of "code tidying" to eliminate duplication, improve naming, and extract common logic—but don't do this before the feature runs through.

5. Summary: One Diagram to Explain Harness Engineering

You (The Decision Maker)
    │
    ├── Set Blueprints ──→ Requirements → PRD → Visual Framework
    │
    ├── Lay Foundation ──→ Non-functional Requirements → Tech Stack → Architecture Draft
    │
    ├── Establish Rules ──→ Document Solidification → Development Standards → Git Gate
    │
    └── Harness AI Dev ──→ Small-step Iteration → Instant Acceptance → Atomic Commits

Core Cognitive Upgrade: Vibe Coding is not you acting as a PM for the AI; it's you acting as the chief engineer, with the AI as the workers. If the chief engineer doesn't draw blueprints, set standards, or check quality, even the best workers can't build a good building.

The essence of Harness Engineering is—turning the act of "harnessing AI" itself into a replicable, verifiable engineering process.