📁 Anatomía de un workspace portátil

Un workspace portátil empieza con dos archivos en la raíz, y es fácil confundirlos. El README.md es para personas: onboarding humano, cómo ejecutar, cómo probar, qué hay en cada carpeta. El AGENTS.md es para agentes: instrucciones concisas, reglas estables y, en la parte superior, un orden de lectura explícito que le dice al agente qué archivos abrir antes de actuar.

Este es el árbol completo que propone el kit. Vas a reconocer cada carpeta a lo largo de este módulo:

meu-projeto/
├── README.md              # onboarding humano
├── AGENTS.md              # instrucciones + orden de lectura (Codex, Gemini, GLM)
├── CLAUDE.md              # "@AGENTS.md" + residuo específico de Claude
├── context/
│   ├── overview.md        # qué es, hechos verificados, preferencias, hipótesis
│   ├── current-state.md   # qué funciona y qué está pendiente
│   ├── sources.md         # de dónde vino cada información + regla de refresh
│   └── decisions/         # una decisión aceptada por archivo
├── tasks/
│   └── current.md         # objetivo, responsable, criterio de listo, próxima acción
├── handoffs/
│   └── latest.md          # continuación para la próxima sesión
├── .agents/
│   └── skills/            # skills canónicas del proyecto
└── scripts/
    └── check.sh           # verificación mínima

Conceptos clave

La carpeta context/ es el conocimiento duradero del proyecto. Los dos primeros archivos responden a preguntas diferentes. El overview.md responde "¿qué es esto?": qué hace el proyecto, para quién, los hechos verificados (cada uno con fuente y fecha), las preferencias del dueño y las hipótesis aún no confirmadas. Cambia despacio. El current-state.md responde "¿cómo está ahora?": qué funciona, qué está roto o pendiente, qué cambió desde el overview. Cambia en cada sesión.

# Overview
- ID: overview | Alcance: proyecto
- Fuente: | Fecha de observación:
- Estado: borrador | Revisar en:

## Qué es
## Para quién
## Hechos verificados (con fuente y fecha)
## Preferencias (del dueño del proyecto)
## Hipótesis (no verificadas)

# Estado actual — AAAA-MM-DD
- Última sesión:
- Qué funciona:
- Qué está roto / pendiente:
- Hechos que cambiaron desde el overview:

Conceptos clave

Dos archivos que casi nadie crea y que resuelven el problema más común de contexto: "¿cuál de las varias versiones de esta información es la correcta?" El sources.md es una tabla de de dónde vino cada cosa: ruta o URL, tipo (archivo local, export fechado o conexión viva), fecha, alcance y la regla de refresh. La carpeta decisions/ guarda una decisión aceptada por archivo, con contexto, la decisión en sí y las consecuencias.

Conceptos clave

El texto original observa que mucha gente habla de memoria y de handoff, pero se olvida del trabajo actual. El tasks/current.md es eso: qué estamos haciendo ahora, quién es responsable y cuál es el criterio de terminado. Hace que el agente entienda no solo el historial, sino lo que tiene que pasar en esta sesión. Y es el archivo que la pregunta 1 del readback ("¿cuál es el objetivo y el criterio de aceptación?") va a buscar.

Este es el tasks/current.md real del kit, el día en que se escribió este curso. Fíjate en que cada línea responde a una pregunta que un agente nuevo haría:

# Tarea actual
- Objetivo: validar el piloto — skill `session-handoff` portada a Codex
  vía polyskill y readback pasando en los dos runtimes.
- Dueño: Nei (decide piloto y skills); el agente ejecuta.
- Criterio de terminado: `scripts/readback-test.sh . both` genera respuestas que
  citan AGENTS.md/tasks/handoffs en ambos; `scripts/sync-skills.sh drift`
  sin DRIFT.
- Próxima acción concreta: Fase 0 del plan en
  `~/projetos/wifi/DIAGNOSTICO-CLAUDE-CODEX-2026-09-14.md` —
  `scripts/adapt-instructions.sh ~/.claude`, revisar, guardar
  `~/.codex/AGENTS.md`, readback en `~/projetos/wifi`.
- Bloqueos: ninguno (publicación ya hecha; docs/ sigue fuera del git).

Conceptos clave

El handoff es el archivo que cierra una sesión y abre la siguiente. El texto original describe el flujo: sesión → /handoff → Markdown → /prime → nueva sesión. El comando de handoff analiza la sesión buscando decisiones tomadas, tareas inconclusas, próximos pasos y rutas de archivo, y guarda todo en Markdown. Un archivo llamado latest.md apunta siempre al más reciente. El /prime lee ese contexto de vuelta. Así no tienes que buscar información en archivos JSONL, y el resumen viaja a cualquier proveedor.

Conceptos clave

Las dos últimas carpetas guardan capacidad, no conocimiento. .agents/skills/ es donde viven las skills canónicas del proyecto (Codex ya busca ahí; Claude recibe una copia generada). scripts/ guarda comandos reproducibles, como el check.sh que verifica si los archivos obligatorios existen y no están vacíos. Y aquí viene el aviso más importante del módulo, directo del Prompt B: esos nombres son convenciones; dile explícitamente a cada agente qué leer. No des por hecho que los cargan solos.

Conceptos clave