name: agent-doc-discipline description: Disciplina de escritura para documentos que los agentes consumen (las cinco superficies, especificaciones, tickets, .omc/skills/) — cada regla verificable y con un porqué, pasos antes que referencias, un significado en un solo lugar, no repetir lo que el entorno ya dice. Obligatoria en la generación de semillas de drydock y en el pase de sedimentos C5 de lanzamiento; optativa para cualquier otra edición de documentos orientados a agentes. Compañera de la disciplina de código mínimo: esa disciplina el código, esta disciplina los documentos. level: 3
¿Qué hace Disciplina de Documentación para Agentes?
Usa esta habilidad para aplicar una disciplina de escritura al crear o editar cualquier documento que un agente consuma para actuar: las cinco superficies (CLAUDE.md, CONTEXT.md, docs/standards/, design-system/, .omc/skills/), especificaciones, tickets y archivos de habilidades. La prueba que debe superar un documento: una sesión de agente nueva puede actuar con solo leerlo.
Obligatorio cuando: drydock genera semillas de superficies, el pase de sedimentos C5 de lanzamiento escribe una lección en una ranura. Optativo para cualquier otra edición — pero cualquier edición a un documento orientado a agentes debería cumplir estas reglas.
Cuándo no usarlo
Documentos escritos solo para humanos: narrativa de docs/business/, historias de decisión ADR, READMEs para incorporación de humanos. Pueden seguir las reglas cuando no cueste nada, pero no están sujetos a esta disciplina.
La Disciplina
Escribe para un lector sin historial de chat. El documento se describe a sí mismo: nada se apoya en "como se discutió", una sesión anterior o conocimiento que vive en la cabeza de alguien. Prueba: una sesión de agente completamente nueva puede actuar con solo leer el documento.
Cada regla verificable y con un porqué. Nada de "mantenlo limpio" — escribe la condición observable y la razón. Prueba: un agente puede decidir aprobar/reprobar solo con el texto, y el porqué está indicado junto a la regla.
Un significado, un hogar. Cada regla o definición tiene un único lugar autoritativo; la duplicación es deriva esperando ocurrir. Prueba: cambiar un comportamiento es una edición en un solo lugar.
Nunca repitas lo que el entorno confiesa. Scripts de paquete, diseños de directorio, salida de --help son consultas, no documentos — una consulta copiada se vuelve obsoleta. Documenta solo lo que no se puede encontrar mirando: la convención no escrita, la razón detrás de una elección, el problema. Prueba: cada línea sobrevive a "¿se puede buscar esto en otro lado?".
Pasos primero, referencias después, material poco frecuente detrás de un puntero. Qué hacer, en orden, al inicio; reglas de consulta bajo demanda debajo; material de baja frecuencia empujado detrás de un puntero cuyo texto nombra las ramas que deberían desencadenar su consulta. Prueba: la siguiente acción se puede encontrar dentro de la primera pantalla.
Cada paso termina con un criterio de finalización. Hecho debe distinguirse de no hecho — un límite vago invita a la finalización prematura. Prueba: para cada paso, "¿cómo sé que esto está terminado?" tiene una respuesta en el texto.
Promueve lo positivo. Indica el comportamiento deseado; una prohibición se reserva para barreras duras y siempre va acompañada del objetivo positivo. Prueba: cada prohibición en el documento nombra la acción alternativa.
Elimina percebes al escribir. Cuando el documento contiene material obsoleto o redundante, elimínalo en la misma edición; cuando no lo contiene, agrega solo el material requerido y no inventes eliminaciones. Una oración que el modelo ya obedece por defecto agrega carga sin beneficio — elimina toda la oración. Prueba: cada línea releída gana su lugar frente a "¿esto cambia el comportamiento respecto al valor predeterminado?", y cualquier material obsoleto o redundante encontrado durante la edición se elimina.
Verificación
Antes de reportar un cambio de documento como completado, confirma:
- una sesión nueva podría actuar sin preguntar nada a un humano
- cada regla es verificable y establece su porqué; ninguna regla repite una consulta
- los significados viven en un solo lugar; los punteros nombran sus ramas desencadenantes
- el material obsoleto o redundante encontrado durante la edición se eliminó, mientras que el contenido válido no relacionado se preservó