AGENTS.md y CLAUDE.md para una base de conocimiento

AGENTS.md y CLAUDE.md son archivos markdown planos que los agentes de código leen antes de trabajar en una carpeta. En una base de conocimiento, es donde les dices a los agentes cómo están organizadas tus notas y qué reglas debe seguir cada documento. Ninguno de los dos archivos tiene campos obligatorios ni un esquema: escribes las instrucciones en markdown normal.

Esta guía explica primero la configuración manual. Junto a cada parte verás qué cambia con Knowtarium, nuestra base de conocimiento cifrada de extremo a extremo que escriben juntos personas y agentes, y las convenciones que da a cada agente que conectas.

AGENTS.md

AGENTS.md es un formato abierto para guiar a los agentes de código, gestionado por la Agentic AI Foundation dentro de la Linux Foundation. Lo leen muchos agentes de código, entre ellos OpenAI Codex y Cursor. Lo pones en la raíz de tu carpeta y puedes añadir más en subcarpetas: gana el AGENTS.md más cercano al archivo que se está editando, y lo que escribes en el chat se impone a todos ellos.

CLAUDE.md

CLAUDE.md es la versión de Claude Code. Según la documentación de Anthropic, Claude Code lo lee desde varios lugares, del más general al más concreto:

Las organizaciones también pueden distribuir un CLAUDE.md gestionado. Los archivos no se anulan entre sí: Claude Code los concatena, desde la raíz del sistema de archivos hasta el lugar donde lo iniciaste, así que las instrucciones más específicas van al final. Los archivos de las subcarpetas se cargan cuando Claude lee un archivo de esa subcarpeta. Un CLAUDE.md puede incluir otros archivos con @path/to/file, hasta cuatro niveles de profundidad. Anthropic recomienda que cada archivo no pase de 200 líneas.

En Knowtarium

Knowtarium añade controles que un archivo de instrucciones no puede dar. Haga lo que haga un agente con tus reglas, cada cambio que hace va firmado y se puede deshacer con un clic, solo borra documentos si le diste ese permiso y no puede marcar nada como revisado por una persona. En las carpetas donde activas la revisión, sus cambios esperan como diffs hasta que los apruebas.

(se abre a tamaño completo en una pestaña nueva) (se abre a tamaño completo en una pestaña nueva)

Si usas más de un agente, escribe tus reglas una sola vez en AGENTS.md. Las versiones recientes de Claude Code leen AGENTS.md por su cuenta cuando no hay ningún CLAUDE.md ni CLAUDE.local.md en la carpeta o por encima de ella (v2.1.277 y posteriores). Si además quieres instrucciones específicas para Claude, o usas una versión más antigua, crea a su lado un CLAUDE.md que lo importe:

@AGENTS.md
 
## Claude Code
 
- Trabaja en modo plan en cualquier cambio que toque más de tres documentos.

Claude lee primero el AGENTS.md importado y luego las líneas que vienen debajo. Todos los demás agentes leen AGENTS.md directamente, así que las reglas nunca se desincronizan.

La mayoría de los ejemplos de AGENTS.md están escritos para código: comandos de compilación, tests, estilo. Una base de conocimiento necesita otras reglas. Estas son las que más importan cuando los agentes escriben buena parte de tus notas.

Estructura de carpetas

Di para qué sirve cada carpeta de nivel superior y dónde van los documentos nuevos. Sin esto, los agentes se inventan carpetas, y dos agentes archivan el mismo tipo de nota en dos sitios distintos.

Nombres

Un concepto por archivo, un patrón de nombres. Los nombres con fecha para decisiones y reuniones hacen que la carpeta se ordene sola.

Enlaces

Elige un estilo de enlace y dilo. Los enlaces markdown estándar funcionan en todas las herramientas; los [[wikilinks]] solo en algunas. Diles a los agentes que actualicen los enlaces cuando muevan un archivo, y que se permite enlazar a un documento que nadie ha escrito todavía.

Frontmatter para la procedencia y la vigencia

Es la regla que más plantillas omiten, y la que permite revisar más adelante una base de conocimiento escrita por agentes. Exige que cada documento diga quién lo escribió y cuándo se queda desfasado. El Open Knowledge Format, una especificación abierta publicada por Google Cloud, te da los nombres de los campos: type (el único obligatorio), generated, verified, status, stale_after y sources. Usar un formato publicado significa que cualquier herramienta que lea OKF entiende tus notas.

Citar las fuentes

Exige una fuente para cada cifra, fecha, nombre y cita, citada junto a la afirmación. La guía para que los agentes citen sus fuentes profundiza en ello.

Lo que los agentes nunca deben hacer

