Modulo 4.4: context.md — escrevendo contexto critico

📝 Template de 5 campos

Template fixo reduz fricção. Mesma estrutura toda vez, preenchimento em 30 segundos.

📐 context.md completo

## Projeto ativo
payments-v2

## Foco atual
Implementar retry logic no webhook da Stripe com backoff exponencial

## Bloqueios
- Aguardando API key de staging do time de infra (ticket INFRA-142)
- Precisa decidir: idempotency key no header ou dedup DB?

## Ultima decisao
2026-04-22 — escolhemos FastAPI sobre Flask por suporte async nativo.
Razao: 80% dos nossos endpoints sao IO-bound.

## Proximo passo
Escrever teste de integracao que simula webhook chunked (payload >6MB)

## Hipoteses ja descartadas
- Usar Kafka como fila (over-engineering para o volume atual)
- Celery como worker (equipe nao tem experiencia operacional)

💡 Hipoteses descartadas importam

Evita Claude sugerir solucoes ja rejeitadas. Custo: 2 linhas. Beneficio: horas de retrabalho evitado.

⏱️ Frequencia: toda sessao

context.md e volatil por design. Atualiza toda sessao — manual ou via hook.

📅 Cadencia esperada

Por tipo de usuario:

•Dev solo: atualizar no fim da sessao. 30 segundos.
•Team lead: atualizar apos cada reuniao importante.
•Content creator: atualizar ao trocar de projeto/serie.
•Todos: se passou 1 semana sem atualizar, revisar.

🤖 Automatizando: SessionEnd + Gemini

Melhor caso: hook SessionEnd chama Gemini, resume sessao, atualiza context.md sozinho.

📐 Fluxo automatico

Voce fecha Claude Code
         │
         ▼
SessionEnd hook dispara
         │
         ▼
Script le transcript JSONL da sessao
         │
         ▼
Envia para Gemini Flash: 'resuma em 150 palavras'
         │
         ▼
Gemini responde com decisoes, bloqueios, proximo passo
         │
         ▼
Script atualiza ~/.memory/context.md
         │
         ▼
Proxima sessao ja abre com contexto fresco

Custo por sessao: ~$0.001 (quase zero)
Esforço manual: zero

💡 Trilha 6 detalha

Modulo 6.4 tem implementacao completa em Python. Copy/paste funcional em 10 minutos.

🎯 context.md por projeto

Cada projeto tem seu proprio context.md. Hook escolhe pelo cwd.

📐 Estrutura multi-projeto

~/.memory/
├── prime.md                   (global, sempre)
├── context.md                 (fallback generico)
└── projects/
    ├── payments-v2/
    │   └── context.md         (projeto especifico)
    ├── landing-redesign/
    │   └── context.md
    └── data-pipeline/
        └── context.md

# Hook escolhe:
PROJ=$(basename "$CWD")
PROJ_CTX="$HOME/.memory/projects/$PROJ/context.md"
if [[ -f "$PROJ_CTX" ]]; then
  CONTEXT=$(cat "$PROJ_CTX")
else
  CONTEXT=$(cat ~/.memory/context.md)
fi

💡 Isolamento limpo

Sem mistura de contextos entre projetos. Projeto A nao aparece em sessao do projeto B.

🚨 Conflitos com CLAUDE.md

Quem ganha quando CLAUDE.md e context.md dizem coisas diferentes?

⚖️ Ordem de precedencia

Como o modelo pondera:

•additionalContext do hook entra depois do CLAUDE.md no prompt.
•Posicao posterior = maior atencao em texto longo.
•Na pratica, context.md ganha se conteudo for mais especifico.
•Regra: duplicar informacao volatil em CLAUDE.md e erro.

💡 Divisao clara

CLAUDE.md: regras perenes ('sempre usar PT-BR'). context.md: estado ativo ('projeto X, foco Y'). Sem overlap.

🧪 Lab: crie o seu agora

Outra vez, pause e aplique. 10 minutos para context.md funcional.

Minuto 0-3

Crie ~/.memory/context.md com template.

Minuto 3-7

Preencha com situacao real do projeto atual. Nao invente.

Minuto 7-10

Valide: alguem novo no projeto, lendo seu context.md, entenderia em 30s onde voce parou? Se nao, refine.

💡 Template em labs/

labs/context-md/context.md esta la. Copie, edite, pronto.

📝 Resumo do Modulo

✓

5 campos fixos — projeto, foco, blocks, decisao, next.

✓

Atualizacao toda sessao — manual ou automatica.

✓

Gemini Flash automatiza — SessionEnd le JSONL e atualiza sozinho.

✓

Isolamento por projeto — hook escolhe por cwd.

Proximo:

4.5 — UserPromptSubmit: injecao por turno

← Modulo anterior Proximo Modulo →