MoAI-ADK implements the Harness Engineering paradigm. Instead of writing code themselves, developers design the environment (the harness) in which AI agents can produce optimal code.

“Human steers, agents execute.” — The engineer’s role shifts from writing code to designing the harness: SPECs, quality gates, feedback loops.

Traditional vibe coding lets the AI generate code freely and then reviews the result manually. Harness engineering is the opposite — it guides AI agents with specifications (SPECs), automated verification, and a continuous feedback loop to produce code of consistent quality.

So what is a harness? It is the entire system that surrounds the base model and orchestrates execution — the layer that decides how the model thinks and plans, how it calls tools, how it perceives and manages context, where it stores its artifacts, and how its results are evaluated. MoAI-ADK is exactly this harness, layered on top of Claude Code.

Harness engineering is where the three core values of v3.0 meet.

The second core value in particular is the key innovation. The realistic near-term path to AI’s recursive self-improvement (RSI) is not modifying model weights directly, but improving the harness around the model. MoAI-ADK takes exactly this path — it recursively improves the harness (skills and agent guidance), not the model.

graph TD
    subgraph Harness["Harness Engineering"]
        direction TB
        SF["Scaffolding First
Generate empty file stubs"] --> FC["Failing Checklist
Register acceptance-criteria tasks"]
        FC --> SV["Self-Verify Loop
Code→Test→Fix→Pass"]
        SV --> GC["Garbage Collection
Remove dead code"]
        GC --> CM["Context Map
Maintain architecture docs"]
        CM --> SP["Session Persistence
Track progress across sessions"]
        SP --> LA["Language-Agnostic
Auto-detect 16 languages"]
        LA --> SF
    end

    style Harness fill:#f0f7ff,stroke:#1565C0

Each component maps to a specific MoAI command:

When /moai run starts, the agent creates the required file structure before writing any code:

src/
├── auth/
│   ├── handler.go      ← empty stub
│   ├── handler_test.go  ← empty test
│   ├── service.go       ← empty stub
│   └── service_test.go  ← empty test
└── middleware/
    └── jwt.go           ← empty stub

This prevents the agent from creating files chaotically and keeps the project structure consistent.

The SPEC’s acceptance criteria are automatically registered as a task list:

- [ ] JWT token issuance endpoint
- [ ] Token verification middleware
- [ ] Refresh token logic
- [ ] Expired token handling
- [ ] 85%+ test coverage

Each item is checked off once it is implemented and its tests pass. Work is complete only when every item is checked.

The core cycle the agent runs autonomously:

graph TD
    A["Write code"] --> B["Run tests"]
    B --> C{"Pass?"}
    C -->|"Fail"| D["Analyze errors"]
    D --> A
    C -->|"Pass"| E["Next item"]

This loop repeats up to 100 times in /moai loop and includes convergence detection (applying an alternative strategy when the same error repeats). If you want to declare the completion condition yourself, use the goal engine (/moai goal "<condition>") — the session keeps working on its own until the condition is met or the turn limit is reached.

The architecture documents generated by /moai codemaps give the agent the full structure of the codebase. With them, the agent can:

• Choose an implementation approach that does not conflict with existing code
• Follow the appropriate patterns and conventions
• Understand dependency relationships and gauge the blast radius

Even if a Claude Code session is interrupted, progress.md records the completed steps:

## Progress
- [x] Phase 1: Analysis complete
- [x] Phase 2: Handler implementation
- [ ] Phase 3: Write tests ← resume here
- [ ] Phase 4: Refactoring

/moai run --resume SPEC-XXX automatically resumes from where it left off.

The harness is not a fixed environment. As the loop runs, observations accumulate, and the harness learns from them and improves its own guidance.

Loop runs → Observations accumulate → Patterns learned → Guidance evolves (approval gate)

Automatic evolution never runs in a closed loop without human oversight. The evaluator and the permission controls sit outside the evolution loop:

• 5-layer safety pipeline — snapshots and rollback (moai harness rollback) let you restore at any time
• User approval gate — Tier-4 auto-updates always pass through user approval
• Constitution system — immutable rules (FROZEN) are excluded from evolution (see Constitution System)

moai harness status      # Check learning status (observation count, patterns, proposals)
moai harness apply       # Apply a proposal (must pass the user approval gate)
moai harness rollback    # Roll back the last apply
moai harness disable     # Disable learning

Fixing the harness is itself an experiment. When a harness component — a rule, agent, or hook — is edited, decision observability applies: each edit records a falsifiable prediction (which failure class stops recurring), and must pass a two-sided check before acceptance — held-in (the edit demonstrably catches the motivating failure) and held-out (existing guards and tests still pass). Rejected edits are preserved on record, so the same failed attempt is never repeated.

When you build your own custom skills or agents, you need to know which assets moai update overwrites and which it preserves. MoAI-ADK cleanly separates the namespaces into “template-managed” (universally distributed) and “user-owned” (user-created).

Skills with the moai-* prefix and moai-harness-* are universal assets provided by the MoAI-ADK package. They are distributed to every user project and are overwritten with the latest template when moai update runs. If you edit these assets directly, your changes will be lost on the next update.

Skills with the hns-* prefix (the canonical namespace generated by the Harness v4 Builder) and the .claude/agents/harness/ directory are owned by the user project. The previous-generation prefixes harness-* / my-harness-* are recognized the same way. moai update never deletes or modifies them; it backs them up before updating and preserves them as-is.

If you want your own domain-specific skills or agents to survive moai update, always use the hns-* prefix (and place agents in .claude/agents/harness/). If you create them with a moai-* or moai-harness-* prefix, they are treated as template-managed and will be overwritten on the next update. When you create a harness with /moai harness "<natural-language request>", the Builder automatically assigns names that follow this rule.

• SPEC-Based Development — How to write the SPEC documents that feed the harness
• TRUST 5 Quality — The five quality criteria the harness verifies
• Constitution System — The immutable rules governing harness evolution