Eight practices for writing specs that serve as direct input to
automated test-generation agents, extracted from the M15 Mechanical
Process Nodes milestone review: module layout tables, integration
boundary marking, explicit library semantics, concrete interfaces over
"implementation detail", error messages as test data, pattern tables as
parametric matrices, scenario selection, and pre-dispatch testability
assessment.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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>
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>
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>
