Skip to content

Checklists

Short, practical checklists for AI-assisted development — meant to be run, not filed. Copy a block into your task notes, your PR description, or straight into the chat with the agent, and tick the boxes as you go.

These are a starting point, not a standard. Adapt them to your team and your task. If an item doesn't apply, strike it rather than skip it silently — and if you keep needing an item that isn't here, add it. The goal is a habit you actually keep, not a form you dread.

The deeper "why" behind most items lives in the foundation pages, linked inline. The two you'll lean on most are Verification and Review and Context Management.

Before coding

Most failed AI sessions fail right here — not in the code, but in an unclear goal or missing context. Spend a minute here to save an hour later. See Plan and Design First and Prompting Best Practices.

  • Is the goal clear? Stated as a concrete outcome in one sentence, not a vibe.
  • Is there a short plan or design note? For anything non-trivial, the approach and the files to touch are written down before code is generated.
  • Has the agent been given the right files and context? Point it at the specific files and directories that matter, instead of letting it scan and clutter its context.
  • Are constraints and non-goals explicit? Language, framework, style, dependencies — and what to leave untouched ("don't change the public API", "don't refactor unrelated code").
  • Is the task small enough to verify? You can confirm it worked by reading a reviewable diff and running a check, not by squinting at 800 new lines.

During coding

Keep the work isolated, checkpointed, and honest as it grows. See Context Management.

  • Is the agent following project rules? The conventions in CLAUDE.md / AGENTS.md are being respected, not quietly ignored.
  • Are tests being added or updated appropriately? New behavior gets new tests; changed behavior gets updated ones — now, not "later".
  • Are changes committed or isolated frequently? Small, logical commits so you can roll back one step instead of the whole session.
  • Are risky experiments kept on branches or worktrees? Speculative work doesn't run on your main line. See Parallel Sessions and Worktrees.
  • Is risky or autonomous work running in a sandbox? Unattended runs, and anything touching untrusted input, are contained so a mistake or prompt injection can't reach the rest of your system. See Security, Permissions & Sandboxing.
  • Are important findings saved to markdown or memory? The root cause, the gotcha, the decision. The model forgets between sessions; a file doesn't.

Before merge

The gate where a human stays accountable. AI-generated code can be confident and wrong, over-built, or subtly architecture-breaking. See Verification and Review.

  • Did the agent run tests, linting, type checks, and the build? And do they pass? Confirm with output, not a claim.
  • Did another review pass happen (AI and/or human)? For example a /code-review pass, or a second model used as a cross-check.
  • Did a human review the final diff? Line by line, the actual change that's shipping — not the summary of it.
  • Are there redundant, over-complex, or architecture-breaking changes? Watch for unnecessary abstractions, dead code, "while I was in here" extras, and new patterns that don't fit existing boundaries.
  • No secrets or confidential data leaked? No credentials, API keys, tokens, or confidential data committed in the diff — or pasted into a prompt during the session. See Security, Permissions & Sandboxing.
  • Are new dependencies real and vetted? Every added package actually exists, is the one you meant, and is maintained — AI can confidently invent plausible-sounding package names.
  • Is there a clear final checklist for manual testing or production verification? The specific things to click, run, or watch after this ships.

When to reset the session

A 10-second gut check you can run mid-session. AI quality degrades gradually, and the signals are easy to miss when you're heads-down. If you notice any of these, the fix is usually to stop, summarize where you are, and start a fresh session — not to keep arguing with a degrading one.

  • Over-agreeing — the agent caves to every pushback and stops offering real pushback of its own.
  • Ignoring rules — it drops a constraint you set earlier, or quietly violates CLAUDE.md conventions it was following.
  • Flooding low-value output — walls of text, repeated explanations, or restating things you've already settled.
  • Fixing symptoms, not causes — patching the error message instead of the underlying problem.
  • Weakening tests — loosening assertions, deleting cases, or mocking away the thing under test to make a suite "pass".
  • Losing the goal — drifting into tangents, or solving a problem you didn't ask about.
  • Polluted context — re-suggesting rejected ideas, mixing up files, or contradicting itself.

If you ticked even one of these, summarize the current state in a few lines and open a clean session from that summary. See Knowing When to Reset for the full signals and the reset routine.