Serie de aprendizaje de IA, lección 3: documentación, reglas y skills

Serie de aprendizaje de IA · Lección 3 de 4

Cada sesión nueva de IA empieza sin memoria de tu repositorio. Si las convenciones solo viven en la cabeza de alguien —o en un documento que nadie vuelve a leer—, el modelo las rompe en silencio, y la ruptura parece código que funciona hasta que deja de funcionar.

Estado: esquema. El recorrido en pantalla aún no se ha grabado: esta entrada es el plan que seguirá, y recibirá el recorrido real cuando la lección se emita.

Lo que podrás hacer

• Dar a un repositorio tres cosas distintas: documentación por la que pueda navegar, reglas que deba seguir y skills que pueda reutilizar
• Clasificar cualquier pauta en la capa correcta de las tres
• Convertir una regla escrita en una comprobación que falle cuando la regla se rompe

Se apoya en las lecciones 1 y 2: el contexto permanente de la lección 2 era un solo bloque de instrucciones. Esta lección lo divide en capas con funciones distintas, para que cada sesión cargue solo lo que necesita: la idea de costo del contexto de la lección 1, aplicada a escala de repositorio.

Fuera del alcance: medir o recortar el gasto (lección 4) y construir una aplicación completa. Lo que se construye en pantalla es deliberadamente pequeño: el tema es la estructura que lo rodea.

Las tres capas

Documentación — encontrable, un responsable por hecho

• Un índice, un hecho con responsable claro por tema y una tabla de impacto de cambios
• La documentación sigue siendo encontrable y no queda obsoleta en silencio cuando cambia lo que describe

Reglas — cortas, siempre cargadas, con razones

• El archivo siempre cargado enuncia las prohibiciones y cita el porqué, no solo el qué
• Todo lo más largo va en un documento enlazado, no en el archivo que cada sesión paga por cargar

Skills — procedimientos cargados solo cuando hacen falta

• Un skill es un procedimiento reutilizable que el asistente carga cuando surge una tarea concreta y repetible
• El repositorio del ejemplo práctico no tiene hoy un directorio de skills a nivel de proyecto, así que el skill se construye en directo, no se prepara para la demo

El ejemplo práctico

La lección se desarrolla sobre un repositorio real de uso diario, no un juguete construido para la lección. Cinco patrones, cada uno con una función distinta:

Archivo de entrada — se lee primero

• Un archivo dice qué es el proyecto, qué hacer y qué no hacer, antes que nada
• Cuando más de un agente de IA trabaja en el repositorio, se replica en el punto de entrada que espera cada agente, para que ninguno lea una copia obsoleta o parcial

Regla aplicada por un test — más fuerte que la prosa

• Una regla que comprueba un test vale más que una regla que vive en un párrafo que alguien podría saltarse
• Este blog lo hace con las traducciones: la categoría y la fecha deben mantenerse idénticas byte a byte entre idiomas, y npm run check:translations falla si no lo están

Cola de decisiones — autorizado antes de empezar

• El trabajo se escribe y se aprueba antes de empezar
• Ningún agente deduce el alcance de un mensaje de chat vago

Índice de impacto de cambios — "si cambias X…"

• Una tabla que dice qué documentos quedan obsoletos cuando cambia un archivo concreto
• La conexión se consulta, no se redescubre después de que algo se rompa

Definición de hecho — varía según el cambio

• Lo que cuenta como verificado depende del tipo de cambio
• Una edición de documentación necesita otra prueba que una migración de esquema

# Rules File — Skeleton
## What this project is
One paragraph. Link to README for everything else.

## Never
- Edit generated or vendored directories (why: overwritten on update)
- Commit secrets or expose them via public env vars (why: shipped to the browser)
- Mark work done without the check for its change type (why: see Definition of Done)

## Where things live
- Architecture → docs/ARCHITECTURE.md
- Change impact → docs/CHANGE_IMPACT.md
- Definition of done → docs/DONE.md

En pantalla

• Primero, el modo de fallo — una sesión nueva hace un cambio que viola una convención que nadie escribió donde el modelo pudiera encontrarla
• Estructura de la documentación — índice, un responsable por hecho, tabla de impacto de cambios
• Reglas — qué va en el archivo siempre cargado y qué en un documento enlazado
• Aplicación — una regla escrita se convierte en un test, se rompe a propósito y luego se arregla
• Un skill, construido en directo — para una tarea que de verdad se repite, comparado después con trabajar sin él
• Ejercicio de clasificación — pautas reales clasificadas en documentación, reglas o skills, incluida una mal clasificada a propósito y corregida

¿En qué capa va?

# Sorting Guidance
Is it a fact about how the system works?          → Documentation
Is it always true, and does breaking it hurt?     → Rules (with the why)
Is it a procedure you repeat for a specific task? → Skill
Can a test check it?                              → Also write the test

Verifica antes de confiar en ello

• Que cada archivo y ruta del ejemplo práctico sigue existiendo y sigue diciendo lo que se afirma: los repositorios se desvían, y esta lección se apoya en rutas reales
• Cómo llama la herramienta mostrada a un archivo de reglas y a un skill, dónde vive cada uno y cómo se carga
• Si en esa herramienta los skills se cargan bajo demanda o siempre: el segmento de skills en directo depende de ello
• Si la recomendación de tamaño del archivo de reglas sigue coincidiendo con el consejo actual del proveedor
• Que el skill construido en directo se reutiliza de verdad después, y no es un accesorio de demo

Preguntas frecuentes

"¿No puedo ponerlo todo en el archivo de reglas?" Puedes, y cada sesión lo paga. Los archivos de reglas largos se leen por encima y se diluyen para los modelos. Mantén las reglas cortas y enlaza el resto.

"¿Cómo sé que una regla se cumple de verdad?" Escribe una comprobación que falle cuando no se cumpla. Una regla sin comprobación es una sugerencia.

"¿Cuándo se convierte un prompt en un skill?" La tercera vez que pegas el mismo procedimiento. Guárdalo una vez y cárgalo cuando surja la tarea.

Siguiente: lección 4

La lección 4 va al final a propósito. Usa todo lo que enseñan las tres primeras —elección de modelo, calidad del prompt y del contexto, y estructura del repositorio— como palancas para recortar lo que cuesta un flujo de trabajo con IA.