No code is written without a plan file that authorises it — for humans and agents alike.
This repo documents a workflow I run day to day on a live production system, generalised onto a synthetic example (a reservation system) so it can be shared publicly without exposing a real client's product or business logic. The method is real. The example domain is not.
Most AI-native engineering advice stops at "write good prompts." That's not the bottleneck once a team is generating most of its code with agents. The bottleneck becomes:
- The quality of the specification going in.
- The strength of the review and testing gates coming out.
- How fast a reviewer — human or agent — can tell a correct answer from a merely plausible one.
Reviewing a thousand lines of plausible-looking generated code is exhausting and low-signal. You end up approving things you don't fully understand. Reviewing a two-page spec is fast, high-signal, and it's where the real decisions actually live.
The thesis: code review moves upstream and becomes plan review.
An engineer grabs a ticket, prompts their way to something that runs, and closes it — without ever really understanding what the business needed. The code compiles, the tests pass, and it's wrong in a way nobody catches for three months.
If you can't write the plan, you didn't understand the problem, and you don't get to generate the code. That's the whole rule.
A fresh chat. The agent is told to act as a Principal Architect and to read the project's context first — global rules, architecture docs, the schema, the spec template. Its job in this phase is not to write code. It's to interview the human, adversarially, before anything is planned: impact on the data model, API contracts, state-machine transitions, auth and data-isolation scope, error cases, business-rule edge cases. Numbered questions. It waits for real answers.
See docs/grill-me-transcript.md for a worked example.
The agent asks precise questions ("what happens if a reservation is cancelled after payment has been captured?"). The human answers. Data shapes, models and API contracts get debated until the logic has no holes left. This is where the human spends time up front to save hours of code review later.
With full alignment, the agent writes the plan following the exact template in
plans/templates/00-spec-template.md: what to read before
touching code, what files change, and explicit, checkable acceptance criteria. It's saved,
versioned, in plans/.
See plans/01-cancel-reservation.md for a complete example.
A fresh chat, zero code. A different agent session audits the plan adversarially: missing state transitions, race conditions on concurrent writes, auth and data-isolation gaps (could a CLIENT see or mutate another client's data?), schema/validation mismatches, error-path status codes, unlisted side effects. One question always gets asked: is there a scenario that passes every acceptance criterion and is still wrong?
A completely fresh chat, to clear the context window so the agent executes instead of continuing a
brainstorm. It works the plan step by step, marks each step [x] as it completes it, and — this is
the part that matters — stops and asks rather than guessing the moment it hits a blocker or
something that contradicts the plan. When it's done, it updates .ai/decisions.log.
CLAUDE.md— the global rules an agent reads before doing anything in this repo..ai/architecture.md— the system's data flows and state machine, kept current so an agent (or a new engineer) never has to guess it..ai/decisions.log— a running, dated ledger of technical decisions. Newest first. Not open for re-litigation unless the team explicitly reopens one.plans/— every feature, as a spec, before it was code.
I run this workflow on a live regulated healthcare platform in production — real users, real compliance constraints. That repo isn't public, for the obvious reasons (client data, business logic, a live product I don't own outright). Everything here — the domain, the example plan, the decision-log entries — is synthetic, built to show the shape of the method honestly rather than pretend a toy example is the real system. If you ask me about it in an interview, that's exactly what I'll tell you.
Gilberto Marcano — Engineering Manager. This is the most differentiated thing I have for AI-native engineering roles: not that I use AI tools, but that I've rebuilt how a team works around the assumption that most code will be agent-generated. linkedin.com/in/giildev