Skill: codebase-orient
Propósito
Orientar a Claude sobre el estado actual de este repositorio antes de realizar trabajos no triviales. Crea o reconcilia un paquete fijo de cuatro artefactos con trazabilidad en docs/ai/. El código fuente y la configuración del proyecto siguen siendo la autoridad.
Cuándo usar esta skill
Usar esta skill cuando
- Se ingresa a un repositorio nuevo o desconocido
- Se inicia una sesión nueva después de un tiempo significativo fuera del repositorio
- Antes de trabajos de implementación amplios o de múltiples archivos
- Antes de refactorizaciones, limpiezas, planificación de arquitectura o traspaso de agente
- Después de cambios estructurales: rutas, esquemas, autenticación, despliegue, configuración o superficies de administración
- Cuando
docs/ai/falta, está desactualizado, incompleto o internamente inconsistente - Cuando la estructura del repositorio, las superficies de cambio, los destinos de despliegue, el comportamiento de autenticación, las rutas de administración, los comandos o la estructura de pruebas no están claros
- Cuando el agente gastaría un contexto significativo redescubriendo lo que ya está en o cerca de
docs/ai/ - Cada vez que el usuario dice "escanear", "orientar", "comprender", "mapear", "revisar", "auditar", "relevar", "familiarizar" o "antes de empezar"
Omitir esta skill cuando
- Se realiza una edición pequeña, local y conocida en un solo archivo
- Se corrige un error de un solo archivo donde el archivo relevante y el cambio ya están claros
- Se realizan cambios solo de copia o de cadenas de texto
- La tarea está estrictamente limitada a archivos ya verificados en el contexto actual
docs/ai/se acaba de actualizar y la tarea es lo suficientemente limitada como para no necesitar un pase completo de orientación
Guía de uso consciente de tokens
docs/ai/ es un caché de orientación. Un caché nuevo reduce el costo de tokens de redescubrimiento del repositorio en múltiples sesiones y traspasos de agente.
- Si
docs/ai/está nuevo y completo: léelo como contexto y continúa. Omite volver a ejecutar la orientación. - Si
docs/ai/puede estar desactualizado o falta: ejecuta la skill para actualizar el caché. El costo inicial de tokens se amortiza en el trabajo futuro. - Si la tarea es pequeña y el archivo objetivo ya es conocido: omite la orientación. Usa lecturas dirigidas.
- Si el agente gastaría muchos tokens redescubriendo lo que
docs/ai/ya captura: actualiza el caché.
No ahorres tokens omitiendo la orientación y luego adivinando la estructura. Si el descubrimiento amplio del repositorio se repetiría o sería costoso, mejor actualiza el caché.
Reglas estrictas durante la orientación
- No modifiques el código de la aplicación o fuente.
- No refactorices.
- No hagas commits.
- Verifica las afirmaciones contra el código fuente antes de escribirlas.
- Marca cada afirmación significativa con una etiqueta de confianza.
Modo normal vs modo simulación
Modo normal (predeterminado - usa cuando el usuario no especifique):
- Resuelve automáticamente pequeñas incertidumbres relevantes para la tarea leyendo archivos fuente
- Crea un paquete completo en el primer uso en un repositorio limpio
- Reutiliza un paquete limpio exacto actual sin reescribirlo
- Trata una solicitud no específica de actualizar o reconciliar como una reconciliación completa
- Informa qué cambió al final
Modo simulación / solo informe (usa cuando el usuario diga "simulación", "solo informe", "no escribir", "proponer cambios primero", "solo auditoría", "sin escrituras" o similar):
- Inspecciona y recopila cambios propuestos
- Informa las ediciones propuestas a
docs/ai/sin escribirlas - Espera la aprobación explícita antes de escribir
Si no se especifica el modo, se usa el modo normal por defecto.
Ciclo de vida y seguridad de escritura
- Actualización explícita: Actualiza o reconcilia solo cuando el usuario lo solicite explícitamente después de encontrar un paquete exacto actual.
- Actualización con ámbito: Sigue un ámbito explícito del usuario y sus dependencias directas. Registra la cobertura con ámbito sin avanzar ni reclamar una instantánea completa del paquete. No crees un paquete compatible parcial antes de que exista un paquete completo.
- Adopción heredada: Los artefactos Markdown sin
ORIENTATION_STATE.jsonson material heredado. Inspecciónalos, pero obtén aprobación explícita antes de escribir un manifiesto o cambiarlos. Reconcílialos desde la fuente después de la aprobación. - Árbol sucio: Antes de escribir un estado que represente trabajo no commiteado, pregunta si escribir una instantánea sucia o solo informe. Registra la condición del árbol; mantenlo marcado como sucio hasta que una actualización limpia lo reemplace.
- Sin historial de Git utilizable: Realiza una reconciliación completa y registra que la comparación de revisiones no está disponible.
- Ediciones manuales: Orient es dueño del paquete. No prometas comportamiento de fusión o preservación para el estado de Orient editado manualmente.
Etiquetas de confianza
- Hecho: verificado directamente en código o documentación
- Inferencia fuerte: respaldado por múltiples archivos
- Inferencia débil: plausible pero no confirmado
- Desconocido: necesita más inspección antes de editar
Distinguir cómo se estableció una afirmación:
- verificado independientemente desde fuente/config: afirmación verificada contra la fuente real o archivo de configuración, no tomada de la documentación
- heredado de documentación existente: afirmación tomada de CLAUDE.md, README u otra documentación sin verificación independiente
- heredado y luego verificado: afirmación originada en documentación y posteriormente confirmada contra la fuente
- existencia de ruta confirmada: archivo encontrado pero no leído
- lectura parcial: parte del archivo inspeccionada; puede no capturar el contexto completo
- lectura completa de la fuente: contenido completo del archivo inspeccionado
- inferido de la implementación: deducido de cómo se comporta el código, no declarado explícitamente
- inferido de comentarios/pruebas/fixtures: obtenido de un contexto no autoritativo; tratar como Inferencia fuerte como máximo
- comportamiento verificado por prueba: confirmado por la ejecución exitosa de una prueba
- desconocido: base no establecida; no presentar como Hecho
En informes finales y documentos de orientación, etiqueta cada afirmación no trivial con uno de los orígenes anteriores para que los lectores puedan juzgar qué afirmaciones necesitan ser verificadas nuevamente antes de actuar sobre ellas.
Orden de descubrimiento
Nota de personalización: El orden de descubrimiento a continuación es intencionadamente amplio y funciona en la mayoría de las formas de proyecto sin editar. Puedes ajustar las rutas de archivo y el orden para un proyecto específico, pero esto es opcional, no requerido antes del primer uso.
Ejecutar en este orden:
- Archivos de instrucciones del proyecto como
CLAUDE.md,AGENTS.mdyREADME.md, si están presentes: propósito del producto, reglas del agente, convenciones del proyecto. Regla de documentos como hipótesis- Trata estos documentos como hipótesis útiles, no como verdad autoritaria.
- Extrae afirmaciones fácticas de alto impacto sobre arquitectura, rutas, despliegue, pruebas y archivos fuente de verdad.
- Verifica esas afirmaciones contra el código fuente antes de confiar en ellas. Concéntrate en afirmaciones que afectarían ediciones futuras; no audites cada oración.
- No copies afirmaciones de estos documentos en
CODEBASE_MAP.mdsin etiquetar si están verificadas independientemente desde fuente/config o heredadas de documentación existente. - Si un documento de instrucciones está desactualizado o engañoso en comparación con lo que muestra la fuente, registra la deriva en
OPEN_QUESTIONS.mdbajo la regla de informes de riesgos ocultos y etiquétalo como deriva de documentación. - Mapea la topología de la capa de instrucciones: nota qué archivos de instrucciones están presentes (por ejemplo,
CLAUDE.md,AGENTS.md,.claude/settings.json) y en qué ámbito (proyecto-local vs nivel de usuario). Registra esto enCODEBASE_MAP.md; ayuda a futuros agentes a saber qué reglas se aplican.
- Manifiesto del proyecto (por ejemplo,
package.json,pyproject.toml,Cargo.toml): dependencias, scripts, comandos de construcción/prueba - Archivos de construcción y configuración (por ejemplo, configuración del framework, configuración del bundler): adaptador, configuración de construcción
- Directorio
scripts/, si está presente: puede contener herramientas ejecutadas manualmente no representadas en los scripts del paquete o CI - Puntos de entrada y capa de enrutamiento: todas las páginas, controladores o rutas de API
- Lógica de negocio central: tipos de dominio, modelos, puntuación, lógica de informes
- Servicios del lado del servidor: autenticación, base de datos/esquema, correo electrónico, integraciones externas
- Capa de UI/presentación: componentes, vistas, plantillas
- Archivos de internacionalización o copia: archivos de configuración regional
- Ciclo de vida de solicitudes / middleware: ganchos, interceptores, middleware
- Capa de base de datos: migraciones, instantáneas de esquemas
- Pruebas: estructura de pruebas y forma de cobertura
- Documentación: documentación existente, matrices de verificación. Si se encuentra un plan de lanzamiento, documento de seguimiento de hitos o registro de cambios de versión, agrega una sección
## Estado de la versiónenCODEBASE_MAP.mdque resuma la versión actual, el hito activo y qué está bloqueando el próximo lanzamiento. Omite esta sección si no hay un artefacto del ciclo de vida de lanzamiento. - Incertidumbre conocida
Sondas específicas del framework
Aplica estas sondas además del orden de descubrimiento genérico cuando se detecte el framework relevante.
La skill reutilizable actualmente incluye un conjunto de sondas ajustadas explícitamente para SvelteKit. Otros frameworks usan actualmente el orden de descubrimiento genérico a menos que la evidencia posterior de uso en vivo o evaluación justifique una sección de sonda ajustada dedicada.
SvelteKit
Busca con glob los siguientes patrones de archivo cuando se detecte un proyecto SvelteKit:
src/routes/**/+page.svelte: páginas de ruta de la UI; cada archivo es un candidato de ruta; verifica subdirectorios, no solo elsrc/routes/+page.sveltede nivel superiorsrc/routes/**/+page.server.ts: carga de datos del lado del servidor, acciones de formulario y control de acceso a nivel de rutasrc/routes/**/+layout.svelte: shells de diseño compartidossrc/routes/**/+layout.server.ts: funciones de carga del lado del servidor para autenticación, sesión o datos a nivel de diseñosrc/routes/**/+server.ts: endpoints de API y manejadores de solicitudes solo del servidor
Los archivos de ruta del lado del servidor (+page.server.ts, +layout.server.ts, +server.ts) son críticos para comprender autenticación, carga de datos, acciones de formulario, endpoints de API y control de acceso a nivel de ruta. No los saltes al mapear rutas o superficies de cambio.
- La plantilla estándar del shell de la aplicación es
src/app.html. - La elección del adaptador en
svelte.config.jsdetermina el destino de despliegue: confirma antes de hacer afirmaciones relacionadas con el despliegue.
Regla de precisión de CI/despliegue
Al leer archivos de flujo de trabajo de CI o despliegue, conserva los detalles operativamente relevantes. No redondees detalles específicos en resúmenes vagos.
Captura e informa:
- nombre del grupo de concurrencia (qué ejecuciones compiten entre sí)
- comportamiento de
cancel-in-progress: si estrue, di "las ejecuciones más nuevas cancelan las ejecuciones en curso del mismo grupo", no solo "previene despliegues paralelos" - comportamiento de
fail-fast - rutas de artefactos de despliegue
- formato de nomenclatura de lanzamiento, incluidos cualquier componente de marca de tiempo o hash
- política de retención y poda para lanzamientos o artefactos antiguos
- condiciones de activación manual vs automática
- secretos y variables de entorno requeridos
- si el despliegue sobrescribe en el lugar, se organiza en una ruta temporal, usa enlaces simbólicos o usa directorios de lanzamiento versionados
Etiqueta las afirmaciones de CI/despliegue con verificado independientemente desde fuente/config cuando se lean directamente del archivo de flujo de trabajo. No resumas estos detalles de maneras que pierdan precisión que un operador necesitaría durante un incidente.
Heurística de profundidad de lectura
No leas todos los archivos CSS, de configuración o generados grandes por defecto.
- Lectura completa: archivos que afectan directamente la tarea solicitada (puntos de entrada, enrutamiento, autenticación, esquema, configuración de construcción, el archivo a editar).
- Lectura parcial o solo confirmación de ruta: superficies secundarias como grandes hojas de estilo, código de proveedor, salida generada o archivos de configuración no relevantes para la tarea. Si solo confirmas la ruta de un archivo o lees una parte, dilo explícitamente en el informe usando las etiquetas existencia de ruta confirmada o lecturas parciales definidas en Etiquetas de confianza.
- Omitir: archivos claramente fuera del alcance (por ejemplo, activos binarios, archivos de bloqueo, instantáneas de prueba) a menos que una pregunta específica los haga relevantes.
En caso de duda, prefiere confirmar la existencia primero y leer completamente solo si una afirmación lo requiere.
Existencia de ruta vs lectura de contenido
La existencia de ruta por sí sola es suficiente para afirmaciones de inventario de bajo riesgo (confirmar una estructura de directorios, enumerar recuentos de archivos o notar que un archivo de configuración está presente).
Lee el contenido real del archivo cuando la afirmación afecte comportamiento, arquitectura, riesgo, comandos, despliegue, autenticación, enrutamiento o superficies de cambio. No etiquetes una afirmación como verificada independientemente desde fuente/config basada solo en la existencia de ruta cuando el archivo es barato de inspeccionar y su contenido afectaría materialmente el mapa.
Regla de lectura de archivos pequeños de fuente de verdad
Si un archivo pequeño parece definir vocabulario o tokens de fuente de verdad utilizados en todo el proyecto, lee suficiente de él para verificar el vocabulario en lugar de heredar el vocabulario de la documentación.
Ejemplos donde esto se aplica:
- archivos de tokens de propiedades personalizadas CSS
- archivos de configuración de rutas o menús
- archivos pequeños de esquemas o constantes
- registros de comandos o plugins
Usa una lectura parcial cuando sea suficiente. Etiqueta las afirmaciones resultantes con el origen de afirmación apropiado (lectura parcial, lectura completa de la fuente). No las etiquetes como verificadas independientemente desde fuente/config si no leíste realmente el archivo.
Regla de glob barato de artefactos
Antes de dejar una pregunta abierta sobre la existencia o alcance de activos estáticos, scripts, salidas generadas, documentación, pruebas, migraciones o archivos de configuración, resuélvela con un glob barato de rutas.
Patrones de glob comunes a probar:
static/**/*public/**/*scripts/**/*tests/**/*otest/**/*ospec/**/*.github/workflows/*docs/**/*migrations/**/*dist/**/*obuild/**/*
No leas profundamente todos los archivos coincidentes por defecto. Usa el glob para resolver preguntas de existencia y alcance de manera barata. Realiza lecturas dirigidas solo cuando se necesite el contenido de un archivo específico.
Cuatro artefactos producidos
El paquete de orientación contiene cuatro archivos:
1. CODEBASE_MAP.md — Mapa del código base
Propósito: ser el mapa de descubrimiento de estructura, superficies y convenciones. Sustituye al descubrimiento repetitivo del repositorio.
Debe incluir:
- Resumen del proyecto: propósito, función, audiencia objetivo
- Topología de la capa de instrucciones: archivos de instrucciones presentes con su ámbito; las diferencias de ámbito entre archivos importan
- Estructura del directorio: cómo se organizan los directorios de alto nivel y sus funciones
- Pila tecnológica: lenguaje, runtime, framework, ORM/DB, pruebas, CI, destino de despliegue
- Comandos de desarrollo: cómo ejecutar el servidor de desarrollo local, el conjunto de pruebas, el linter, el formateador
- Rutas y puntos de entrada: lista de rutas de página (método, ruta, visibilidad/autenticación, archivo fuente). Las rutas API y las rutas de página residen en sus propias subsecciones con los mismos campos. Enumera las rutas en orden alfabético por ruta para que los agentes futuros puedan ubicar los archivos rápidamente.
- Comportamiento de autenticación: mecanismo de autenticación, middleware/sesiones, proveedores OAuth, manejo de protección de ruta
- Incluye rutas de administración y cualquier punto final de API
- Modelos de datos / tipos de dominio: modelos centrales con sus propiedades, relaciones y ubicaciones de definición
- Servicios/integraciones externas: dependencias de servicios (DB, caché, cola, email, observabilidad, SaaS, SMS/pago). Cada servicio externo incluye su propósito, alcance de autenticación consumido y si se crea un cliente por solicitud o se reutiliza un singleton.
- Superficies de cambio del depósito de migraciones de esquemas: una sección que detalla
- Rutas de migración, incluyendo patrones de glob a nivel de proveedor que las CI u operadores pueden usar para pasar como argumentos, más un comando de aplicación real (por ejemplo,
alembic upgrade headonpx prisma migrate deploy) - Ubicación de instantáneas de esquemas (si las hay) y cuándo se actualizan (por ejemplo, antes de la migración, después de la migración, manualmente)
- Estrategia de rollback: declarativo (reversión a instantánea) o transaccional (migraciones hacia abajo). Si es transaccional, nota si la herramienta admite aplicación hacia abajo; si es declarativo, nota que las instantáneas se restauran en lugar de revertir migraciones.
- Rutas de migración, incluyendo patrones de glob a nivel de proveedor que las CI u operadores pueden usar para pasar como argumentos, más un comando de aplicación real (por ejemplo,
2. OPEN_QUESTIONS.md — Incertidumbres y riesgos
Propósito: rastrear incertidumbres, riesgos y déficits de información encontrados durante la orientación que deben resolverse antes de que el trabajo pueda proceder de manera segura.
Debe incluir incertidumbre sobre:
- el estado de
docs/ai/(desactualizado, falta, incompleto, internamente inconsistente) - mala salud de la capa de instrucciones (falta un CLAUDE.md, conflicto entre CLAUDE.md y código real)
- estado desactualizado de la documentación, brechas de cobertura de prueba
- configuraciones, flujos de trabajo o dependencias que eran difíciles de rastrear
- hallazgos en los que una afirmación no pudo ser verificada independientemente desde fuente/config
Regla de informes de riesgos ocultos
Registra conclusiones que indiquen riesgo material que una lectura casual del repositorio no revelaría. Ejemplos:
- Servicio externo sin fallback ni degradación elegante
- Lógica de autenticación que depende de un estado mutable compartido sin sincronización
- Punto final de API que omite la verificación de autorización
- Mecanismo de límite de tasa o protección contra abusos faltante en un endpoint expuesto públicamente
- Secreto o credencial encontrado en código fuente (reportar y preguntar cómo proceder; no lo muevas ni lo cures)
- Dependencia con CVE conocido o un mantenimiento deficiente, cuando la dependencia está cerca de la superficie de ataque
Si se encuentra cualquiera de estos o riesgos similares, agrégalos a OPEN_QUESTIONS.md bajo un encabezado ## Riesgos ocultos. Etiqueta cada uno con el filepath exacto y el fragmento de código que generó la preocupación, más "No verificado" o "Verificado desde fuente".
3. ORIENTATION_STATE.json — Estado de orientación
Un archivo JSON que rastrea la última orientación completa. Los campos exactos se determinan dinámicamente durante la ejecución de la skill, pero deben incluir:
last_run_at: marca de tiempo de la última ejecución de orientaciónbranch: nombre de la rama en el momento de la orientacióncommit: hash del commit en el momento de la orientacióngit_clean: booleano que indica si el árbol de trabajo estaba limpiogit_history_available: booleano que indica si la orientación pudo usar el historial de Gitcovered_areas: lista de áreas (puntos de entrada, enrutamiento, autenticación, esquema, pruebas, etc.) cubiertas por esta orientaciónscope: "full" o un ámbito personalizado especificado por el usuarioartifacts: rutas a los tres archivos producidostimestamp: marca de tiempo ISO 8601 de cuándo se escribió este archivo de estado
4. AGENT_HANDOFF.md (opcional) — Traspaso de agente
Propósito: proporcionar un resumen sucinto para que un agente entrante continúe el trabajo sin repetir la orientación de descubrimiento.
Crear solo cuando el usuario solicite un traspaso o cuando el agente saliente necesite documentar el estado para que un agente entrante lo retome. No crear en una orientación de rutina.
El archivo debe contener:
- Resumen de lo que se ha hecho: uno o dos párrafos que describan el trabajo completado durante la sesión saliente, referenciando archivos tocados, comandos ejecutados y decisiones tomadas.
- Siguiente trabajo previsto: descripción de la próxima tarea prevista, incluyendo archivos que probablemente necesiten ser cambiados y cualquier dependencia que el agente entrante deba conocer.
- Incertidumbres y riesgos sin resolver: incertidumbres y riesgos conocidos de la sesión saliente que el agente entrante necesita resolver o evitar. Si hay un archivo
OPEN_QUESTIONS.md, enlázalo y señala riesgos o incertidumbres particularmente urgentes. - Sesión (fecha y hora): marca de tiempo de cuándo se creó este traspaso.
- Estado de Git: rama actual, estado limpio/sucio y hash del commit actual al final de la sesión saliente.
Meta reglas
Regla de sobrescritura vs adición
Cuando esta skill contenga una regla que también exista en las instrucciones del proyecto, la nivelación sigue:
- Si el proyecto define una regla consistente con esta skill, úsalas juntas.
- Si el proyecto define una regla inconsistente, la regla del proyecto tiene prioridad (el proyecto tiene autoridad sobre la skill reutilizable).
- Si el proyecto no define la regla, usa la regla de esta skill tal como está.
- No agregues reglas a esta skill editando la skill. En su lugar, comunica al usuario que la regla debe definirse en las instrucciones de nivel de proyecto.
La skill no debe ser editada para personalización
Si encuentras una regla que no se ajusta al proyecto, díselo al usuario en lugar de editar esta skill. El usuario puede entonces elegir agregar una personalización a nivel de proyecto (por ejemplo, en CLAUDE.md o su archivo de configuración de agente) que sobrescriba o refine la regla reutilizable. Esto asegura que las actualizaciones de la skill no sobrescriban la personalización del proyecto.