Modulo 4.1: SessionStart: a injecao deterministica

🎯 O que e SessionStart

SessionStart dispara antes da primeira mensagem do usuario. Seu script retorna texto via additionalContext e o prompt ja nasce enriquecido.

📐 Fluxo do SessionStart

Voce abre Claude Code em algum diretorio
         │
         ▼
Claude Code coleta settings.json (project + user + global)
         │
         ▼
Encontra hook SessionStart, executa o command
         │
         ▼
┌─────────────────────────────────────────┐
│  Seu script:                             │
│   1. Le input JSON (cwd, session_id)     │
│   2. Decide o que carregar (prime.md)    │
│   3. Retorna JSON com additionalContext  │
└─────────────────────────────────────────┘
         │
         ▼
Claude Code anexa o additionalContext ao system prompt
         │
         ▼
Primeira mensagem do usuario chega; modelo ja conhece contexto

💡 Garantia de execucao

Diferente de CLAUDE.md, que depende do modelo ponderar, SessionStart EXECUTA. Se o script roda, o contexto entra. Simples e deterministico.

🧪 Configuracao minima em 5 linhas

Hello world do SessionStart. Em 2 minutos voce tem hook funcionando.

📐 settings.json minimo

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":\"Sou Mario, dev backend Python. Palavra-codigo: XIBATA-7.\"}}'"
      }]
    }]
  }
}

💡 Copie e cole

Esse JSON literal funciona. Coloque em .claude/settings.local.json do seu projeto. Abra Claude Code. Pergunte 'qual a palavra-codigo?'. Deve responder XIBATA-7.

🔐 Refazendo o teste da palavra-codigo

Mesmo experimento do modulo 1.3, mas agora com hook. O momento eureka do curso.

Fase A: so CLAUDE.md (baseline)

Coloque a palavra em CLAUDE.md, abra 10 sessoes, pergunte. Espere 6-8 acertos.

Fase B: SessionStart hook

Remova CLAUDE.md. Configure hook com a mesma palavra. Abra 10 sessoes, pergunte.

Resultado

Fase B: 10/10 acertos. Diferenca de 30pp na taxa de sucesso.

Implicacao

Para qualquer regra critica, CLAUDE.md e insuficiente. Hook e o padrao.

💡 Lab pronto

labs/palavra-codigo/ tem tudo: hook.sh, settings.json, run_experiment.sh. Voce roda em 10 minutos.

📄 O formato do prime.md

Configuracao basica aponta para arquivo prime.md. Detalhes no modulo 4.2 — aqui so o formato geral.

📋 Prime.md compact

Template de 100-200 tokens:

•Role: papel principal
•Stack: tecnologias do dia-a-dia
•Style: preferencias de comunicacao
•Current context: projeto ou tema ativo (opcional)
•Claude directives: instrucoes explicitas

💡 Mantenha enxuto

200 tokens e cap. Prime inchado nega o beneficio. Se estiver crescendo, separe em context.md (modulo 4.4).

🔀 Condicional por cwd / projeto

Um unico hook atende N projetos. Script le cwd e escolhe prime/context especifico.

📐 Hook com routing por cwd

#!/usr/bin/env bash
# session_start.sh

INPUT=$(cat)
CWD=$(echo "$INPUT" | jq -r '.cwd')

# Extrair nome do projeto do cwd
PROJ=$(basename "$CWD")

# Carregar memoria especifica do projeto (se existir) + base
BASE_FILE="$HOME/.memory/prime.md"
PROJ_FILE="$HOME/.memory/projects/$PROJ/context.md"

BASE=$(cat "$BASE_FILE" 2>/dev/null || echo "")
PROJ_CTX=$(cat "$PROJ_FILE" 2>/dev/null || echo "")

CONTEXT="${BASE}\n\n${PROJ_CTX}"

# Montar JSON de saida
python3 -c "
import json, sys
print(json.dumps({
  'hookSpecificOutput': {
    'hookEventName': 'SessionStart',
    'additionalContext': '''$CONTEXT'''
  }
}))
"

💡 Cresce sem esforço

Novo projeto? So criar ~/.memory/projects/X/context.md. Hook pega automatico.

🩺 Diagnosticando 'nao disparou'

Checklist direto para o bug mais comum dos primeiros 30 minutos.

📐 Checklist de 5 pontos

1. Script executavel?
   $ chmod +x ~/.memory/hooks/session_start.sh

2. JSON de output valido?
   $ cat mock_input.json | ./hook.sh | jq .
   (se jq falhar, JSON ta quebrado)

3. Path absoluto no settings.json?
   "command": "/home/user/.../session_start.sh"  ✓
   "command": "./session_start.sh"               ✗

4. Nome do evento correto?
   "SessionStart"   ✓
   "sessionStart"   ✗
   "session-start"  ✗

5. Conflito entre niveis?
   Claude Code usa o settings de maior precedencia.
   Project (.claude/settings.json) > User > Global

⚠️ Teste com echo primeiro

Antes de setup complexo: "command": "echo '{}'" so para ver se dispara. Se nao dispara echo vazio, o problema esta em settings, nao no script.

📝 Resumo do Modulo

✓

Hook SessionStart e o #1 — 90% dos ganhos de memoria vem dele.

✓

additionalContext e o canal — texto injetado no prompt antes do usuario.

✓

10/10 de acerto — contra 7/10 do CLAUDE.md.

✓

Lab palavra-codigo prova — ver e acreditar.

Proximo:

4.2 — prime.md: escrevendo sua identidade

← Voltar para Trilha Proximo Modulo →