Escribe los límites estrictos como reglas que empiecen por “Nunca”: nunca marcar algo como revisado por una persona, nunca borrar, nunca sobrescribir la edición de una persona. La documentación de Anthropic señala que las instrucciones concretas y concisas se siguen con más constancia que las generales.

Cómo registrar una revisión

Cuando un agente confirma un documento, debería indicarlo de una forma fija: su propia entrada en verified con una marca de tiempo. Así cualquiera distingue la revisión de un agente de la de una persona.

En Knowtarium

En las carpetas con revisión activada, Knowtarium convierte esas entradas en un nivel de confianza. La entrada de un agente hace que un documento sea machine-confirmed, la tuya lo hace human-reviewed, y las dos después del último cambio lo dejan totalmente verificado. Cuando apruebas ahí el cambio de un agente, la app escribe tu entrada por ti.

(se abre a tamaño completo en una pestaña nueva) (se abre a tamaño completo en una pestaña nueva)

Copia esto en AGENTS.md en la raíz de tu carpeta de notas y cambia la lista de carpetas para que coincida con la tuya. Se queda holgadamente por debajo de las 200 líneas que recomienda Anthropic.

---
type: Instructions
title: Reglas para agentes
---
 
# Base de conocimiento: reglas para agentes
 
Esta carpeta es una base de conocimiento que escriben juntos personas y agentes.
Cada archivo es markdown plano con frontmatter YAML (OKF v0.2).
Lee este archivo entero antes de cambiar nada.
 
## Estructura
 
- El index.md de cada carpeta enumera lo que contiene. Léelo primero.
- log.md registra lo que ha cambiado, lo más reciente primero. Añade una línea por cada sesión.
- company/     misión, glosario, cómo trabajamos
- customers/   segmentos, interviews/ (un archivo por entrevista)
- metrics/     un archivo por métrica; computations/ para las consultas aprobadas
- decisions/   un archivo por decisión, con el nombre YYYY-MM-DD-titulo-corto.md
- references/  copias del material de origen que citas (PDF, CSV, páginas guardadas)
- Nunca crees una carpeta nueva en el nivel superior. Pregunta antes.
 
## Encontrar cosas
 
- Empieza por el index.md de la raíz y sigue los enlaces. No leas todos los archivos.
- Busca antes de escribir. Si ya existe un documento sobre el tema, actualízalo.
 
## Nombres
 
- Un concepto por archivo. Los nombres de archivo van en minusculas-con-guiones.md.
- index.md y log.md están reservados. Nunca los uses para un documento.
 
## Enlaces
 
- Usa enlaces markdown estándar, nunca [[wikilinks]].
- Enlaza desde la raíz del paquete: [Churn](/metrics/churn.md).
- Enlazar a un documento que aún no existe está bien. No crees
  un archivo vacío solo para arreglar el enlace.
- Cuando cambies el nombre de un archivo o lo muevas, actualiza todos los enlaces a él.
 
## Frontmatter
 
Cada documento empieza con frontmatter. Deja las claves que no reconozcas
exactamente como están.
 
```yaml
---
type: Metric                # obligatorio: Metric, Decision, Interview, ...
title: Churn
description: Una frase, que se usa en index.md y en la búsqueda.
status: stable              # draft | stable | deprecated
generated: { by: <tu-nombre>/<versión>, at: <hora UTC, ISO 8601> }
stale_after: <hora UTC>     # cuándo deja de ser seguro citarlo
sources:
  - id: billing-export
    resource: /references/billing-2026-09.csv
    title: Exportación de facturación, septiembre de 2026
---
```
 
- Firma en `generated` cada documento que escribas o cambies.
  Actualiza `generated.at` en cada cambio importante.
- Pon `stale_after`: 90 días para las métricas, 1 año para las decisiones.
- Los documentos nuevos empiezan como `status: draft`.
 
## Fuentes
 
- Cada cifra, fecha, nombre y cita necesita una fuente.
- Añade la fuente a `sources` con un `id` corto y estable, y cítala
  después de la afirmación con una nota al pie: El churn bajó al 2,4 %.[^billing-export]
- Cita solo fuentes que hayas abierto en esta sesión. Nunca te inventes una URL.
- Si no encuentras una fuente, escribe la afirmación bajo
  "## Preguntas abiertas" en lugar de presentarla como un hecho.
 
## Revisar la edición de una persona
 
- Lee el cambio y luego todos los documentos que lo enlazan o que comparten
  una fuente con él.
- Si todo sigue cuadrando, añádete a `verified`:
  - { by: <tu-nombre>/<versión>, at: <hora UTC> }
- Si algo ya no cuadra, propón la corrección. No la apliques sin decir nada.
 
