Add best-practices library, knowledge distillation pipeline settings, and first session log

- best-practices/: 11 topic files + INDEX.md extracted from cluster-bootstrap
  and custom-claude-skills (validation, k8s, helm, ansible, secrets, debugging, etc.)
- settings.yaml: pipeline config (log retention, tracked projects, max logs per run)
- CLAUDE.md: updated with best-practices loading and pipeline documentation
- memory/log/: first session log demonstrating the format

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Paul O'Reilly
2026-03-12 23:39:06 +13:00
parent a4967df815
commit e0f8e6471c
15 changed files with 472 additions and 2 deletions

View File

@@ -0,0 +1,50 @@
# Documentation Standards
Every project maintains four core markdown files.
## CLAUDE.md
The primary reference for Claude sessions. Should contain:
- Project overview and architecture
- Repository structure (keep updated as the project evolves)
- Key design decisions with rationale
- Conventions and coding standards
- Environment details (IPs, URLs, credential references — never actual values)
- Common operations / how-to recipes
- Put critical rules at the top — Claude reads sequentially and earlier content has more influence
## MEMORY.md (Tiered Memory System)
Long-running projects accumulate significant context. Use a **tiered memory** structure:
**MEMORY.md** is a **thin index only** — one-line descriptions with links to topic files in `memory/`. No content lives in MEMORY.md itself. Keep it under ~50 lines.
**memory/** contains the actual content, split by topic:
- `memory/project-status.md` — Current milestone, what's next, blockers
- `memory/gotchas-<topic>.md` — Gotchas grouped by technology
- `memory/process-lessons.md` — How-to-work-with-this-repo lessons
- `memory/m<N>-reflection.md` — One file per milestone reflection
- `memory/decisions.md` — Architecture and design decisions
**Principles:**
- Split by topic, not by time
- Index descriptions matter — they're used to decide what to read
- Prune aggressively — stale memory is worse than no memory
- Each file should be self-contained and greppable
- Deduplicate with CLAUDE.md — stable conventions go in CLAUDE.md, learnings and gotchas go in memory
## FUTURE.md
Backlog of improvement ideas, each with:
- **Problem:** What's painful or manual today
- **Idea:** What the improvement looks like
- **Open questions:** Unknowns to research before starting
- **Depends on:** Other items or milestones that should come first
## README.md
Human-readable project documentation:
- Architecture summary
- Quick start / setup instructions
- Milestone table with status
- Scripts section listing every script with purpose and usage