Buenas prácticas

El agente no conoce las aplicaciones del equipo. Lo que no encuentra escrito lo descubre leyendo el repositorio, y eso es lo más caro del ciclo: decenas de archivos que después se reenvían en cada turno. Además, leer de más también responde peor, porque la precisión de cualquier modelo cae a medida que crece la entrada.

La regla de fondo, que coincide con lo que se midió en 2026 sobre archivos de contexto para agentes: poco contexto fijo, solo lo que el código no dice, y lo demás se consulta en el momento. Todo lo de esta página sale de esa regla.

El inventario

Una fila por cosa con carpeta propia. Un workspace Angular con siete proyectos son siete componentes; una solución .NET con capas es uno.
«Consume» es la relación que más vale. De ahí salen las ramas de un requerimiento y el análisis de impacto. Contrastala con el código: kb apps verificar <APP>, y --aplicar suma lo que falte.
Aplicaciones y módulos declarados (kb apps aplicacion): así «el backend de ro» o «el host» se resuelven solos, sin preguntar.
Alias solo para lo que no se deduce: una sigla interna, un nombre viejo.
Rutas lógicas, nunca absolutas.
Sin el manual adentro: el inventario guarda la tabla, y las reglas están en kb apps guia. kb apps actualizar lo deja así.

Las fichas

Solo datos. Comandos, usuarios de prueba, cómo se entra, decisiones con su porqué, zonas que no se tocan, trampas («la suite tarda 11 minutos», «no usar X porque…»). Lo que se deduce del código —árbol de carpetas, lista de proyectos, qué hay en cada módulo— no va: lo da el índice generado y no se desactualiza.
Confirmadas. verified: con quién y cuándo. Una ficha sin confirmar se lee «con cautela» y no ahorra la verificación.
Con su clasificación (clasificacion:): sin ella la política de IA no puede decidir qué modelos trabajan con ese código.
Sin dos verdades. Si el equipo ya documentó la arquitectura en el CLAUDE.md o el AGENTS.md del repositorio, la ficha apunta a eso (kb ficha cosechar --aplicar) en vez de copiarlo. Las reglas de código y estilo mandan en el repositorio; la ficha guarda lo que cruza repositorios.
Comandos en la tabla, no en un bloque de código: kb pruebas y el Pull Request los leen de ahí. kb arquitectura --aplicar los trae del código.

El mapa y el índice

Construilo al dar de alta la app y cada vez que cierra un requerimiento que agregó pantallas, controllers o casos: kb mapa construir <APP>, segundos.
Publicalo (kb publicar-base): el índice (unos pocos KB de markdown) le sirve a todo el equipo, y el mapa permite consultar sin tener el código de los demás componentes.
Para un caso nuevo, la receta (kb mapa receta <APP> <tipo> <COMPONENTE>) y no «mirá cómo se hizo X»: da los archivos exactos con uno real al lado.
Para el impacto, el vecindario inverso (kb mapa vecindario <APP> <archivo> --inverso): quién depende de lo que vas a tocar.
Cuando kb mapa avisa «mapa viejo», se reconstruye. No es por calendario: es porque cambiaron archivos que cubre.

El glosario

aplicaciones/GLOSARIO.md (kb glosario --agregar) es el vocabulario del negocio. Dos cosas lo hacen rendir:

se llena durante el análisis, cada vez que aparece un término que un recién llegado no entendería;
en «Qué es», los nombres con que vive en el código entre comillas invertidas (PlanContinuidad, procedimientos/): kb mapa buscar los usa para llegar al archivo desde la palabra de negocio.

Los contratos

Nunca se adivina un endpoint de otra API. kb contratos buscar <API> <operación> trae una operación del OpenAPI que el código ya tiene.
Que el spec del código esté al día. Si NSwag o Swashbuckle lo escriben al compilar, se versiona actualizado. kb contratos sembrar avisa cuando no coincide con los controllers.

Los estándares

Uno por tipo (frontend, backend, base de datos) más comunes.md. kb contexto entrega solo los del tipo de la app: el de base de datos no viaja con un cambio de pantalla.
Reglas verificables antes que párrafos: lo que un linter, un analizador o una prueba de arquitectura puede comprobar, que lo compruebe.

Las sesiones y los modelos

Una tarea por sesión, y el expediente como memoria: lo que no está escrito se pierde en la próxima compactación.
El modelo de cada fase según MODELOS.md: razonamiento para analizar, uno más barato para implementar con un plan aprobado. Ver Modelos por fase.
kb tokens dice dónde se fue el consumo de un requerimiento: si es exploración, falta ficha, índice o glosario.

Cada cuánto

Cuándo	Qué	Comando
Al dar de alta una app	inventario, ficha, mapa, contratos, base E2E	`kb apps descubrir` · `kb ficha sembrar` · `kb mapa construir` · `kb contratos sembrar` · `kb pruebas validar`
Al empezar un requerimiento	qué leer y si sigue vigente	`kb contexto <APP>`
Al crear archivos	la forma de la casa	`kb mapa receta` · `kb estructura`
Al cerrar un requerimiento	lo que cambió, a la base	`kb mapa construir` · `kb apps verificar` · `/kb-entrega` · `kb publicar-base`
Con cada versión de kbspec	la máquina y la base al día	`kb actualizar` · `kb apps actualizar --ver` · `kb publicar-base`
Una vez por mes	lo que se fue quedando	`kb apps verificar` · `kb configuracion probar` · `kb validar`