Redacción de Documentación Técnica
Compila la documentación técnica en un vehículo de conocimiento estable, mantenible y fácil de navegar. Primero decide a dónde pertenecen los hechos y qué necesita el lector, luego organiza el contenido y, por último, pule la expresión.
Principios fundamentales
- Identifica el tipo de información antes de escribir; no conviertas el proceso de descubrimiento directamente en la estructura del artículo.
- Cada hecho persistente tiene un único
canonical owner; el owner puede ser el código fuente, la configuración, el esquema, un generador, un documento o un registro de decisiones. - Elige el tipo de documento según la intención del lector (
reader intent), no según el nombre del archivo o el material existente. - Antes de escribir, establece un
Contrato de Documento: lector, objetivo, tema, alcance, exclusiones, fuentes autorizadas y límite de detalle. - El tipo de documento no puede ampliar el alcance; el documento superior resume a los hijos directos y enlaza al propietario del detalle.
- Organiza el contenido según prerrequisitos, dependencias y resultados verificables, no según el orden de investigación, implementación o confirmación (
commit). - Coloca el estado actual, las razones de diseño y la narrativa histórica en responsabilidades documentales distintas.
- Al cruzar límites, enlaza los detalles autoritativos; solo conserva contenido que esté dentro del alcance actual y sea suficientemente estable.
- El agente principal debe congelar primero el plan de redacción (
authoring plan) y luego decidir si delega; los subagentes solo ejecutan tareas de escritura local con límites claros.
Contrato de trabajo
Antes de ejecutar una escritura, reescritura, división, fusión o revisión estructural, forma un breve Contrato de Documento. Puede realizarse internamente; solo conviértelo en un artefacto visible si la tarea requiere alineación.
Registra los siguientes campos:
- Intención del lector (
Reader intent): El lector quiere aprender, completar una tarea, consultar, comprender, hacer seguimiento o cumplir una regla. - Tipo de documento (
Document type): El tipo de documento principal que coincide con la intención; un documento conserva solo una intención principal. - Tema (
Subject): El tema o nivel del sistema del que es directamente responsable el documento. - Alcance (
Scope): Los objetos, comportamientos y profundidad incluidos. - Exclusiones (
Exclusions): Contenido explícitamente reservado para otros documentos o fuentes autoritativas. - Autoridades (
Authorities): Código fuente, configuración, archivos generados, registros de decisiones o documentos existentes que respaldan los hechos actuales. - Límite de detalle (
Detail ceiling): El nivel máximo de detalle permitido dado el tema actual y los objetivos del lector.
Si no se puede determinar el owner, la intención del lector, el alcance o las fuentes autoritativas, primero mantén la incertidumbre y reporta las brechas; no inventes decisiones de producto o comportamiento actual basándote en la experiencia.
Flujo de trabajo de redacción
1. Ubica la tarea y la posición del documento
Identifica si se trata de una creación, actualización, división, fusión o revisión estructural. Lee los archivos AGENTS.md, CLAUDE.md, CONTEXT.md, el índice de documentación y los documentos adyacentes aplicables para confirmar la jerarquía existente en el repositorio, las convenciones de nombres y enlaces.
Si el documento de destino no existe, trata la tarea como documentación en terreno virgen (greenfield documentation): a partir del directorio de código, APIs públicas, esquemas de configuración, pruebas, ejemplos, comandos y archivos generados, elabora un mapa de documentos candidatos. Primero decide si se necesita un documento de entrada o un conjunto de documentos divididos por owner e intención del lector; no comprimas todo el marco de código en un único documento extenso y general.
Condición de finalización: cuando ya existe documentación, ya conoces la ruta de destino, el documento padre, los hijos directos y las reglas locales aplicables; cuando no existe documentación, ya conoces los límites principales del marco de código, el conjunto de documentos candidatos, el owner preliminar de cada documento y las fuentes autoritativas.
2. Inventaría y clasifica la información
Enumera los hechos, explicaciones, pasos, ejemplos, limitaciones y material histórico que se planea conservar. Clasifícalos por tipo de información y distingue entre estado actual, razones persistentes, procedimientos operativos, material de consulta, reglas, incidentes y contenido generado.
Cuando se necesite una tabla de clasificación detallada, lee references/information-and-ownership.md.
Condición de finalización: cada pieza de contenido candidato tiene un tipo de información; no se ha mezclado material de diferentes tipos en un párrafo indefinido.
3. Enruta los hechos al canonical owner
Para cada hecho persistente, busca un owner existente. Prioriza el código fuente, la configuración, los esquemas, los generadores y los registros de decisiones existentes como fuentes autoritativas; el documento solo posee las explicaciones, procedimientos o contratos estables dentro de su ámbito de responsabilidad.
Para contenido que ya tiene un owner, conserva solo un resumen necesario y un enlace al owner. Si se descubren múltiples owners en conflicto, primero reporta el conflicto y registra los problemas de autoridad que deben resolverse.
Condición de finalización: cada hecho no trivial tiene uno y solo un owner; el documento actual no duplica detalles autoritativos de otros lugares.
4. Selecciona el tipo de documento según la intención del lector
Elige entre Tutorial, How-to, Referencia, Explicación, ADR, Política o Informe de incidentes (Postmortem) según el objetivo del lector. No asignes múltiples tipos principales a un archivo solo porque contiene varios tipos de contenido; cuando la mezcla de intenciones afecte la navegación o el mantenimiento, divide el documento.
Lee references/document-types-and-composition.md para obtener pautas sobre selección de tipos y patrones de estructura.
Condición de finalización: puedes decir en una frase "quién lee este documento para qué" y señalar un tipo de documento principal.
5. Fija el alcance y el límite de detalle
Escribe el tema, la audiencia, el objetivo, las inclusiones, las exclusiones, las fuentes autoritativas y el límite de detalle. Limita el documento a su propio tema, nivel y responsabilidades de hijos directos; traslada los mecanismos de nivel inferior, pruebas, listas de verificación y detalles de implementación a su owner.
El tipo de documento no puede ampliar el alcance. El documento padre describe la composición, las responsabilidades y el comportamiento de alto nivel; los documentos hijos poseen definiciones de tipos, parámetros, mecanismos de prueba u operaciones específicas.
Condición de finalización: cada sección puede responder "¿cómo sirve al objetivo actual del lector y al alcance?"; el material fuera de los límites ya tiene un destino o un enlace.
6. Formula un plan de redacción ejecutable
Primero organiza los conceptos previos que el lector debe conocer, luego organiza las operaciones, explicaciones o consultas que dependen de ellos. Utiliza la estructura correspondiente al tipo de documento; no conviertas el orden de investigación, implementación, discusión o confirmación en un orden pedagógico.
Para documentos grandes, registra el árbol de secciones, el owner de los hechos, las dependencias entre secciones, el archivo de destino, las exclusiones y los criterios de aceptación de cada sección. El plan debe permitir que otro agente complete una tarea local sin rediseñar la estructura global.
Condición de finalización: el lector no necesita saltar a secciones posteriores para comprender términos necesarios, prerrequisitos o acciones de secciones anteriores; cada párrafo principal responde a una pregunta clara; cada unidad del plan tiene un alcance único y criterios de finalización.
7. Selecciona el modo de ejecución y delega
Por defecto, sigue la ruta de un solo agente. Solo abre subagentes cuando se cumplan todas las condiciones siguientes:
- El plan ya está congelado, sin conflictos sin resolver sobre intención del lector, tipo de documento, alcance,
ownery estructura principal. - Existen al menos dos unidades de trabajo que se pueden leer, escribir y validar de forma independiente.
- Cada unidad de trabajo tiene un archivo de destino único o un
ownerde sección; las tareas no editarán simultáneamente el mismo párrafo. - Las dependencias están registradas explícitamente; los hechos que deben compartirse ya tienen una fuente autoritativa, en lugar de depender de que los subagentes se adivinen mutuamente.
- El costo de despacho y fusión es menor que el costo de que el agente principal mantenga continuamente todo el contexto del documento.
Cuando se cumplan las condiciones, lee references/orchestration-and-delegation.md; el agente principal genera un informe de despacho e invoca a los subagentes. El agente principal conserva el plan global, la atribución de hechos, los enlaces entre secciones, las decisiones de fusión y la validación final. Los subagentes no rediseñan el tipo de documento, no modifican otras unidades de trabajo y no presentan hechos no verificados como conclusiones.
Si no se cumplen las condiciones, el agente principal continúa la escritura solo. Las adiciones locales a un solo archivo, las revisiones de unos pocos párrafos, las actualizaciones de Referencia con un solo owner y las dependencias fuertemente seriales pertenecen a la ruta de un solo agente.
Condición de finalización: ya se ha elegido explícitamente entre ejecución de un solo agente o ejecución delegada; si se delega, todas las tareas tienen límites, dependencias, formato de salida y criterios de aceptación.
8. Escribe directamente sobre el contrato actual y el comportamiento observable
Expresa el contenido con sujetos, acciones, APIs, opciones y resultados concretos. Primero escribe el estado actual y el comportamiento observable por el lector, luego añade valores predeterminados, limitaciones, excepciones, fundamentos y compensaciones. Distingue claramente entre "debe", "por defecto", "recomendado" y "puede".
Los Tutoriales y Cómo hacer (How-to) pueden centrarse en un ejemplo mínimo como explicación; las Referencias se centran en definiciones y límites recuperables; los ADR e Informes de incidentes conservan las razones o la cronología que necesitan.
Cuando se necesiten reglas completas y listas de verificación, lee references/writing-and-validation.md.
Condición de finalización: el texto expresa hechos, contratos o pasos mantenibles, no procesos de razonamiento, registros de implementación o metadiscurso vacío; la salida de las tareas delegadas ya ha sido recopilada por el agente principal.
9. Fusiona y unifica
Si se utilizaron subagentes, el agente principal revisa cada salida para verificar que cumpla con el plan de redacción. Resuelve hechos duplicados, desviaciones terminológicas, límites de sección, enlaces cruzados e inconsistencias de estilo; registra los problemas no resueltos de forma centralizada, sin permitir que los agentes locales inventen decisiones globales por sí mismos. No incorpores directamente las explicaciones del proceso de los subagentes en el texto principal; solo fusiona los resultados mantenibles.
Condición de finalización: cada unidad delegada tiene un resultado o una razón de bloqueo clara; el mismo hecho no tiene múltiples owners; el directorio global, los enlaces, la terminología y las rutas del lector son consistentes.
10. Enlaza, reduce y valida
Elimina hechos duplicados, listas copiadas manualmente, contexto irrelevante y detalles que superen el límite de detalle. Conecta a los owners, documentos hijos, código fuente y registros de decisiones con enlaces que expliquen el objetivo. Realiza la validación estructural y lingüística siguiendo el orden de los archivos de referencia.
Condición de finalización: se han verificado el owner, el tipo, el alcance, el orden de dependencias, los límites actuales/históricos, los enlaces y las reglas de expresión; no quedan conflictos o incertidumbres sin resolver.
Límites
No conviertas en reglas generales la jerarquía de archivos específica del repositorio, los comandos de script, el presupuesto de palabras, las reglas de compilación de bloques de código, los flujos bilingües o la terminología particular. Lee las convenciones locales del proyecto y sométete a ellas; esta Habilidad solo proporciona un marco de decisión documental estable entre proyectos.
No trates README, architecture.md o AGENTS.md como tipos de documento fijos y universales. Primero determina la intención del lector y luego sigue las convenciones específicas del proyecto para estos soportes.
Entrega final
Al finalizar, proporciona una breve explicación: tipo de documento e intención del lector, manejo de canonical owners, límites de alcance, enlaces o divisiones involucrados, y conflictos fácticos que aún requieren decisión humana. No disfraces los problemas no resueltos como estado actual.