Files

Paul O'Reilly f41c22d0ac Add question-reframing guidance to CLAUDE.md; commit accumulated project files

- CLAUDE.md: add "Question the question" and "One clarifying question" rules
  to Tone and Interaction — XY problem detection, false premise checks, and
  explicit reframe pattern before answering
- Add claude/ detail-file directory (topic docs referenced from CLAUDE.md)
- Add ABOUT.md, FUTURE.md
- Update memory/, scripts/, settings.yaml with accumulated session changes

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-25 09:37:28 +12:00

2.2 KiB

Raw Permalink Blame History

Spec-Driven Development

Any coding project with multiple milestones MUST have specs before code. Hard requirement, not a suggestion. Workflow: Plan → Spec → Test → Code.

At project start or when starting a new milestone, always read:

best-practices/spec-driven-development.md — spec structure, requirement numbering, scenarios, maintenance
best-practices/test-driven-development.md — edge case discovery, property-based testing, AI agent testing patterns

Required artifacts

Every multi-milestone coding project must have:

SPEC.md — Index file at the project root. Lists all spec files with a "when to read" column. Same thin-index pattern as MEMORY.md.
spec/ directory — One spec file per subsystem. Each spec follows: Overview, Responsibilities, Dependencies, Data Model, Requirements (numbered), Scenarios (given/when/then).
Numbered requirements — Each spec uses a prefix (e.g., IG-1 for ingestion, DB-1 for database). Requirements must be independently testable and unambiguous.
Test files that reference spec IDs — every test function name includes its requirement ID: test_ig3_dedup_by_message_ts.

Workflow

Plan — architecture decisions, milestone breakdown, technology choices (PLAN.md)
Spec — detailed contracts, data models, interfaces, requirements, scenarios (spec/)
Test — write tests from the spec before code exists. They should all fail.
Code — implement until tests pass. Minimum code to satisfy the spec.
Update — if implementation reveals spec issues, update spec → test → code in that order.

When to write specs

Before M1 implementation begins — write specs for all subsystems in M1's scope
Before each subsequent milestone — specs for new subsystems, updates to existing specs for changes
Spec changes and test changes ship in the same commit
Code changes that affect interfaces require spec changes in the same commit

What does NOT need a spec

Infrastructure-only projects (Helm values, Kustomize manifests, Ansible playbooks) — declarative, not behavioural
Single-script utilities — a well-commented script with a test is sufficient
Documentation-only changes

2.2 KiB Raw Permalink Blame History