My AI agent kept destroying its own work every session. Here's the 6-file system that fixed it.

Abdullah Abbas — Mon, 01 Jun 2026 20:55:00 +0000

Every vibe coder hits this wall eventually.

Session 1: agent builds the feature perfectly.
Session 3: agent breaks the feature it built.
Session 5: agent has no idea the feature ever existed.

This isn't a model problem. It's a memory problem.

AI agents start completely blind every single session. No memory of
what they built, what rules they follow, or what decisions were made.

The Fix

A folder called _ai/ with 5 files, plus a CLAUDE.md in your root:
your-project/
CLAUDE.md ← agent reads this first, every session
_ai/RULES.md ← hard rules it cannot violate
_ai/ARCHITECTURE.md ← full map of the codebase
_ai/DECISIONS.md ← why the code is the way it is
_ai/SESSION_HANDOFF.md ← agent writes what it did, reads it next session
_ai/BUILD.md ← build commands, loaded only when needed

The Two Files That Matter Most

DECISIONS.md — How many times has your agent "fixed" something
that was intentionally done a certain way? You put the reason in
DECISIONS.md and it never touches it again. Most underrated file
in the system.

SESSION_HANDOFF.md — The agent writes a full summary at the end
of every session. What it did, what it changed, what's next.
Reads it at the start of the next session. Persistent memory
with zero plugins.

The Council Protocol

Baked into CLAUDE.md. Required before any risky change:

Propose approach
Critique it — what could go wrong
Revise based on the critique
Only then implement

Stops agents from charging into complex changes without thinking first.

Works With

Claude Code, Cursor, Windsurf — anything that reads markdown.