The Compounding Knowledge Lifecycle — Agent Guide

Puntos clave

1. La apuesta de compound engineering. "cada unidad de trabajo debería facilitar la siguiente unidad." El código mejora el producto, no el proceso; lo que se compone es el conocimiento — cada problema resuelto, concepto nombrado, convención documentada en una forma recuperable en el momento exacto en que el trabajo futuro la necesita.
2. El verdadero cuello de botella = la recuperación. , no la escritura. Los postmortems "se pudren en las wikis porque nadie vuelve a leerlos". Este sistema cierra el ciclo al hacer que la recuperación sea automática en 5 skills, en lugar de una disciplina voluntaria.
3. Un learning (documento de solución). = 1 archivo markdown = 1 problema resuelto, bajo docs/solutions/<category>/. Todo el frontmatter está al servicio de la búsqueda, no de la narrativa: title (objetivo de grep #1), tags (superficie de sinónimos — grep tags:.*(menu|routing|handoff) sin abrir un archivo), module/component ("¿es esta mi zona?"), problem_type (el interruptor de enrutamiento), applies_when (una autoevaluación de 3 líneas), severity (clasificación cuando coinciden varios), date (señal de obsolescencia).
4. problem_type = 2 vías. bug-track (qué se rompió: runtime_error, test_failure, performance_issue, security_issue…) y knowledge-track (qué se decidió/descubrió: architecture_pattern, design_pattern, tooling_decision, convention, workflow_issue, best_practice…). "Un sistema que solo retiene los bugs olvida la parte esencial de lo que aprende un equipo." Censo vivo: 35 learnings, 6 categorías, con skill-design a la cabeza (20).
5. Pattern doc. = un nivel superior: generalizado a partir de varios learnings → más apalancamiento, más riesgo si queda obsoleto. Ninguno promovido todavía aquí (docs/solutions/patterns/critical-patterns.md = una casilla en espera).
6. Captura = /ce-compound. , disciplina central = timing: documentar mientras el contexto sigue fresco (en la misma sesión que la corrección, mientras los intentos fallidos y el "ah, ¡ERA por eso!" siguen presentes). Una semana después → degenera en un resumen.
7. Mecánica. fan-out de subagentes (context analyzer = category/name/frontmatter, solution extractor = cuerpo en prosa problem/investigation/solution/prevention, related-docs finder = anti-duplicado); solo el orquestador escribe UN documento, los subagentes nunca tocan archivos versionados. Otros puntos de entrada: /ce-debug (ofrece un compound tras la causa raíz), /ce-pov ("compound it" → tooling_decision en modo headless), modo ligero (lecciones pequeñas, omite el anti-duplicado).
8. "La vida de un learning". (ejemplo canónico): issue #714 (el agente se detiene después del menú) → causa raíz (enrutamiento por opción en un archivo de referencia que no se había cargado) → corrección + /ce-compound → learning post-menu-routing-belongs-inline.md → prueba de regresión + doctrina en AGENTS.md ("Inline the Trigger, Not the Content"). Un incidente, 4 artefactos durables. "Compounding" = se retiran clases de fallos, no solo se acumulan documentos.
9. Mapa de memoria, eje = durabilidad. DURABLE (git): docs/solutions/ (los 35 learnings), CONCEPTS.md (vocabulario/glosario, nunca specs), STRATEGY.md (dirección/tracks), docs/plans/ + brainstorms/ (el POR QUÉ). EFÍMERO (derivado): repo-profile cache (derivado 1×/commit, compartido por 9 skills, nunca una fuente de verdad — eliminarlo no pierde nada). Regla: el conocimiento que se echaría de menos → git; lo re-derivable → /tmp. Los planes nunca se editan después de la ejecución → siguen explicando el por qué meses después.
10. Detección: nada te empuja el conocimiento. (sin digest, sin "lee la wiki"). 5 skills lo extraen (pull) en el momento de la decisión, mediante un protocolo learnings-researcher compartido, grep-first (la memoria está diseñada para ser buscada sin ser leída). Embudo: 35 documentos → greps paralelos de frontmatter → un puñado de candidatos (frontmatter de ~30 líneas) → lectura completa de los ganadores → 5 hallazgos destilados en el contexto del llamador.
11. Consumidores. /ce-plan (learnings → constraints & KTDs), /ce-brainstorm (enmarca el alcance), /ce-code-review (revisor siempre activo: veredicto followed / violated contra el diff real — "el diente más afilado"; una violación = un hallazgo con file:line, no una sugerencia), /ce-ideate (poda callejones sin salida pasados), /ce-debug (saca a la luz causas raíz conocidas).
12. 2 reglas de confianza. (1) La evidencia presente gana — si un learning contradice el código actual, el conflicto se señala en lugar de invalidarlo (una memoria equivocada con confianza es peor que ninguna); (2) La fecha es una señal — cada learning lleva su fecha para evaluar si el mundo ha avanzado.
13. Refresh — "una memoria que solo crece termina mintiendo.". 3 contrafuerzas en tempos distintos: tiempo de lectura (la evidencia presente gana, gratis); tiempo de escritura (al añadir/editar una entrada de CONCEPTS.md, inspeccionar su vecindario de coherencia — los términos hermanos referenciados — y corregir la deriva para la que hay evidencia; acotado, nunca una auditoría completa por una corazonada); bajo demanda (/ce-compound-refresh, un barrido deliberado, NO un seguimiento por defecto, solo se ejecuta cuando hay una razón, toma una pista de alcance — /ce-compound-refresh payments — porque un refresh de todo el corpus casi nunca es el gasto correcto).
14. El ciclo completo vía /ce-explain. (un skill lanzado "ayer", todo ocurrió realmente): el brainstorm extrae el repo-profile de la caché; la planificación saca a la luz 5 learnings (3 de aplicación obligatoria: enrutamiento de menú inline [legado del #714], portabilidad de $ARGUMENTS, ancla SKILL_DIR); la implementación crea su prueba de regresión espejo; la revisión audita el diff contra 8 learnings (todos seguidos) y rechaza una corrección propuesta por el revisor que habría reintroducido el modo de fallo original ("la memoria no solo informó el trabajo, lo defendió"); vocabulario compound (Explainer, Check-in → CONCEPTS.md); residuo → issue #1057 → futuro learning #36. "Ningún paso requirió que alguien recordara consultar la memoria."
15. Por qué se compone (metáfora financiera). learning = principal, cada recuperación que cambia una decisión = pago de intereses, pattern doc = reinversión. Modos de fallo evitados: podredumbre de wikis, guía obsoleta que mata el trabajo nuevo, acumulación sin curar, memoria invisible, decadencia, silos (un único docs/solutions/ sirve a 9 skills).
16. Vínculo directo con este repositorio. la convención docs/solutions/ (frontmatter module/tags/problem_type) documentada en el CLAUDE.md del repo veille es exactamente este sistema; los skills compound-engineering:* (ce-compound, ce-plan, ce-code-review, ce-compound-refresh…) están instalados aquí. Un candidato natural para su promoción a nivel de toda la firma (un patrón de capitalización).