abdulmubdibindar/opencode-learn

ICM Architect

Construye espacios de trabajo donde la estructura de carpetas hace la orquestación. Un agente, leyendo los archivos correctos en el momento adecuado, reemplaza un marco multi-agente: las carpetas numeradas transportan la secuencia, la jerarquía transporta el alcance del contexto, los archivos de texto plano transportan el estado. Un humano puede abrir cualquier carpeta y ver exactamente en qué estado se encuentra el sistema, porque el estado son solo archivos.

Piensa en el espacio de trabajo como una biblioteca. Los archivos de enrutamiento son el catálogo: pequeños, estables, apuntan a todo y almacenan casi nada. El contenido vive en los estantes (carpetas de etapa, archivos de nodo, material de referencia). Un bibliotecario — un modelo — recorre el edificio, y la pregunta decide a qué estante se dirige. Nadie fotocopia la biblioteca en una mochila; eso es lo que es el relleno de contexto. El catálogo es pequeño a propósito.

Método: Metodología de Contexto Interpretable (Van Clief & McDermott, arXiv:2603.16021, con licencia MIT).

Los invariantes

Cada ICM, cualquiera que sea su forma, obedece estos. Al construir o reestructurar, haz cumplir los diez:

1. Una carpeta, un trabajo. Cada carpeta realiza un solo paso o contiene un solo tipo de cosa, y declara su propio propósito en un archivo dentro de sí misma. La estructura es la documentación.
2. Un archivo de entrada pequeño y estable. CLAUDE.md (o AGENTS.md) en la raíz responde "¿dónde estoy, dónde vive todo, a dónde voy para la tarea X?" y nada más. Apunta a menos de ~60 líneas. Enruta; nunca contiene contenido.
3. La numeración codifica el orden. 01_, 02_, … donde la secuencia importa. Renombrar carpetas reordena el pipeline — ese es el objetivo.
4. Cada contrato a nivel de carpeta es explícito. Un CONTEXT.md por carpeta de trabajo: qué lee (entradas), qué hace (proceso), qué escribe (salidas), qué verifica un humano. Consulta assets/templates/stage-CONTEXT.md.
5. Fábrica vs. producto. El material de referencia (reglas, voz, esquemas, plantillas — estable entre ejecuciones) vive estructuralmente aparte de los artefactos de trabajo (salidas, borradores — nuevo cada ejecución). Configura la fábrica una vez; el producto es lo que emite cada ejecución.
6. Cada salida es una superficie de edición. Las salidas intermedias son archivos de texto plano que un humano puede abrir, editar y guardar antes de que el siguiente paso los lea. Nada avanza hasta que una persona ha leído la última salida.
7. Carga solo lo que el paso necesita. Un agente que ejecuta un paso lee su contrato, sus referencias y sus entradas — no todo el espacio de trabajo. 2.000–8.000 tokens por paso es el rango saludable.
8. Texto plano, enlazable, consultable. Markdown + frontmatter YAML. Los enlaces ([[wikilinks]] o rutas relativas) lo convierten en un grafo; las etiquetas frontmatter lo hacen consultable. Un hogar por hecho — un enlace vence a una copia.
9. El sistema de archivos es la máquina de estados. El "estado" se puede derivar escaneando lo que existe en las carpetas de salida. Los índices generados (mapas de archivos, registros) se reconstruyen mediante script, nunca se editan a mano.
10. Instanciar copiando. Nueva unidad de trabajo = copiar una carpeta de plantilla, no una página en blanco. Mantén las plantillas en una carpeta _templates/ o _system/.

Elige un modo

• Construir a partir de un proceso, idea o problema descrito → Modo Construir.
• Una carpeta, repositorio o bóveda existente que necesita estructura ICM → Modo Reestructurar.

Modo Construir

1. Extraer la estructura del diálogo. La estructura ya está en cómo la persona describe el trabajo — no impongas una forma, saca a relucir la suya. Pregunta (de a pocas, no todas a la vez):

• ¿Cuál es la unidad de trabajo que se repite? (¿un episodio, un cliente, un informe, una persona, un equipo?)
• Guíame a través de una ejecución, de principio a fin. ¿Dónde te detienes y verificas algo antes de continuar?
• ¿Qué se mantiene igual en cada ejecución (voz, reglas, marca, esquema) vs. qué es nuevo cada ejecución?
• ¿Cómo se ve "terminado"? ¿Qué artefacto sale del espacio de trabajo?
• ¿Quién más toca esto, y qué necesitan encontrar sin preguntarte?

Sus pausas se convierten en límites de etapa. Sus "siempre verifico X antes de Y" se convierten en puertas humanas. Su "siempre tiene que sonar como / seguir Z" se convierte en material de referencia de fábrica.

2. Elegir la forma. Lee references/forms.md y elige:

Forma	Úsala cuando
Pipeline	La misma secuencia se ejecuta repetidamente, produciendo un entregable cada ejecución
Paraguas	Varios pipelines distintos comparten una capa de marca/voz/referencia
Biblioteca de registros	La unidad es un registro (persona, cliente, sesión) que se acumula, no una ejecución
Paquete de conocimiento	El producto es el conocimiento navegable en sí mismo (un cerebro, una wiki, un modelo de algo)
Mapa de contexto	El sujeto es una organización: equipos, procesos, datos y los vínculos entre ellos

Los espacios de trabajo reales mezclan formas (una biblioteca de registros cuyos registros son minipaquetes de conocimiento; un pipeline que emite en una biblioteca de registros). Compón libremente — los invariantes se mantienen en cada nivel, recursivamente.

