dab3db3727
- best-practices/v1: replace 9 stale symlinks (into planning/v1) with real files synced byte-identical from the canonical best-practices project; add INDEX.md, scripting.md, mechanical-test-generation.md (canonical had drifted heavily, e.g. api-design.md 463->807 lines) - planning/v1: delete duplicated best-practices/ copy (requires: inheritance confirmed via spec/harness.md HC-1/HC-7) - scripts/sync-best-practices.sh: idempotent re-sync from canonical checkout - code-methodology/v1: INDEX.md + scripting.md references now resolve; point test-writing tasks at mechanical-test-generation.md - spec-writing/v1: worked spec exemplar (module layout table, Why: lines, exact error messages, parametrize pattern table) + CLAUDE.md pointer + mount entry
2.2 KiB
2.2 KiB
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.