79 lines
2.4 KiB
Markdown
79 lines
2.4 KiB
Markdown
|
# SPEC.md Canonical Format Specification
|
||
|
|
|
||
|
|
`SPEC.md` is the single source of truth for Spec-Driven Development (SDD). All sections are written in Caveman encoding.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 1. Document Sections
|
||
|
|
|
||
|
|
### §G — Goal
|
||
|
|
One single line in Caveman dialect stating the product intent.
|
||
|
|
```markdown
|
||
|
|
# §G
|
||
|
|
build distributed rate limiter with sliding-window Redis Lua script.
|
||
|
|
```
|
||
|
|
|
||
|
|
### §C — Constraints
|
||
|
|
Hard constraints, technology stack limits, and explicit out-of-scope declarations.
|
||
|
|
```markdown
|
||
|
|
# §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.
|
||
|
|
```markdown
|
||
|
|
# §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.
|
||
|
|
```markdown
|
||
|
|
# §R
|
||
|
|
id|domain|finding|source
|
||
|
|
R1|redis lua|reclaim memory via `redis.replicate_commands()`|redis.io/docs/manual/programmability/lua-api
|
||
|
|
R2|token bucket|GCRA algorithm reduces atomic roundtrips to 1|en.wikipedia.org/wiki/Generic_cell_rate_algorithm
|
||
|
|
```
|
||
|
|
|
||
|
|
### §V — Invariants
|
||
|
|
Non-negotiable behavioral invariants. Numbered monotonically `V1`, `V2`, ...
|
||
|
|
```markdown
|
||
|
|
# §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.
|
||
|
|
```markdown
|
||
|
|
# §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.
|
||
|
|
```markdown
|
||
|
|
# §B
|
||
|
|
id|date|cause|fix
|
||
|
|
B1|2026-04-20|lua script script error on empty redis key|V1
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 2. Sectioned Ownership
|
||
|
|
- `spec` is the sole mutator of `SPEC.md`.
|
||
|
|
- `build` flips only task status (`.` → `~` → `x`).
|
||
|
|
- `check` is strictly read-only.
|
||
|
|
- `backprop` appends `§B` rows and drafts `§V` lines.
|