6154031cf9
Extends api-design.md beyond its security/operations focus with three new dimensions: - §0 API-First Design Process — OpenAPI 3.1 as single source of truth, Spectral governance, dogfooding (UIs consume the public API, no privileged backdoors), auth-required-by-default as a design stance. - §7 Documentation and Developer Experience — Scalar/Mintlify, RFC 9457 Problem Details error envelope, interactive playgrounds, generated SDKs (Stainless, Speakeasy, Fern), RFC 9745 deprecation signals and changelog UX. - §8 Contract Testing and API Quality — schema validation in the test suite, Pact CDC vs provider verification, Schemathesis property-based fuzzing, oasdiff drift detection in CI, the API test pyramid. Intro, cross-refs in §3.1/§3.3/§4.1, and Sources block reorganised by topic. Index entry in BESTPRACTICES.md updated. PLAN file included for traceability. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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