8. Context engineering

Context engineering es el oficio de decidir qué información ve el modelo en cada turno: ni más (caro y ruidoso), ni menos (impreciso).

Goose ofrece varias herramientas para esto: gooseignore, prompt templates, plans, persistent instructions (cubierto en el capítulo 6) y técnicas de prompting.

---

Quick tips antes de la teoría

Cinco prácticas que mueven la aguja sin entrar en mucha sofisticación:

1. Sé específico: “agregá tests” → “agregá tests unitarios al módulo src/auth/login.ts cubriendo los casos de email inválido, password vacío y rate limit”.
2. Mostrá ejemplos: si querés un estilo particular, pasá un archivo de ejemplo en el prompt.
3. Definí el output esperado: “respondé en JSON con campos summary y risks”.
4. Pedí plan antes de actuar: en tareas grandes, mode plan ahorra horas.
5. Cerrá el feedback loop: “corré los tests y arreglá los que fallen”. No aceptes “el código se ve bien”.

---

El archivo gooseignore

Como .gitignore pero para Goose. Cada línea es un patrón que el agente no debe leer ni modificar.

# .goose/gooseignore o ~/.goose/gooseignore (global)
node_modules/
.env*
*.log
build/
dist/
*.lock
*.snap
**/__snapshots__/
secrets/

¿Por qué importa?

• Ahorra tokens: el agente no llenará el context con archivos irrelevantes.
• Protege secretos: si tu .env queda fuera del context, no termina en el modelo.
• Bloquea modificaciones accidentales: no puede tocar archivos generados (snapshots, locks).
• Performance: las búsquedas internas (grep, list_files) son más rápidas.

Patrones soportados

Glob estándar:

*.log
**/__pycache__/**
src/**/test/**
!src/important/test/**     # negación: incluir aunque matchee otro pattern

Heredencia

flowchart LR
    G[~/.goose/gooseignore\nglobal] --> P[.goose/gooseignore\nproyecto]
    P --> S[.goose/gooseignore\nsubcarpeta]

Reglas se acumulan. Las más cercanas al directorio de trabajo tienen prioridad.

gooseignore vs .gitignore

Por default Goose respeta .gitignore. gooseignore es adicional: cosas que git rastrea pero vos no querés que el agente vea.

Casos típicos donde tenés gooseignore distinto a .gitignore:

• Tests con miles de fixtures (en git pero pesados).
• Archivos generados que sí están commiteados (snapshots, schemas auto-gen).
• Archivos sensibles que están en git pero no querés exponer al agente externo.

---

Prompt templates

Templates parametrizados para tareas que repetís:

~/.config/goose/prompts/
├── code-review.md
├── changelog.md
├── refactor-test.md
└── bug-report.md

Ejemplo code-review.md:

---
name: code-review
description: Review de un PR
parameters:
  - name: pr_number
    type: integer
  - name: focus
    type: string
    default: security,performance
---

Analizá el PR #{{ pr_number }} de este repositorio. Foco principal en: {{ focus }}.

Para cada hallazgo:
- Archivo:Línea
- Severidad: critical / high / medium / low
- Descripción
- Sugerencia concreta

Devolvé el resultado en JSON con un array `findings`.

Uso:

goose prompt run code-review --param pr_number=42 --param focus=security

O dentro de sesión:

> /prompt code-review pr_number=42 focus=security

---

Plans y planning mode

/mode plan ya lo vimos en el capítulo 3. Acá profundizamos en cómo armar plans útiles.

Pedir plans estructurados

> /mode plan
> Quiero migrar este proyecto de Express a Fastify. Hacé un plan con:
> 1. Lista de archivos afectados ordenada por prioridad
> 2. Riesgos por archivo (low/medium/high)
> 3. Estrategia de testing por etapa
> 4. Estimación de esfuerzo en horas
> Output en formato markdown con secciones.

El modelo va a producir un plan que podés guardar y compartir con el equipo:

> guardá este plan en docs/plan-migracion-fastify.md

Plans guardados

Goose tiene un mecanismo para conservar plans:

goose plan save migracion-fastify
goose plan list
goose plan show migracion-fastify
goose plan execute migracion-fastify --step 3

execute --step N corre solo el paso N del plan. Útil para refactors largos donde querés ir por partes con commits intermedios.

---

Estructura de un buen prompt para tareas grandes

Plantilla que funciona consistentemente:

# Contexto
[Qué proyecto, qué módulo, qué problema general]

# Objetivo
[Qué tiene que estar verdadero al final]

# Restricciones
- [Lo que NO se puede tocar]
- [Lo que NO se puede romper]
- [Convenciones a respetar]

# Output esperado
- [Archivos que se deberían modificar]
- [Tests que deben pasar]
- [Documentación a generar]

# Validación
[Cómo vas a verificar que el agente terminó OK]

Ejemplo concreto:

# Contexto
Tenemos un endpoint POST /users en src/routes/users.ts que valida con Joi.
Migración general del proyecto: Joi → Zod.

# Objetivo
Migrar la validación a Zod manteniendo el mismo comportamiento externo.

# Restricciones
- No cambiar la firma del request/response
- No tocar otros endpoints
- Tests existentes deben seguir pasando

# Output esperado
- src/routes/users.ts con Zod
- src/schemas/user.ts con la definición Zod (nuevo archivo)
- bun test debe pasar

# Validación
Corré bun test al final y reportá el resultado.

Con esta estructura el agente no inventa scope ni se sale de tema.

---

Selección de archivos en el context

A veces querés ser explícito sobre qué archivos el agente debe leer primero:

> Leé src/auth/login.ts y src/auth/middleware.ts. Después agregá un nuevo método loginWithMagicLink que envíe un email con token de un solo uso.

Eso es mejor que dejar que el agente busque por su cuenta. Le ahorra tokens y evita que descubra archivos no relacionados.

Comandos útiles

> /open src/auth/login.ts
> /open src/auth/middleware.ts
> Ahora agregá loginWithMagicLink

/open carga el archivo al context activo de la sesión. Goose lo trata como si vos se lo hubieras pegado.

---

Anti-patterns frecuentes

El “limpiá esto”

> arreglá el código

¿Qué código? ¿Arreglar qué? Sin especificidad, el agente decide cosas que no ibas a aprobar. Sé concreto.

El context dump

> [pega 3000 líneas de logs]
> ¿qué onda?

Demasiado context, el modelo se distrae. Filtrá antes:

> [pega solo las 50 líneas con errores]
> Agrupá los errores por causa raíz

Cambiar de tema sin reset

> arreglá el bug de auth
> [...]
> ahora rediseñá la home page

El history del bug de auth ensucia el context. Hacé /clear o nueva sesión.

No iterar el persistent.md

Si el agente comete el mismo error tres veces, agregá la regla. Eso convierte el persistent.md en un harness real (ver tutorial Harness Engineering).

---

Métrica clave: tokens por turn

> /tokens
turn 1: 4.2k in / 0.8k out
turn 2: 5.1k in / 1.2k out
turn 3: 12.4k in / 2.3k out  ← creció mucho

Si los tokens por turn explotan, algo se sumó al context que no debería estar. Causas típicas:

• Archivo grande cargado innecesariamente.
• History muy largo, conviene /compact.
• Persistent instructions infladas — recortá.
• Tool output enorme (un cat de un archivo enorme).

Mantener tokens bajos = respuestas más rápidas + más baratas + más precisas.

---

¿Qué viene?

El context manda — pero también las herramientas. En el próximo capítulo cubrimos las extensions: built-in y MCP servers, cómo extender capacidades de Goose con el ecosistema MCP.