| name | aiase-harness |
| description | Harness Engineering โ how to build the integrated environment (CLAUDE.md/AGENTS.md, hooks, skills, commands, structured state) that makes AI agents work reliably across sessions. Load when the user asks about CLAUDE.md, AGENTS.md, hooks, harness design, or Claude Code project configuration from the AIASE course. |
Harness Engineering
From AIASE 2026 (NCKU), Week 5. The harness is the deterministic shell that wraps the probabilistic LLM core โ it defines what cannot be negotiated, enforces rules the model cannot override, and maintains state across sessions.
"You cannot skip layers. Poor prompt engineering breaks context engineering; weak context engineering breaks harness engineering."
Three-Layer Hierarchy
| Layer | Focus | Scope |
|---|
| Prompt Engineering | Craft single-prompt wording | Individual interactions |
| Context Engineering | Timing and format of information delivery | Session-level design |
| Harness Engineering | Integrated orchestration (commands, hooks, skills, agents) | Multi-session system architecture |
Six Harness Components
| Component | File/Path | Function |
|---|
| Context Management | claude-progress.txt, feature_list.json | Session continuity and state tracking |
| System Prompt | CLAUDE.md / AGENTS.md | Role definition + invariant rules |
| Lifecycle Hooks | settings.json | Event-driven control (pre/post-tool, stop, notification) |
| Sub-agents | .claude/agents/*.md | Role-specific agent definitions |
| Skills | .claude/skills/*/SKILL.md | Modular domain knowledge injection |
| Slash Commands | .claude/commands/ | Repeatable multi-step SOPs |
Also: init.sh โ ensures clean environment setup across sessions.
AGENTS.md / CLAUDE.md: Standard 6-Section Structure
# Project Overview
Objectives and scope.
# Tech Stack
Languages, frameworks, databases, ORMs.
# Architecture & Directory Structure
Layered design and file placement rules.
# Coding Conventions
Naming, async patterns, dependency injection, PascalCase, etc.
# Testing Protocols
Unit test structure, mocking rules, pre-commit validation.
# PR Guidelines
Commit message format, dependency direction checks.
Keep it under ~100 lines. Use it as a table of contents pointing to /docs subdirs. Oversized AGENTS.md causes context pollution and poor compliance.
Key Design Principles
- Minimal tool sets โ each agent gets only the tools it needs
- Explicit handoff protocol โ next agent doesn't guess; all state is structured
- One thing per session โ incremental progress over all-at-once attempts
- Clean state guarantee โ
init.sh ensures reproducibility
- Structured state โ JSON over Markdown for machine-readable records
DDD Four-Layer Architecture (encode in AGENTS.md)
| Layer | Content | Dependency Rule |
|---|
| Domain | Entities, Value Objects, Aggregates | No external deps |
| Application | DTOs, Use Cases, Validators | Orchestrates domain |
| Infrastructure | Database, Repository, External APIs | Implements data access |
| API | Controllers, Middleware | No business logic |
Dependency direction: API โ Infrastructure โ Application โ Domain (unidirectional, enforced by lint).
Harness Evolution Principle
"Every harness component encodes assumptions about model limitations. Prune scaffolding as models improve."
- Stage 1 (Sonnet 4.5): Context Reset mechanism needed; self-eval failure identified
- Stage 2 (Opus 4.5): Sprint structure + GAN feedback loop (Planner/Generator/Evaluator)
- Stage 3 (Opus 4.6): Simplified harness; end-of-run eval sufficient
Anti-Patterns
| Mistake | Impact | Fix |
|---|
| Oversized AGENTS.md | Context pollution | Keep ~100 lines; use as table of contents |
| Stale documentation | AI learns outdated rules | Automate doc maintenance via sub-agent |
| No reset mechanism | Context anxiety builds | Add intentional compaction triggers |
| Missing init.sh | Session start inconsistency | Codify clean-state boot sequence |
Agentic Project Checklist
See also: [[aiase-sdd]] for spec writing, [[aiase-rpi]] for the research-plan-implement workflow, [[aiase-multi-agent]] for agent team design.
