MCP Explained: A One-Page Guide
Host, client and server, the three primitives, both transports, one tool call step by step, and a safety checklist.
- Any MCP client
- Any MCP server
- Claude Code
1 file5.3 KB.md
Six phases of checkboxes for working with a coding agent, from the first prompt to the commit.
By Matthews WongUpdated
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.
Exactly what the download contains. Read it first, then copy or download.
# 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.
Download the Markdown file and open it in your editor or print it. The checkboxes render in any Markdown viewer.
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.
One logical change, then tests, then read the diff, then ask for the command and its output. Repeat until the plan is done.
Commit per unit and write what you learned into the instructions file your agent reads, so the next session does not repeat the mistake.
Delete the boxes your tooling already enforces and add the ones your project needs, such as a migration check or a security review.
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 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.
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.
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.
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.
Short answers before you download it.
Free lessons and articles on this site that explain the ideas behind it.
Primary sources checked on the research date. Follow them for the current version.
Host, client and server, the three primitives, both transports, one tool call step by step, and a safety checklist.
1 file5.3 KB.md
A 70-line starter CLAUDE.md: project, stack, commands, hard rules, how to verify work and what not to do.
1 file2.1 KB.md
A planning prompt that covers business, domain, tech design and steps, then lists the decisions it needs from you.
1 file2.3 KB.md