Agents make mistakes. An agent that can modify anything will eventually modify the wrong thing. The harness architecture addresses this by physically separating the areas an agent is allowed to modify from the areas it must never touch.
The principle: permitted mistakes are recoverable. Mistakes in forbidden areas ruin the project.
Core: What Agents Cannot Touch
Core is the part of the project that cannot be recovered if damaged. It contains the system's source of truth about current state, the memory pipeline that provides continuity across sessions, and the agent's behavioral principles. A change to Core requires an explicit decision about why it needs to change.
The test for whether something belongs in Core: "If this file is corrupted, is the system unrecoverable?" If yes, it belongs in Core.
In practice: state machine files, memory consolidation scripts, the context builder that generates the agent's system prompt, and verified historical records all belong in Core. These are files whose correctness is more important than their improvability.
Shell: Where Agents Operate
Shell is everything else — implementation files, configuration, temporary state. An agent that corrupts a Shell file can have its changes reverted. The fail-rollback cycle is safe here.
The important nuance: Shell files can reference Core files, but Core files should not depend on the current state of Shell files. Core defines the system's invariants; Shell implements behavior that varies.
CLAUDE.md as the Harness Brain
Every project using this architecture has a CLAUDE.md at the root. This is the first file a new agent session reads. It must contain:
- The project's current state as of the most recent session — not the state from three months ago when it was written
- An explicit reading order for new sessions
- A clear list of files that must not be modified
- The current implementation status, kept synchronized with actual code
The most common failure mode: CLAUDE.md accurately describes the project as it was six weeks ago. A new session reads it and rebuilds features that already exist, or skips features that are still needed. The document drifts from reality without any agent noticing, because agents read documents before they inspect code.
Health Score and Automatic Rollback (Advanced)
For long-running autonomous projects, the harness can include a health score system. A tracker calculates a score each iteration based on build success rate, test pass rate, and error frequency. A rollback guard watches the three-iteration moving average; if it drops below a threshold, it restores Shell to the last golden snapshot.
This is optional. Most projects do not need it. But if a project has 20+ agent sessions over multiple months, a health score makes the difference between a project that degrades gracefully and one that requires manual recovery.
The Protected File Checklist
| Question | Belongs in |
|---|---|
| If corrupted, is the system unrecoverable? | Core |
| Content accumulated from past verified sessions? | Core |
| Recoverable with git revert if modified? | Shell |
| Listed in CLAUDE.md "Never Touch These"? | Core |
Evolution Log
- 2026-03-23 — Extracted verified patterns from companion bot + game project harness. Organized as a general-purpose architecture prescription. Core/Shell boundary tested across 2 long-running projects over 3+ months.
- 2026-04-01 — Reformatted to current post template. Added health score section and protected file checklist. Verification upgraded to Established based on continued use across both projects.