Applied AI-Accelerated Government Development

Bring a Non-Standard Module Up to Standard

Updated

Intermediate

What you'll learn

~35 min
  • Plan the change read-only, then pin an off-pattern route's current behavior with characterization tests (tests that record what the code does today) in an isolated worktree (a second checkout of the repository on its own branch) before any edit
  • Move the route onto the response contract, pagination, withPermission(), schema validation and provenance in one reviewable change
  • Separate the deliberate behavior changes from the behavior that must be preserved, and enforce the split with a diff check instead of a prompt instruction
  • Choose between updating every consumer in one pull request and versioning the response, and say why

Same stack, different habits

Most feature work in a long-running codebase is not a new feature. It is a module that was written before the team agreed on its patterns: it runs on the same stack as everything else, it works, and it does five things differently from the rest. This lesson moves one such module onto the patterns from Lessons 5 to 11: a closed role set enforced by withPermission(), errors as a contract, pagination, schema validation, and provenance of every value.

This is same-stack conformance. Moving behavior out of an older platform, where the rules are undocumented and the data layer is different, is a separate job: Lessons 22 and 23 cover extracting behavior from an older system and replacing it behind differential tests. The tests you wrote in Lessons 12 and 13 are what make this lesson safe: they prove behavior is preserved, so you can let an AI CLI do the mechanical rewrite.

This lesson is platform-neutral: nothing in it changes with your cloud, so the third column points at the lesson where your platform touches the pattern, and says so where it does not.

ProblemThe patternWhere your platform lesson lands itYou decide
Change a route without changing what it doesPlan read-only, characterization tests first in a worktree, then refactor, then the same tests plus the new contractNothing platform-specific; the diff check runs in the pipeline, which 37 lands on your code hostWhether a module without tests may be touched at all
Keep the agent from editing the tests that judge itA protected path plus a diff check; CODEOWNERS on the test files (Lesson 25: the agent proposes, a protected test decides)37: code-owner review or a required-reviewer policy, by hostWhich paths are protected, and who owns them
Change a response shape other code readsUpdate every consumer in the same pull request, or version the responseNothing platform-specificHow many consumers, and who owns them
Rows that existed before provenanceBackfill an explicit “unknown” originNothing platform-specific; the migration runs against your managed SQL Server in 34, 35 or 36Whether an empty origin is acceptable to your data owner

Anatomy of an off-pattern route

This is the vehicles route, written before the platform patterns existed. It signs the caller in correctly and then does everything else by hand.

REFERENCE CODE src/app/api/vehicles/route.ts (before): off-pattern route handler before conformance open reference hide reference Reference pattern for your workspace agent; open to inspect or compare this file. You do not type or paste this by hand.
// src/app/api/vehicles/route.ts (BEFORE)
import { NextResponse } from "next/server";
import { requireSession } from "@/lib/auth/session";
import { store } from "@/lib/auth/store";
import { withPool } from "@/lib/db/pool";
export async function GET() {
try {
await requireSession(store);
const result = await withPool((pool) => pool.request().query("SELECT * FROM vehicles ORDER BY plate_number"));
return NextResponse.json(result.recordset);
} catch (e: any) {
return NextResponse.json({ error: e.message }, { status: 500 });
}
}
export async function POST(req: Request) {
try {
const session = await requireSession(store);
if (!session.roles.includes("admin") && !session.roles.includes("operator")) {
return NextResponse.json({ error: "Forbidden" }, { status: 403 });
}
const body = await req.json();
await withPool((pool) => pool.request()
.input("plate", body.plateNumber).input("make", body.make)
.input("model", body.model).input("year", body.year)
.query("INSERT INTO vehicles (plate_number, make, model, year) VALUES (@plate, @make, @model, @year)"));
return NextResponse.json({ success: true }, { status: 201 });
} catch (e: any) {
return NextResponse.json({ error: e.message }, { status: 500 });
}
}
LineProblemThe pattern
SELECT *, no limitEvery column and every row, with no pageNamed columns, a page size with a platform cap, OFFSET and FETCH
NextResponse.json(result.recordset)A bare array; no envelopeThe list envelope with paging metadata
session.roles.includes(...) inlineRole names written into the route; a new route can forgetwithPermission() over a closed role set
body.plateNumber straight into SQL parametersNo validation, no length or type limitsA schema, and only parsed.data reaches the database
e.message in the responseLeaks database and driver textErrors are a contract: a code and a safe message
catch (e: any)Untyped; a session failure becomes a 500The guard turns a missing session into 401
No origin on the rowNobody can tell a typed record from a synced oneProvenance of every value (data_source)

