3efe153ca1
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>
2.2 KiB
Milestones & Reflections
Milestone Structure
Break projects into numbered milestones (M1, M2, ...). This provides clear checkpoints, measurable progress, and natural reflection points.
Milestone Completion Checklist
Every milestone MUST include:
1. Verification Script
scripts/verify-m<N>.sh — automated checks confirming all milestone outcomes.
- Idempotent, non-destructive, returns non-zero on failure
- Colour output (green/red) for pass/fail
- Environment-resilient (no sudo, test from accessible side)
- Check for default/insecure credentials
2. Milestone Reflection
Write memory/m<N>-reflection.md by reviewing the entire conversation from milestone start. Cover:
- Process improvements: What slowed us down? Wrong assumptions? Where did we go in circles? What would make this faster if redone from scratch?
- Key knowledge for reproduction: Critical facts, gotchas, non-obvious config details, version-specific quirks, debugging detours
- Scripts and automation: Existing tools that proved valuable, new scripts to build, patterns to extract into reusable automation
- Future improvements: Ideas that surfaced but don't belong in current scope — add to FUTURE.md
3. Updated README.md
Ensure the scripts section, milestone table, and setup steps are current.
4. Updated CLAUDE.md
Reflect new repo structure, conventions, and patterns discovered during the milestone.
Reflection Quality
Good reflections capture:
- Commit stats (total commits, fix percentage) to measure validation discipline
- Longest detour and root cause
- Most avoidable waste and what would have prevented it
- Concrete checklist items for future similar work
Evaluate Content Placement Before Building
Before creating a new document, system, or catalog, discuss where it belongs conceptually. Different content types have different lifecycles:
- Accumulated learnings → memory files (gotchas, process lessons)
- Authoritative maintained maps → CLAUDE.md or dedicated reference docs
- Behavioral contracts → spec files
- Active work state → CONTEXT.md
Picking the wrong home creates maintenance friction later. A five-minute placement discussion saves a future migration.