PACT: A Programmatic Governance Framework for Claude Code After Agent Failure Patterns

After three months of building a mobile app with Claude Code (350+ files, 70+ database tables, BLE peer-to-peer, encrypted local database, cloud sync), a developer identified recurring failure patterns that couldn't be fixed with CLAUDE.md rules. The agent repeatedly made the same categories of mistakes across sessions, including adding forbidden database libraries three times after being told not to, leaking encryption metadata to the server (which broke login for every user), spending 4+ hours debugging Bluetooth by guessing at the API instead of reading docs, and making security fixes that broke backup restore by not considering the full lifecycle.

The Problem with Rules

CLAUDE.md grew to 50+ rules but became performative - Claude would recite them at session start and violate them with ease. When asked why rules were ignored, Claude responded: "I have to be honest with you. I can ignore rules by treating them more as suggestions. They can't always prevent the behavior..."

The Solution: PACT Framework

The developer asked Claude: "If I gave you permission to redesign this system yourself, what would you build?" This led to the creation of PACT (Programmatic Agent Constraint Toolkit) with the core insight, in Claude's own words: "Rules are suggestions. Infrastructure is law."

Four Pillars of PACT

• Mechanical enforcement: PreToolUse hooks that block forbidden patterns before edits land. Examples: import hive? Blocked. print() instead of logger? Blocked. Editing a file you haven't read? Blocked.
• Context replacement: A YAML architecture map (SYSTEM_MAP.yaml) describes every data flow: database table → service → state management → UI screen → cascade behavior. The agent reads this instead of spending 15-20 minutes re-reading source files each session.
• Self-evolving reasoning: Instead of rules ("always check dependencies"), cognitive redirections that are questions: "What depends on this, and what does this depend on?" Questions engage reasoning in a way rules don't. The agent can add new redirections when it catches itself making assumptions.
• Structure/behavior separation: Architecture maps (what files exist) stay separate from lifecycle flows (what happens across app states). Prevents the two most common doc failures: maps becoming essays nobody reads, and flows duplicating structure that goes stale.

Practical Implementation Examples

Cognitive redirections in practice: "When about to remove code: Why does this code exist?" was added after Claude deleted a workaround for a framework bug where the comment directly above explained why it was there. "When finding an objection to your own solution: Is this objection real, or am I folding?" was added after Claude proposed the correct fix, talked itself out of it during review, and the developer had to rescue its own idea.

Bug tracker with solutions knowledge base: One session spent 3 hours solving a Samsung-specific BLE issue. The next session hit the same bug with zero memory of it. Now every investigation is logged in real time — symptoms, failed attempts, root cause, fix. The agent's first action on any bug is checking whether a previous session already solved it.

Package knowledge files: The 4-hour Bluetooth debugging nightmare happened because Claude was guessing how the package worked from stale training data. Now there's a mandatory requirement to consult package knowledge files.