Milestone v2 — Persistent Development Context

Storage: two-tier cache

~/.claude/projects/<project>/memory/milestone_<slug>.md  ← HOT (~100 tok, auto-loaded vía MEMORY.md)
<project-root>/.milestones/<slug>.md                      ← AUTHORITATIVE (historial completo)

Regla de lectura: Snapshot de memoria primero. Solo .milestones/ si necesitas historial completo o la memoria no existe. Nunca leer ambos si la memoria tiene la información suficiente.

Regla de escritura: Cada write a .milestones/<slug>.md → actualizar también el snapshot. Ruta: ~/.claude/projects/$(pwd | sed 's|/|-|g; s|^-||')/memory/.

Por qué esto importa: Leer un archivo de milestone de 70 líneas cuesta ~1.500 tok. El snapshot cuesta ~100 tok. En una conversación de 40 mensajes, cada tool call reenvía TODO el historial — el contexto acumulado invisible multiplica el coste real 5-10x. Un snapshot en memoria elimina lecturas y mantiene el contexto mínimo.

When to use milestone vs alternatives

Antes de crear un milestone, pregúntate:

• ¿Abarca múltiples sesiones? → No: usar TodoWrite o Plan mode