La carpeta es el agente
Cómo un repo de Git y un archivo markdown se convierten en un agente de AI con Claude Code
Ayer leí un artículo de Kieran Klaassen en Every que se llama “The Folder Is the Agent.” Kieran es el ingeniero detrás de Cora, el asistente de email de Every, y el creador del plugin Compound Engineering — uno de los más populares para trabajar con agentes en Claude Code. Corre 44 agentes de AI desde diferentes carpetas en su máquina. Su argumento: no necesitas frameworks complicados ni orquestación sofisticada. Una carpeta con los archivos correctos convierte un modelo genérico en un especialista.
Este framework minimalista es algo con lo que he estado experimentando ya hace unas semanas y se los quiero compartir hoy porque me ha funcionado muy bien.
No soy ingeniero en una empresa de AI. Soy Data Architect en un gobierno local. Trabajo en una agencia pública en California que sirve a las comunidades más vulnerables del condado. Y tengo un agente de AI que me ayuda a hacer ese trabajo todos los días. Le llamo Gaudí (gaudi-os, técnicamente).
Cómo funciona un agente de Claude Code
gaudi-os es una carpeta. Esto es lo que contiene:
gaudi-os/
├── CLAUDE.md # identidad, principios, convenciones
├── README.md # setup de una página
├── .memory/ # la memoria del agente
│ ├── MEMORY.md # índice
│ ├── user_sergio_data_architect.md
│ ├── reference_data_intake_playbook.md
│ ├── feedback_iterative_refinement.md
│ └── ...
├── skills/ # workflows reutilizables
│ ├── debrief/
│ │ └── SKILL.md # genera notas, action items, actualiza perfiles
│ ├── status-report/
│ │ └── SKILL.md # log semanal desde el vault
│ └── ...
├── .claude/
│ └── settings.local.json # creado después de clonar
└── .gitignore
Eso es todo. No hay servidor. No hay base de datos. No hay dependencias que instalar. Creas la carpeta, un archivo de configuración local (CLAUDE.md), y el agente está listo.
¿Por qué funciona? Porque Claude Code lee el CLAUDE.md al inicio de cada sesión. Ese archivo le dice al modelo quién soy, qué hago, cómo trabajo, y qué principios guían las decisiones que tomo. El modelo se despierta fresco cada vez. Los archivos son su contexto.
Kieran tiene 44 de estas carpetas.
El archivo que lo define todo
El corazón de gaudi-os es ese CLAUDE.md. Un solo archivo markdown. Esto es lo que tiene:
Identidad. Le dice al modelo quién soy y dónde trabajo:
You are operating as Sergio Sanchez, Data Architect and de facto AI lead at First 5 Alameda County.
Acceso al vault. El agente sabe que mi base de conocimiento vive en un vault de Obsidian organizado con el método PARA — proyectos, áreas, recursos, archivo. Sabe navegar la estructura, buscar entidades, y cruzar información.
Convenciones editoriales. Cosas como “Child care” son dos palabras y “Healthcare” es una. Usa la Oxford comma y APA para citas.
Gestión de resultados. El agente sabe dónde guardar cada tipo de documento — los que van para audiencias específicas en un repo, el conocimiento de vuelta al vault.
El ciclo de retroalimentación. Cada skill — cada workflow que el agente ejecuta — no solo produce un output. También escribe conocimiento de vuelta al vault. Un /debrief genera actualizaciones a perfiles de personas, action items, y una nota de la reunión. Un /status-report escribe un log semanal. El sistema se alimenta a sí mismo.
“There Are No Edge Cases”
Así se llama el principio de diseño central de gaudi-os.
What engineers call “edge cases” are often the default experience for the communities we serve. A form that breaks on a non-English name isn’t an edge case — it’s exclusion. A system that fails silently when data is missing isn’t robust — it’s erasing whoever that data represents.
Esto no es filosofía abstracta. Es instrucción operativa. Le dice al agente cómo evaluar su propio trabajo:
Datos: los registros van a llegar incompletos, tarde, y desordenados. Esa es la realidad de la recolección de datos comunitarios. Diseña para eso.
Automatización: las dependencias externas van a cambiar. Los sistemas tienen que reconciliar antes de actuar, fallar de manera visible cuando no pueden, y nunca tirar trabajo silenciosamente.
Documentos: cuando los datos cuentan una historia incompleta, muestra la incertidumbre. No escondas los fallas o deficiencias.
Herramientas para staff: asume comodidad técnica variada. Asume workflows interrumpidos. Asume que la persona tiene otras doce cosas pendientes.
El estándar no es “¿funciona?” El estándar es “¿funciona para las personas que menos pueden darse el lujo de que no funcione?”
Lo que me llamó la atención es que la mecánica es la misma. Kieran está en la frontera del AI, en una de las empresas líderes del planeta, corriendo 44 agentes para velocidad e ingeniería. Yo soy una persona en gobierno local enfocado en equidad y comunidades vulnerables. Y los dos usamos lo mismo: una carpeta con un CLAUDE.md. Y eso es suficiente.
Memoria que viaja contigo
El directorio .memory/ es la otra pieza clave. Yo no mantengo esos archivos a mano. Son el sistema de memoria de Claude Code — markdown plano con frontmatter y un índice.
Lo único que hice fue un hack sencillo: redirigir dónde se guardan.
Normalmente, Claude Code guarda la memoria del agente en un directorio del sistema, algo como ~/.claude/projects/.../memory/. Eso significa que la memoria está atada a la máquina. Si clonas el repo en otra computadora, el agente empieza de cero.
La solución: un archivo .claude/settings.local.json con una sola línea:
{"autoMemoryDirectory": ".memory"}Eso le dice a Claude Code que guarde la memoria dentro del repo. Y como el repo está en Git, las lecciones que el agente aprende se guardan con commit y viajan con él.
¿Por qué tiene que ser .local? Porque Claude Code bloquea autoMemoryDirectory en el settings.json regular por cuestiones de seguridad. No querrías que cualquier repo que clones pueda redirigir dónde se escribe tu memoria. Es una restricción deliberada: solo funciona en settings.local.json, que normalmente está en .gitignore y no se incluye en el repo. Lo creas a mano después de clonar. Un paso manual de cinco segundos.
El resultado es que el agente acumula lecciones. Cosas que se pierden entre sesiones. El agente las captura en archivos planos. Siguiente sesión, las lee y no repite errores.
---
name: Design debate pattern with Tufte/Lupi/Cairo
description: Spinning up persona-based design debates produces better interfaces than going straight to code — use for any data review or visualization UI.
type: feedback
---
When building a data review interface, run a design debate between Tufte (density, data-ink ratio), Lupi (humanism, preattentive processing), and Cairo (functional scaffolding, accessibility) before writing code.
**Why:** The R&R fuzzy match review UI came out significantly better than a default card layout would have. Key insights from the debate: yellow diff highlights (Cairo's diff-tool convention), 3-tier confidence borders (Lupi's preattentive processing), sticky headers (Cairo's scaffolding), compact bands instead of cards (consensus). Research notes from a previous Tufte/Lupi project are in the vault archive at `archive/projects/tufte-lupi-statusline-design/`.
**How to apply:** Use for any interface where a human reviews data items in bulk. The debate format works as a subagent prompt. The synthesis is what gets built.No es RAG. No es un vector store. Es un directorio con archivos .md en Git.
Un agente, no cuarenta y cuatro
Kieran utiliza 44 agentes porque su problema es escala de desarrollo: features, bug fixes, code review, ops monitoring, todo en paralelo. Es un solo ingeniero construyendo un producto completo. Más agentes le dan más y mejor throughput.
Mi problema es diferente. En gobierno local, el cuello de botella no es cuántas features puedes hacer deploy. Es mantener el contexto. Documentar decisiones. No perder el hilo entre reuniones con diez stakeholders de diferentes departamentos. Capturar lo que se dijo en un debrief y que eso alimente la preparación de la próxima reunión.
Un agente bien configurado, con contexto profundo sobre tu trabajo, tus convenciones, tus compañeros de equipo, y tus principios de diseño, resuelve eso. Por ahora no necesito un enjambre. Necesitaba una carpeta con claridad.
El agente que necesitas depende de tu trabajo. Lo único que necesitas es poder describir claramente tus métodos, guías, workflows.
Para los suscriptores de pago les dejo aquí una prompt que gaudi-os escribió para crear un agente como él. Solo necesitas crear una carpeta nueva y abrir Claude Code o usar Cowork (en la app de Claude Desktop) y pegarla. Te entrevistará y creará los archivos necesarios.
Hasta la próxima, ay’tamos.
– chekos
