8aa400a5d4
Add 37 new entries and update 7 existing entries across 13 topic files. Major contributions from agent-runtimes (K8s secrets, CI, Docker gotchas), cluster-bootstrap (ArgoCD SSA, etcd tuning, DB migrations, Compose networking), and cluster-apps/octopus-deploy (Helm vs raw manifests, ArgoCD source types). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
3.8 KiB
3.8 KiB
Best Practices Index
Generalised best practices extracted from real project work via the /distill-best-practices skill. 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; DB migration patterns; K8s constraint planning; deployment checklists
- Security Architecture — Server boundary rule: no credential crosses to the client; proxy + identity mapping pattern; defense in depth; anti-patterns
- Secrets Management — SOPS + age, credential handling, file naming, encryption gotchas, .env source injection, URL-safe passwords
- Git & Source Control — Commit practices, GitOps workflows, remote conventions
- Kubernetes Patterns — Volume mounts, deployment strategies, naming, bootstrap ordering, ArgoCD SSA quirks, etcd tuning, Secret volume gotchas
- 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, read-only review skills, formatter/hook separation
- Linting & Formatting — Tool choices per language, PostToolUse hook, pre-commit integration, formatter contract
- Spec-Driven Development — Spec structure, requirement numbering, test-first workflow, multi-model review, plan-first approach, agent prompt conventions
- 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
- Database Selection — SQLite is not a production database; always use PostgreSQL for services with FQDNs, multiple consumers, or concurrent access
- Docker — gosu PID 1, GIT_SSH_COMMAND scope, slim image health checks, buildx local images, Compose networking/restart gotchas, volume paths, override merge behaviour
- API Design — Transport security, auth (OAuth2/JWT/mTLS), versioning, pagination, error handling, idempotency, rate limiting, input validation, zero-trust patterns
- Octopus Process Templates — OCL syntax, step template references, channel scoping, parameters, versioning, Platform Hub patterns
- LLM Code Security — Security vulnerabilities in AI-generated code: injection flaws, hardcoded secrets, hallucinated packages, over-permissive defaults, IaC risks, crypto mistakes, review checklist
- CI Container Builds — Registry cache with inline metadata, buildx in DinD, layer ordering, pip caching, path filter gotchas, SHA tagging strategy
- Agent Repos & Container Agents — Task submission, harnesses, monitoring, multi-model workflows, agent repo forks, workspace layout, artifact passing via git branches