📁 Anatomia de um workspace portátil

Um workspace portátil começa com dois arquivos na raiz, e é fácil confundi-los. O README.md é para gente: onboarding humano, como rodar, como testar, o que tem em cada pasta. O AGENTS.md é para agentes: instruções concisas, regras estáveis e, no topo, uma ordem de leitura explícita que diz ao agente quais arquivos abrir antes de agir.

Essa é a árvore completa que o kit propõe. Você vai reconhecer cada pasta ao longo deste módulo:

meu-projeto/
├── README.md              # onboarding humano
├── AGENTS.md              # instruções + ordem de leitura (Codex, Gemini, GLM)
├── CLAUDE.md              # "@AGENTS.md" + resíduo específico do Claude
├── context/
│   ├── overview.md        # o que é, fatos verificados, preferências, hipóteses
│   ├── current-state.md   # o que funciona e o que está pendente
│   ├── sources.md         # de onde veio cada informação + regra de refresh
│   └── decisions/         # uma decisão aceita por arquivo
├── tasks/
│   └── current.md         # objetivo, dono, critério de pronto, próxima ação
├── handoffs/
│   └── latest.md          # continuação para a próxima sessão
├── .agents/
│   └── skills/            # skills canônicas do projeto
└── scripts/
    └── check.sh           # verificação mínima

Conceitos-chave

A pasta context/ é o conhecimento durável do projeto. Os dois primeiros arquivos respondem a perguntas diferentes. O overview.md responde "o que é isto?": o que o projeto faz, para quem, os fatos verificados (cada um com fonte e data), as preferências do dono e as hipóteses ainda não confirmadas. Muda devagar. O current-state.md responde "como está agora?": o que funciona, o que está quebrado ou pendente, o que mudou desde o overview. Muda a cada sessão.

# Overview
- ID: overview | Escopo: projeto
- Fonte: | Data de observação:
- Status: rascunho | Revisar em:

## O que é
## Para quem
## Fatos verificados (com fonte e data)
## Preferências (do dono do projeto)
## Hipóteses (não verificadas)

# Estado atual — AAAA-MM-DD
- Última sessão:
- O que funciona:
- O que está quebrado / pendente:
- Fatos que mudaram desde o overview:

Conceitos-chave

Dois arquivos que quase ninguém cria e que resolvem o problema mais comum de contexto: "qual das várias versões desta informação é a certa?" O sources.md é uma tabela de de onde veio cada coisa: caminho ou URL, tipo (arquivo local, export datado ou conexão viva), data, escopo e a regra de refresh. A pasta decisions/ guarda uma decisão aceita por arquivo, com contexto, a decisão em si e as consequências.

Conceitos-chave

O texto original observa que muita gente fala de memória e handoff, mas esquece do trabalho atual. O tasks/current.md é isso: o que estamos fazendo agora, quem é responsável e qual o critério de pronto. Ele faz o agente entender não só o histórico, mas o que precisa acontecer nesta sessão. E é o arquivo que a pergunta 1 do readback ("qual o objetivo e o critério de aceite?") vai buscar.

Este é o tasks/current.md real do kit, no dia em que este curso foi escrito. Repare que cada linha responde a uma pergunta que um agente novo faria:

# Tarefa atual
- Objetivo: validar o piloto — skill `session-handoff` portada pro Codex
  via polyskill e readback passando nos dois runtimes.
- Dono: Nei (decide piloto e skills); agente executa.
- Critério de pronto: `scripts/readback-test.sh . both` gera respostas que
  citam AGENTS.md/tasks/handoffs em ambos; `scripts/sync-skills.sh drift`
  sem DRIFT.
- Próxima ação concreta: Fase 0 do plano em
  `~/projetos/wifi/DIAGNOSTICO-CLAUDE-CODEX-2026-09-14.md` —
  `scripts/adapt-instructions.sh ~/.claude`, revisar, gravar
  `~/.codex/AGENTS.md`, readback em `~/projetos/wifi`.
- Bloqueios: nenhum (publicação já feita; docs/ segue fora do git).

Conceitos-chave

O handoff é o arquivo que fecha uma sessão e abre a próxima. O texto original descreve o fluxo: sessão → /handoff → Markdown → /prime → nova sessão. O comando de handoff analisa a sessão procurando decisões tomadas, tarefas inacabadas, próximos passos e caminhos de arquivo, e salva tudo em Markdown. Um arquivo chamado latest.md aponta sempre para o mais recente. O /prime lê esse contexto de volta. Assim você não fica procurando informação em arquivos JSONL, e o resumo viaja para qualquer provedor.

Conceitos-chave

As duas últimas pastas guardam capacidade, não conhecimento. .agents/skills/ é onde ficam as skills canônicas do projeto (o Codex já procura ali; o Claude recebe cópia gerada). scripts/ guarda comandos reproduzíveis, como o check.sh que confere se os arquivos obrigatórios existem e não estão vazios. E aqui vem o aviso mais importante do módulo, direto do Prompt B: esses nomes são convenções; diga explicitamente a cada agente o que ler. Não presuma que eles carregam sozinhos.

Conceitos-chave