contexto-del-sistema-de-archivos

Ingeniería de Contexto Basada en el Sistema de Archivos

Utilice el sistema de archivos como la capa de desbordamiento principal para el contexto del agente, porque las ventanas de contexto son limitadas mientras que las tareas a menudo requieren más información de la que cabe en una sola ventana. Los archivos permiten a los agentes almacenar, recuperar y actualizar una cantidad de contexto efectivamente ilimitada a través de una única interfaz.

Prefiera el descubrimiento dinámico de contexto (extraer contexto relevante bajo demanda) sobre la inclusión estática, porque el contexto estático consume tokens independientemente de su relevancia y desplaza el espacio para información específica de la tarea.

Cuándo Activarla

Active esta habilidad cuando:

• Los resultados de herramientas estén inflando la ventana de contexto
• Los agentes necesiten persistir el estado a lo largo de trayectorias largas
• Los subagentes deban compartir información sin pasar mensajes directos
• Las tareas requieran más contexto del que cabe en la ventana
• Se estén construyendo agentes que aprendan y actualicen sus propias instrucciones
• Se estén implementando blocas de notas para resultados intermedios
• Las salidas de terminal o registros necesiten ser accesibles para los agentes

No active esta habilidad para trabajo adyacente gestionado por otras habilidades:

• Memoria semántica entre sesiones, seguimiento de entidades o grafos de conocimiento temporales: sistemas-de-memoria.
• Resumen de conversaciones, compactación o redacción de traspasos duraderos: compresión-de-contexto.
• Tácticas de eficiencia de tokens que no requieran almacenamiento en archivos: optimización-de-contexto.
• Diseño de topología multiagente o protocolo de traspaso: patrones-multiagente.
• Ediciones de modelo que eliminen contenido de la ventana activa: contexto-autogestionado.

Conceptos Clave

Diagnostique las fallas de contexto según estos cuatro modos, porque cada uno requiere un remedio diferente del sistema de archivos:

1. Contexto faltante -- la información necesaria está ausente del contexto total disponible. Solución: persista los resultados de herramientas y los resultados intermedios en archivos para que no se pierda nada.
2. Contexto infrarecuperado -- el contenido recuperado no encapsula lo que el agente necesita. Solución: estructure los archivos para una recuperación dirigida (formatos compatibles con grep, encabezados de sección claros).
3. Contexto sobrerrecuperado -- el contenido recuperado excede con creces lo necesario, desperdiciando tokens y degradando la atención. Solución: descargue el contenido masivo a archivos y devuelva referencias compactas.
4. Contexto enterrado -- la información especializada está oculta entre muchos archivos. Solución: combine glob y grep para búsqueda estructural junto con búsqueda semántica para consultas conceptuales.

Utilice el sistema de archivos como la capa persistente que aborda los cuatro: escriba una vez, almacene de forma duradera, recupere de forma selectiva.

Temas Detallados

El Compromiso entre Contexto Estático y Dinámico

Trate el contexto estático (instrucciones del sistema, definiciones de herramientas, reglas críticas) como bienes inmuebles caros: consume tokens en cada turno independientemente de su relevancia. A medida que los agentes acumulan capacidades, el contexto estático crece y desplaza la información dinámica.

Utilice el descubrimiento dinámico de contexto en su lugar: incluya solo punteros estáticos mínimos (nombres, descripciones de una línea, rutas de archivo) y cargue el contenido completo con herramientas de búsqueda cuando sea relevante. Esto es más eficiente en términos de tokens y a menudo mejora la calidad de la respuesta al reducir información contradictoria o irrelevante en la ventana.

Acepte el compromiso: el descubrimiento dinámico requiere que el modelo reconozca cuándo necesita más contexto. Los modelos fronterizos actuales manejan esto bien, pero los modelos menos capaces pueden no activar las cargas. En caso de duda, opte por incluir restricciones críticas de seguridad o corrección de forma estática.

Patrón 1: Sistema de Archivos como Bloc de Notas

Redirija los resultados grandes de las herramientas a archivos en lugar de devolverlos directamente al contexto, porque una sola búsqueda web o consulta de base de datos puede volcar miles de tokens en el historial de mensajes donde persisten durante toda la conversación.

