A 7-File Governance Layer to Prevent LLM Session Drift

A developer on r/LocalLLaMA shared a solution to prevent LLM coding assistants like Claude from silently undoing architectural decisions across sessions. Instead of treating LLM sessions as conversations, they now treat them as stateless processes that need a protocol.

The Core Problem

Every LLM session starts with zero memory. You re-explain, it re-interprets, and it drifts confidently. The developer noted: "You won't even notice until you are deep inside the project maybe three files deep or four files or who knows even on the last part of project."

The 7-File Governance Layer

The fix isn't a better prompt but a governance layer that any model can read and immediately operate within. The system uses seven files, each owning a specific concern with no overlap:

• active_context.md - Session controller, defines what's in scope right now
• contracts.md - Behavioral law, data schemas, enum values, required behavior
• agent_core.md - Execution discipline, how to operate, validate, report
• agent_project.md - Project intent, why this system exists, expected outcomes
• decisions.md - ADR log, non-obvious choices and why they were accepted
• build_plan.md - Module roadmap, implementation order and deliverables
• state.md - Living journal, what's done, what changed, what remains

Key Design Decisions

The developer explained two critical separations:

Separating contracts.md from agent_core.md: "When a behavioral conflict appeared, the model had no way to know which layer to defer to. Was this a schema rule or an execution preference? When they're separate, the hierarchy is unambiguous, contracts always win."

Including decisions.md: "I almost skipped it ('I'll just remember'). Three weeks later I couldn't reconstruct why we'd chosen Postgres over SQLite for a specific module. The ADR log exists precisely because 'I'll remember' is not a protocol."

The Operational Loop

Every session follows this order, no exceptions:

1. Read active_context.md → extract what's in scope
2. Re-ground against contracts.md → behavioral rules locked
3. Confirm operating constraints from agent_core.md + agent_project.md
4. Check decisions.md → don't reverse accepted choices
5. Execute only what active_context.md authorizes, per build_plan.md
6. Validate with tests — don't declare done without evidence
7. Update state.md with factual outcomes
8. If a new non-trivial decision was made, log it in decisions.md

Workflow Impact

The active_context.md scope lock proved particularly valuable: "Before this, I would start a session to fix a bug and then end up refactoring an unrelated module because 'it was right there.' Felt productive.........and it Was."