What it does

Forbids the agent from inventing requirements. Before any feature work begins, the agent looks for an existing story file (with explicit acceptance criteria), confirms ambiguities with the human, and then turns each acceptance criterion into a failing test before writing implementation code.

When to use it

In teams that already write user stories or PRDs
When the agent is operating semi-autonomously and might otherwise scope-creep into “improvements”
When a non-technical product owner needs to verify the agent built what was asked
For greenfield projects where you want to enforce spec-first culture from day one

How it works

Add to your CLAUDE.md:

## Story-Driven Development

Before starting any feature work:

1. Check `{{stories_dir}}/` for an existing story or acceptance criteria
2. If criteria are ambiguous, ask before coding — do not invent requirements
3. If no story exists for the requested work, flag it — do not proceed with assumptions
4. Implementation must satisfy all acceptance criteria in the story
5. For ATDD: convert each AC into a failing test before implementation begins

Configure for your stack

Replace {{stories_dir}} with your project’s story location:

docs/stories/ (markdown files, one per story)
linear://team/issues/ (link to Linear via MCP)
.github/ISSUE_TEMPLATE/ (GitHub Issues with AC sections)
notion:// (Notion via MCP)

Example story format

# Story: Member can be removed by admin

linear: TEAM-115
status: in-progress

## Acceptance Criteria

- [ ] Admin sees a "Remove" button next to each member in the org settings page
- [ ] Clicking "Remove" opens a confirmation modal showing the member's name
- [ ] Confirming removal calls DELETE /api/orgs/:orgId/members/:userId
- [ ] On success, the member is removed from the list without page reload
- [ ] On error, an inline error message is shown without removing the member
- [ ] A non-admin viewing the page does not see the Remove button at all
- [ ] The removed member loses access immediately (cannot use existing JWT)

## Dev Notes

- RLS policy on org_members must enforce admin-only deletion
- Cascade delete role_assignments on member removal
- Add audit log entry: action=member_removed

The agent reads this story, generates 7 failing tests (one per checkbox), commits them, then implements until all are green.

Why it matters

Without a story, the agent decides what to build based on ambient context — and that decision is often subtly wrong. A non-technical reviewer can’t catch the difference between “what was built” and “what was asked.” A story file makes the contract explicit and reviewable in plain English. ATDD then makes the test suite the authoritative interpretation of that contract.