Why AI Coding Agents Keep Falling Over: A Three-Layer Architecture and Self-Healing Mechanism

Symptom: Impressive in a demo, broken by Tuesday

Deploy a fix with Claude Code, Cursor, or Codex. It touches the right files, writes a decent commit message, runs the deploy, and then a small issue surfaces: CRLF line endings break a shell script on the server, an environment variable is read from the wrong file, a webhook secret rotates on redeploy. The agent notices the failure, "fixes" it by retrying or resetting state, and then reports success. Next week, in a fresh session, it repeats the exact same thing.

This isn't the model being dumb — it's determined by the shape of the work. There's a structural mismatch between single-step tasks and real production tasks.

The arithmetic problem: errors compound

Suppose the agent is right 90% of the time on each step — generous, for things like "parse this API response and write the correct line." Chain steps together and the probabilities multiply:

Steps executed by the model	Success rate
3 decisions, rest done by scripts	0.9³ = 73%
5 steps	0.9⁵ = 59%
10 steps	0.9¹⁰ = 35%

Real tasks (fetch, parse, transform, validate, write, deploy, verify) often involve ten to fifty steps. If the model executes every step by improvising code or commands on the fly, the overall job's success rate collapses and you have to watch it the whole time.

The fix isn't better prompts — it's taking the steps that have a single correct answer out of the model's hands.

The three-layer architecture: Directive, Orchestration, Execution

The author calls this the D.O.E. model. Each layer does exactly one kind of work, and the boundaries between layers are the key.

