best-practices/CLAUDE.md

CLAUDE.md — Best Practices

Overview

Cross-project best practices extracted from real project work. Maintained by the /distill-best-practices skill, which reads memory files from all tracked projects and proposes updates here.

Repository Structure

best-practices/
  BESTPRACTICES.md         # Index — lists all topic files with descriptions
  CLAUDE.md                # This file
  README.md                # Human-readable overview
  <topic>.md               # One self-contained file per topic

Conventions

• One file per topic. Each file is self-contained and readable in isolation.
• BESTPRACTICES.md is the index. One line per topic with a link and description. Loaded by context-load at session start.
• Distillation maintains this repo. The /distill-best-practices skill reads memory files from tracked projects and proposes additions/updates here.
• Topic files follow a consistent structure: title, overview, then numbered or bulleted practices with rationale.
• Keep practices actionable. Each entry should be something a developer or agent can follow, not just an observation.
• Include rationale. Every practice should explain why — the incident, gotcha, or pattern that motivated it.
• Prune when fixed. If a practice was specific to a version bug that's been fixed, remove it.

For Container Agents

When this repo is cloned to /best-practices inside agent containers:

• Read BESTPRACTICES.md for the index
• Read only the topic files relevant to your current task
• Do not modify files in this repo from within a container agent

Source Control

• Gitea org: skynet
• Remote: git@gitea.oreillyit.nz-ai-enablement:skynet/best-practices.git