Mastering AI Coding: A Team‑Focused Harness Engineering Implementation Guide

Why Harness Engineering?

AI coding tools can generate code at near‑zero cost, but delivering high‑quality, maintainable code remains difficult. The authors identify three fatal problems that arise when AI is used without constraints:

Architecture chaos : agents pick arbitrary libraries, leading to a tangled code base that is hard to refactor.

Context avalanche : after a few dozen files the model forgets earlier naming conventions (e.g., user_id becomes uid), causing bugs.

Loss of maintainability : the generated code becomes a black box that only the AI understands.

Harness Engineering solves these issues by adding a systematic “harness” layer that supplies constraints, shared knowledge, and state management to the LLM.

Core Idea

An Agent is defined as Model + Harness. The model provides intelligence; the harness supplies tools, memory, and rules that turn raw generation into disciplined development.

Six Pillars of Harness Engineering

Context Management – Progressive disclosure via an AGENTS.md index (≈100 lines) that points to detailed spec files, change directories, and layered knowledge. This keeps the prompt size small while allowing the AI to drill down when needed.

Tool System – Three categories of external capabilities:

MCP (Model Context Protocol) : adapters for databases, code repositories, APIs, CI/CD, monitoring, etc.

Skills : reusable, domain‑specific procedures (e.g., rainbow-config for a configuration service, skill-creator to auto‑generate new skills).

Knowledge Base : mounted iWiki docs, code repositories, or custom markdown files that inject business context.

Execution Orchestration – The “3+1 Phase” workflow (Planner → Generator → Evaluator → Archiver) orchestrates multi‑agent collaboration. Each phase has a dedicated role and produces a concrete artifact (requirements, code, test results, archive).

State & Memory – Short‑term session memory, persistent Memories across sessions, and long‑term Git‑backed Spec Deltas that record every design decision.

Evaluation & Observability – Four verification layers (L1 syntax, L2 unit tests, L3 rule compliance, L4 architectural impact). Automated tools such as go build, go test, and golangci‑lint are invoked, followed by optional human review.

Guardrails & Recovery – Hard rules (e.g., “all APIs must have Swagger annotations”), soft constraints (prefer internal utilities), safety policies (auto‑generate SQL scripts for DB changes), and automatic Git rollback on compile failures.

Implementation Roadmap

The adoption plan is split into three phases.

Phase 1 – Foundation

Install the CodeBuddy IDE plugin (VS Code, JetBrains, CLI).

Select a model (Claude‑4.6‑Sonnet, GPT‑5.4, DeepSeek‑V3.2, etc.) based on task complexity and data‑sensitivity.

Enable Memories so the assistant remembers language preferences, naming conventions, and logging standards.

Create reusable Commands (e.g., /init, /spec-create, /spec-plan) that act as templated prompts.

Phase 2 – Tool Integration

Add MCP servers via a mcp.json file. Example for a MySQL MCP:

{
  "mcpServers": {
    "db-mysql": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-mysql"],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "readonly_user",
        "MYSQL_PASSWORD": "${DB_PASSWORD}",
        "MYSQL_DATABASE": "your_database"
      },
      "timeout": 10000,
      "transportType": "stdio"
    }
  }
}

Mount knowledge bases in the Knot platform (iWiki, code repo, custom markdown) and enable automatic reference.

Publish team‑wide Rules (global, language‑specific, security) through Knot so every developer loads them automatically.

Seed the .codebuddy/skills/ directory with business‑level skills (e.g., rainbow-config).

Phase 3 – Continuous Improvement

Adopt the 3+1 Phase SDD workflow for every feature (see below).

Archive completed .codebuddy/plan/ work in .codebuddy/plan/archive/ to keep a long‑term knowledge base.

Run the harness-audit skill regularly to score compliance and surface gaps.

3+1 Phase Workflow

Phase 1 – Plan : Provide a natural‑language description; the Planner generates requirements.md. Human reviews and creates task.md.

Phase 2 – Generate : The Generator reads the spec, loads relevant Rules, Skills, and MCPs, then writes source code and unit tests.

Phase 3 – Evaluate : The Evaluator runs L1–L4 checks, reports violations, and may reject the PR.

Phase 4 – Archive : The Archiver commits the spec delta, updates the knowledge base, and stores the artifact under .codebuddy/plan/archive/.

Each phase is driven by a dedicated agent role (Planner, Generator, Evaluator, Archiver) and can be invoked from the IDE or the web UI.

Key Artifacts

AGENTS.md – a concise (~100 line) index that describes the project, architecture layers, directory layout, and common commands. Example excerpt:

# AI Development Assistant

## Project Overview
This is a Go micro‑service using the Gin framework.

## Architecture
- Controller → Service → Repository → Model

## Directory Structure
- internal/   # business logic
- pkg/        # shared utilities
- api/        # OpenAPI / Swagger specs

## Common Commands
- `go build ./...`
- `go test ./...`
- `golangci-lint run`

Rules – markdown files under .codebuddy/rules/ with front‑matter (type, description, globs) that encode hard constraints (e.g., “no business logic in controllers”) and style guidelines.