Escriba el resultado en un archivo de bloc de notas, extraiga un resumen compacto y devuelva una referencia al archivo. El agente luego utiliza la recuperación dirigida (grep para patrones, leer con rangos de línea) para acceder solo a lo que necesita.

def handle_tool_output(output: str, threshold: int = 2000) -> str:
    if len(output) < threshold:
        return output

    file_path = f"scratch/{tool_name}_{timestamp}.txt"
    write_file(file_path, output)

    key_summary = extract_summary(output, max_tokens=200)
    return f"[Output written to {file_path}. Summary: {key_summary}]"

Use grep para buscar en el archivo descargado y read_file con rangos de línea para recuperar secciones específicas, porque esto conserva la salida completa para referencia posterior mientras mantiene solo ~100 tokens en el contexto activo.

Patrón 2: Persistencia de Planes

Escriba los planes en el sistema de archivos porque las tareas de horizonte largo pierden coherencia cuando los planes salen de la atención o se resumen. El agente relee su plan en cualquier punto, restaurando la conciencia del objetivo y el progreso.

Almacene los planes en formato estructurado para que sean legibles tanto para humanos como para máquinas:

# scratch/current_plan.yaml
objective: "Refactorizar el módulo de autenticación"
status: en_progreso
steps:
  - id: 1
    description: "Auditar los endpoints de autenticación actuales"
    status: completado
  - id: 2
    description: "Diseñar el nuevo flujo de validación de tokens"
    status: en_progreso
  - id: 3
    description: "Implementar y probar los cambios"
    status: pendiente

Relea el plan al inicio de cada turno o después de cualquier actualización de contexto para reorientarse, porque esto actúa como "manipulación de la atención mediante la recitación".

Patrón 3: Comunicación entre Subagentes a través del Sistema de Archivos

Enrute los hallazgos de los subagentes a través del sistema de archivos en lugar de pasar mensajes, porque las cadenas de mensajes de varios saltos degradan la información mediante resúmenes en cada salto ("juego del teléfono").

Haga que cada subagente escriba directamente en su propio directorio de trabajo. El coordinador lee estos archivos directamente, preservando la fidelidad completa:

workspace/
  agents/
    research_agent/
      findings.md
      sources.jsonl
    code_agent/
      changes.md
      test_results.txt
  coordinator/
    synthesis.md

Imponga el aislamiento de directorios por agente para evitar conflictos de escritura y mantener una propiedad clara de cada artefacto de salida.

Patrón 4: Carga Dinámica de Habilidades

Almacene las habilidades como archivos e incluya solo los nombres de las habilidades con descripciones breves en el contexto estático, porque meter todas las instrucciones en el mensaje del sistema desperdicia tokens y puede confundir al modelo con información contradictoria.

Habilidades disponibles (cargar con read_file cuando sea relevante):
- optimización-de-base-de-datos: Ajuste de consultas y estrategias de indexación
- diseño-de-api: Mejores prácticas REST/GraphQL
- estrategias-de-pruebas: Patrones de pruebas unitarias, de integración y e2e

Cargue el archivo completo de la habilidad (por ejemplo, skills/optimización-de-base-de-datos/SKILL.md) solo cuando la tarea actual lo requiera. Esto convierte un costo de token estático O(n) en O(1) por tarea.

Patrón 5: Persistencia de Terminal y Registros

Persista la salida del terminal en archivos automáticamente y use grep para la recuperación selectiva, porque la salida del terminal de procesos de larga duración se acumula rápidamente y el copiado/pegado manual es propenso a errores.

terminals/
  1.txt    # Salida de la sesión de terminal 1
  2.txt    # Salida de la sesión de terminal 2

Consulte con grep dirigido (grep -A 5 "error" terminals/1.txt) en lugar de cargar historiales completos de terminal en el contexto.

Patrón 6: Aprendizaje a través de la Automodificación

Haga que los agentes escriban preferencias y patrones aprendidos en sus propios archivos de instrucciones para que las sesiones subsiguientes carguen este contexto automáticamente, en lugar de requerir actualizaciones manuales del mensaje del sistema.

