ai-coding-ok

🧠 ai-coding-ok

English | 中文

The PDCA memory loop for AI coding. superpowers gives Claude discipline for one session. ai-coding-ok gives Claude memory that stays accurate across 50 iterations.

---

The Problem

You ship a feature with Claude. Three sessions later, Claude "fixes" a bug by silently deleting a constraint it added last week. By iteration 50, your codebase has invisible regressions everywhere.

This isn't a prompt problem. It's a memory problem with no feedback loop.

Most AI tools (including superpowers) solve single-session discipline — plan before code, TDD, review. None of them solve cross-session memory drift.

---

How ai-coding-ok Solves It

A four-stage PDCA closed loop, enforced on every task:

  Plan          Do            Check         Act
 ─────▶       ─────▶         ─────▶        ─────▶
read         write          run           update
memory       code +         tests,        memory
files        tests          verify        files
                            no
                            regression

Phase	What happens
Plan	Claude reads project-memory.md, decisions-log.md, task-history.md before touching code
Do	Code + tests in the same change
Check	Tests run; regression in unrelated features is caught
Act	Claude writes back to memory: task-history.md always; decisions-log.md on architecture change; project-memory.md on fact change

The Act step is what most tools skip. Without it, your memory file is a snapshot that rots after 10 iterations because nobody updates it. With it, context stays accurate because every task closes the loop.

---

Three-Tier Memory

Tier	File	Content	Update frequency
Long-term	project-memory.md	Architecture, constraints, known issues	Rarely
Mid-term	decisions-log.md	ADRs (why we chose X over Y)	On arch changes
Short-term	task-history.md	Last 30 task summaries	Every task

Iteration 50 reads the same three files iteration 1 read — but they have grown 50 entries of compounded context. That's the point.

---

Install

Claude Code (recommended)

/plugin install ai-coding-ok@claude-plugins-official

Then in any project, in Claude Code:

install ai-coding-ok

Claude will:

1. Copy templates into your project
2. Ask one question: "In one sentence, what are you building?"
3. Infer your tech stack and fill all placeholders automatically
4. Bootstrap the first task-history entry — PDCA loop is active immediately

Cursor / Copilot / OpenCode (script install)

git clone https://github.com/Mark7766/ai-coding-ok
cd your-project
bash /path/to/ai-coding-ok/install.sh --cursor   # or --copilot / --opencode

The templates auto-load via .cursor/rules/ai-coding-ok.mdc (Cursor), .github/copilot-instructions.md (Copilot), or ~/.config/opencode/AGENTS.md (OpenCode).

---

What gets installed in your project

your-project/
├── AGENTS.md                          # Architecture cheatsheet (AI reads first)
├── CLAUDE.md                          # Claude Code auto-load shim → @AGENTS.md
├── .cursor/rules/ai-coding-ok.mdc     # Cursor: alwaysApply PDCA rule
└── .github/
    ├── copilot-instructions.md        # Copilot: auto-loaded behavior rules
    ├── project-metadata.yml           # Machine-readable project facts
    ├── PULL_REQUEST_TEMPLATE.md       # PR template (memory-update checklist)
    ├── ISSUE_TEMPLATE/                # Issue templates
    ├── workflows/                     # CI + memory-update reminder
    └── agent/
        ├── system-prompt.md           # Agent persona + PDCA workflow
        ├── coding-standards.md        # Coding conventions
        ├── workflows.md               # Scenario playbooks
        ├── prompt-templates.md        # Prompt template library
        └── memory/
            ├── project-memory.md      # 🧠 long-term: project facts
            ├── decisions-log.md       # 📝 mid-term: ADRs
            └── task-history.md        # 📜 short-term: last 30 tasks

---

Pairs with superpowers

ai-coding-ok and superpowers solve different problems and compose cleanly:

superpowers brings per-session discipline. ai-coding-ok brings cross-session memory.

The combo flow:

1. ai-coding-ok Mode B  (Plan: load memory)        ← every task starts here
2. superpowers          (brainstorming → planning → execution)
3. ai-coding-ok Mode C  (Act: write memory back)   ← every task ends here