c8691368e4
Additive/refining entries left uncommitted in the working tree from an earlier distill session (found during the 2026-07 sweep commit): agent-repos 5-step plan pattern; ai-parallel-agents cheap-model scope; spec-driven spec-inversion and caller/callee cross-reference rules.
best-practices
Cross-project best practices extracted from real project work via the /distill-best-practices skill.
How It Works
The knowledge distillation pipeline in claude-foundations processes session logs and memory files from all tracked projects, extracting generalisable practices into topic files here.
Pipeline
/log— Captures session decisions and gotchas into per-projectmemory/log//reflect-logs— Processes logs into structured topic memory files/distill-best-practices— Reads memory files across projects, proposes updates to this repo
For Humans
Browse BESTPRACTICES.md for the full index. Each topic file is self-contained.
For Agents
Container agents get this repo cloned to /best-practices. Read BESTPRACTICES.md for the index, then read only the topic files relevant to your task.
Topics
| File | Description |
|---|---|
ansible.md |
Inventory, templates, idempotency, credential safety |
database-selection.md |
SQLite vs PostgreSQL decision criteria |
debugging.md |
Systematic diagnosis, full-chain testing, common pitfalls |
docker.md |
gosu PID 1, GIT_SSH_COMMAND scope, slim image patterns |
docker-uid-matching.md |
UID wrapper entrypoint, gosu pattern |
documentation.md |
CLAUDE.md, MEMORY.md, FUTURE.md, README.md structure |
git-source-control.md |
Commit practices, GitOps workflows, remote conventions |
helm.md |
Schema validation, version verification, values structure |
kubernetes.md |
Volume mounts, deployment strategies, naming, bootstrap ordering |
linting.md |
Tool choices per language, PostToolUse hook, pre-commit |
milestones.md |
Milestone workflow, verification, reflection process |
networking.md |
nftables, systemd sockets, Docker forwarding, TLS |
octopus-process-templates.md |
OCL syntax, step templates, Platform Hub patterns |
scripting.md |
Shell conventions, verification scripts, idempotency |
secrets-management.md |
SOPS + age, credential handling, encryption gotchas |
security-architecture.md |
Server boundary rule, proxy patterns, defense in depth |
skills-development.md |
Skill authoring, context injection, tool restrictions |
spec-driven-development.md |
Spec structure, requirement numbering, test-first workflow |
test-driven-development.md |
Edge case discovery, property-based testing, AI agent patterns |
validation.md |
Validate locally, deploy once; full-chain testing |
Source Control
- Gitea:
skynet/best-practices - Remote:
git@gitea.oreillyit.nz-ai-enablement:skynet/best-practices.git