def remember_preference(key: str, value: str):
    preferences_file = "agent/user_preferences.yaml"
    prefs = load_yaml(preferences_file)
    prefs[key] = value
    write_yaml(preferences_file, prefs)

Proteja este patrón con validación porque la automodificación puede acumular instrucciones incorrectas o contradictorias con el tiempo. Trátelo como experimental: revise las preferencias persistidas periódicamente.

Técnicas de Búsqueda en el Sistema de Archivos

Combine ls/list_dir, glob, grep y read_file con rangos de línea para el descubrimiento de contexto, porque los modelos están entrenados específicamente en la navegación del sistema de archivos y esta combinación a menudo supera a la búsqueda semántica para contenido técnico donde los patrones estructurales son claros.

• ls / list_dir: Descubrir la estructura del directorio
• glob: Encontrar archivos que coincidan con patrones (por ejemplo, **/*.py)
• grep: Buscar contenidos de archivos, devuelve líneas coincidentes con contexto
• read_file con rangos: Leer secciones específicas sin cargar archivos completos

Utilice la búsqueda en el sistema de archivos para consultas estructurales y de coincidencia exacta, y la búsqueda semántica para consultas conceptuales. Combine ambas para un descubrimiento completo.

Guía Práctica

Cuándo Usar el Contexto del Sistema de Archivos

Aplique los patrones del sistema de archivos cuando la situación coincida con estos criterios, porque agregan una sobrecarga de E/S que solo se justifica por el ahorro de tokens o las necesidades de persistencia:

Úselo cuando:

• Los resultados de las herramientas superen ~2000 tokens
• Las tareas abarquen múltiples turnos de conversación
• Múltiples agentes necesiten estado compartido
• Las habilidades o instrucciones excedan el tamaño cómodo del mensaje del sistema
• Los registros o la salida del terminal necesiten consultas selectivas

Evítelo cuando:

• Las tareas se completen en un solo turno (la sobrecarga no está justificada)
• El contexto quepa cómodamente en la ventana (no hay problema que resolver)
• La latencia sea crítica (la E/S de archivos agrega un retraso medible)
• El modelo carezca de capacidades de herramientas del sistema de archivos

Organización de Archivos

Estructura los archivos para que los agentes puedan descubrirlos, porque los agentes navegan listando y leyendo nombres de directorios:

project/
  scratch/           # Archivos de trabajo temporales
    tool_outputs/    # Grandes resultados de herramientas
    plans/           # Planes activos y listas de verificación
  memory/            # Información persistida aprendida
    preferences.yaml # Preferencias del usuario
    patterns.md      # Patrones aprendidos
  skills/            # Definiciones de habilidades cargables
  agents/            # Espacios de trabajo de subagentes

Utilice convenciones de nomenclatura coherentes e incluya marcas de tiempo o ID en los archivos de bloc de notas para desambiguar.

Para bucles de investigación autónomos, almacene la evidencia en bruto recuperada junto a la ejecución que la consumió, por ejemplo researcher/runs/<run-id>/sources/evidence/raw/. No deje volcados de investigación en bruto en la raíz del repositorio; los artefactos a nivel de raíz se vuelven difíciles de auditar y fáciles de citar sin procedencia.

Contabilidad de Tokens

Mida de dónde provienen los tokens antes y después de aplicar los patrones del sistema de archivos, porque optimizar sin medir conduce a un esfuerzo desperdiciado:

• Realice un seguimiento de la relación entre contexto estático y dinámico
• Monitoree los tamaños de los resultados de las herramientas antes y después de la descarga
• Mida con qué frecuencia se utiliza realmente el contexto cargado dinámicamente

Ejemplos

Ejemplo 1: Descarga de Resultados de Herramientas

Entrada: La búsqueda web devuelve 8000 tokens
Antes: 8000 tokens añadidos al historial de mensajes
Después:
  - Escribir en scratch/search_results_001.txt
  - Devolver: "[Resultados en scratch/search_results_001.txt. Hallazgo clave: El límite de velocidad de la API es 1000 req/min]"
  - El agente busca en el archivo con grep cuando necesita detalles específicos
Resultado: ~100 tokens en contexto, 8000 tokens accesibles bajo demanda

Ejemplo 2: Carga Dinámica de Habilidades

Entrada: El usuario pregunta sobre indexación de bases de datos
Contexto estático: "optimización-de-base-de-datos: Ajuste de consultas e indexación"
Acción del agente: read_file("skills/optimización-de-base-de-datos/SKILL.md")
Resultado: Habilidad completa cargada solo cuando es relevante

Ejemplo 3: Historial de Chat como Referencia de Archivo

Disparador: Límite de la ventana de contexto alcanzado, se requiere resumen
Acción:
  1. Escribir el historial completo en history/session_001.txt
  2. Generar un resumen para la nueva ventana de contexto
  3. Incluir referencia: "Historial completo en history/session_001.txt"
Resultado: El agente puede buscar en el archivo de historial para recuperar detalles perdidos en el resumen

Directrices

1. Escriba las salidas grandes en archivos; devuelva resúmenes y referencias al contexto
2. Almacene planes y estado en archivos estructurados para su relectura
3. Utilice espacios de trabajo de archivos de subagentes en lugar de cadenas de mensajes
4. Cargue habilidades dinámicamente en lugar de meter todas en el mensaje del sistema
5. Persista la salida del terminal y los registros como archivos buscables
6. Combine grep/glob con búsqueda semántica para un descubrimiento completo
7. Organice los archivos para que los agentes puedan descubrirlos con nombres claros
8. Mida los ahorros de tokens para validar que los patrones del sistema de archivos sean efectivos
9. Implemente la limpieza de archivos de bloc de notas para evitar el crecimiento ilimitado
10. Proteja los patrones de automodificación con validación
11. Mantenga la evidencia en bruto junto a la ejecución, evaluación y propuesta que la utilizó

Problemas Comunes

1. Crecimiento ilimitado del directorio scratch: Los agentes crean archivos temporales sin limpieza, eventualmente consumiendo disco y haciendo ruidosos los listados de directorios. Implemente una política de retención (basada en antigüedad o recuento) y ejecute la limpieza en los límites de la sesión.
2. Condiciones de carrera en el acceso a archivos multiagente: Las escrituras concurrentes en el mismo archivo corrompen el estado silenciosamente. Imponga el aislamiento de directorios por agente o use archivos de solo anexión con entradas con prefijo de agente.
3. Referencias de archivo obsoletas después de movimientos/cambios de nombre: Los agentes mantienen rutas de turnos anteriores que ya no existen después de refactorizaciones o reorganización de archivos. Siempre verifique la existencia del archivo antes de leer una ruta en caché; redescubra con glob si la verificación falla.
4. Falsas coincidencias de patrones glob: Los patrones demasiado amplios (por ejemplo, **/*) extraen archivos irrelevantes al contexto, desperdiciando tokens y confundiendo al modelo. Limite los glob a directorios y extensiones específicas.
5. Suposiciones sobre el tamaño del archivo: Leer un archivo sin verificar su tamaño puede volcar 100K+ tokens en el contexto en una sola llamada de herramienta. Verifique el tamaño del archivo antes de leer; use lecturas con rango de línea para archivos grandes.
6. Falta de verificación de existencia de archivos: Los agentes asumen que los archivos existen de turnos anteriores, pero pueden haber sido eliminados o movidos. Siempre proteja las lecturas con comprobaciones de existencia y maneje los errores de archivo faltante con elegancia.
7. Deriva del formato del bloc de notas: Los bloc de notas no estructurados se vuelven imposibles de analizar después de muchas escrituras porque las convenciones de formato se erosionan con las anexiones sucesivas. Defina y aplique un esquema (YAML, JSON o markdown estructurado) desde la primera escritura.
8. Rutas absolutas codificadas: Se rompen cuando los repositorios se descargan en diferentes ubicaciones o cuando se ejecutan en contenedores. Use rutas relativas desde la raíz del proyecto o resuelva las rutas dinámicamente.

Integración

Esta habilidad gestiona el almacenamiento de contexto respaldado por archivos.

… [truncado para traducción]