Case Study: Adding Pagination With an Agent

From request to merged PR

Task: add cursor pagination to GET /orders in a small web service. Setup: a clean checkout, a new branch agent/orders-pagination, tests green on the branch before starting, an AGENTS.md with test/lint commands and the rule "money is integer paise", and an agent running in a container with no production credentials. Task text: goal and reason, files to look at, constraints (response stays backward compatible; no new dependencies), how to verify (the unit-test command), scope (orders endpoint only). Plan first: the agent proposes steps and the cursor design (last-id cursor, default page size 20, max 100); the engineer approves, adding a requirement for the last-page case. Implement: the agent writes failing tests (page size, next cursor, last page, invalid cursor), the engineer reviews the tests, then it implements in two small commits, running tests each time. Safeguards: step cap and cost budget; the patch gate and secret scan pass; stuck-run detection never trips. Review: a 60-line diff and a summary; the engineer checks that no test was weakened, reads error handling for invalid cursors, and runs the service locally. Merge: CI passes, one human reviewer approves, the PR notes that an AI agent was used and how it was verified.

Direct, bound, verify, review

Good results come from clear tasks, bounded runs, independent verification and human review.

The workflow on one page

Each line maps to a section of this course.

Setup      clean branch, green baseline, AGENTS.md, container without prod credentials      (Sec 1, 2, 3)
Task       goal + files + constraints + verify command + scope                                (Sec 4)
Plan       agent proposes, human approves (cursor design, last-page case)                      (Sec 4)
Implement  failing tests (reviewed) -> small commits -> tests each time                        (Sec 2, 4)
Safeguards step/cost caps, stuck-run detection, patch gate, secret scan, protected paths        (Sec 5)
Review     60-line diff, test changes scrutinised, local run, summary                          (Sec 5, 7)
Merge      CI green + one human approval + PR notes AI use and verification                   (Sec 2, 7)

Capture lessons in the instruction file

Every mistake that cost you time is a candidate for a one-line rule in AGENTS.md.

Quick check: Why did the engineer approve the plan before the agent wrote code?

• Plans are required by CI
• Fixing a plan is cheap; undoing wrong implementation is costly
• Agents cannot code without permission from a manager
• It makes the model faster