enu
CLAUDE.md2 starsChanged 4 months agoApache-2.0View on GitHub
Guía para asistentes de IA que trabajen en este repositorio. enu es un motor para construir coding harnesses a medida («a self-extensible coding harness with no host runtime», ADR-025): un único binario Go con un kernel mínimo donde todo lo demás — incluido el agente oficial, que es la demo de referencia del motor — son extensiones Lua. Crítico: por defecto el proyecto está en fase de diseño. Los documentos en docs/ son el proyecto. La API se valida escribiendo…
- Commits and pushes
The file
We split this CLAUDE.md into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 190
No inventes API para tapar un hallazgo sin antes comprobar que el patrón se repite y que no se compone con lo existente.
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
Guía para asistentes de IA que trabajen en este repositorio.
Qué es este proyecto
enu es un motor para construir coding harnesses a medida («a
self-extensible coding harness with no host runtime», ADR-025): un único
binario Go con un kernel mínimo donde todo lo demás — incluido el agente
oficial, que es la demo de referencia del motor — son extensiones Lua.
Crítico: por defecto el proyecto está en fase de diseño. Los documentos
en docs/ son el proyecto. La API se valida escribiendo pseudocódigo contra
ella antes de congelarla. Tu trabajo en una tarea de diseño es diseño y
documentación (razonar sobre la API, encontrar grietas, registrar
decisiones): no crees ficheros de código Go o Lua salvo que se pida
explícitamente; el pseudocódigo ilustrativo vive dentro de los .md.
Excepción — fase de construcción: cuando la tarea sea implementar el kernel, se rige por docs/plan/implementacion.md y su protocolo de sesión (una feature por sesión, puntero, checkpoints, tests). Eso es "pedirlo explícitamente": ahí sí se escribe código. El default "no código" sigue valiendo para todo lo demás. Cómo operar en esa fase: la sección "Cuando implementes" de abajo.
Idioma y estilo
- La fuente documental interna está en español (
docs/— contratos, ADR, findings, plan, worklog — y los mensajes de commit). Escribe en español, con el mismo registro: prosa densa pero precisa, frases que justifican el porqué de cada decisión, no solo el qué. El frente público va en inglés (ADR-025): README, web de docs, quickstart y cualquier artefacto de adquisición se redactan en inglés primero, con versión española enlazada donde exista. - Los identificadores de la API son en inglés y
snake_case(enu.fs.read,enu.task.spawn); la prosa que los rodea, en español. - Tono: afirmativo y razonado. Cada decisión se acompaña de su motivación y, cuando aplica, de las alternativas descartadas. Imita la voz de los documentos existentes antes de añadir nada.
Estructura del repositorio
Todo vive en docs/. Orden de lectura sugerido (y dependencias conceptuales):
| Documento | Rol |
docs/core/filosofia.md | Principios fundacionales y "lo que enu no es". El porqué del proyecto. |
docs/core/arquitectura.md | Vista estática: las capas, el inventario de primitivas del kernel. |
docs/core/modelo-ejecucion.md | Vista dinámica: concurrencia, comunicación, limitaciones (con diagramas mermaid). |
docs/contracts/api.md | La API v1 del core — la "superficie sagrada". Firmas y semánticas. |
docs/decisions/adr/ | Decisiones técnicas (ADR): un fichero por decisión (adr-NNN-<slug>.md) + índice. |
docs/contracts/providers.md | Contrato de la extensión oficial de providers (registro TOML + adaptadores Lua). |
docs/contracts/agente.md | Contrato de la extensión oficial agent (motor headless: turno, tools, permisos, subagentes). |
docs/contracts/sesiones.md | Contrato de persistencia: JSONL append-only. |
docs/contracts/chat.md | Contrato de la extensión oficial chat (la UI). |
docs/contracts/guia-plugins.md | Sabiduría práctica para autores de plugins + checklist. |
docs/contracts/malla.md | Contrato de la extensión oficial mesh (borrador v0.1; su §11 sigue abierta). |
docs/validation/ | El ejercicio de validación: una ronda de pseudocódigo por fichero (ronda-N-<slug>.md) + índice. |
docs/findings/ | Grietas que la v1 necesita cerradas: un fichero por hallazgo (gNN-<slug>.md) + índice con el estado vivo. |
docs/postponed/ | Lo que se decidió no decidir todavía (P##): un fichero por entrada (pNN-<slug>.md) + índice, cada uno con su disparador de reapertura. |
docs/plan/implementacion.md | Plan de construcción incremental: una feature por sesión (S##), ordenado por dependencias del kernel. |
docs/plan/estado.md | El estado vivo del plan: puntero ▶ y tablero de fases (el registro por sesión vive en docs/worklog/). |
docs/worklog/ | Bitácora operativa: un fichero por sesión (sNN-<slug>.md) con las decisiones por debajo del umbral de G##. |
docs/ops/release.md | Runbook operativo para cortar una release estable (los steps que ADR-013 deja fuera). |
Además, dos carpetas por tipo de artefacto: docs/audits/ (informes de
auditoría fechados y cerrados) y docs/archive/ (planes ya ejecutados que solo
conservan valor histórico, como la migración de la VM). Nada de lo que hay ahí
gobierna el diseño actual.
Convenciones de la estructura (desde 2026-07-17): carpetas en inglés, ficheros
en español; los registros van a un fichero por entrada y el README.md
índice de cada carpeta concentra el estado vivo (contadores, tablas); todo
.md de docs/ lleva frontmatter YAML (claves en inglés, valores en
español) con type/status/id y los campos de su tipo — al crear o cerrar
una entrada, frontmatter y texto deben quedar cuadrados. El detalle del
esquema: docs/README.md §«Frontmatter».
README.md es el índice de entrada con el mismo orden de lectura;
docs/README.md es el mapa por capas de docs/.
Las ideas centrales que NUNCA debes contradecir
Antes de proponer cualquier cosa, interiorízalas (detalle en docs/core/filosofia.md
y docs/decisions/adr/README.md):
- El core no sabe lo que es un agente. Modelo Emacs/Textadept, no Neovim: kernel diminuto de primitivas + intérprete Lua. Agente, MCP, chat, comandos slash, providers: todo son extensiones Lua, incluidas las oficiales, sin privilegio arquitectónico. Vara para casos dudosos: si algo se describe con el vocabulario del kernel (plugins, rutas, versiones), es del kernel; si necesita vocabulario de producto (agente, chat, tools, token), es de una extensión.
- Corolario de completitud: si una feature oficial no se puede construir con la API pública, la API está incompleta — el arreglo va en la API, no en un atajo privilegiado. Este es el motor de las rondas de pseudocódigo.
- Lua decide, Go ejecuta. Todo trabajo pesado (búsqueda, diff, markdown, highlighting, streaming HTTP) es primitiva Go, paralela por dentro. CPU ardiendo en Lua = señal de que falta una primitiva o de que el trabajo va a un worker.
- La API del core es sagrada (
docs/contracts/api.md): pequeña, aburrida, crece solo por adición;enu.version.apise incrementa con cada adición. Romper una firma rompe el mundo. Matiz pre-1.0 (ADR-025, pieza 4): mientras el proyecto sea pre-1.0 se admiten roturas de firma justificadas por un ADR — nunca por la vía de hecho —; la API se declara públicamente experimental hasta el criterio externo de corte de la 1.0. - Modelo de concurrencia "del navegador" (ADR-004): estado Lua principal
single-threaded con event loop (async por corrutinas, await implícito) +
workers explícitos opt-in (sin memoria compartida, sin
ui, paso de mensajes JSON-ables) + primitivas Go paralelas. Aislamiento por tarea, no por plugin (ADR-008); robustez por watchdog +pcallen cada frontera de hook. - Cero dependency hell: un binario estático Go (
CGO_ENABLED=0), extensiones oficiales embebidas congo:embedpero inactivas por defecto (ADR-010).
Convenciones de la API (al editar docs/contracts/api.md o contratos)
- Namespace global
enucon submódulos;requirereservado para módulos de plugins. Identificadores en inglés,snake_case. - Notación de firmas:
enu.mod.fn(arg: tipo, opts?: tabla) -> tipo. - Marcadores: ⏸ suspende (solo dentro de una task) y [W] (disponible en workers). Úsalos consistentemente.
- Async por funciones suspendientes (estilo secuencial), no callbacks ni promesas explícitas.
- Errores estructurados y lanzados:
error({ code, message, detail? }), capturables conpcall. Códigos reservados v1:ENOENT,EEXIST,EACCES,EIO,EHTTP,ENET,ETIMEOUT,ECANCELED,EBUDGET,EINVAL,ECLOSED. Las extensiones acuñan los suyos con la misma forma (p. ej.EPROVIDER). - Tiempos en milisegundos; rutas UTF-8.
- Namespaces de eventos reservados al core: solo
core:yui:. Todo lo demás (incluidoagent:) es de un plugin por convención (namespace = nombre del plugin); el loader garantiza unicidad de nombre.
El flujo de trabajo de diseño (cómo se decide aquí)
Este es el corazón del proyecto y debes respetarlo:
- Validación por pseudocódigo (
docs/validation/, una ronda por fichero). Se escriben escenarios reales usando solo lo especificado en los contratos. Cada punto donde el código no se puede escribir es un hallazgo. Las rondas acumuladas hasta hoy: Ronda 1 (H1-H3), Ronda 2 "caminos feos" (F1-F5), Rondas 3-4 "zonas sin torturar" (G1-G16), Ronda 5 "orquestación por un tercero" (G27). Revisiones de coherencia añadieron G17-G23, G26. - Registro de problemas (
docs/findings/, un fichero por hallazgogNN-<slug>.md). Las grietas que la v1 sí necesita cerradas se numeranG##y se resuelven una a una: se discuten opciones, se decide, se aplica la resolución a todos los documentos afectados, y la entrada pasa a RESUELTO (en su texto y en su frontmatter). El estado vivo (contador y abiertas) está en la cabecera dedocs/findings/README.md— consúltala ahí, no aquí. - Decisiones pospuestas (
docs/postponed/, un fichero por P##). Lo que se decide no decidir todavía se numeraP##y siempre lleva un disparador: la señal concreta que indica que toca reabrirlo. Nada está rechazado; está esperando. Cuando unP##se reabre y se decide, sale de aquí y entra en el ADR. - ADR (
docs/decisions/adr/, un fichero por decisiónadr-NNN-<slug>.md). Formato ligero: contexto → decisión → consecuencias. Las entradas nunca se reescriben: si una decisión cambia, se añade una nueva que la reemplaza (supersede), y en la vieja solo se marca el estado ("Reemplazada por ADR-NNN", ysuperseded_byen su frontmatter). Estados: Aceptada · Propuesta · Abierta · Reemplazada. El número y estado de cada ADR viven en su propio fichero (con índice endocs/decisions/adr/README.md) — consúltalos ahí, no aquí (la cifra escrita aquí ya se desfasó una vez).
Reglas de oro del flujo:
- Una resolución no está hecha hasta que es coherente en todos los
documentos. Si tocas una semántica en
api.md, busca y actualiza cada contrato que la presuponía (agente.md,providers.md,sesiones.md,chat.md,guia-plugins.md). La mayoría de hallazgos G17-G23 nacieron justo de contratos que presuponían API inexistente. - Respeta los enlaces cruzados. Los documentos se referencian entre sí con
rutas relativas (
[api.md](docs/contracts/api.md) §3) y por número de hallazgo/ADR. Al resolver algo, deja el rastro: enlaza el cambio desde el fichero del hallazgo endocs/findings/y cita elG##/F##/P##/ADR-NNNque lo motiva. - La web publica la Capa 1; la trazabilidad se mantiene en la fuente. Una
sección de un contrato que no debe aparecer en la web de docs se envuelve
entre
<!-- enu:interno -->y<!-- /enu:interno -->; el resto de la trazabilidad ((G##),(P##),> ✅ …) se queda endocs/—sigue siendo la fuente de verdad— y la web la limpia en build. Alta o baja de páginas de la wiki:/alta-wiki. Detalle en docs/README.md §«Publicación web». - No inventes API para tapar un hallazgo sin antes comprobar que el patrón se
repite y que no se compone con lo existente. Varios "hallazgos" se cierran
demostrando que ya eran expresables (semáforo con
enu.task.future, etc.). - Antes de añadir una primitiva al core, pregúntate si es vocabulario de producto (entonces va a una extensión) o si la división "Lua decide, Go ejecuta" la justifica por rendimiento.
Cuando implementes (fase de construcción)
Si la tarea es construir el kernel (no diseñar), el plan manda: docs/plan/implementacion.md. No improvises el orden ni juntes features: una sesión = una feature. El estado vive en el repo, no en tu memoria. Protocolo, sin saltarte pasos:
- Antes de tocar nada, abre
docs/plan/estado.mdy lee el puntero ▶ ("Próxima sesión") y «Último cierre». Eso es dónde seguir y en qué estado quedó; el detalle de la sesión (enunciado, dependencias, fase) está endocs/plan/implementacion.md. Implementa solo esa sesión; respeta el grafo de dependencias (no abras una sesión cuyas dependencias no estén cerradas). - Tests — la lógica clave no se skippea. Si la sesión está en el
inventario 🔒 (§"Política de tests" del plan), lleva tests unitarios Go
exhaustivos de sus casos límite, obligatorios, nombrando el
G##que blindan. Si es un wrapper fino, basta el snippet Lua + el checkpoint; no inventes tests de código ajeno. Toda sesión dejago build ./...verde. - La API del core es sagrada. Implementas api.md, no lo amplías.
Si descubres que la API no basta, párate: es un hallazgo
G##que se resuelve primero en los documentos (findings → api.md → contratos) y solo después se implementa. El código nunca corrige la espec por la vía de hecho. - Al terminar, en el mismo commit que la feature: en
docs/plan/estado.md, avanza el puntero ▶, marca el tablero si cerraste una fase, y actualiza «Último cierre». Las decisiones operativas y desviaciones que no llegan aG##se registran creandodocs/worklog/sNN-<slug>.md(un fichero por sesión, con su fila en el índicedocs/worklog/README.md). Si cierras una fase, ejecuta antes su checkpoint de integración (🔎); si falla, no avances el puntero. Un commit que toca código sin mover el puntero es una sesión a medias. - Commit en español citando la sesión (
S07: ...) y elG##si lo hubo.
El plan tiene todo el detalle (las 45 sesiones, los 11 checkpoints, el inventario 🔒 y los hitos de veto). Esta sección solo garantiza que lo consultes y lo sigas aunque arranques sin más contexto que este fichero.
Agentes y skills del flujo
El flujo de arriba está mecanizado en .claude/README.md
(el mapa): skills /planificar-sesion, /sesion, /hallazgo, /ronda,
/juicio y /mutacion, y los agentes clean-room (jueces, verificador,
auditor, escenarista BDD). Ante una tarea de desarrollo, consulta el mapa y
usa la skill que corresponda en vez de improvisar el protocolo. Las reglas de
no-contaminación de los jueces (qué reciben y qué herramientas tienen) no se
relajan.
Convenciones de Git
- Modelo de ramas (desde 2026-07-14):
developes la rama de integración y la rama por defecto del repo — ahí aterriza todo el trabajo y de ahí salen las versiones no estables.mainqueda reservada para versiones estables: solo recibe merges desdedevelopcuando se corta una estable, nunca trabajo directo. - Worktree de trabajo (desde 2026-07-15): cada tarea nueva se trabaja en
un worktree y una rama nuevos, nunca directamente en el directorio
principal del repo — así varias tareas conviven sin pisarse el árbol de
trabajo. Al arrancar la tarea, crea el worktree con la herramienta
EnterWorktree(nómbralo como la rama de la tarea, p. ej.claude/<tema>): lo deja en.claude/worktrees/con una rama nueva desdeorigin/developy mueve la sesión dentro. Como la herramienta bautiza la rama con un nombre autogenerado (worktree-...), renómbrala acto seguido a la convención:git branch -m claude/<tema>. Nunca empujes a otra rama sin permiso explícito. - Limpieza post-merge (siempre, sin excepción): cuando la rama se fusiona
en
develop, elimina el worktree y la rama —ExitWorktree(remove)si la sesión sigue dentro, ogit worktree removemás el borrado de la rama local y remota si no — y deja el repo en su estado de reposo: el checkout principal endevelopactualizado (git switch develop && git pull --ff-only) y ninguna rama local ya fusionada viva (git branch -d <rama>). - Mensajes de commit en español, descriptivos y referenciando el hallazgo
cuando aplique. Estilo observado en el historial:
Resuelve G27: nu.task.all alinea resultados con inputs (Promise.all)Ronda 5 de pseudocódigo: orquestación de agentes (loops deterministas + paralelo)Resolve G6 (per-function caps) and add ADR-010 (official extensions opt-in)
git push -u origin <rama>; reintenta solo ante fallos de red (backoff exponencial 2s/4s/8s/16s).- No abras un Pull Request salvo que se pida explícitamente.
- Licencia: el proyecto es Apache 2.0 (LICENSE), copyright de Diego Barea, que conserva la titularidad (ADR-014); las contribuciones externas siguen el DCO (ADR-030), sin cesión ni CLA. No introduzcas código de terceros con licencia incompatible ni cabeceras de copyright ajenas sin acordarlo; las contribuciones externas se rigen por CONTRIBUTING.md.
Glosario de prefijos de seguimiento
- ADR-NNN — decisión técnica registrada (su fichero en
docs/decisions/adr/). - G## — grieta/hallazgo que la v1 necesita cerrar (su fichero en
docs/findings/). - H##, F## — hallazgos de las rondas 1 y 2 de pseudocódigo (ya resueltos e integrados en la API).
- P## — discusión pospuesta con su disparador (un fichero por entrada en
docs/postponed/). - §N — referencia a una sección numerada dentro de un documento.
- ⏸ — función suspendiente (solo en task). [W] — disponible en workers.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