3. Andamiar la estructura más pequeña que soporte el trabajo. Copia los iniciadores de assets/templates/ y complétalos. No crees carpetas para etapas que aún no existen, cubos "varios" vacíos o profundidad especulativa. Tres etapas reales vencen a siete imaginadas. Si todo el trabajo cabe en un solo prompt guardado, dilo y no construyas un espacio de trabajo.

4. Escribir los contratos. CLAUDE.md raíz (identidad + tabla de enrutamiento), CONTEXT.md raíz (la definición del pipeline o esquema), un CONTEXT.md por carpeta de etapa/centro, setup/questionnaire.md si la fábrica necesita configuración por usuario. Escribe las entradas como rutas de archivo explícitas, divididas en trabajo (esta ejecución) y referencia (cada ejecución).

5. Validar con la prueba de recorrido (abajo).

Modo Reestructurar

1. Inventariar antes de tocar. Enumera el árbol. Para cada área anota: qué es, cuándo se tocó por última vez, qué se refiere a ello. Nunca elimines ni muevas en esta pasada.

2. Encontrar la forma oculta. Pregunta al propietario (o infiere y confirma): ¿cuál es la unidad que se repite aquí? ¿Dónde entra y sale el trabajo? El desorden generalmente contiene un pipeline, biblioteca o mapa real que creció sin un esqueleto — extráelo, no lo reemplaces. Entrevista a la carpeta como entrevistarías a la persona.

3. Clasificar cada archivo en uno de cinco roles:

• Catálogo — identidad/enrutamiento (se convierte en o alimenta CLAUDE.md / archivos de índice)
• Contrato — describe cómo funciona un paso (se convierte en un CONTEXT.md)
• Fábrica — referencia estable (→ _shared/, _system/ o references/)
• Producto — artefactos específicos de la ejecución (→ etapa output/ o carpetas de registro)
• Muerto — obsoleto, duplicado o reemplazado (→ proponer _archive/, nunca eliminar en silencio)

4. Proponer antes de mover. Presenta el árbol objetivo y un mapa de migración (ruta antigua → ruta nueva → rol). Obtén aprobación. Esta es una puerta humana en un método construido sobre puertas humanas — respétala.

5. Migrar. Mueve archivos, escribe el archivo de entrada y los contratos, des-duplica hacia un hogar por hecho (deja un enlace donde vivía la copia si algo pudiera referenciarlo). Separa el método de la instancia: si la estructura se reutilizará en otro lugar, la plantilla en blanco vive aparte de este despliegue completado.

6. Validar con la prueba de recorrido.

La prueba de recorrido

Valida cualquier ICM — nuevo o reestructurado — recorriéndolo en frío, como un agente sin memoria:

• Abre la raíz. ¿Puedes responder ¿dónde estoy? y ¿a dónde voy para la tarea actual? dentro del archivo de entrada más un máximo de dos lecturas adicionales?
• Elige cualquier etapa/nodo. ¿Su contrato nombra rutas de entrada exactas, el trabajo, la salida y la verificación humana?
• ¿Puedes declarar el estado del pipeline simplemente escaneando lo que existe en las carpetas output/ (o en el frontmatter del nodo)?
• ¿Algún archivo de enrutamiento lleva carga útil de contenido? Mueve la carga útil a un estante; deja un puntero.
• ¿Algún hecho está almacenado en dos lugares? Elige un hogar; enlaza desde el otro.
• Verificación de tokens: el archivo de entrada + un contrato + sus entradas deberían estar aproximadamente en 2k–8k tokens.

Si un paso falla, arregla la estructura — no explicando más, sino moviendo o dividiendo archivos hasta que el recorrido funcione.

Barreras de protección

• No sobre-estructures. La escalera es: chat → prompt/skill guardado → carpetas + un agente. Solo sube cuando el escalón inferior esté genuinamente automatizado y se repita. Un espacio de trabajo para algo hecho dos veces es andamio, no arquitectura.
• Saber dónde ICM pierde. La colaboración multi-agente en tiempo real, el servicio multiusuario de alta concurrencia y la ramificación automatizada en medio del pipeline necesitan genuinamente código de marco. ICM es para trabajo secuencial, revisado por humanos y repetible — que es la mayor parte del trabajo de conocimiento, pero no todo.
• Anti-patrones vistos en la práctica: archivos de entrada duplicados que divergen (genera uno a partir del otro, o haz que uno sea un puntero); documentos de esquema que exigen nombres que los archivos reales dejaron de usar (actualiza el esquema o los archivos — elige uno); ediciones manuales en índices generados; sesiones de taller que producen diapositivas en lugar de datos estructurados (cada sesión de trabajo debería terminar en un artefacto que la estructura pueda contener); patrones declarados de arriba hacia abajo (un equipo que se queja es una queja — la misma forma que aparece tres veces de forma independiente es estructura).

Referencias

• references/core.md — los cinco principios de diseño, la jerarquía de contexto de cinco capas, convenciones de nomenclatura, disciplina de tokens. Léelo al escribir contratos o cuando una decisión estructural sea cuestionada.
• references/forms.md — las cinco formas en profundidad: árboles esqueleto, movimientos definitorios, modos de fallo. Léelo en el paso 2 del modo Construir o en el paso 2 del modo Reestructurar.
• assets/templates/ — iniciadores copiables: CLAUDE.md, CONTEXT.md del espacio de trabajo, stage-CONTEXT.md, node.md, schema.md, questionnaire.md.