Prefixer: ámbito primero, ensanchar si falla, registrar el delta
Un agente que busca en todo el repositorio paga por cada resultado irrelevante en tokens. Un mapa de espacios de nombres, una docena de líneas que dicen qué vive dónde, le permite buscar dentro del área correcta desde la primera llamada. Esta habilidad construye ese mapa, lo mantiene vivo y obliga al agente a realizar búsquedas con ámbito primero. Hace un trabajo: búsqueda de código más barata y mejor.
Límite de tamaño. Por debajo de aproximadamente cien archivos, o cuando la forma del repositorio es obvia de un vistazo, omita el mapa y limite las búsquedas por nombres de directorio; el mapa comienza a ser rentable a partir de ese punto.
Cómo trabajar
- Orientarse una vez. Verifique si existe
.prefixer/namespaces.md. Si no existe y la tarea requerirá más de dos búsquedas, mapee el segmento en el que está trabajando (§1 a §3), luego busque dentro de él. Si existe un mapa, léalo y comience con ámbito. - Buscar con ámbito, ensanchar si falla. La primera búsqueda va al espacio de nombres más restrictivo plausible, no a la raíz del repositorio (§4 a §6).
- Registrarlo. Termine la tarea con una línea en
.prefixer/metrics.jsonl, y un delta cuando exista una línea base (§7 a §8). Salida obligatoria, no opcional.
Dónde es rentable
- Primera sesión en un repositorio grande o desconocido. Lea doce líneas del mapa en lugar de escanear el árbol; la primera búsqueda ya está con ámbito.
- Monorepos. Un espacio de nombres por paquete: las búsquedas dejan de traer ruido de paquetes hermanos al contexto.
- Múltiples códigos base. Un mapa a nivel de organización selecciona el código base, el mapa del repositorio selecciona el espacio de nombres dentro de él. Dos niveles, nunca un escaneo de unión.
- Exploración repetida. "Dónde vive X", refactorizaciones, áreas de funcionalidad desconocidas; la tasa de acierto en el primer intento es donde el mapa paga su alquiler.
- Repositorios que visitará de nuevo. El mapa persiste entre sesiones; cada agente futuro comienza orientado en lugar de volver a escanear.
A. El mapa de espacios de nombres
1. Mapee el segmento, no el mundo
Regla: Cuando un repositorio no tiene .prefixer/namespaces.md y el trabajo necesita más de dos búsquedas, mapee la parte del repositorio que toca esta tarea: de tres a cinco espacios de nombres; no todo el árbol. Un mapa parcial que da ámbito a las búsquedas de hoy es mejor que un mapa completo que tomó una hora. Agréguelo cuando una búsqueda real caiga fuera de él, nunca en anticipación. Ejecute bash scripts/init_namespaces.sh (en el directorio de esta habilidad) para obtener un andamio, luego corrija sus suposiciones: nombre para qué sirve cada espacio de nombres.
Por qué: la adopción es incremental por diseño. El mapa es un archivo de trabajo, no un censo; se gana una fila cuando una búsqueda necesita esa fila.
Los borradores no son mapas. Cualquier fila cuyo prefijo o contains todavía diga TODO está incompleta; termínela o córtela antes de confiar en el mapa. El andamio informa cuántas filas de borrador quedan.
Documentos existentes primero. Si AGENTS.md, CLAUDE.md o el README ya describen el diseño, siembre contains a partir de ellos (el andamio hace esto) y trate namespaces.md como canónico para el ámbito de búsqueda; no mantenga dos tablas de contenido que se desvíen.
Inicio de sesión mejor que recordar. Leer el mapa una vez por sesión es el paso que más probablemente se omita. Si el arnés puede inyectar archivos al inicio de la sesión, haga que emita namespaces.md: cada búsqueda comienza entonces con ámbito sin necesidad de disciplina. Cableado incluido: scripts/install_hook.sh escribe el hook por usted (scripts/session_start.sh emite el mapa más un veredicto de salud); fragmentos escritos a mano viven en integrations/. Receta y fundamento: references/namespaces.md.
2. Manténgalo pequeño y respaldado por globs
Regla: de 5 a 12 espacios de nombres. Cada fila es un prefijo corto, un glob de ruta y un propósito de una línea escrito para desambiguación. Si dos filas coincidirían con la misma búsqueda con igual frecuencia, combínelas. Si una fila nunca da ámbito a una búsqueda real, córtela.
Formato:
# namespaces
repo: acme-payments
| prefijo | ámbito | contiene |
|---------|---------------------|-----------------------------|
| api: | src/api/** | Manejadores REST, rutas |
| auth: | src/auth/** | inicio de sesión, sesiones, tokens |
| sso: | src/auth/sso/** | Área del subequipo SSO |
| test: | tests/**, **/*.test.* | Suites, fixtures |
El encabezado repo: es el calificador único de este código base (del remoto git); hace que cada prefijo sea globalmente único cuando una organización ejecuta muchos códigos base: acme-payments:auth: nunca puede chocar con checkout-service:auth:.
Las filas se anidan: una fila con sangría pertenece al espacio de nombres de arriba, para subequipos dentro de un módulo o paquetes dentro de un servicio. La etiqueta se compone, auth:sso:, por lo que el mismo nombre bajo dos padres se mantiene distinto (orders:checkout: vs payments:checkout:).
Los nombres se derivan, no se declaran. Los prefijos y el texto de contains provienen del vocabulario propio del código base: nombres de directorios, los términos dominantes en los archivos que una fila abarca, nunca de categorías que usted invente. Los nombres derivados siguen el repositorio a medida que evoluciona; los inventados se desvían. El andamio hace esto por usted: corrija lo que hace mal, conserve lo que hizo bien.
Detalles del formato y mapas para otras formas de repositorio: references/namespaces.md.
3. Actualice, nunca regenere
Regla: Cuando el mapa esté desactualizado, edite las filas desactualizadas. No reescriba el archivo. La regeneración completa pierde el detalle acumulado que lo hizo útil. Pode filas muertas, agregue las que faltan, mantenga el resto byte-idéntico; un mapa reescrito también rompe el prefijo de caché de indicación de cada sesión que lo cargó. Después de la curación, ejecute bash scripts/check_namespaces.sh: una fila cuyos globs no resuelven nada es una mentira que el mapa le está diciendo a cada sesión futura. Cuando el mapa se sienta desactualizado o el registro haya crecido, ejecute bash scripts/suggest_map.sh: lee metrics.jsonl y el árbol y propone las filas que las búsquedas reales ya solicitaron.
Múltiples códigos base: el mismo truco se acumula. Un mapa a nivel de organización selecciona el código base (pay: services/payments/**), el mapa del repositorio selecciona el espacio de nombres dentro de él. El encabezado repo: de cada mapa mantiene los prefijos únicos entre códigos base; cuarenta servicios pueden tener todos un auth/ porque una etiqueta calificada payments:auth: nombra exactamente uno. Nunca unifique cada repositorio en una búsqueda que sea el fallo de grep raíz a escala organizativa. Consulte references/namespaces.md.
B. Ámbito de búsqueda
4. El más restrictivo primero
Regla: Cada búsqueda comienza en el espacio de nombres más restrictivo que podría contener la respuesta. grep "expire" src/auth/ es mejor que grep "expire" .. Un fallo cuesta una llamada; una búsqueda amplia cuesta toda la lista de resultados en tokens.
Deje que el script aplique la regla: bash scripts/search.sh auth "expire" resuelve la etiqueta a sus globs, busca dentro de ellos, ensancha un nivel en caso de fallo y registra la línea de métricas; los §4 a §8 se ejecutan solos. --scope <ns> imprime la lista de globs, --paths <ns> los archivos resueltos, --list cada etiqueta; el mapa como un índice que otros comandos pueden consultar.
Cuidado con: buscar en la raíz del repositorio "por si acaso", patrones glob como **/* sin restricción de ruta, find usado donde un glob de espacio de nombres sería suficiente.
5. Ensanchar un nivel en caso de fallo
Regla: ¿No encontró nada dentro de un espacio de nombres? Ensanche un nivel: espacio de nombres, luego su área padre, luego el repositorio, luego los directorios de proveedores y generados. No salte de un fallo directamente a un escaneo de todo el repositorio, y no busque en node_modules, vendor, dist, build o archivos de bloqueo a menos que la tarea trate sobre ellos.
6. Responder con etiquetas de espacio de nombres
Regla: Reporte los hallazgos como prefijo:ruta:línea (auth:src/auth/session.ts:42). La próxima búsqueda, la suya o la de una sesión futura, comenzará entonces ya con ámbito. Cuando un archivo resista todos los espacios de nombres, eso es señal de que el mapa tiene un vacío; menciónelo en lugar de inventar una etiqueta.
C. Seguimiento
7. Línea base antes de afirmaciones
Regla: Antes de recomendar cambios en la búsqueda, cuente el comportamiento actual: búsquedas por tarea, llamadas a herramientas por tarea, tasa de acierto en el primer intento. Sin una línea base no hay delta, solo una historia. Registre una ejecutando una sonda fija: bash scripts/measure_search.sh --baseline orientation -- grep -rn "TODO" . en la raíz del repositorio, o contando las primeras tareas antes de que exista el mapa. Consulte references/metrics.md para saber qué registrar y cómo puntuarlo.
8. Registrar cada tarea
Regla: Agregue una línea JSON a .prefixer/metrics.jsonl al final de cada tarea:
{"ts":"2026-10-26T14:03:11Z","task":"find-session-expiry","searches":3,"tool_calls":4,"first_try_hit":true,"est_tokens":1400}
est_tokens es chars/4, una estimación; mantenga el campo incluso cuando no pueda medirlo exactamente. Al final de la sesión, reporte el delta contra la línea base. scripts/measure_search.sh envuelve una búsqueda y registra una línea por búsqueda en la raíz del repositorio (hits, scope; --baseline marca la sonda, --hit|--miss registra first_try_hit). Las líneas de tarea escritas a mano agregan tool_calls y first_try_hit. Un esquema, campos opcionales; references/metrics.md los enumera. scripts/report_metrics.sh lee el registro: tasa de aciertos, gasto por ámbito, el delta con ámbito vs línea base.
Manejo de Git. Confirme namespaces.md: es el prefijo compartido del que se beneficia cada sesión futura. metrics.jsonl es telemetría local; el andamio escribe un .prefixer/.gitignore para él. Confírmelo solo si el equipo desea datos de tendencia.
Banderas rojas
Estos pensamientos significan deténgase. Está racionalizando.
| Pensamiento | Realidad |
|---|---|
| "Un grep amplio no hará daño" | El grep amplio es el costo que esta habilidad existe para eliminar. Asígnele ámbito. |
| "Sé dónde probablemente está" | Verifique en el espacio de nombres. Una suposición incorrecta cuesta más que una verificación con ámbito. |
| "Mapee todo el repositorio primero" | Mapee el segmento en el que está. El resto se gana filas cuando las búsquedas las necesitan. |
| "El mapa es excesivo para esta tarea" | Un mapa parcial aún se amortiza para la tercera búsqueda. |
| "Omita la línea base, solo aplíquelo" | Sin línea base no hay evidencia. Mida primero. |
| "Regeneraré todo el mapa, es más rápido" | La regeneración elimina el detalle curado y rompe el caché. Edite las filas desactualizadas. |
| "Un mapa con andamio cuenta" | Un mapa lleno de filas TODO es un borrador, no un mapa. Termínelas o córtelas. |
| "Busque en directorios de proveedores para ser exhaustivo" | El código generado es donde los tokens van a morir. Búsquelo solo cuando sea el tema. |
Cuándo no usar prefijo
- Scripts de un solo archivo y repositorios desechables: no hay nada a lo que dar ámbito.
- Tareas con un archivo obvio: ábralo, no construya infraestructura para ello.
- Cuando la ruta ya lo dice: una búsqueda dentro de
src/auth/no necesita ceremoniaauth:a su alrededor. - Código de proveedores o generado, a menos que sea el tema de la tarea.
- Repositorios de menos de ~100 archivos cuya forma sea obvia: asigne ámbito por nombres de directorio y omita el mapa.
Referencias
references/namespaces.md: formato de mapa, formas de repositorio, apilamiento de múltiples repositoriosreferences/metrics.md: definiciones de métricas, esquema JSONL, informes de deltascripts/init_namespaces.sh: andamiar un mapa de espacios de nombres para el repositorio actualscripts/check_namespaces.sh: pasar lint a un mapa: ámbitos muertos, etiquetas duplicadas, borradoresscripts/search.sh: búsqueda con ámbito como comando: resolver, buscar, ensanchar, registrarscripts/suggest_map.sh: leer el registro + el árbol, proponer ediciones al mapascripts/measure_search.sh: ejecutar una búsqueda y registrarla en un solo pasoscripts/report_metrics.sh: leer el registro: tasa de aciertos, gasto de ámbito, deltascripts/session_start.sh: emitir el mapa (+ salud) para hooks de inicio de sesiónscripts/install_hook.sh: cablear el hook SessionStart para devin/claudescripts/doctor.sh: verificar el estado de un repositorio: mapa, lint, hook, sellos de instalaciónscripts/eval_scope.sh: medir el delta de tokens de una búsqueda con ámbito vs raízscripts/eval_repo.sh: pasar lint + evaluar cada espacio de nombres en un mapa, % medio ahorradoscripts/visualize.py: renderizar el mapa en el árbol de archivos + los ahorros medidos como un informe HTMLSPEC.md: el contrato de formato namespaces.md, para herramientas que leen o escriben mapasintegrations/: fragmentos de hook de inicio de sesión + un flujo de trabajo de lint de PR para repositorios consumidores
Libros de jugadas adyacentes mantenidos para autores de canalizaciones e indicaciones (fuera del trabajo principal de esta habilidad): references/index-prefixes.md, references/prefix-library.md, references/cache-ordering.md.