Step zero: plan it read-only

Before the agent can edit anything, have it read and propose. Opened with its plain name, Claude Code and Copilot CLI refuse file edits in plan mode, Codex refuses them when started with codex --sandbox read-only, and Antigravity waits for your approval of its outline (its documentation does not say it blocks edits), so run git status before you approve (the tool modes table has each tool’s details).

ToolPlan-first start
Claude Codeclaude, then Shift+Tab or /plan
Codex CLIcodex --sandbox read-only, then /plan or Shift+Tab (plan mode has no launch flag; the sandbox flag refuses the edits, and leaving /plan does not lift it, so once you approve the plan, switch to Auto with /permissions)
Antigravity CLIagy, then Shift+Tab or /plan
GitHub Copilot CLIcopilot, then Shift+Tab or /plan
Plan the conformance work for src/app/api/vehicles/route.ts: the consumers,
the tests, the files you would touch, and what the migration needs.
Do not edit anything yet.

Lesson 2 holds the dated four-tool equivalents table; Lesson 1 holds permissions and sandbox. For this lesson, ask for the plan of the whole job: which route, which consumers, which tests, which files the refactor may touch, and what the migration needs. You read it, correct it, and approve it; only then does the agent get write access.

Step one: pin what it does now, in a worktree

Do not start with the refactor prompt. Start with tests that record today’s behavior, so you can tell a deliberate change from an accident. Characterization tests assert what the code does, not what it should do.

Run the agent in a worktree so the characterization work sits on its own branch and checkout, and your working tree stays untouched while it runs. Claude Code starts one with claude --worktree <name>; Codex CLI accepts codex --worktree. Module 19 lesson 5 teaches the subagent, background and worktree ladder in general; here you need only the isolation.

Write Vitest characterization tests in a worktree for src/app/api/vehicles/route.ts that record its current behavior without changing the route, and mark tests that pin defects with [PINS DEFECT].

What to check in the characterization plan

  • Uses the Vitest setup from Lesson 12 (cookie jar and in-memory store, mocking only src/lib/db/pool).
  • Records GET (200 with the rows as returned by the pool, 401 with no session) and POST (403 for a viewer, 201 for an operator, the four inserted columns, and 500 on a database error).
  • Ends the test name with the literal tag [PINS DEFECT] on any test that pins a defect (such as the bare array or the leaked driver message in the 500 body), and leaves the route untouched.
SESSION Plan, characterize in a worktree, refactor, get caught, repair
  1. Typed in the terminal: claude
  2. Mode:Plan mode (Shift+Tab)
  3. You type in the session: Plan the conformance work for src/app/api/vehicles/route.ts: the consumers, the tests, the files you would touch, and what the migration needs. Do not edit anything yet.
  4. The tool replies: Read 9 files. Proposed plan: 1. Characterize first, on a branch of its own: 7 tests, two of them marked [PINS DEFECT] (bare array, driver message in the 500 body). 2. Refactor the route onto withPermission(), pagination, the response helpers and a zod schema; src/lib/schemas/vehicles.ts is new. 3. Consumers: 3 found by searching for /api/vehicles (page hook, fleet summary report, selector). 4. Migration for data_source as its own additive file; I will not run it. 5. Files I will NOT touch: the characterization test file except its two marked tests, and the CODEOWNERS file. Approve, edit, or reject?
  5. You type in the session: Write Vitest characterization tests in a worktree for src/app/api/vehicles/route.ts that record its current behavior without changing the route, and mark tests that pin defects with [PINS DEFECT].
  6. The tool replies: Created worktree .claude/worktrees/vehicles-characterize on branch worktree-vehicles-characterize. Created src/app/api/vehicles/route.characterization.test.ts with 7 tests. Two test names end in [PINS DEFECT]: - GET returns a bare array [PINS DEFECT] - a database error returns the driver message in the body [PINS DEFECT] The route was not modified.
  7. Typed in the terminal: npx vitest run src/app/api/vehicles
  8. The tool replies: ✓ |server| src/app/api/vehicles/route.characterization.test.ts (7 tests) Test Files 1 passed (1) Tests 7 passed (7)
  9. You type in the session: Now refactor the route to the platform patterns. Update every consumer of /api/vehicles. Behavior must be preserved except the two defects.
  10. The tool replies: Done. 7 files changed, 1 migration file added. The five preserved tests pass. I also loosened the 'viewer POST returns 403' test: the new guard returns the same status with a different body, so I changed its body assertion. Not verified: I did not run the migration, and the consumer changes are covered by type checks only.
  11. Typed in the terminal: node scripts/check-pins.mjs main
  12. The tool replies: check-pins: FAILED src/app/api/vehicles/route.characterization.test.ts: lines 31-33 changed inside 'POST by a viewer returns 403', which is not marked [PINS DEFECT] Only tests marked [PINS DEFECT] may change. Revert that test or mark it with a reason a reviewer accepts.
  13. You type in the session: The check is right. Revert the viewer test to its original assertions. It pins the 403 status only, and the 403 body is lesson 07's envelope, so do not revert the route to the legacy body.
  14. The tool replies: Reverted. The test pins the 403 status, which a viewer still gets. The 403 body is now lesson 07's { error: { code, message } } envelope from the guard, and I added it to the deliberate-changes table instead of loosening a test. $ node scripts/check-pins.mjs main check-pins: ok (2 changed tests, both marked [PINS DEFECT]) $ npx vitest run src/app/api/vehicles Tests 7 passed (7)

