Best Practices

Best Practices

Status: Complete · The durable habits that keep a team‑of‑one operation healthy over time. Where Operator Techniques are tactical moves, these are standing rules.

Organized by area. Each is a Do / Don't pair so the boundary is unambiguous.

---

Spec discipline

✅ Do	❌ Don't
Treat the spec as the source of truth; edit it before code	Patch code directly and "get to the spec later"
Write edge cases explicitly — they are the spec	Spec only the happy path
Version specs/ alongside src/ in the same commit	Let the spec and code diverge silently
Keep one bounded context per spec file	Write a mega‑spec describing three domains
Reconcile every hot‑fix back into the spec the same day	Accumulate "spec debt"

Context hygiene

✅ Do	❌ Don't
Prime with only the relevant slice + spec + .cursorrules	Dump the whole repo into the context window
Start a fresh context when answers drift	Fight a polluted, stale session
Keep files small and single‑responsibility (~100 lines)	Let monoliths grow until the model loses precision
Use narrow contracts between contexts	Let agents read across bounded contexts "for convenience"

Code structure (AI readability)

✅ Do	❌ Don't
Self‑documenting features/<slice>/ layout	Scatter a feature across unrelated folders
Split by responsibility	Split arbitrarily just to hit a line count
Encapsulate vendor/external code behind an adapter seam	Let a vendor SDK leak into domain logic

Review & QA

✅ Do	❌ Don't
Verify in a fresh, adversarial context	Let the writer be the sole judge
Review the diff; flag unrequested scope	Skim the whole file and trust it
Add a regression test for every bug before fixing	Fix and move on without a guard
Use diverse lenses for high‑blast‑radius changes	Repeat one identical check N times

Security defaults

✅ Do	❌ Don't
Validate and sanitize all external input	Trust generated code to be secure by default
Keep secrets in env/secret stores, never in code or prompts	Paste API keys into a chat or commit them
Enforce authZ in the spec and test it	Assume the agent added permission checks
Review dependencies the agent adds	Auto‑install whatever it suggests

→ Deep dive: Risks, Security & Governance.

Git & versioning

✅ Do	❌ Don't
Small, coherent commits tied to a slice	Giant "AI did a bunch of stuff" commits
Commit spec + code + tests together	Commit code without its spec change
Keep main shippable; flag incomplete work	Leave the trunk broken between sessions

Cost & tooling

✅ Do	❌ Don't
Score tools against the Zero‑Ops rubric	Adopt a tool that needs a dedicated admin
Favour standard exit formats (plain Postgres, portable components)	Accept deep lock‑in for convenience
Match the model tier to task entropy	Burn frontier‑model tokens on trivial edits

---

The five non‑negotiables

These are the operational face of the canonical First Principles (P2, P3, P5, P4, P6). If you forget everything else, keep these:

1. The spec is the source of truth. Code that disagrees with the spec is a bug in one of them — reconcile immediately.
2. The writer never judges its own work. Verify in a fresh, adversarial context.
3. Gate the irreversible. Auth, payments, deletion, schema drops — human decides, never auto.
4. Isolate bounded contexts. Isolation is what keeps generation precise.
5. You own the output. "The AI wrote it" is not an explanation an operator gets to give.

---

Reality check. Best practices are a target, not a purity test. Under real deadline pressure you will occasionally hand‑fix and reconcile late, or ship with thinner tests than you'd like. The goal isn't perfection — it's making the deviation deliberate and tracked, not silent and forgotten. A practice you broke knowingly and logged is recoverable; one you broke without noticing is technical debt with compound interest.

---

See also: Operator Techniques · KPIs & Metrics (how you'll know these are working) · When NOT to Use SAE.