Five Layer Defense

Five-Layer Defense System

How ai-coding-ok v3.1+ guarantees the PDCA loop is never skipped — even in long sessions, short commands, and edge cases.

---

The problem: plain text instructions are not enough

Early versions of ai-coding-ok relied entirely on Markdown instructions like "⚠️ Must read memory files before coding." In practice, AI models would skip these instructions when:

• The session was long (30+ rounds, early instructions pushed out of context)
• The user gave a short command ("add a search feature")
• The AI was in "inertia mode" after many rounds of coding
• Sub-agents were spawned without inheriting the PDCA mandate

The solution: A defense-in-depth system where each layer independently catches PDCA violations.

---

The five layers

graph TB
    subgraph "Layer 1: Hardest"
        L1[CLAUDE.md<br/>⛔ STOP — CALL Skill before any code<br/>Auto-loaded at session start]
    end
    subgraph "Layer 2: All platforms"
        L2[AGENTS.md<br/>7-step Plan mandate + 4-step Act mandate<br/>AI reads first on every task]
    end
    subgraph "Layer 3: All platforms"
        L3[copilot-instructions.md<br/>Mandatory Memory Updates output section<br/>Cannot be omitted from response]
    end
    subgraph "Layer 4: Claude Code"
        L4[Claude Code Hooks<br/>SessionStart + UserPromptSubmit + PreToolUse + Stop<br/>Exit 2 blocks session end without Act]
    end
    subgraph "Layer 5: Claude Code"
        L5[Install-time auto-config<br/>SOURCE_DIR_PATTERN regex<br/>Hooks only fire on source file changes]
    end
    L1 --> L2 --> L3 --> L4 --> L5

Loading

---

Layer 1: CLAUDE.md STOP Instruction

Platform: Claude Code
Mechanism: CLAUDE.md is auto-loaded by Claude Code at session start. It contains:

⛔ STOP — CALL Skill("ai-coding-ok") BEFORE ANY CODE WORK.
THEN CALL Skill("ai-coding-ok") AFTER ALL WORK.
THIS IS NON-NEGOTIABLE.

@AGENTS.md

Why it works: Claude Code cannot skip loading CLAUDE.md. The first line is a STOP instruction — the AI sees it before processing any user request. The @AGENTS.md import pulls in the full PDCA mandate.

Failure mode it catches: New session, short command ("add a login page") — Claude Code loads CLAUDE.md first, hits the STOP, invokes the skill.

---

Layer 2: AGENTS.md Plan + Act Mandate

Platform: All platforms (Claude Code, Copilot, Cursor, OpenCode)
Mechanism: AGENTS.md contains explicit instructions at the top:

## ⚠️ AI Agent Required Reading (must execute on every task)

### Plan Phase (mandatory, before starting the task)
1. Read AGENTS.md
2. Read .github/agent/system-prompt.md
3. Read .github/agent/workflows.md
4. Read .github/agent/coding-standards.md
5. Read .github/agent/memory/project-memory.md
6. Read .github/agent/memory/decisions-log.md
7. Read .github/agent/memory/task-history.md

### Act Phase (mandatory, after finishing the task)
1. Update task-history.md (always)
2. Update decisions-log.md (if architecture changed)
3. Update project-memory.md (if facts changed)
4. Update agent docs if content is stale

> ⛔ Above steps cannot be skipped.

Why it works: This is the first file the AI reads when entering a task. The word "mandatory" and "cannot be skipped" combined with the explicit 7-step checklist makes it hard to ignore.

Failure mode it catches: Layer 1 missed (CLAUDE.md not loaded for some reason). AGENTS.md is always read as the architecture cheatsheet.

---

Layer 3: copilot-instructions.md Mandatory Output Section

Platform: All platforms (auto-loaded by Copilot, read by other tools)
Mechanism: .github/copilot-instructions.md requires the AI's response to include a ## Memory Updates section:

