1.4 KiB
1.4 KiB
Documentation Voice
Use terse, normative statements. Avoid "the user wants", "currently", "now", "fixed", "regressed", "recently". State what the system does, not what happened.
Bullet Budget
At most 120 lines per file. Nearly empty or empty files are honest.
Single-Home Rule
architecture.md: structural/runtime decisions (component boundaries, chosen abstractions, protocol/storage direction, explicit "X over Y" with reason).product.md: behavior, UX, defaults, scope, naming/terminology, workflow decisions.style.md: visual/aesthetic language, presentation/typography conventions, prose/voice rules.
Concreteness Test
Every bullet must change a fresh agent's behavior. "Provide configurable, reference-compatible interactions" is delete-tier. "Status bar: powerline segments, solid right edge, inward-facing left triangle, no bold, elapsed time ≤3 chars" is keep-tier.
Exclusions
- Project docs digest (already documented).
- Global user taste not a project decision.
- Current-task state (bugs in flight, progress, plans, TODOs, "for now").
- File paths, line numbers, function/type names, commit/issue ids (product component vocabulary allowed).
Friction Markers
A terse marker like "(recurrently regressed)" MAY close a bullet where it strengthens the instruction; keep rare.
Grouping
Group bullets under short ## domain sections. One line per bullet where possible.