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>
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>
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>
Learnings from F58 3-way model comparison (Sonnet/MiniMax/Haiku):
- Read-only test gates: filesystem enforcement (chmod a-w) because
prompt instructions are insufficient — MiniMax edited tests 7x,
Haiku rewrote entirely, only Sonnet respected constraints
- Model selection table: Sonnet minimum for constrained implementation,
Haiku/MiniMax viable for review and test-writing
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Registry cache with inline metadata, buildx docker driver for DinD,
dependency layer separation (stub package pattern for setuptools),
pip cache retention, scheduled base image builds. Includes measured
results from Gitea Actions with DinD runners.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Comprehensive guide covering task submission to the agent-runtimes
control plane, available harnesses, monitoring, multi-model workflows,
agent repo forks with workspace layout, and artifact extraction patterns.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Two new topic files from research:
- api-design.md: Transport security, OAuth2/JWT/mTLS auth, API patterns
(versioning, pagination, idempotency, rate limiting), input validation,
secrets handling, zero-trust service mesh patterns. Maps to OWASP API
Security Top 10.
- llm-code-security.md: Common vulnerabilities in LLM-generated code
(injection, hardcoded secrets, hallucinated packages, over-permissive
defaults, IaC risks, crypto mistakes). Includes per-technology review
checklists and cites 18 research sources (2024-2026).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Migrated from claude-foundations. Tracks per-project git SHAs for
incremental distillation runs.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Migrates 20 topic files from claude-foundations/best-practices/ to this
standalone repo. Adds BESTPRACTICES.md index, CLAUDE.md conventions, and
updated README.md. Container agents clone this repo to /best-practices.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
