Skip to content
AtomPRD

RFC-000 — Design rationale

Status: ratified. Source: atomprd/specs/rfcs/RFC-000-design-rationale.md.

Summary

Section titled “Summary”

RFC-000 enumerates the design principles every other RFC inherits:

  1. Atoms over chapters. A PRD shreds into 500–2000-token units with stable IDs. The chapter shape is optimised for human reading top-to-bottom; atoms are optimised for LLM-context-window pulls and per-feature diffs.
  2. Closed vocabulary. 26 kinds, fixed. New kinds require an RFC. Open kind sets cause downstream tools to fail at dispatch.
  3. Typed relations. 20 relation types with kind-pair enforcement. Untyped edges devolve into “magic strings”.
  4. Two layers. Intent (prose) and Behavior (structured) are separate jsonb fields. The split lets PMs author Layer 1 before engineers fill Layer 2, and lets codegen lower Layer 2 deterministically.
  5. Per-field provenance. Every Layer 2 field carries A / B / C / D attribution. This makes “who set this?” answerable and makes lock-and-iterate feasible.
  6. Schema is the truth. @atomprd/spec is Zod-first. Hand-rolled parsers in tools are forbidden.

Why these specifically

Section titled “Why these specifically”

Each principle solves a failure mode observed in pre-AtomPRD attempts:

  • Chapter PRDs in LLM pipelines → context overflow → arbitrary truncation → hallucinations on truncated sections. Atoms fix this.
  • Tools inventing kinds when the spec is loose → vendor lock-in to the inventing tool. Closed vocabulary fixes this.
  • Untyped “see also” links → silent breakage on rename. Typed relations + stable IDs fix this.
  • Mixed-prose-and-structure fields → either codegen guesses or the format becomes write-only. Two layers fixes this.
  • “Who wrote this step?” being unanswerable → no audit trail, no confident automation. Provenance fixes this.
  • Tools rolling their own parsers → schema drift across the ecosystem. Zod-first spec fixes this.

See also

Section titled “See also”