claude-foundations/BESTPRACTICES.md

Note: Best practices are now maintained in skynet/best-practices. AI agents with /best-practices mounted should read /best-practices/INDEX.md instead. The content below is kept as a local copy for context-load compatibility.

Best Practices Index

Generalised best practices extracted from real project work. Each topic file is self-contained — read only the files relevant to the current project.

Topics

• Validation & Deployment — Validate locally, deploy once; full-chain testing; pre-flight checks
• Secrets Management — SOPS + age, credential handling, file naming, encryption gotchas
• Git & Source Control — Commit practices, GitOps workflows, remote conventions
• Kubernetes Patterns — Volume mounts, deployment strategies, naming, bootstrap ordering
• Helm Charts — Schema validation, version verification, values structure
• Ansible — Inventory, templates, idempotency, credential safety
• Scripting — Shell conventions, verification scripts, idempotency, colour output
• Documentation Standards — CLAUDE.md, MEMORY.md, FUTURE.md, README.md structure and tiered memory
• Milestones & Reflections — Milestone workflow, verification, reflection process
• Debugging Methodology — Systematic diagnosis, full-chain testing, common pitfalls
• Claude Code Skills — Skill authoring, context injection, tool restrictions
• Linting & Formatting — Tool choices per language, PostToolUse hook, pre-commit integration, formatter contract
• Spec-Driven Development — Spec structure, requirement numbering, test-first workflow, context tiers, anti-patterns
• Test-Driven Development — Edge case discovery, property-based testing, mutation testing, AI agent testing patterns, test architecture
• Networking & Infrastructure — nftables safety, systemd socket activation, Docker forwarding, TLS SNI vs Host header, wildcard certs
• Docker UID Matching — UID wrapper entrypoint for mounted volumes, gosu pattern, when to use vs K8s securityContext
• Octopus Process Templates — OCL syntax, step template references, channel scoping, parameters, versioning, Platform Hub patterns
• Platform Hub Knowledge Base — Comprehensive guide: architecture, OCL syntax, template patterns, gotchas, API reference