agentleFS
dbareagimenodbareagimeno/enu/CLAUDE.md

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
  1. Very specific:

    No inventes API para tapar un hallazgo sin antes comprobar que el patrón se repite y que no se compone con lo existente.

    line 190

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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):

DocumentoRol
docs/core/filosofia.mdPrincipios fundacionales y "lo que enu no es". El porqué del proyecto.
docs/core/arquitectura.mdVista estática: las capas, el inventario de primitivas del kernel.
docs/core/modelo-ejecucion.mdVista dinámica: concurrencia, comunicación, limitaciones (con diagramas mermaid).
docs/contracts/api.mdLa 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.mdContrato de la extensión oficial de providers (registro TOML + adaptadores Lua).
docs/contracts/agente.mdContrato de la extensión oficial agent (motor headless: turno, tools, permisos, subagentes).
docs/contracts/sesiones.mdContrato de persistencia: JSONL append-only.
docs/contracts/chat.mdContrato de la extensión oficial chat (la UI).
docs/contracts/guia-plugins.mdSabiduría práctica para autores de plugins + checklist.
docs/contracts/malla.mdContrato 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.mdPlan de construcción incremental: una feature por sesión (S##), ordenado por dependencias del kernel.
docs/plan/estado.mdEl 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.mdRunbook 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):

  1. 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.
  2. 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.
  3. 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.
  4. La API del core es sagrada (docs/contracts/api.md): pequeña, aburrida, crece solo por adición; enu.version.api se 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.
  5. 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 + pcall en cada frontera de hook.
  6. Cero dependency hell: un binario estático Go (CGO_ENABLED=0), extensiones oficiales embebidas con go:embed pero inactivas por defecto (ADR-010).

Convenciones de la API (al editar docs/contracts/api.md o contratos)

  • Namespace global enu con submódulos; require reservado 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 con pcall. 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: y ui:. Todo lo demás (incluido agent:) 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:

  1. 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.
  2. Registro de problemas (docs/findings/, un fichero por hallazgo gNN-<slug>.md). Las grietas que la v1 sí necesita cerradas se numeran G## 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 de docs/findings/README.md — consúltala ahí, no aquí.
  3. Decisiones pospuestas (docs/postponed/, un fichero por P##). Lo que se decide no decidir todavía se numera P## y siempre lleva un disparador: la señal concreta que indica que toca reabrirlo. Nada está rechazado; está esperando. Cuando un P## se reabre y se decide, sale de aquí y entra en el ADR.
  4. ADR (docs/decisions/adr/, un fichero por decisión adr-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", y superseded_by en su frontmatter). Estados: Aceptada · Propuesta · Abierta · Reemplazada. El número y estado de cada ADR viven en su propio fichero (con índice en docs/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 en docs/findings/ y cita el G##/F##/P##/ADR-NNN que 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 en docs/ —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:

  1. Antes de tocar nada, abre docs/plan/estado.md y 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á en docs/plan/implementacion.md. Implementa solo esa sesión; respeta el grafo de dependencias (no abras una sesión cuyas dependencias no estén cerradas).
  2. 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 deja go build ./... verde.
  3. 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.
  4. 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 a G## se registran creando docs/worklog/sNN-<slug>.md (un fichero por sesión, con su fila en el índice docs/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.
  5. Commit en español citando la sesión (S07: ...) y el G## 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): develop es 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. main queda reservada para versiones estables: solo recibe merges desde develop cuando 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 desde origin/develop y 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, o git worktree remove más el borrado de la rama local y remota si no — y deja el repo en su estado de reposo: el checkout principal en develop actualizado (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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.