## Nunca
 
- Nunca añadas una entrada `human:` a `verified`. Eso solo lo hace una persona.
- Nunca quites ni reordenes las entradas `verified` de otra persona.
- Nunca borres un documento. Pon `status: deprecated` y explica por qué.
- Nunca sobrescribas la edición de una persona. Si no estás de acuerdo, dilo y para.
- Nunca edites archivos de references/. Son las pruebas.
 
## Cuando termines
 
- Añade una entrada con fecha a log.md.
- Enumera todos los archivos que has creado, cambiado, movido o marcado como deprecated.

Sustituye los plazos de vigencia de la sección Frontmatter por los tuyos. OKF considera documento cualquier archivo .md salvo index.md y log.md, así que la plantilla empieza con su propio frontmatter y un type para que el paquete siga siendo válido. El bloque de frontmatter de ejemplo que incluye está ahí para que lo copien los agentes.

Algunas reglas solo importan en un sitio. Con AGENTS.md, pon un segundo archivo en esa carpeta, como metrics/AGENTS.md; los agentes usan el más cercano. Claude Code también tiene reglas limitadas a rutas: archivos markdown en .claude/rules/ con un campo paths, que solo se cargan cuando Claude lee un archivo que coincide.

---
paths:
  - "metrics/**/*.md"
---
 
# Métricas
 
- Cada métrica enlaza a la consulta que la calcula en metrics/computations/.
- Nunca cambies una cifra sin una nueva entrada de fuente.

Así el archivo de la raíz se mantiene breve. La documentación de Anthropic advierte de que los archivos de instrucciones más largos ocupan más contexto y se siguen peor.

En Claude Code, ejecuta /context y mira en Memory files para confirmar que tu archivo se ha cargado. Con cualquier agente, empieza una sesión pidiéndole que repita las reglas para escribir un documento nuevo. Si no puede, el archivo no se está leyendo o es demasiado largo.

Luego comprueba el resultado, no la promesa. Dos greps detectan los despistes más habituales:

# documentos sin type: el único campo OKF obligatorio
$ grep -rL "^type:" --include="*.md" . | grep -v -e "/index.md$" -e "/log.md$"
 
# wikilinks que se han colado
$ grep -rn "\[\[" --include="*.md" .

Cuando el mismo error aparezca dos veces, añade una regla para él. Es también lo que aconseja Anthropic para CLAUDE.md: escribe lo que, si no, tendrías que volver a explicar.

Knowtarium incluye una skill de convenciones que recibe, junto con sus herramientas, cada agente que conectas (Claude Code, Codex, Cursor, Claude Desktop y otros), así que no tienes que escribir las convenciones de una base de conocimiento de Knowtarium en cada archivo de instrucciones.

Qué enseña

• Leer primero el índice propio del espacio de trabajo. Si tiene un index.md, leerlo y seguir sus enlaces en lugar de cargar todos los documentos.
• Leer antes de escribir. Títulos y descripciones antes que los documentos enteros, y cada cambio indica la versión en la que se basa, así que un agente no puede sobrescribir una edición que no ha leído.
• Saber cómo se aplica un cambio. En la mayoría de las carpetas, un cambio se guarda al instante y se puede deshacer, así que hay que ser prudente; en las carpetas con revisión activada, espera aprobación. En ambos casos, decirle a la persona cuál de las dos cosas ha pasado.
• Revisar después de la edición de una persona. En las carpetas con revisión activada, leer los documentos relacionados, registrar la revisión si todo sigue cuadrando y señalar un conflicto si algo no cuadra.

Cómo se combina con tu AGENTS.md

En Knowtarium, tu AGENTS.md son las instrucciones de la carpeta: lo escribes en la app, y los agentes lo reciben con cada nota que escriben allí.

Algunas reglas no dependen de que nadie lea un archivo. En Knowtarium, cada cambio que hace un agente va firmado con su propia clave, los agentes solo borran documentos si les diste ese permiso, no pueden marcar nada como revisado por una persona y, en las carpetas con revisión activada, no pueden saltarse tu revisión. Un agente solo llega al espacio de trabajo y a las carpetas a los que lo conectaste. La app no llama a ninguna IA por sí misma: cuando quieres que revisen tus ediciones, se lo pides a tu agente, y él sigue la skill.

Los agentes se conectan por MCP con npx knowtarium connect, con el plugin de Knowtarium en Claude Code y Codex (que incluye la skill), con la extensión en Claude Desktop o con un clic en Cursor y VS Code. Los conectores para apps de chat como claude.ai y ChatGPT llegarán más adelante. Consulta cómo trabajan los agentes con Knowtarium.