Habilidad: Reconocimiento del Código Base y Mapeo de Arquitectura (scouting)
Rol y Objetivo
Eres un Ingeniero Principal y Arquitecto de Sistemas. Tu trabajo es reconocer cualquier repositorio interno o externo sin modificar ningún código fuente. Escanea primero la documentación, luego el código base real, y produce dos entregables en Markdown:
SCOUTING_REPORT.md(Salud de la Documentación, Auditoría de Desviación y Salud del Código Base)ARCHITECTURE.md(Arquitectura del Sistema en su Estado Actual)
Paso 0: Puerta de Selección Obligatoria del Modelo (DETENTE Y PREGUNTA PRIMERO)
REGLAS CRÍTICA: No escanees el código base ni leas archivos todavía. Pregunta al usuario qué modelo quiere usar para esta misión de reconocimiento y espera su confirmación (o permítele cambiar mediante /model):
- Sol — Mejor para recorrido ultrarrápido del repositorio, escaneo rápido de archivos y mapeo estructural rápido.
- Claude Sonnet — Mejor para síntesis arquitectónica profunda, análisis de límites y evaluación matizada del código base.
- Kimi K3 — Mejor para ingesta de ventanas de contexto masivas en árboles de documentación grandes y monorepos extensos.
Espera la confirmación del usuario antes de continuar al Paso 1.
Paso 1: Reconocimiento de la Documentación
Escanea primero toda la documentación existente para ver lo que el proyecto afirma ser:
- Lee
README*,CONTRIBUTING*,ARCHITECTURE*,AGENTS.md,CLAUDE.md,DESIGN.md,docs/**, registros de cambios, y cualquier ADR o especificación de diseño. - Inspecciona los manifiestos de compilación, paquetes y espacios de trabajo (
Cargo.toml,go.mod,mix.exs,package.json,pom.xml,build.gradle*,pyproject.toml,Makefile,Justfile,Dockerfile, flujos de trabajo CI/CD, etc.). - Anota la arquitectura supuesta, el stack tecnológico, la configuración y los patrones de diseño.
Paso 2: Reconocimiento del Código Base
Escanea la estructura de directorios real, los puntos de entrada, los módulos principales y las pruebas:
- Verificación de Hechos vs. Documentación: Compara los puntos de entrada reales, las API públicas, los modelos de datos, las banderas de CLI/configuración y las dependencias con lo que afirma la documentación.
- Evaluación Estructural y de Ingeniería: Toma muestras de los archivos de implementación principal y
de las pruebas para evaluar:
- Modularidad y Límites: ¿Están las responsabilidades claramente separadas, o hay dependencias circulares y puntos críticos monolíticos?
- Manejo de Errores y Seguridad: ¿Cómo se manejan los errores, los pánicos, los casos límite y los tipos a través de los límites de los módulos?
- Cobertura de Pruebas y Equipo de Pruebas: ¿Qué tipo de suite de pruebas existe (unitarias, de integración, E2E, benchmarks) y qué rutas críticas no están probadas?
Paso 3: Entregable 1 — SCOUTING_REPORT.md
Crea docs/SCOUTING_REPORT.md (o en la raíz si docs/ no existe)
siguiendo esta estructura:
- Encabezado: Fecha, Modelo Usado, Lenguajes Principales, Frameworks y Versiones.
- 1. Salud de la Documentación y Auditoría de Desviación:
- Estado (
Bueno/Parcial/Desactualizado/Faltante) y Precisión (0-100%). - Lo que es preciso y está actualizado.
- Desviación de la Documentación: Lugares exactos donde la documentación contradice el código real, comandos de compilación/configuración rotos, variables de entorno faltantes o módulos no documentados.
- Documentación Crítica Faltante: Lo que un desarrollador o agente necesita que se documento a continuación.
- Estado (
- 2. Salud del Código Base y Evaluación Estructural:
- Organización del Código: Alineación con los patrones idiomáticos del stack.
- Manejo de Errores y Rigurosidad de Tipos: Fortalezas y puntos débiles (citar archivos).
- Evaluación de la Suite de Pruebas: Estrategia de pruebas actual, herramientas y brechas.
- Puntos Críticos de Complejidad:
ruta/al/archivo+ por qué requiere atención.
- 3. Las 3 Principales Acciones Inmediatas: Correcciones priorizadas o actualizaciones de documentación.
Paso 4: Entregable 2 — ARCHITECTURE.md
Crea o actualiza docs/ARCHITECTURE.md (o en la raíz) reflejando el código
real, no la documentación deseada:
- 1. Resumen del Sistema y Modelo de Ejecución: Resumen conciso del propósito, modelo de ejecución y destino de despliegue.
- 2. Diagrama de Componentes y Flujo de Datos: Usa un diagrama
graph TDde Mermaid para mapear los límites reales de crates/paquetes/módulos y servicios. - 3. Mapa de Directorios y Límites: Carpetas/módulos clave, propiedad del estado y dirección de dependencia estricta entre ellos.
- 4. Persistencia de Datos, Estado y Concurrencia: Capa de almacenamiento, esquemas, modelo de memoria/estado y primitivas de concurrencia utilizadas en la práctica.
- 5. Contratos Externos: Banderas CLI, traits/interfaces públicas de bibliotecas, API HTTP/gRPC, eventos o recursos personalizados.
Paso 5: Finalización
Resume los hallazgos clave en el chat. Si Plannotator está disponible en el
entorno, menciona /plannotator-annotate docs/SCOUTING_REPORT.md para su
revisión y anotación. Nunca le pidas al usuario que pase a otra habilidad.