SPEC.md Canonical Format Specification

SPEC.md is the single source of truth for Spec-Driven Development (SDD). Use concise plain English or the project's adopted compact notation.

1. Document Sections

§G — Goal

A concise statement of product intent.

# §G
build distributed rate limiter with sliding-window Redis Lua script.

§C — Constraints

Hard constraints, technology stack limits, and explicit out-of-scope declarations.

# §C
- Go 1.22+ stdlib + go-redis/v9.
- ⊥ external dependencies outside Redis.
- memory overhead ≤ 50MB @ 100k keys.
- out of scope: clustering, dynamic cluster topology changes.

§I — Interfaces

Public membranes: CLI commands, API endpoints, environment variables, or exported signatures.

# §I
api: POST /v1/limiter/check → 200 {allowed:bool, remaining:int, reset_ms:int}
cmd: `limiter-cli bench --rate=<n>` → stdout benchmark summary
env: REDIS_URL ! set

§R — Research Log (Optional)

Distilled external facts, primary documentation links, or RFC references.

# §R
id|domain|finding|source
R1|dependency version|verified version-specific constraint|<primary-source-url>
R2|transaction behavior|verified atomicity guarantee|<primary-source-url>

§V — Invariants

Non-negotiable behavioral invariants. Numbered monotonically V1, V2, ...

# §V
V1: ∀ check req → atomic sliding window evaluate in Redis Lua
V2: Redis down → fail open (return allowed:true with header warning)
V3: latency p99 ≤ 2ms @ 10k rps

§T — Tasks

Ordered pipe table of implementation tasks. Numbered T1, T2, ...

Status: . todo, ~ wip, x done.
cites: Invariants (V<n>) or Interfaces (I.<name>) that the task must satisfy.

# §T
id|status|task|cites
T1|x|scaffold Redis client with fallback|V2,I.api
T2|~|implement sliding window Lua script|V1
T3|.|expose HTTP endpoint & healthcheck|I.api

§B — Bug Log

Feedback memory capturing bugs and regressions found during build/check/production.

# §B
id|date|cause|fix
B1|2026-04-20|lua script script error on empty redis key|V1

2. Sectioned Ownership

spec owns goals, constraints, interfaces, research, task definitions, and general invariants.
build flips only task status (. → ~ → x).
check is strictly read-only.
backprop appends §B rows and amends bug-related §V invariants.
Each owner may edit its sections within the authorized task without a separate handoff.

2.5 KiB Raw Blame History