Andrew Crookston. @acr
Updated September 30, 2026 · 18 essays · Stockholm RSS ↗

Cheat Sheet

AI Coding Workflow

This is the cheat sheet for my AI Coding Field Guide article.

The chain: Scope → Plan → Execute → Verify → Wrap-up. Skip any step and the output suffers.

Andrew Crookston

The cycle drawn as five stations on a rulebook plinth holding AGENTS.md and SKILLS: Scope, Plan, Execute, Verify and Wrap-up, each with the files it produces, and lettered return paths for tests failing, a stuck debug loop, a mistake found and a completed task Foundation: the rulebook AGENTS.md SKILLS 1 Scope 2 Plan 3 Execute 4 Verify 5 Wrap-up PLAN-xx.md ADR-xx.md code changes PLAN-xx.md test output PLAN-xx.md PR a b c d
Fig. 1: The cycle.

Foundation: the rulebook

  • AGENTS.md — coding conventions, design patterns, git workflow, verification rules
  • Checked into git — the whole team benefits
  • Keep it under 200 lines. If it belongs in a linter config, it doesn't belong here.
  • Every mistake becomes a new rule. The file compounds over time.
  • Reference files: sub-pages for specific contexts (e.g. @code-review.md)
  • Rules/ — modular instruction files, path-scoped. Load alongside AGENTS.md automatically.
  • Skills — on-demand expertise (deployments, migrations, security review). Can spawn subagents.
  • Permissions — pre-allow build/test scripts, deny destructive commands and .env reads. Reduces friction but doesn't eliminate it.
  • Avoid conflicting or overlapping skills.
  • Keep the core rulebook lean. Split detail into sub-pages and skills.
  • Deep dive: Anatomy of the .claude/ Folder

The cycle

1Scope

  • Define boundaries before any code. "What are the edge cases?" "How does this interact with X?"
  • Discuss architecture, trade-offs and edge cases. Iterate until the approach is solid.
  • You know what you want. The agent needs you to articulate it with precision.
  • Spend time here. Scoping takes longer than the implementation. That's the point.
  • Never inject new ideas mid-task. Finish. Commit. Clear context. Start fresh.
  • Claude Code has a planning mode — Shift-Tab to switch. This is where I spend most of my time.

2Plan

Every plan covers five things:

  1. What to build — scoped tight, one clear deliverable
  2. What not to touch — explicit boundaries, no "improving" nearby code
  3. How to prove it works — define the verification step upfront
  4. Constraints — which libraries, patterns, and conventions to follow
  5. Definition of done — tests passing, linter clean, diff under 200 lines
Bad plan
"Add user notifications."
Good plan
"Add an email notification when an appointment is confirmed. Use the existing EmailService. Don't modify the API layer. Run the integration suite. Show me the output."

3Execute

  • Hand the agent the plan. Let it work.
  • Use skills to sequence steps correctly (e.g. coding, testing skills)
  • If you're correcting mid-task, go back to scope — the approach needs rethinking.
  • Keep changes small and reviewable.
  • Watch, don't steer.
  • Large refactors work as a sequence of small, verified steps.

4Verify

The form varies. The discipline doesn't.

Never trust the agent's claim. Trust output.

  • New feature → spin up the full stack, walk through the user flow
  • Bug fix → run the integration suite before and after, show both
  • API change → hit the endpoint with real payloads, show request and response
  • Refactor → run the full test suite, then smoke test affected flows
  • Frontend → start the dev server, load the page, describe what renders

When the agent says "done" — say "show me the test output."

Use skills to verify: code review, security, QA. Skills enforce consistency across reviews.

PR review cycle: triage → fix → test → repeat.

5Wrap-up

  • Tests pass. Linter clean. Diff reviewable. Commit and push.
  • Before the next task: what went wrong? What took too long?
  • Add new rules to AGENTS.md or improve skills. Every answer compounds.
  • Check /insights to improve the cycle.
  • Clear context. Start fresh. One task, one session.

Feedback loops

SituationWhere to go
a Tests failBack to execute. The plan is fine. The code needs fixing.
b Stuck in a debug loopStop. Back to scope. The approach needs rethinking.
c Mistake foundAdd a rule to AGENTS.md. The system gets better.
d Task completeCommit. Clear context. Start fresh at scope.

Discipline: context hygiene

  • Don't mix unrelated tasks in one session. The "kitchen-sink session" kills quality.
  • For long tasks: write a handoff doc (goal, progress, next steps) before starting a new session

Common anti-patterns

ProblemFix
Agent builds the wrong thingTighter scoping. Constrain the approach.
Infinite debug loop (fix → fail → fix → fail)Stop the agent. Research root cause. Go back to scope.
2000-line diff you can't reviewBreak the plan into smaller pieces.
Agent "improves" code you didn't ask aboutAdd "what not to touch" to the plan.
Quality degrades mid-sessionContext pollution. Clear and start fresh.
ProblemFix
Agent claims it works but didn't testAdd verification rules to AGENTS.md. Demand output.
Fix introduces a new bugCommit before you debug. Always.
Agent ignores or conflicts on rulesCheck for conflicting instructions. Simplify. Review in long sessions.
Every repo needs fresh setupThe tax of Stage 3. Reuse what you can. Accept the rest.
Messy PR — mixed features, wrong branchTighter scoping. Smaller changes. One task, one session.