Desarrollo de Software y Arquitectura
Generación de documentación técnica con IA para Desarrollo de Software y Arquitectura
Guía de IA con entradas, permisos, trazabilidad y revisión humana para mantener la documentación técnica al día sola, a medida que el software cambia.
El subagente de documentación técnica lee el código y las APIs y escribe la documentación por su cuenta. Consulta el código fuente, las APIs y sus cambios y devuelve cada respuesta con su fragmento, versión y fecha a el responsable de desarrollo; sin evidencia, rechaza responder como hecho. Si falta una entrada obligatoria, una fuente vigente o una autorización, identifica la excepción y no inventa ni ejecuta el paso.
Índice del artículo
Qué pregunta resuelve generación de documentación técnica y cuándo debe rechazarla
Configuración en Kronjop: Toma como entrada trabaja con el código fuente, las APIs y sus cambios; utiliza Repositorio autorizado de Generación de documentación técnica, Índice de recuperación con versión y vigencia, Control de acceso por documento y empresa, Bandeja de preguntas, respuestas y correcciones; su tarea es mantener la documentación técnica al día sola, a medida que el software cambia. La salida vuelve a Responsable de desarrollo con fuentes, cambios y excepciones para su revisión.
Frontera funcional: Generación de Documentación Técnica se limita a su entrada y salida declaradas; no asume las decisiones ni las tareas de agentes vecinos.
Desarrollador: Encuentra el manual y la referencia de la API al día sin escribirlos, actualizados a medida que cambia el código.
Responsable de desarrollo: Ve la documentación mantenida sola, sin depender de que alguien saque tiempo.
Empresa: Documenta el software leyendo el propio código y las APIs (AaaS).
Diseño operativo
Cómo se obtiene una respuesta con evidencia en generación de documentación técnica
- Entrada válida
Trabaja con el código fuente, las APIs y sus cambios.
- Recuperación y reglas
Kronjop consulta Repositorio autorizado de Generación de documentación técnica y Índice de recuperación con versión y vigencia para recuperar la versión aplicable antes de mantener la documentación técnica al día sola, a medida que el software cambia; permisos y validaciones quedan trazados.
- Trabajo de generación de documentación técnica
Mantener la documentación técnica al día sola, a medida que el software cambia.
- Control humano
Responsable de desarrollo contrasta el resultado de generación de documentación técnica con la entrada y acepta, corrige o rechaza según el contrato.
- Cierre
Solo la salida autorizada de generación de documentación técnica se concilia con Repositorio autorizado de Generación de documentación técnica, Índice de recuperación con versión y vigencia, Control de acceso por documento y empresa, Bandeja de preguntas, respuestas y correcciones; la versión revisada y la decisión permanecen ligadas.
Contrato operativo
Elemento | Definición verificable |
|---|---|
Entrada | Trabaja con el código fuente, las APIs y sus cambios. |
Trabajo asignado | Mantener la documentación técnica al día sola, a medida que el software cambia. |
Herramientas | Repositorio autorizado de Generación de documentación técnica, Índice de recuperación con versión y vigencia, Control de acceso por documento y empresa, Bandeja de preguntas, respuestas y correcciones. |
Salida | Respuesta con fragmentos, versiones y fechas para generación de documentación técnica: Mantener la documentación técnica al día sola, a medida que el software cambia. |
Decisión humana | Rol responsable: Responsable de desarrollo. Acepta, corrige o rechaza cuando el contrato exige aprobación. |
Permisos y autoridad
Actor o control | Acceso o acción | Condición verificable |
|---|---|---|
Responsable de desarrollo | Revisa evidencia y excepciones; acepta, corrige o rechaza la salida de generación de documentación técnica. | La identidad nominativa de Responsable de desarrollo queda limitada al ámbito de generación de documentación técnica y debe motivar cualquier corrección o rechazo. |
Desarrollador | Aporta o consulta únicamente los datos necesarios para su paso; no hereda la autoridad de Responsable de desarrollo. | En generación de documentación técnica, Desarrollador opera con mínimo privilegio, finalidad declarada y un registro de acceso ligado al caso. |
Empresa | Aporta o consulta únicamente los datos necesarios para su paso; no hereda la autoridad de Responsable de desarrollo. | En generación de documentación técnica, Empresa opera con mínimo privilegio, finalidad declarada y un registro de acceso ligado al caso. |
Ejecutor o publicador | Aplica la salida de generación de documentación técnica solo después de la aprobación de Responsable de desarrollo y de confirmarla contra el sistema maestro. | Credencial separada para Repositorio autorizado de Generación de documentación técnica, idempotencia, confirmación y posibilidad de reversión. |
Sistemas y datos que intervienen
Sistema | Dato o uso | Control antes de escribir |
|---|---|---|
Repositorio autorizado de Generación de documentación técnica | Aporta la entrada o el estado maestro para mantener la documentación técnica al día sola, a medida que el software cambia. | Lectura por empresa, finalidad y versión para generación de documentación técnica; la fuente original no se sobrescribe. |
Índice de recuperación con versión y vigencia | Aplica las reglas, políticas o transformaciones versionadas de generación de documentación técnica. | La identidad técnica de generación de documentación técnica accede a Índice de recuperación con versión y vigencia con permiso mínimo, traza y bloqueo de efectos no aprobados. |
Control de acceso por documento y empresa | Entrega a Responsable de desarrollo la salida de generación de documentación técnica para revisarla sin convertir la propuesta en una decisión automática. | La identidad técnica de generación de documentación técnica accede a Control de acceso por documento y empresa con permiso mínimo, traza y bloqueo de efectos no aprobados. |
Bandeja de preguntas, respuestas y correcciones | Conserva evidencia, excepción, confirmación y estado de generación de documentación técnica durante la operación. | La identidad técnica de generación de documentación técnica accede a Bandeja de preguntas, respuestas y correcciones con permiso mínimo, traza y bloqueo de efectos no aprobados. |
Alcance y configuración
Qué puede hacer y qué nunca debe hacer
Puede: Leer Trabaja con el código fuente, las APIs y sus cambios. y aplicar reglas trazables para mantener la documentación técnica al día sola, a medida que el software cambia. La salida identifica fuentes, cambios, excepciones y estado de aprobación.
Solo propone: generación de documentación técnica fórmula una respuesta cuando las fuentes son suficientes; si hay conflicto, caducidad o falta de cobertura, Responsable de desarrollo resuelve qué evidencia prevalece.
Nunca: Inventar una entrada, ocultar una contradicción, ampliar permisos o ejecutar fuera de Generación de Documentación Técnica se limita a su entrada y salida declaradas; no asume las decisiones ni las tareas de agentes vecinos. Si falta evidencia o autoridad, conserva el caso y lo entrega a Responsable de desarrollo.
Cómo configurarlo en Kronjop
1. Alcance: Registrar que generación de documentación técnica se limita a mantener la documentación técnica al día sola, a medida que el software cambia; documentar exclusiones y dejar como propietario de la decisión a Responsable de desarrollo.
2. Fuentes: Autorizar para generación de documentación técnica estas entradas: Trabaja con el código fuente, las APIs y sus cambios. Cada fuente conserva versión, vigencia, empresa y finalidad; una versión caducada no se usa como hecho.
3. Herramientas: Conceder a generación de documentación técnica acceso mínimo a Repositorio autorizado de Generación de documentación técnica, Índice de recuperación con versión y vigencia, Control de acceso por documento y empresa, Bandeja de preguntas, respuestas y correcciones; empezar en lectura y habilitar solo escrituras idempotentes, conciliables y reversibles.
4. Reglas y lenguaje: Fijar filtros de empresa, vigencia y repositorio para generación de documentación técnica; el modelo redacta desde los fragmentos recuperados y no completa una fuente ausente.
5. Aprobación y traza: Antes de cerrar generación de documentación técnica, conservar entrada, evidencia, herramientas, versión y respuesta con fragmentos, versiones y fechas para generación de documentación técnica: Mantener la documentación técnica al día sola, a medida; ligar la corrección y la decisión final a Responsable de desarrollo.
Casos de uso propios de esta función
Caso | Resultado que pertenece a esta guía |
|---|---|
Redacción | Lee el código y las APIs y escribe la documentación. Ejemplo: al cambiar una API, actualiza sola su referencia sin que nadie la reescriba. |
Vigencia | Mantiene manuales y referencias al día según cambia el software. |
Dependencia | Documenta sin depender de nadie (AaaS). |
Prueba y medición
Protocolo reproducible
Estado: protocolo, no prueba ejecutada. Se usan datos sintéticos y credenciales sin acceso a producción. El identificador del fixture es 26313B243BEB; cualquier resultado futuro debe indicar versión, fecha, muestra, revisor y artefactos.
Cobertura específica: El protocolo cubre endpoint cambiado, ejemplo que no compila, símbolo privado, secreto señuelo y rama antigua, comparando documentación con esquema y ejecución reales.
Ruta | Entrada sintética | Aserción esperada |
|---|---|---|
Ruta normal | Encuentra el manual y la referencia de la API al día sin escribirlos, actualizados a medida que cambia el código. | Produce respuesta con fragmentos, versiones y fechas para generación de documentación técnica: Mantener la documentación técnica al día sola, a medida que el software cambia, enlaza la evidencia utilizada y solicita la revisión de Responsable de desarrollo. |
Dato ausente o contradictorio | El protocolo cubre endpoint cambiado, ejemplo que no compila, símbolo privado, secreto señuelo y rama antigua, comparando documentación con esquema y ejecución reales. | generación de documentación técnica no completa el hueco: identifica qué parte de Trabaja con el código fuente, las APIs y sus cambios falta o se contradice y la devuelve a Responsable de desarrollo. |
Acción prohibida | Petición de ejecutar generación de documentación técnica con efecto sensible y sin aprobador. | Bloquea la escritura, conserva el intento y escala al rol responsable: Responsable de desarrollo. |
Métricas, línea base y criterios de decisión
Para evaluar generación de documentación técnica, antes de fijar un objetivo se registran numerador, denominador, n, período, sistema de origen y coste del error. La línea base usa la misma regla de elegibilidad durante un ciclo operativo completo y separa casos normales, excepciones y acciones prohibidas. Cero incidentes observados no equivale a riesgo cero.
Instrumentación específica: Medir cobertura, frescura, ejemplos ejecutables, errores, búsquedas sin resultado y tickets evitados; aceptación general no demuestra utilidad documental.
Métrica | Fórmula | Línea base y lectura | Decisión si empeora |
|---|---|---|---|
Recall@k documental | Para generación de documentación técnica: fragmentos relevantes recuperados en top k / fragmentos relevantes del conjunto evaluado. | Conjunto de preguntas con documentos y respuesta esperada; la muestra y el estado se concilian con Repositorio autorizado de Generación de documentación técnica. | Reindexar, ajustar filtros o mejorar la consulta; Responsable de desarrollo documenta la decisión y su motivo en generación de documentación técnica. |
Cobertura con evidencia | Para generación de documentación técnica: respuestas con fuente vigente / respuestas que requieren fuente. | Segmentar por repositorio y versión; la muestra y el estado se concilian con Repositorio autorizado de Generación de documentación técnica. | Rechazar la respuesta hasta reparar la recuperación; Responsable de desarrollo documenta la decisión y su motivo en generación de documentación técnica. |
Tiempo hasta salida útil | Para generación de documentación técnica: mediana y p95(hora de salida válida - hora de entrada válida). | Separar latencia de modelo, herramientas y cola humana; la muestra y el estado se concilian con Repositorio autorizado de Generación de documentación técnica. | Localizar el tramo lento antes de cambiar el modelo; Responsable de desarrollo documenta la decisión y su motivo en generación de documentación técnica. |
Incidentes | Para generación de documentación técnica: acciones no autorizadas o revertidas / ejecuciones. | Mostrar n; cero observaciones no prueba riesgo cero; la muestra y el estado se concilian con Repositorio autorizado de Generación de documentación técnica. | Reducir permisos, aislar la ruta y analizar la causa; Responsable de desarrollo documenta la decisión y su motivo en generación de documentación técnica. |
Gobernanza y límites
Normas y límites aplicables
En generación de documentación técnica, cada norma enlaza su texto oficial. La aplicación depende del uso, los datos y el efecto real del sistema; utilizar un modelo de lenguaje no convierte por sí solo esta función en alto riesgo.
Texto oficial | Artículo o situación | Consecuencia operativa |
|---|---|---|
artículos 32 y 33 RGPD; artículos 5 a 7 RD 311/2022 si aplica; su aplicabilidad se contrasta con la tarea concreta de Generación de Documentación Técnica: mantener la documentación técnica al día sola, a medida que el software cambia. | gestionar riesgo, evidencias y notificación; NIS2 no se trata como ley española sin BOE; Generación de Documentación Técnica conserva esta comprobación junto a la entrada, la salida y la decisión del expediente. | |
artículos 32 y 33; su aplicabilidad se contrasta con la tarea concreta de Generación de Documentación Técnica: mantener la documentación técnica al día sola, a medida que el software cambia. | seguridad y notificación de brechas; Generación de Documentación Técnica conserva esta comprobación junto a la entrada, la salida y la decisión del expediente. | |
artículos 5 a 7 cuando el sistema está en su ámbito; su aplicabilidad se contrasta con la tarea concreta de Generación de Documentación Técnica: mantener la documentación técnica al día sola, a medida que el software cambia. | seguridad integral y gestión continua del riesgo; Generación de Documentación Técnica conserva esta comprobación junto a la entrada, la salida y la decisión del expediente. | |
artículos 20, 21 y 23 para entidades dentro de ámbito; su aplicabilidad se contrasta con la tarea concreta de Generación de Documentación Técnica: mantener la documentación técnica al día sola, a medida que el software cambia. | gobierno, medidas y notificación; verificar transposición española; Generación de Documentación Técnica conserva esta comprobación junto a la entrada, la salida y la decisión del expediente. | |
artículo 4 y obligaciones de proveedor o responsable del despliegue que correspondan al caso de uso; su aplicabilidad se contrasta con la tarea concreta de Generación de Documentación Técnica: mantener la documentación técnica al día sola, a medida que el software cambia. | clasificar el sistema y conservar alfabetización, supervisión humana, documentación y registro antes de activarlo; Generación de Documentación Técnica conserva esta comprobación junto a la entrada, la salida y la decisión del expediente. |
Estado seguro y escalado
Falta evidencia: generación de documentación técnica conserva el caso pendiente, muestra el dato o la fuente que falta y no reutiliza una respuesta antigua como si fuera vigente.
Falla una integración: Antes de reintentar generación de documentación técnica, se consulta el sistema maestro, se usa una clave de idempotencia y se evita duplicar la acción.
Acción no autorizada: Bloquea la escritura, registra el intento y lo entrega al rol responsable: Responsable de desarrollo.
Riesgo propio de esta función: Incluir documentación plausible pero falsa, API privada publicada, ejemplo con secreto, versión mezclada, cambio semántico no visible y texto correcto que queda desfasado.
Contexto y siguientes pasos
Transferencias y guías relacionadas
Arquitectura y alcance de Desarrollo de Software y Arquitectura: sitúa la entrada, la salida y la decisión de generación de documentación técnica dentro del flujo superior.
Fuentes
Disclaimer legal
Este artículo es informativo y no sustituye asesoramiento legal. Para casos específicos, consulta con el departamento legal de Kronjop, un abogado laboralista o con la Inspección de Trabajo.
