PDCA Workflow

PDCA Workflow

The Plan → Do → Check → Act closed loop that runs on every coding task. This is the core mechanism that prevents "AI fixed bug X and broke feature Y."

---

Overview

PDCA (Plan-Do-Check-Act) is a four-stage quality management cycle adapted for AI-assisted coding. ai-coding-ok enforces this loop on every task — before, during, and after coding.

graph LR
    P[Plan<br/>Read memory<br/>Understand context] --> D[Do<br/>Write code<br/>Write tests]
    D --> C[Check<br/>Run tests<br/>Verify no regression]
    C --> A[Act<br/>Update memory<br/>Close the loop]
    A -.->|Next task| P

Loading

---

The four phases

Phase 1: Plan (before writing code)

Trigger: Any development task in a project with ai-coding-ok installed.

What happens: The AI reads 7 files in order:

#	File	What it provides
1	AGENTS.md	Architecture cheatsheet, project overview
2	.github/agent/system-prompt.md	Agent persona, role switching, behavior boundaries
3	.github/agent/workflows.md	Scenario playbooks (Feature/Bug/Refactor/Release)
4	.github/agent/coding-standards.md	Coding conventions
5	.github/agent/memory/project-memory.md	Long-term project facts and constraints
6	.github/agent/memory/decisions-log.md	Historical technical decisions (ADRs)
7	.github/agent/memory/task-history.md	Recent task context (last 30 entries)

Time cost: ~30 seconds. The three memory files are typically <10KB combined.

Output: The AI has full context — it knows the architecture, constraints, past decisions, and recent changes.

Phase 2: Do (write code)

What happens:

• Write implementation code
• Write tests in the same change
• Follow the coding standards from coding-standards.md
• Follow the scenario workflow from workflows.md
• Self-check against constraints from project-memory.md

Phase 3: Check (verify)

What happens:

• Run the test suite
• Verify no regression in unrelated features
• Check against security constraints
• Confirm the change matches the plan

Phase 4: Act (update memory)

⚠️ This is the phase most tools skip — and why ai-coding-ok exists.

File	Update condition	Frequency
task-history.md	Always — every task gets an entry	Every task
decisions-log.md	Architecture/tech decisions changed	On architecture changes
project-memory.md	Project facts changed (new modules, deps, etc.)	Rarely
Agent docs (AGENTS.md, etc.)	Factual content is stale	When outdated

Each task-history entry follows this format:

### [TASK-XXX] Brief title
- **Date**: YYYY-MM-DD
- **Type**: feat / fix / refactor / chore
- **Summary**: What was done and why
- **Files changed**: Key files modified
- **Notes**: Important context for future sessions

---

Why Act is the critical phase

Without the Act phase, your memory files are a snapshot that rots:

Iteration	Without Act	With Act
1	Memory is accurate (fresh install)	Memory is accurate
5	Memory is stale (3 features added, not recorded)	Memory reflects 5 tasks of context
20	Memory is useless (architecture changed, memory says old thing)	Memory has 20 entries of compounded context
50	AI makes decisions based on wrong information	AI reads 50 entries of accurate history

The Act phase is what turns memory from a snapshot into a living record.

---

Enforcement mechanisms

ai-coding-ok uses a Five-Layer Defense System to ensure PDCA is never skipped:

Layer	Mechanism	Platform
1	CLAUDE.md STOP instruction	Claude Code
2	AGENTS.md Plan 7-step mandate	All platforms
3	copilot-instructions.md mandatory output section	All platforms
4	.claude/settings.local.json hooks (Stop hook exit 2)	Claude Code
5	Install-time auto-configuration	Claude Code

---

Example: A feature from start to finish

Task: "Add a search endpoint for products"

Plan:
  → Read project-memory.md: "FastAPI + SQLite, products table in products.py"
  → Read decisions-log.md: "ADR-003: SQLite FTS5 for full-text search"
  → Read task-history.md: "TASK-012: Added products table schema last week"
  → AI now knows: use FTS5, don't create a new table, test in test_products.py

Do:
  → Add search endpoint in api/products.py
  → Add tests in tests/test_products.py
  → Follow coding-standards.md (type hints, docstrings, pytest fixtures)

Check:
  → Run pytest: 47 passed, 0 failed
  → No regression in existing product endpoints
  → Search with empty query returns 400 (handled)

Act:
  → task-history.md: [TASK-013] Add product search endpoint
  → (No architecture change, so decisions-log.md and project-memory.md not updated)
  → Output includes "## Memory Updates" section confirming the update

---

PDCA vs other approaches

Approach	Plan	Do	Check	Act
Ad-hoc AI coding	❌ Skip	✅ Code	⚠️ Maybe	❌ Skip
TDD	⚠️ Implicit	✅ Code + test	✅ Tests	❌ Skip
superpowers	✅ Brainstorm	✅ Execute	✅ Review	❌ Skip
ai-coding-ok	✅ Read 7 files	✅ Code + test	✅ Verify	✅ Write memory

ai-coding-ok is the only approach that closes the loop with Act — writing back to memory so the next session inherits all context.

---

Next steps

• Three-Tier Memory — understand the memory files in detail
• Four Modes (A/B/C/D) — how Install/Plan/Act/Upgrade mode switching works
• Daily Workflow — what PDCA looks like day-to-day