Skills – self‑describing YAML/markdown files that expose a name, description, pre‑conditions, step‑by‑step instructions, and code templates. Example front‑matter for a Rainbow configuration skill:

---
name: "rainbow-config"
description: "Operations for the Seven‑Color (Rainbow) configuration service. Includes init, query, and watch."
---
## Preconditions
- Import `pkg/rainbow`
- Set APP_ID and GROUP env vars

## Steps
1. Initialize connection
2. Query a KV group
3. Register change listener

## Notes
- Use exponential back‑off for retries
- Cache results for 5 minutes

Knowledge Base Usage

Three access patterns are supported:

Explicit reference : type @KnowledgeBase and pick a specific library.

Automatic reference : enable the auto‑lookup switch; the assistant pulls relevant docs without prompting.

Team sharing : publish a knowledge base in Knot so every member can import it with a single click.

Standard Operating Procedures (SOPs)

SOP‑A: New Feature Development

Switch to Plan mode and ask the assistant to generate a requirements.md for the feature.

Review the spec, add acceptance criteria, and commit the file.

Run Agent mode to generate task.md, source code, and tests.

Let the Evaluator run L1–L4 checks; fix any failures.

Archive the work.

SOP‑B: Bug Fix

Open a single‑PR branch per bug.

Write a reproducible test that captures the failure.

Commit with the format fix: [module] description (#issue).

Run the Evaluator before merging.

SOP‑C: AI‑Assisted Code Review

Before merging, invoke the assistant with a diff and a checklist (syntax, tests, rule compliance, security).

Address any reported issues, then perform a manual review.

Red Lines (Non‑Negotiable Rules)

Never code before a concrete Spec exists.

All project‑level Rules must be version‑controlled in the repository.

Reusable logic must be captured as a Skill.

Critical metadata (e.g., DB schema) must be accessed via MCP, not duplicated.

Every change must have a clear, conventional commit message.

Anti‑Pattern Checklist

Giant one‑shot prompts – replace with incremental Plan → Generate steps.

Skipping spec review for “simple” tasks – even small changes need a spec.

Stale Rules – schedule monthly reviews.

Over‑loading MCPs – only enable P0/P1 servers.

Monolithic Skills – keep each Skill focused on a single responsibility.

Blind trust of AI output – always run the Evaluator and a human review.

Compliance Audit Skill – harness-audit

The harness-audit skill evaluates a repository against seven dimensions, produces a numeric score (out of 100), grades each dimension, and emits actionable recommendations.

Scoring Dimensions

AGENTS.md (15 %)

Rules (20 %)

Skills (15 %)

MCP configuration (10 %)

Plan/SDD workflow (15 %)

Project engineering conventions (15 %)

Commit message quality (10 %)

Sample Report Excerpt

Overall Score: 75 / 100  Grade: A (Excellent)

AGENTS.md          14/15  93%  🟢
Rules              18/20  90%  🟢
Skills             12/15  80%  🟢
MCP                 0/10   0%  🔴
Plan                12/15  80%  🟢
Engineering        13/15  87%  🟢
Commit Conventions  6/10   60%  🟡

Key Findings:
- No <code>mcp.json</code> – AI cannot read live DB schema.
- Commit messages often lack type/scope.
- Completed plans are not archived.

Recommendations:
P0: Add a DB MCP (30 min).
P1: Configure a <code>commit‑msg</code> hook to enforce <code>type: [scope] description</code>.
P1: Create <code>.codebuddy/plan/archive/</code> and move finished specs there.

The audit can be run locally ( /audit project) or against a remote Git repo via the Knot MCP.

Maturity Roadmap

Phase 1 – Foundation (1‑2 weeks): install CodeBuddy, set up Memories, define Commands, create initial Rules and AGENTS.md.

Phase 2 – Tool Integration (2‑4 weeks): add DB and iWiki MCPs, publish team Skills, adopt the 3+1 Phase for a pilot feature.

Phase 3 – Continuous Improvement (ongoing): run harness-audit quarterly, refine Rules, expand Skills, and automate plan archiving.

Quick Wins

Add a minimal mcp.json for the primary database (≈30 min).

Create .codebuddy/plan/archive/ and move finished specs there (5 min).

Install a commit‑msg Git hook to enforce the type: [scope] description format (≈20 min).

Suggested Audit Cadence

Initial audit when a repository is first onboarded.

Quarterly team audit to track improvement.

Pre‑merge audit for high‑risk changes (optional).

Monthly Knot‑platform audit to compare across projects.

Takeaway

Harness Engineering turns AI from a “free‑form code generator” into a disciplined development partner by:

Embedding hard constraints (Rules, Guardrails) directly into the prompt.

Providing persistent, version‑controlled knowledge (Specs, Knowledge Bases, Skills).

Orchestrating multi‑agent workflows that mirror traditional software‑engineering stages.

Automating compliance checks so teams can focus on solving business problems rather than policing code quality.

When the harness is in place, the cost of delivering good code drops dramatically while the quality baseline stays high.