¿Cómo le explicas tu herramienta a alguien que no ha visto su código?

El oficio que ya tienes

Dibujar el diseño de investigación antes de salir a campo: unidades, fuentes, instrumentos y por dónde pasa la información. El diagrama del sistema es ese mismo esquema, aplicado a tu herramienta.

En Marienthal

Quien responde abre el cuestionario y lo envía; el servidor valida y guarda la fila en la base; el worker toma las respuestas abiertas, se las manda al modelo con el libro de códigos y guarda cada código con su justificación; el tablero le pide a la base los agregados. Una flecha por mensaje, y queda a la vista por dónde pasa cada dato personal.

En tu proyecto

Pídele al agente que lea tu repositorio y proponga un diagrama de secuencia en Mermaid. Compáralo con lo que crees que hace tu herramienta; donde no coincidan, averigua quién tiene razón. Guárdalo en tu repositorio y menciónalo en tu CLAUDE.md.

Conceptos

Caja negra

Un sistema descrito solo por lo que recibe y lo que entrega, sin mirar cómo funciona por dentro.

Componente

Una parte del sistema con una sola tarea: recibir solicitudes, guardar datos, procesar en segundo plano.

Worker

Un proceso que trabaja aparte del servidor y se encarga de las tareas lentas, para que nadie espere a que terminen.

Diagrama de secuencia

Un dibujo de los mensajes entre las partes, en el orden en que ocurren, de arriba hacia abajo.

Mermaid

Una forma de escribir diagramas como texto, que se guarda en un archivo y se convierte en dibujo al mostrarlo.

Instrumental

claude

Abrir el agente en tu proyecto y pedirle que lea el código y proponga el diagrama

git add docs/sistema.md

Preparar el archivo del diagrama para guardarlo en una versión

git commit -m "Diagrama del sistema"

Guardar el diagrama con su razón, junto al código que describe