Layer	Nature	Where it lives	Who changes it
Directive	Intent expressed in prose: goal, inputs, tools, output, edge cases, verification	directives/*.md	Written by humans; the agent appends learnings
Orchestration	Judgment: which directive applies, which inputs to use, whether it succeeded	The agent itself; CLAUDE.md is its job description	Humans, rarely changed
Execution	Determinism: fetch, parse, transform, deploy	executions/*.py	Written by the agent; guarded by tests

Directives never contain code, scripts never contain policy ("if X, ask the user"), and the agent contains neither: it reads one and runs the other. The model makes three decisions instead of fifty executions — and decisions are exactly what models are genuinely good at. A script that parses a response only needs to be correct once to be correct forever.

What a directive looks like

**CLAUDE.md** is a repo-level configuration file that Claude Code reads automatically at the start of every session. It lives in the project root and its contents are Markdown. It's typically used to hold project conventions, build and test commands, code style, and prohibitions. In the D.O.E. model, it plays the role of the orchestration layer's job description: it tells the agent how the three-layer architecture is divided, which directive file to read for a given kind of task, and in what order to handle failures. By analogy, Cursor uses `.cursorrules`, and the more general multi-agent convention is commonly `AGENTS.md`. These files contain no business code themselves — they only describe "how to work" — so humans rarely change them, and one change takes effect for all subsequent sessions.
# Directive: Deploy the API

## Goal
Ship the current branch to the API server and prove it's live.

## Execution tools
executions/deploy_service.py --target api   # normalize CRLF/BOM, upload, restart

## Edge cases & learnings
- Shell scripts committed from Windows carry CRLF line endings and fail with "bad interpreter".
  deploy_service.py now normalizes them.
- The webhook secret rotates on redeploy; the script refreshes it.

## Verification
GET /health returns 200 and the commit hash matches HEAD.

The "Edge cases & learnings" section is where the return on investment lives. Every pit the agent hits gets written down where the next session can read it before acting — instead of rediscovering it at 2 a.m.

The self-healing mechanism: making month three far better than week one

Structure alone only stops the bleeding. What actually makes the system better over time is one rule about failure: recovery is not a fix. When something goes wrong, the agent runs a loop in a fixed order:

1. Diagnose the root cause: keep asking "why" until you reach the layer where a fix would prevent recurrence.
2. Fix: resolve it in code, config, or infrastructure.
3. Add a test: one that would catch this problem.
4. Add a standard: write it into the directive (plus a lint rule if the pattern is mechanically detectable).
5. Recover last: reprocess the stuck item, restart the service.

Most agent sessions do step 5 first and stop there. "We reprocessed the stuck item" and "added a cron job to retry failures" feel like progress, but they leave the root cause in place. Putting recovery last means every failure leaves behind a test, a rule, and sometimes a lint rule, making an entire class of errors impossible to repeat.

A real example

While building the checkout flow for their own store, a secrets linter found a hardcoded Stripe key in an old helper script in the repo. Deleting that key is just recovery. The real fix was making lint_secrets.py run before every commit and adding a line to CLAUDE.md requiring it. After that, that class of error can never enter that repo's git history — no matter who (or what) is at the keyboard.

The difference between recovery and a fix deserves more detail. Recovery means getting the currently stuck workflow running again — retrying, restarting a service, resetting state, manually reprocessing a queue item. Its goal is "get through this one time." A fix targets the root cause: if CRLF broke a shell script, the fix isn't re-uploading an LF version, it's making the deploy script normalize line endings before transfer, plus a test or lint rule to prevent a recurrence. Recovery is tactical and one-off; a fix is structural and cumulative. Agents naturally prefer recovery, because recovery produces fast, clear feedback, while a fix requires stepping away from the current task to ask "why." Putting recovery last in the loop uses process to force structural work first.

A secrets linter is a class of static analysis tool that scans a codebase for suspected hardcoded credentials — API keys, tokens, private keys, webhook secrets, and so on — and raises an error at commit or CI time. It typically relies on regex patterns (such as the sk_live_, AKIA prefixes) plus entropy detection to identify high-randomness strings. Unlike runtime protections, a linter blocks secrets before the code enters the version repository, so it prevents keys from being written into git history — and once written, git history is very hard to purge completely; even if the file is deleted afterward, the key remains in older commits. Hooking lint_secrets.py into a pre-commit hook or CI means the rule applies automatically whether a human or an agent commits, without relying on either party's memory.

Start for free today

1. Put a CLAUDE.md (or .cursorrules / AGENTS.md) in the repo root describing the three-layer architecture and the self-healing loop.
2. Pick the one task the agent fails at most often, write a directive with the six sections above, and point it at a script.
3. Move the deterministic parts of that task into the script and add tests for the script.
4. Tell the agent: "Read CLAUDE.md, then run the deploy directive." Watch what it appends to "Edge cases & learnings."

The author has released a free Agent Ops Kit Lite (MIT license) on GitHub, including CLAUDE.md, operations-principles directives, a directive template, and a secrets linter — enough to try the approach on a single task in an afternoon. The author also sells a full Agent Ops Kit ($29) with more directives, tested execution scripts, and multi-agent templates; the free version works standalone.

The core insight

AI coding agents' reliability problem won't be solved by a stronger model or a cleverer prompt. It requires an architectural separation of "judgment" and "execution," and having every failure settle into reusable rules and tests. The value of this approach is compounding: build the structure in week one, and by month three the system makes itself better. For developers running platforms with a small team who don't want to watch the agent the whole time, this is a starting point worth trying.

One-line Summary

AI coding agents' reliability problems are solved by separating judgment from execution and letting failures settle into rules.

Paragraph Summary

The article argues that AI coding agents repeatedly fail in production not because of model capability but because of task structure: 90% per-step accuracy leaves only 35% across ten chained steps, with errors compounding. The author proposes a D.O.E. three-layer architecture that separates prose intent (directives), judgment (orchestration, described by CLAUDE.md), and deterministic operations (execution scripts), so the model makes a few decisions instead of fifty improvised executions. Paired with a self-healing mechanism — requiring recovery to come after root-cause diagnosis, fixes, tests, and standards — every failure leaves reusable rules and tests. The "Edge cases & learnings" section in directives lets the next session read about pitfalls in advance. The free, open-source Agent Ops Kit Lite provides templates and a secrets linter and can be tried the same day.