AI Coding Spec Packet Before Code Generation

A copy-ready packet for giving AI coding tools a bounded task, acceptance criteria, file ownership, tests, and review evidence before code generation starts.

Published on 2026-05-03 · Updated 2026-05-06 · 7 min read · Author: Spec Coding Editorial Team · Review policy: Editorial Policy

The packet exists to slow the right thing down

AI coding tools are fast at producing a diff. They are much worse at knowing which diff should exist. A spec packet is the small document you hand to the tool before it writes code. It is not a full design doc, and it is not a loose prompt. It is a bounded work order: the behavior to change, the files that may be touched, the acceptance criteria that prove success, and the evidence a reviewer should expect after generation.

The goal is not to make AI slower. The goal is to stop the expensive kind of speed: a quick patch that expands scope, rewrites unrelated code, invents tests that only match its own implementation, and leaves the human reviewer guessing what was authorized.

Use it when the change can be reviewed

A spec packet works best for a task that fits inside one review surface: a feature branch, a migration, an endpoint change, a bug fix, or a narrow UI behavior. If the work still needs product discovery, architecture agreement, or security sign-off, do not hand it to an AI tool yet. First write the higher-level spec, use the Feature Spec Generator, or start from the Feature Spec Template.

The packet should answer one blunt question: after the tool finishes, how will a reviewer decide whether the generated code did the right thing? If that answer is vague, generation is premature.

The six fields that matter

I keep the packet short enough to paste into an AI coding workspace, but strict enough that every generated change has a boundary. These six fields are the minimum.

• Task summary: the one behavior change the tool should implement.
• Allowed files: the files or directories it may edit, plus any files it may read but not change.
• Non-goals: explicit changes it must not make, including refactors and dependency additions.
• Acceptance criteria: Given/When/Then rows that describe observable behavior.
• Evidence required: tests, logs, screenshots, or manual checks expected in the final response.
• Review rule: what blocks merge if the generated diff cannot prove it.

Copy this packet

This version is intentionally plain. Put it in the ticket, paste it into the coding tool, and keep it with the PR description so the reviewer can compare the output to the original request.

AI coding spec packet

Task:
- Implement:
- User or system behavior to preserve:

Allowed write scope:
- Files/directories the AI may edit:
- Files the AI may read for context:
- Files the AI must not change:

Non-goals:
- Do not refactor unrelated code.
- Do not add dependencies unless explicitly approved.
- Do not rename public fields, routes, events, or error codes.
- Do not change generated files unless the generator is part of this task.

Acceptance criteria:
- Given:
  When:
  Then:
- Given:
  When:
  Then:

Failure paths:
- Invalid input:
- Permission or ownership failure:
- Timeout, retry, or partial failure:
- Rollback or recovery expectation:

Evidence required before review:
- Tests to add or update:
- Existing tests to run:
- Manual check, screenshot, log, or metric:
- PR description must map each acceptance criterion to evidence.

Merge blocker:
- If any acceptance criterion has no evidence, the PR is not ready.

Example: retry behavior without scope creep

Imagine a payment webhook sometimes fails when the ledger service times out. The tempting AI prompt is "add retry logic to the webhook handler." That prompt invites the model to redesign error handling, change the client wrapper, and invent a retry policy nobody approved. The packet is tighter.

Task:
- Add retry handling when LedgerClient.recordPayment returns a timeout.

Allowed write scope:
- src/payments/webhook-handler.ts
- src/payments/webhook-handler.test.ts

Non-goals:
- Do not change LedgerClient public API.
- Do not add a retry library.
- Do not change webhook signature validation.

Acceptance criteria:
- Given LedgerClient times out once
  When the webhook handler processes a valid payment event
  Then it retries once and records the payment.
- Given LedgerClient times out twice
  When the webhook handler processes the event
  Then it returns the existing retryable failure response.
- Given signature verification fails
  When the handler receives the event
  Then no ledger call is attempted.

Now the review is mechanical. The generated diff either stays inside two files or it does not. It either proves each criterion or it does not. The tool can still help, but it is no longer allowed to decide the shape of the work by itself.

File ownership is not optional

Most AI coding drift starts with file ownership. A model sees a helper, decides it can be cleaner, and edits it. Then one small task turns into a soft refactor. The packet should name write scope and read scope separately. "You may inspect the API client, but you may not edit it" is a useful instruction. So is "if the task appears to require another file, stop and ask for approval instead of editing it."

This matters even more when multiple people or agents work in the same repository. A clear write scope reduces merge conflicts and makes review easier. It also makes generated work easier to revert if the approach is wrong.

Evidence beats explanation

Ask the AI tool for evidence, not confidence. A final answer that says "implemented successfully" is almost worthless. A final answer that says "AC-1 is covered by webhook-handler.test.ts case 'retries once on timeout'" is reviewable. The packet should require that mapping every time.

For UI work, evidence might be a screenshot and a viewport list. For API work, it might be contract tests and an error-response fixture. For database work, it might be a dry-run migration log and rollback notes. The exact evidence changes by domain, but the rule stays the same: no criterion should be left as a claim.

Pair the packet with Spec Skills

The Spec Skills workflow is useful here because it separates drafting, review, and implementation. Use Spec Skills to turn a rough ticket into the packet, then let the coding tool operate inside that packet. If the generated code exposes a missing decision, update the packet before asking for another implementation pass.

This also keeps AI Coding Governance practical. Governance does not need to be a heavy approval board. It can be a repeatable habit: every AI-generated PR starts from a packet, every criterion maps to evidence, and every out-of-scope change is removed before review.

Review the packet before reviewing the code

When the PR arrives, open the packet first. Check whether the diff stayed inside the allowed files. Check whether every acceptance criterion has evidence. Check whether the tool added a dependency, renamed an exported field, or changed generated code without permission. Only then read the implementation details.

If the packet was wrong, fix the packet and regenerate. If the implementation ignored the packet, reject the PR. Do not silently repair the generated diff; that teaches the workflow that sloppy packets are acceptable. The point is to make the work repeatable enough that the next AI-assisted change starts from a clearer contract.

When a Full Packet Is Too Much

Not every AI-assisted change needs the full form. A typo fix, a test rename, or a small copy edit can use a lighter note. The packet becomes mandatory when the generated code touches production behavior, public contracts, permissions, migrations, payments, background jobs, or shared helpers. Those are the places where a helpful model can accidentally make a product decision.

The smaller rule I use is this: if a reviewer would need to ask "why did this file change?", the task needed a packet. If the answer is obvious from the diff and the blast radius is tiny, a short PR note is enough. The goal is not ceremony. The goal is to keep AI-generated changes from smuggling unreviewed decisions into the codebase.

One-page checklist

• The packet names the behavior change in one sentence.
• Allowed write scope is narrower than the repository.
• Non-goals explicitly ban refactors and dependency additions.
• Acceptance criteria include happy path, failure path, and permission or ownership behavior.
• Evidence requirements name tests or checks, not just "run CI".
• The PR description maps criteria to files and evidence.