# 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`