## Output Format (must include all sections)

Every response must include:
- ## Summary
- ## Changes Made
- ## Memory Updates (⚠️ Required)
  - task-history.md: [updated / no changes needed]
  - decisions-log.md: [updated / no changes needed]
  - project-memory.md: [updated / no changes needed]

Why it works: The AI cannot "finish" without including this section. If it tries to omit it, the format constraint flags the response as incomplete.

Failure mode it catches: AI finishes coding and tries to end the response without updating memory. The output format requires the Memory Updates section — it must at minimum acknowledge each file.

---

Layer 4: Claude Code Hooks

Platform: Claude Code only
Mechanism: Four hooks in .claude/settings.local.json:

{
  "hooks": {
    "SessionStart": [
      // Verify CLAUDE.md and AGENTS.md exist, remind about PDCA
    ],
    "UserPromptSubmit": [
      // Check if user's request is a coding task, remind about Plan
    ],
    "PreToolUse": [
      // Block destructive operations (git push, SSH, docker compose)
      // unless explicitly authorized
    ],
    "Stop": [
      // Check if task-history.md was updated in this session
      // If NOT → exit 2 (blocks session end, forces Act)
    ]
  }
}

The Stop hook (most critical)

{
  "matcher": "Stop",
  "hooks": [{
    "type": "command",
    "command": "bash -c '... check if task-history.md was modified ...'",
    "asyncRewake": true
  }]
}

If task-history.md was NOT modified during the session, the Stop hook exits with code 2. This blocks the session from ending and wakes the AI back up ("asyncRewake: true") with a prompt to run the Act phase.

Why it works: This is a mechanical constraint, not a text instruction. The AI cannot bypass it — if memory wasn't updated, the session literally cannot end.

Failure mode it catches: AI finishes coding, doesn't update memory, tries to end the session. The Stop hook fires, exits 2, and wakes the AI to complete Act.

---

Layer 5: Install-time Auto-Configuration

Platform: Claude Code only
Mechanism: During Mode A (Install), the {{SOURCE_DIR_PATTERN}} placeholder in hooks is replaced with the user's actual source directories:

User says: "src/ tests/"
→ Regex: ^src/\\|^tests/

This ensures hooks only fire on changes to actual source files — not on every file in the project.

Why it works: Without this, hooks would fire on changes to README.md, package.json, etc., causing noise and false positives. The pattern scoping makes hooks practical.

---

Defense coverage matrix

Scenario	Layer 1	Layer 2	Layer 3	Layer 4	Layer 5
New session, short command	✅	✅	✅	✅	✅
Long session (30+ rounds)	⚠️	✅	✅	✅	✅
Sub-agent spawned	❌	❌	❌	⚠️	⚠️
"Just fix a typo"	✅	✅	✅	✅	✅
User explicitly says skip	❌	❌	❌	❌	❌
Copilot (no hooks)	❌	✅	✅	❌	❌
Cursor (no hooks)	❌	✅	✅	❌	❌

✅ = Catches this scenario | ⚠️ = Partial coverage | ❌ = Not applicable

---

Platform coverage

Platform	Layers available	PDCA enforcement strength
Claude Code	All 5 layers	🛡️🛡️🛡️🛡️🛡️ Maximum
GitHub Copilot	Layers 2-3	🛡️🛡️🛡️ Strong
Cursor	Layers 2-3	🛡️🛡️🛡️ Strong
OpenCode	Layers 2-3	🛡️🛡️🛡️ Strong

---

Design principle

Each layer is independent — if one fails, the next catches it. No single point of failure.

"Don't put all your eggs in one basket. Put them in five baskets, and make each basket a different shape." — the ai-coding-ok defense philosophy

---

Next steps

• Hooks System — detailed hooks configuration reference
• PDCA Workflow — what the defense system is protecting
• Troubleshooting — when PDCA still doesn't trigger