# Best Practices Index

Compact index of the cross-project best-practices docs mounted at `/workspace/best-practices/`.
One line per doc — read the ones relevant to your current task; consult `spec-driven-development.md`
and `test-driven-development.md` by default on any planning or coding task.

| File | When to read |
|---|---|
| `spec-driven-development.md` | Always for planning/spec tasks — spec structure, requirement numbering, GIVEN/WHEN/THEN scenarios |
| `test-driven-development.md` | Always for coding/testing tasks — testability, edge cases, property-based testing |
| `mechanical-test-generation.md` | Writing specs a test-writer agent will consume, or writing tests directly from a spec — module layout tables, pattern-table-as-parametrize-matrix, exact error messages |
| `security-architecture.md` | Always — server boundary rule, defense in depth, auth patterns |
| `llm-code-security.md` | Always — injection flaws, input validation, OWASP guidance for LLM-authored code |
| `api-design.md` | Task involves an HTTP API — transport security, auth, versioning, error envelopes, docs/SDKs, contract testing |
| `database-selection.md` | Task involves data persistence — choosing a datastore, schema/migration tradeoffs |
| `kubernetes.md` | Task involves K8s resources — manifests, RBAC, networking, operators |
| `docker.md` | Task involves containers — Dockerfile patterns, image builds, multi-stage builds |
| `secrets-management.md` | Task involves credential handling — storage, rotation, delivery to workloads |
| `scripting.md` | Writing or reviewing a shell script — safety conventions (`set -euo pipefail`, quoting, idempotency) |

## Reading order for common tasks

- **Drafting a spec**: `spec-driven-development.md` → `mechanical-test-generation.md` → domain-specific doc(s) (`api-design.md`, `kubernetes.md`, etc.) → `security-architecture.md` / `llm-code-security.md`.
- **Writing code from a spec**: `test-driven-development.md` → `mechanical-test-generation.md` (if the spec was written for mechanical test derivation) → domain-specific doc(s).
- **Writing a shell script**: `scripting.md`.
- **Any task touching credentials**: `secrets-management.md` + `security-architecture.md`.