The Compounding Knowledge Lifecycle — Agent Guide

Puntos clave

1. La apuesta fundacional de compound engineering. "cada unidad de trabajo debería facilitar la siguiente." El código mejora el producto, no el proceso; lo que se acumula es el conocimiento — cada problema resuelto, concepto nombrado y 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 los vuelve a leer". Este sistema cierra el ciclo haciendo que la recuperación sea automática en 5 skills, en lugar de dejarla a la disciplina voluntaria.
3. Un learning (documento de solución). = 1 archivo markdown = 1 problema resuelto, bajo docs/solutions/<category>/. Todo el frontmatter sirve para la búsqueda, no para la narrativa: title (objetivo de grep #1), tags (superficie de sinónimos — grep tags:.*(menu|routing|handoff) sin abrir un archivo), module/component ("¿es mi área?"), problem_type (el switch de enrutamiento), applies_when (una prueba de autoselección de 3 líneas), severity (clasificación cuando coinciden varios), date (señal de obsolescencia).
4. problem_type = 2 tracks. 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 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 escalón más arriba: generalizado a partir de varios learnings → más apalancamiento, más riesgo si queda obsoleto. Todavía no se ha promovido ninguno aquí (docs/solutions/patterns/critical-patterns.md = una plaza a la espera de ser ocupada).
6. Captura = /ce-compound. , disciplina central = timing: documentar mientras el contexto sigue fresco (en la misma sesión que el fix, mientras los intentos fallidos y el "ah, POR ESO era" siguen presentes). Una semana después → se degrada 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 = comprobación de duplicados); solo el orquestador escribe UN doc, 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, se salta la comprobación de duplicados).
8. "La vida de un learning". (ejemplo canónico): el 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 cargaba) → fix + /ce-compound → learning post-menu-routing-belongs-inline.md → test 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 (re-derivada 1×/commit, compartida por 9 skills, nunca una fuente de verdad — eliminarla no pierde nada). Regla: el conocimiento que echarías 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 empuja el conocimiento hacia ti. (sin digest, sin "lee la wiki"). 5 skills lo tiran (pull) en el momento de decisión, mediante un protocolo compartido learnings-researcher, grep-first (la memoria está diseñada para ser buscada sin ser leída). Embudo: 35 docs → greps paralelos de frontmatter → un puñado de candidatos (~30 líneas de frontmatter) → lectura completa de los ganadores → 5 findings destilados en el contexto del llamador.
11. Consumidores. /ce-plan (learnings → constraints y KTDs), /ce-brainstorm (encuadra el alcance), /ce-code-review (revisor siempre activo: veredicto followed / violated contra el diff real — "el diente más afilado"; una violación = un finding 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 prevalece — si un learning contradice el código actual, el conflicto se señaliza en lugar de invalidarlo (una memoria equivocada con seguridad es peor que ninguna); (2) La fecha es señal — cada learning lleva su fecha para ponderar si el mundo ha avanzado.
13. Refresh — "la memoria que solo crece termina mintiendo.". 3 contrafuerzas a distintos ritmos: tiempo de lectura (la evidencia presente prevalece, gratis); tiempo de escritura (al añadir/editar una entrada de CONCEPTS.md, se inspecciona su coherence neighborhood — los términos vecinos referenciados — y se corrige 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 un motivo, 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. (skill lanzada "ayer", todo ocurrió de verdad): el brainstorm extrae el repo-profile de la caché; la planificación saca a la luz 5 learnings (3 de aplicación obligatoria: enrutamiento inline del menú [legado del #714], portabilidad de $ARGUMENTS, ancla SKILL_DIR); la implementación crea su test de regresión reflejado; la revisión audita el diff contra 8 learnings (todos respetados) y rechaza un fix propuesto por el revisor que habría reintroducido el fallo original ("la memoria no solo informó el trabajo, lo defendió"); vocabulario compound (Explainer, Check-in → CONCEPTS.md); lo pendiente → el issue #1057 → futuro learning #36. "Ningún paso requirió que alguien recordara consultar la memoria."
15. Por qué se acumula (metáfora financiera). learning = capital, cada retrieval que cambia una decisión = pago de intereses, pattern doc = reinversión. Modos de fallo evitados: podredumbre de wikis, guías obsoletas que arruinan el trabajo nuevo, acumulación sin curar, memoria invisible, decaimiento, 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; las skills compound-engineering:* (ce-compound, ce-plan, ce-code-review, ce-compound-refresh…) están instaladas aquí. Un candidato natural para promoción a nivel de firma (un patrón de capitalización).