skynet/best-practices
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

distill: best practices from 2026-04-19 cross-project run

Browse Source 
Adds 3 new topic files (ai-parallel-agents, api-integration,
python-patterns) and extends 21 existing topic files with new gotchas
and patterns surfaced from memory across tracked projects. Index
updated accordingly.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Paul O'Reilly
2026-04-25 13:41:47 +12:00
parent 8aa400a5d4
commit 22d49b2c9a
24 changed files with 1394 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
BESTPRACTICES.md
View File

@@ -4,27 +4,30 @@ Generalised best practices extracted from real project work via the `/distill-be
## Topics
- [Validation & Deployment](validation.md) — Validate locally, deploy once; full-chain testing; pre-flight checks; DB migration patterns; K8s constraint planning; deployment checklists
- [Validation & Deployment](validation.md) — Validate locally, deploy once; full-chain testing; pre-flight checks; DB migration patterns; K8s constraint planning; deployment checklists; inert-by-default feature flags; integration failure categorisation; safe persistence pattern
- [Security Architecture](security-architecture.md) — Server boundary rule: no credential crosses to the client; proxy + identity mapping pattern; defense in depth; anti-patterns
- [Secrets Management](secrets-management.md) — SOPS + age, credential handling, file naming, encryption gotchas, .env source injection, URL-safe passwords
- [Secrets Management](secrets-management.md) — SOPS + age, credential handling, file naming, encryption gotchas, .env source injection, URL-safe passwords, per-workload secret scoping
- [Git & Source Control](git-source-control.md) — Commit practices, GitOps workflows, remote conventions
- [Kubernetes Patterns](kubernetes.md) — Volume mounts, deployment strategies, naming, bootstrap ordering, ArgoCD SSA quirks, etcd tuning, Secret volume gotchas
- [Kubernetes Patterns](kubernetes.md) — Volume mounts, deployment strategies, naming, bootstrap ordering, ArgoCD SSA quirks, etcd tuning, Secret volume gotchas, probe timeouts, Kustomize overlay image overrides, PodSecurity for monitoring, Cilium entity identities
- [Helm Charts](helm.md) — Schema validation, version verification, values structure
- [Ansible](ansible.md) — Inventory, templates, idempotency, credential safety
- [Scripting](scripting.md) — Shell conventions, verification scripts, idempotency, colour output
- [Documentation Standards](documentation.md) — CLAUDE.md, MEMORY.md, FUTURE.md, README.md structure and tiered memory
- [Milestones & Reflections](milestones.md) — Milestone workflow, verification, reflection process
- [Debugging Methodology](debugging.md) — Systematic diagnosis, full-chain testing, common pitfalls
- [Debugging Methodology](debugging.md) — Systematic diagnosis, full-chain testing, common pitfalls, DB schema verification after deploy
- [Claude Code Skills](skills-development.md) — Skill authoring, context injection, tool restrictions, read-only review skills, formatter/hook separation
- [Linting & Formatting](linting.md) — Tool choices per language, PostToolUse hook, pre-commit integration, formatter contract
- [Spec-Driven Development](spec-driven-development.md) — Spec structure, requirement numbering, test-first workflow, multi-model review, plan-first approach, agent prompt conventions
- [Spec-Driven Development](spec-driven-development.md) — Spec structure, requirement numbering, test-first workflow, multi-model review, plan-first approach, agent prompt conventions, wave-based TDD dispatch
- [Test-Driven Development](test-driven-development.md) — Edge case discovery, property-based testing, mutation testing, AI agent testing patterns, test architecture
- [Networking & Infrastructure](networking.md) — nftables safety, systemd socket activation, Docker forwarding, TLS SNI vs Host header, wildcard certs
- [Docker UID Matching](docker-uid-matching.md) — UID wrapper entrypoint for mounted volumes, gosu pattern, when to use vs K8s securityContext
- [Database Selection](database-selection.md) — SQLite is not a production database; always use PostgreSQL for services with FQDNs, multiple consumers, or concurrent access
- [Docker](docker.md) — gosu PID 1, GIT_SSH_COMMAND scope, slim image health checks, buildx local images, Compose networking/restart gotchas, volume paths, override merge behaviour
- [Docker](docker.md) — gosu PID 1, GIT_SSH_COMMAND scope, slim image health checks, buildx local images, Compose networking/restart gotchas, volume paths, override merge behaviour, init script privilege order, payload size limits, bind-mount rm gotcha
- [API Design](api-design.md) — Transport security, auth (OAuth2/JWT/mTLS), versioning, pagination, error handling, idempotency, rate limiting, input validation, zero-trust patterns
- [API Integration](api-integration.md) — Client-side third-party API integration: capability verification, app-layer compensation, git+SOPS polling sync, bidirectional SoR
- [Octopus Process Templates](octopus-process-templates.md) — OCL syntax, step template references, channel scoping, parameters, versioning, Platform Hub patterns
- [LLM Code Security](llm-code-security.md) — Security vulnerabilities in AI-generated code: injection flaws, hardcoded secrets, hallucinated packages, over-permissive defaults, IaC risks, crypto mistakes, review checklist
- [CI Container Builds](ci-container-builds.md) — Registry cache with inline metadata, buildx in DinD, layer ordering, pip caching, path filter gotchas, SHA tagging strategy
- [Agent Repos & Container Agents](agent-repos.md) — Task submission, harnesses, monitoring, multi-model workflows, agent repo forks, workspace layout, artifact passing via git branches
- [LLM Code Security](llm-code-security.md) — Security vulnerabilities in AI-generated code: injection flaws, hardcoded secrets, hallucinated packages, over-permissive defaults, IaC risks, crypto mistakes, operational vulnerabilities (idempotency, CI/CD integrity, supply chain provenance, concurrent access), review checklists
- [CI Container Builds](ci-container-builds.md) — Registry cache with inline metadata, buildx in DinD, layer ordering, pip caching, path filter gotchas, SHA tagging strategy, runtime-mounted directory triggers
- [Agent Repos & Container Agents](agent-repos.md) — Task submission, harnesses, monitoring, multi-model workflows, agent repo forks, workspace layout, artifact passing via git branches, read-only test protection, infrastructure failure modes, cost-effective model scope boundaries
- [AI Parallel Agents](ai-parallel-agents.md) — Parallel agent orchestration: multi-facet research dispatch, file contention, WebFetch limits, narrow reads, dataset-wide audits
- [Python Patterns](python-patterns.md) — Non-reentrant Lock deadlocks, Pydantic v2 extra='ignore' silent drops, subprocess routing callables for mocking, model_validator for cross-field validation