Worked example: shipping a small feature with an agent

Applying the four-part template from the "writing a good task" page:

Goal: Limit password-reset requests to 3 per email address per hour, returning a clear error past the limit. Where: the /auth/reset-password route and whatever stores request state. Constraints: don't add a new external dependency (Redis, etc.) — use the existing database. Verification: a test that makes 4 requests for the same email and asserts the 4th is rejected with a 429 status.

Notice this task already names its own success condition — the test is part of the ask, not an afterthought.

Given that task, a reasonable plan — visible to you before or as it acts — looks like:

1. Find the existing reset-password route handler
2. Check the database schema for a place to record attempt timestamps, or add a small table/column if none exists
3. Add the rate-limit check at the top of the handler
4. Write the test described in the task
5. Run the test suite and fix anything that fails

This is the "plan" step from the agent loop page made concrete — each step is checkable on its own, not one giant unstructured edit.

Before writing anything, the agent searches the repo for the existing route, the database models, and any existing rate-limiting pattern elsewhere in the codebase it should be consistent with. If your codebase already rate-limits something else (say, login attempts), a well-scoped task might explicitly point at that pattern: "follow the same approach as the login rate limiter in auth/login.py" — reusing the "show it an example" technique from the task-writing page.

The agent reports back with a diff touching three files: the route handler (added the check), a migration or model change (added a way to track attempts), and a new test file. Applying the three-question review from the diffs page:

• Does this match what I asked, and nothing more? Check that it didn't also refactor unrelated parts of the route handler while it was in there.
• What about edge cases? Does it handle the email address being case-different across requests (User@x.com vs user@x.com)? If the task didn't specify, this is a reasonable follow-up rather than an assumed pass.
• Would I have written it this way? Check the new table/column follows existing naming and migration conventions in the codebase.

Suppose the diff handles the happy path and the exact test case, but doesn't normalize email casing. Rather than hand-editing it yourself, this is a good candidate for a follow-up instruction: "also normalize email case before checking the rate limit, and add a test for that." The agent has the full context of its own previous change, so this is usually faster than describing the fix from scratch yourself.

Following the guardrails page's logic: this whole task ran on a feature branch, touched no production data, and every change is reversible through version control — so it was reasonable to let the agent run the full plan and only review the final diff, rather than approving every individual file edit along the way. If this had involved an actual database migration on production data instead of a local dev database, the migration step specifically would have warranted a stop-and-confirm.