Illustrative session; exact output varies by tool and agency configuration.

The failure in the fifth turn is the reason for the script. The prompt said to preserve behavior; the agent loosened a test anyway, and only a check that does not read the prompt caught it.

The diff check

“Only the two tests marked PINS DEFECT may change” is a rule about the agent’s work, so it cannot live in the agent’s prompt. Enforce it in two places the agent cannot edit. A script compares the characterization test file against the base branch and fails if any changed line sits outside a test whose name ends in [PINS DEFECT]. And the script, the test file and CODEOWNERS are protected paths, owned by people.

REFERENCE CODE scripts/check-pins.mjs: diff check enforcing that only [PINS DEFECT] characterization tests change open reference hide reference Reference pattern for your workspace agent; open to inspect or compare this file. You do not type or paste this by hand.
scripts/check-pins.mjs
// Usage: node scripts/check-pins.mjs <base-ref>
// Fails when a changed line in a characterization test is not inside a test marked [PINS DEFECT].
import { execFileSync } from 'node:child_process';
const base = process.argv[2] ?? 'main';
const files = execFileSync('git', ['ls-files', '*.characterization.test.ts'], { encoding: 'utf8' }).split('\n').filter(Boolean);
let bad = 0;
for (const file of files) {
let old;
try { old = execFileSync('git', ['show', `${base}:${file}`], { encoding: 'utf8' }).split('\n'); } catch { continue; } // new file: nothing to protect yet
const marked = new Set(); // 1-based old-file line numbers inside a [PINS DEFECT] test
let start = -1, mark = false;
const close = (end) => { if (mark) for (let n = start; n <= end; n++) marked.add(n); };
old.forEach((line, i) => {
if (/^\s*it\(/.test(line)) { close(i); start = i + 1; mark = /\[PINS DEFECT\]/.test(line); }
});
close(old.length);
const diff = execFileSync('git', ['diff', '-U0', base, '--', file], { encoding: 'utf8' });
for (const m of diff.matchAll(/^@@ -(\d+)(?:,(\d+))? \+\d+(?:,\d+)? @@/gm)) {
const at = Number(m[1]), len = m[2] === undefined ? 1 : Number(m[2]);
const lines = len === 0 ? [at] : Array.from({ length: len }, (_, k) => at + k); // an insertion is judged by the line it follows
if (lines.some((n) => !marked.has(n))) { console.error(`${file}: lines ${lines[0]}-${lines.at(-1)} changed outside a [PINS DEFECT] test`); bad++; }
}
}
if (bad) { console.error('check-pins: FAILED'); process.exit(1); }
console.log('check-pins: ok');

A CODEOWNERS file excerpt protecting those paths looks like this:

# .github/CODEOWNERS (excerpt; the platform lesson 37 shows the equivalent for your code host)
*.characterization.test.ts @your-org/quality-owners
scripts/check-pins.mjs @your-org/quality-owners
.github/CODEOWNERS @your-org/quality-owners

Run node scripts/check-pins.mjs main as a required pipeline step, so a branch that edits a pinned test cannot merge on the agent’s say-so. This is the small version of the pattern Lesson 25 builds in full: the agent proposes, a protected test decides. Lesson 25 also covers what the script cannot prove, such as whether branch protection is actually switched on. An agent working in a developer’s CLI commits as that developer, so the account-based half of that protection needs the agent to run under its own account, and the path-based half does not.

The two marked tests are the point. After the refactor the diff of the test file shows exactly two intentional edits, and the check has already refused any other.


Step two: plan the refactor with your agent

Switch back to Plan mode (Shift+Tab, /plan, or the desktop app’s mode picker) to plan the route conformance change before editing:

Plan the refactor of src/app/api/vehicles/route.ts onto our platform patterns for permissions, pagination, response envelopes, Zod validation, and row provenance, plus an additive migration file. Ask me anything unclear first.

What to check in the plan before you approve

  • Wraps GET ("vehicles", "read") and POST ("vehicles", "create") in withPermission(), removes inline role checks, and adds "vehicles" to the Lesson 5 permission matrix.
  • GET uses clampPageSize(), ORDER BY with OFFSET and FETCH, an explicit column list (no SELECT *), a separate COUNT(*) query, and listResponse().
  • POST validates with VehicleCreateSchema.safeParse() in src/lib/schemas/vehicles.ts, returns 422 (VALIDATION_ERROR) on failure, sets data_source = 'manual' on insert, and returns singleResponse(row, 201) with no local try/catch.
  • Writes an additive migration for data_source in its own file while keeping the URL, table name, and existing column names unchanged.

If the first plan renames columns or alters the database schema inline instead of creating an additive migration file, push back before approving:

Keep the existing URL and column names unchanged, and put the data_source column change in a separate migration file.

The route that results, with the parts you check marked:

REFERENCE CODE src/app/api/vehicles/route.ts (after): refactored route on the platform patterns open reference hide reference Reference pattern for your workspace agent; open to inspect or compare this file. You do not type or paste this by hand.
// src/app/api/vehicles/route.ts (AFTER)
import { NextRequest } from "next/server";
import { z } from "zod";
import { withPermission } from "@/lib/auth/with-permission";
import { clampPageSize, listResponse, singleResponse } from "@/lib/response";
import { withPool } from "@/lib/db/pool";
import { VehicleCreateSchema } from "@/lib/schemas/vehicles";
const COLUMNS = "id, plate_number, make, model, year, data_source";
export const GET = withPermission("vehicles", "read", async (req: NextRequest) => {
const sp = req.nextUrl.searchParams;
const page = Math.max(1, Number.parseInt(sp.get("page") ?? "1", 10) || 1);
const pageSize = clampPageSize(sp.get("pageSize"));
return withPool(async (pool) => {
const rows = await pool.request()
.input("offset", (page - 1) * pageSize).input("pageSize", pageSize)
.query(`SELECT ${COLUMNS} FROM vehicles ORDER BY plate_number
OFFSET @offset ROWS FETCH NEXT @pageSize ROWS ONLY`);
const count = await pool.request().query("SELECT COUNT(*) AS total FROM vehicles");
return listResponse(rows.recordset, { page, pageSize, total: count.recordset[0].total });
});
});
export const POST = withPermission("vehicles", "create", async (req: NextRequest) => {
const parsed = VehicleCreateSchema.safeParse(await req.json().catch(() => null));
if (!parsed.success) {
return Response.json(
{ error: { code: "VALIDATION_ERROR", message: "Invalid request", fields: z.flattenError(parsed.error).fieldErrors } },
{ status: 422 },
);
}
const v = parsed.data;
const result = await withPool((pool) => pool.request()
.input("plate", v.plateNumber).input("make", v.make).input("model", v.model).input("year", v.year)
.query(`INSERT INTO vehicles (plate_number, make, model, year, data_source)
OUTPUT INSERTED.${COLUMNS.split(", ").join(", INSERTED.")}
VALUES (@plate, @make, @model, @year, 'manual')`));
return singleResponse(result.recordset[0], 201);
});

And here is the reference input schema your agent generates in src/lib/schemas/vehicles.ts:

src/lib/schemas/vehicles.ts
import { z } from "zod";
// Limits come from the column definitions, not from this lesson.
export const VehicleCreateSchema = z.object({
plateNumber: z.string().min(1).max(10).regex(/^[A-Z0-9]+$/),
make: z.string().min(1).max(50),
model: z.string().min(1).max(50),
year: z.number().int().min(1990).max(2035),
});

Check three things the model is most likely to get subtly wrong. The ORDER BY must be present, because SQL Server’s OFFSET clause requires one. Every .input() stays parameterized, with the column list built from a constant and never from the request. And no branch returns err or err.message, or builds a SafeError from one.

⚠Rows that existed before provenance

Adding the data_source column is a schema change, so the migration is its own reviewed file: additive, with a default that keeps old code working. Backfill existing rows with an explicit value that means the origin was never recorded (Lesson 10 defines your vocabulary). Do not label them manual: that states something nobody knows.


Deliberate changes and preserved behavior

Write this table in the pull request description. It is what the reviewer checks the test diff against.

BehaviorBeforeAfterKind
Rows returned for a given pageAll rows, unordered by pageThe same rows, the first page by defaultDeliberate (pagination)
List response shapeBare arrayEnvelope with paging metadataDeliberate, breaking
Viewer POST403403Preserved
Viewer 403 body{ error: "Forbidden" }{ error: { code, message } } (lesson 07)Deliberate
Operator POST with a valid body201201Preserved
POST with a malformed body500 from a thrown error422 with the failing fieldsDeliberate
Database failure bodyDriver messageCode and safe messageDeliberate
No session500 (the guard’s error was swallowed)401Deliberate

Five rows change on purpose, and two do not. A refactor with no such table is a rewrite with a nicer name.


Consumers: one pull request or a versioned response

The envelope change breaks any code that reads the response as an array.

Update every consumer in the same pull request when the consumers are few and in the same repository. Ask the AI CLI to find them rather than trusting memory:

Search the repository for every file that fetches /api/vehicles. For each,
show the code that reads the response and the minimal change to read the
envelope (.data for rows, .meta for paging). Do not change anything else.

Here is the reference before-and-after consumer update your agent applies to each caller:

// BEFORE
const { data: vehicles } = useSWR<Vehicle[]>("/api/vehicles", fetcher);
// AFTER
const { data: res } = useSWR<ListResponse<Vehicle>>(`/api/vehicles?page=${page}&pageSize=${pageSize}`, fetcher);
const vehicles = res?.data ?? [];
const total = res?.meta.total ?? 0;

Version the response when consumers live in other repositories or other teams: serve the envelope only when the request asks for it, migrate the callers, then retire the old shape on a date you announce. The cost is two formats to test until that date.

The decision is the number and ownership of consumers. If you cannot list them, you are in the second case whatever you would prefer.


Order of work when you have many modules

OrderDefectWhy it goes first
1Missing or bypassable withPermission()Any signed-in user can write
1err.message in a responseInternals reach the client
2No pagination on a table that can growTimeouts under load
2No validation on POST or PUTUnchecked input reaches the database
3Bare arrays and ad hoc error shapesConsumer bugs, not exposure
3SELECT *Breaks when the schema changes
4No provenanceA data-quality gap, rarely urgent

Track the list in a table in the repository, one row per module and one column per pattern, with the commit that fixed each. When someone asks which modules have an authorization guard, the answer is a list with commit ids.


Prove it

Run the diff check, the unit suite and the browser suite from Lessons 12 and 13; together they are the proof that behavior is preserved and that only the marked tests moved.

Terminal window
node scripts/check-pins.mjs main
npx vitest run src/app/api/vehicles
npx playwright test e2e/roles.spec.ts

The negative cases, which must fail before you trust the result:

Plant this faultWhat must fail
Edit the viewer-POST test so it passes without withPermission()check-pins.mjs, because that test is not marked [PINS DEFECT]
Remove withPermission() from POSTThe viewer POST test, which expects 403
Build a SafeError from err.messageThe refactored error-body test
Delete the ORDER BYThe migration or integration run against a real SQL Server, which rejects OFFSET without it (mocks will not catch this)
Revert one consumer to read an arrayThe Lesson 13 list-page test

The third row is a limit of the mocks from Lesson 12: they cannot know what your database engine accepts. Run that one query against a real instance before you merge.


KNOWLEDGE CHECK

You are about to refactor a route that has no tests. What do you do first?

KNOWLEDGE CHECK

Your route's consumers are two pages in this repository and a reporting job owned by another team in a different repository. Which approach fits?


Key takeaway

Plan read-only, pin behavior first in a worktree, then move the route onto the patterns in one change, and write the deliberate differences down as a table the tests agree with. Update every consumer you own in the same pull request, and version the response for the ones you do not. A diff check on the pinned tests, owned by people and not by the agent, keeps the rule from being a prompt instruction. The unit and browser suites from Lessons 12 and 13 are what let you hand the mechanical rewrite to an AI CLI and still know what changed.

LEADERSHIP DECISION
Whether an existing module is brought to standard in one reviewed change, and who owns the pinned tests.
PRACTITIONER ACTION
Pin the current behavior in a worktree, move the route, and list each deliberate difference in the table the tests agree with.
SUCCESS MEASURE
Calendar time: the rewrite merges once, with the diff check showing no pinned test changed.

Legend: LEADERSHIP DECISION = what a leader decides · PRACTITIONER ACTION = what the engineer does next · SUCCESS MEASURE = how you know, in calendar time, assessor-hours or cost, contract or revenue risk, or audit finding avoided

Search lessons