poko8nada/spec

Specification

Purpose of docs/spec.md

Captures what the system must do — not how it does it. Agents use it to understand the expected behavior when implementing or modifying features. Requirements that can be expressed as tests should be — docs/spec.md is for what cannot.

What to write

• Functional requirements: what the system must do, from the user's perspective
• Acceptance criteria: specific, verifiable conditions for each requirement
• Edge cases: explicit decisions about boundary conditions and error states
• External interfaces: API contracts, third-party integrations, data formats
• Why Not: why alternative approaches were rejected for each requirement

The bar is: a fresh agent should be able to implement from docs/spec.md without needing the originating chat.

What NOT to write

• Implementation details — how the system works belongs in code
• Technology choices — those belong in docs/overview.md and ADRs
• Anything derivable from code, tests, or type definitions

Format

This document should be written in Japanese.

---
last-validated: YYYY-MM-DD
phase: current
---

# Specification

## [Feature Name]

### Requirements

- [REQ-001] [Actor] must be able to [action] so that [outcome]
- [REQ-002] ...

### Acceptance Criteria

- [REQ-001] Given [context], when [action], then [expected result]
- [REQ-001] Given [context], when [invalid input], then [error state]

### Edge Cases

- [Explicit decision about a boundary condition]

### Why Not

- [Alternative approach]: [reason rejected]

Writing good acceptance criteria

• Express in Given / When / Then format
• One criterion per observable behavior
• Error paths are first-class requirements — not afterthoughts
• If a criterion can be directly expressed as a test, write the test instead
• Include exact route paths, binding names, environment variables, object keys, query parameters, or file patterns when they are part of the behavior
• State required vs optional inputs explicitly
• State what happens on failure explicitly
• Avoid vague nouns like "専用バケット", "対象ファイル", or "適切な値"

Concreteness guide

Write:

• what exact input is read
• from where it is read
• what page or API exposes it
• what success looks like
• what failure looks like
• what this iteration explicitly does not do

If a value is still unknown and implementation would branch based on it, ask before treating the spec as complete.

Maintenance rule

Update last-validated whenever you verify requirements still reflect intent. Mark superseded requirements explicitly rather than deleting them — deletion loses the Why Not context that prevents agents from reintroducing rejected approaches.