A Practical Template for Spec-Driven AI-Assisted Development

Start With the First Slice

Take a small feature: a colleague submits a training request and Office Management reviews it with enough context to decide.

Before the agent writes code, I need to turn that slice into project files it can follow.

I use requirements.md for the expected behavior, design.md for boundaries and tradeoffs, and tasks.md for implementation work. The project instruction file tells the agent how to use them.

This gives each decision a place before implementation starts.

Specify the Outcome: S

In requirements.md, I start with what should be true when the slice is finished:

A colleague can submit a training request, see it after submission, and Office Management can review it with enough context to decide.

This is the S in SCOPE. It anchors the file, but it is not the full requirement.

The same file still needs the users, scope, out-of-scope items, business rules, and acceptance criteria that define the slice.

Capture the Boundaries: C

C lives across requirements.md and design.md.

Product boundaries go in requirements.md:

A colleague can only see their own requests.

Design boundaries go in design.md:

Office Management reviews submitted requests from a shared queue.

Together, they tell the agent where the slice is allowed to move, and where it should stop.

Own the Consequences: O

O belongs in design.md.

This is where I write the tradeoff before it becomes code.

For the first slice, I might decide:

Approval history is not part of this slice. We only store the current status.

That choice is acceptable if it is explicit.

It tells the agent what not to build now, and it tells future work what was postponed.

Prove the Behavior: P

P starts in requirements.md as acceptance criteria.

For this slice, I would write:

After submission, the colleague can see the request, Office Management can review it, and another colleague cannot access it.

That line can become a test, an API check, or a manual scenario.

Verification rule: The format can change. The expected proof should not.

Externalize the Decisions: E

E does not live in one file.

A product rule goes back to requirements.md.

A design choice goes back to design.md.

A follow-up task goes back to tasks.md.

If implementation reveals a missing decision, I don't want it trapped in the chat.

I want it written where the next agent, teammate, or future version of me can find it.

The First Slice as Files

Here is how the same slice could look when SCOPE is written into the project.

# requirements.md

## Outcome
[S] A colleague can submit a training request, see it after submission, and Office Management can review it with enough context to decide.

## Scope
[C] A colleague can only see their own requests.
[C] Office Management can see submitted requests.

## Out of Scope
[O] Approval history is not part of this slice.

## Acceptance Criteria
[P] After submission, the colleague can see the request.
[P] Office Management can review the request.
[P] Another colleague cannot access the request.

# design.md

## Access Model
[C] Requesters query only their own requests.
[C] Office Management reads from a shared submitted-request queue.

## Tradeoff
[O] Store only the current status for this slice. Add approval history later if the workflow needs auditability.

# tasks.md

## First Slice
[E] Create the request model.
[E] Implement colleague submission.
[E] Implement Office Management review.
[E] Add the visibility check.
[E] Record postponed approval history as a follow-up.

The labels are not part of the real template.

I am using them here only to make the mapping visible.

In a real project, I would keep the files clean. The responsibility should be clear from the section and the content.

The Agent Still Needs Instructions

The files show where SCOPE lives.

The agent still needs to know how to use them.

That belongs in AGENTS.md, CLAUDE.md, or the project instruction file for the tool.

I would keep the rule direct: read the spec files before implementation, work from one approved slice, run the expected checks, and write new decisions back to the right place.

The same contract can be wrapped in commands:

/add-spec creates the first version of the spec.

/update-spec updates it when a decision changes.

/implement-spec turns one approved slice into code.

The full command files will come with the starter kit in Article 7. Here, the promise is smaller: the agent should know where SCOPE lives before it edits the code.

The Template Is Only the Start

At this point, SCOPE has a place in the project.

The next problem is execution.

The chat gets longer. Checks fail. The agent finds missing details. A small task starts touching more files than expected.

That is where the template needs operating discipline.

The next article is about running this workflow without losing context, direction, or control.