# AI Coding Checklist: A Workflow for Coding Agents

> A free AI coding checklist for working with a coding agent: prepare, give context, plan first, work in small steps, verify with real output, then commit.

URL: https://www.matthewswong.com/en/toolkit/ai-coding-workflow-checklist/

- Author: Matthews Wong (https://www.matthewswong.com/en/about/)
- Updated: 13 November 2026

> **Key takeaway:** A one-page checklist for getting reliable work out of a coding agent. Six phases: know the goal and the acceptance check, give context, ask for a plan, work in small steps, verify with real output, and finish with a commit and a note of what was learned. It is tool-neutral and works with any agent that reads your repository and runs commands.

- Type: Guide
- Works with: Claude Code, Codex, Cursor, Any coding agent
- Download: [ai-coding-workflow-checklist.md](https://www.matthewswong.com/downloads/toolkit/ai-coding-workflow-checklist/ai-coding-workflow-checklist.md) (2.7 KB)
- License: Free to use, change and share, at work too.

## The file

Exactly what the download contains. Read it first, then copy or download.

### ai-coding-workflow-checklist.md

```markdown
# AI coding workflow checklist

One page for working with a coding agent. It works with any agent that can
read your repository and run commands. Skip a box only on purpose.

## 1. Before you prompt

- [ ] I can state the goal in one sentence.
- [ ] I know the acceptance check: the test, command or screen that proves it
      is done.
- [ ] I know which files are involved, or I will ask the agent to find them
      first.
- [ ] The working tree is clean, so the agent's changes are easy to see and
      easy to undo.

## 2. Give context

- [ ] I point at files by path instead of describing them.
- [ ] I state the constraints: no new libraries, follow this pattern, keep
      this interface.
- [ ] I say what not to touch.
- [ ] I paste the real error, log or screenshot, not my summary of it.
- [ ] I give what the code cannot tell: a decision, a deadline, a rule of the
      business.

## 3. Plan first

- [ ] For anything non-trivial, I ask for a plan before any code.
- [ ] The plan lists the files it will change and how each step is verified.
- [ ] The agent lists its assumptions and the decisions it needs from me.
- [ ] I answer those questions. I do not let it guess.
- [ ] If the plan is wrong, I fix the plan, not the code that comes after.

## 4. Work in small steps

- [ ] One logical change at a time.
- [ ] The agent runs the tests or the build after each step.
- [ ] I read the diff of every step before the next one starts.
- [ ] I stop it the moment it drifts, and I restate the goal.
- [ ] After two failed corrections, I start a fresh session with a better
      prompt.

## 5. Verify

- [ ] I ask for evidence: the command that ran and its output.
- [ ] I never accept "it works" without that output.
- [ ] I run it myself at least once: the tests, the build, the real screen.
- [ ] For a bug, the failure is reproduced first, and the cause is stated
      with evidence before any fix.
- [ ] After the fix, the same reproduction runs again and passes.
- [ ] The diff contains nothing I did not ask for.

## 6. Finish

- [ ] One commit per logical unit, with a message that says what and why.
- [ ] The reproduction is kept as a regression test where practical.
- [ ] I write down what was learned: the gotcha, the decision, the command.
- [ ] I update the instructions file the agent reads, so the next session
      starts with it.
- [ ] Temporary logging and scratch files are removed.

## When it goes wrong

- The agent built something else: the goal or the context was missing. Go
  back to sections 1 and 2.
- It says done but it is not: it had no check to run. Go back to section 5.
- It keeps making the same mistake: write the rule into the instructions
  file, or enforce it with a script.
```

## Use it when

- The agent keeps building something other than what you had in mind.
- You accept a change because it looks done, then find out later that it was not.
- You are introducing a coding agent to a team and want one shared routine.
- A session produced a large diff that nobody can review.

## From download to working

1. **Keep it open beside the agent.** Download the Markdown file and open it in your editor or print it. The checkboxes render in any Markdown viewer.
2. **Do sections 1 to 3 before any code.** State the goal, name the acceptance check, give the context, and ask for a plan. For a one-line fix this takes a minute. For a feature it is where most of the result is decided.
3. **Loop sections 4 and 5 per step.** One logical change, then tests, then read the diff, then ask for the command and its output. Repeat until the plan is done.
4. **Close with section 6.** Commit per unit and write what you learned into the instructions file your agent reads, so the next session does not repeat the mistake.
5. **Trim it to fit your team.** Delete the boxes your tooling already enforces and add the ones your project needs, such as a migration check or a security review.

## Why it is written this way

- **Six phases, in the order the work happens.** Before you prompt, give context, plan first, work in small steps, verify, finish. Each phase has four to six boxes, short enough to check without leaving the task.
- **The acceptance check comes first.** The second box asks for the test, command or screen that proves the work is done. An agent with a check to run can find its own mistakes. Without one, you are the test suite.
- **Assumptions are listed, not guessed.** The plan phase makes the agent list its assumptions and the decisions it needs from you. A wrong assumption is cheap to fix in a plan and expensive to fix in code.
- **Evidence over claims.** The verify phase asks for the command that ran and its output, and for a bug it asks for a reproduction before any fix. The same reproduction runs again after the fix.
- **A short section for when it goes wrong.** Three common failures each point back to the phase that prevents them: a missing goal, a missing check, or a rule that was never written down.

## What goes wrong

- A checklist does not replace reading the diff. If you tick the boxes without looking at the change, you have only moved the risk.
- It is too much ceremony for a typo. Use sections 1, 5 and 6 for small changes and the full list for anything that touches more than one file.
- A rule that must hold every time does not belong on a checklist that people can skip. Enforce it with a script, a hook or a required pipeline step.

## FAQ

### Does this checklist only work with Claude Code?

No. It names no commands and no product features. It works with any coding agent that can read your repository and run commands, and most of it also applies to a chat assistant you paste code into.

### Why should I ask a coding agent for a plan first?

A plan shows you the files the agent will change and the assumptions it is making before any code exists. Correcting a plan takes one message. Correcting code built on a wrong assumption means reading, reverting and redoing the work.

### Why is the agent saying it works not enough?

An agent stops when the work looks done. The Claude Code best practices page puts it this way: a claim that all tests pass tells you very little on its own, so ask for the command that ran and its output. Reading that output is faster than rerunning the check yourself.

### What is the instructions file in the last section?

It is the file your agent loads at the start of a session, for example CLAUDE.md in Claude Code. Write down only what the agent could not work out from the code: a command, a convention, a gotcha. A short file is read more reliably than a long one.

## Learn what this file packages

- Free lesson: [Claude Code Rewind and Plan Mode: Undo Risky Changes](https://www.matthewswong.com/en/learn/claude-code-tips/claude-code-rewind-plan-mode-safe-changes/)
- Free lesson: [Claude Code Git Workflow: Safe Commits, PRs and Push Rules](https://www.matthewswong.com/en/learn/claude-code-tips/claude-code-git-workflow-safe-commits/)
- Free lesson: [CLAUDE.md File Example: Global, Project and Local Layers](https://www.matthewswong.com/en/learn/claude-code-tips/claude-md-file-example/)
- [Agentic Coding Workflow: Best Practices for AI Agents](https://www.matthewswong.com/en/blog/agentic-coding-workflow-best-practices/)
- [Verification Loops: The Core Agentic Coding Skill](https://www.matthewswong.com/en/blog/verification-loops-agentic-coding/)
- [TDD With AI Coding Agents: A Practical Workflow](https://www.matthewswong.com/en/blog/tdd-with-ai-coding-agents/)
- [Spec-Driven Development With AI Coding Agents](https://www.matthewswong.com/en/blog/spec-driven-development-ai-agents/)

## Sources

- [Claude Code docs: best practices for Claude Code](https://code.claude.com/docs/en/best-practices)

[All toolkit items](https://www.matthewswong.com/en/toolkit/)

---

- HTML version: https://www.matthewswong.com/en/toolkit/ai-coding-workflow-checklist/
- Bahasa Indonesia: https://www.matthewswong.com/id/toolkit/ai-coding-workflow-checklist/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json
