Domínio 1 — Agentic Architecture & Orchestration · Lição 7 de 7

Sessões: estado, resumption e forking

Objetivos de aprendizagem

• Retomar sessões nomeadas com --resume <nome-da-sessão> para continuar investigações entre dias de trabalho.
• Usar fork_session para criar ramificações independentes a partir de uma baseline de análise compartilhada.
• Decidir entre retomar a sessão (contexto anterior ainda válido) e começar sessão nova com resumo estruturado injetado (tool results antigos ficaram obsoletos).
• Informar o agente, ao retomar, sobre quais arquivos analisados mudaram — habilitando re-análise direcionada em vez de re-exploração completa.

Sessões e retomada nomeada

No Claude Code / Agent SDK, cada conversa é uma sessão com estado persistido (histórico, resultados de ferramentas, entendimento acumulado do codebase). Uma investigação longa — ex.: "mapear as dependências do fluxo de reembolso" — pode ser retomada dias depois com --resume apontando a sessão específica, sem repetir a exploração:

# Dia 1: investigação longa em uma sessão nomeada
claude "Mapeie as dependencias do fluxo de reembolso"

# Dia 3: retomar exatamente aquela investigação, com todo o contexto
claude --resume refund-flow-investigation \
  "Continue de onde paramos: gere o relatorio de acoplamento"

Vantagem: o entendimento construído (arquivos lidos, arquitetura inferida, decisões tomadas) continua disponível. Custo/risco: o contexto retomado pode estar desatualizado em relação ao estado real do código — o tema da seção seguinte.

Retomar, avisar sobre mudanças, ou recomeçar?

O task statement 1.7 cobra três decisões distintas:

fork_session: explorar caminhos divergentes

Cenário do exam guide: você investiu uma sessão inteira analisando o codebase e agora quer comparar duas estratégias diferentes (ex.: duas abordagens de testes, ou duas rotas de refatoração) partindo da mesma baseline de análise. Retomar a mesma sessão duas vezes contaminaria um caminho com o outro. A solução é fork_session: cada retomada com fork cria uma ramificação independente — as duas herdam a baseline, mas evoluem isoladas, sem poluir a sessão original.

import anyio
from claude_agent_sdk import query, ClaudeAgentOptions

BASELINE_SESSION = "8f2c1e34-analise-do-codebase"  # sessao com a analise pronta

async def explore(approach_prompt):
    options = ClaudeAgentOptions(
        resume=BASELINE_SESSION,   # parte da baseline compartilhada...
        fork_session=True,         # ...mas em um branch independente
        allowed_tools=["Read", "Grep", "Glob"],
    )
    result_text = []
    async for message in query(prompt=approach_prompt, options=options):
        result_text.append(str(message))
    return "\n".join(result_text)

async def main():
    plan_a = await explore(
        "Partindo da analise ja feita, proponha uma estrategia de testes "
        "baseada em testes de integracao por fluxo de negocio."
    )
    plan_b = await explore(
        "Partindo da analise ja feita, proponha uma estrategia de testes "
        "baseada em testes unitarios por modulo com mocks."
    )
    print("=== Abordagem A ===")
    print(plan_a)
    print("=== Abordagem B ===")
    print(plan_b)

anyio.run(main)

flowchart TD
    S[Sessão baseline
análise completa do codebase] -->|fork_session| A[Branch A
estratégia: integração]
    S -->|fork_session| B[Branch B
estratégia: unit + mocks]
    A --> CMP[Comparar propostas
e escolher]
    B --> CMP
    S -.->|sessão original
permanece intacta| S
  

Pegadinhas da prova

• Distrator típico: retomar a sessão após uma grande refatoração "porque o contexto acumulado é valioso". Se os tool results estão obsoletos, retomar propaga um retrato falso; o correto é sessão nova + resumo estruturado injetado.
• Distrator típico: o inverso — recomeçar do zero (re-explorar tudo) quando só dois arquivos mudaram. O correto é retomar e apontar os arquivos alterados para re-análise direcionada.
• Distrator típico: comparar duas abordagens retomando a mesma sessão duas vezes em sequência. A segunda exploração herda as conclusões da primeira (contaminação); use fork_session para branches independentes.
• Distrator típico: refazer manualmente a análise inteira em duas sessões novas para comparar abordagens — joga fora a baseline compartilhada que o fork reaproveita de graça.
• Distrator típico: confiar que o agente "vai perceber" que os arquivos mudaram ao retomar. Ele não percebe: os tool results antigos continuam no histórico como se fossem atuais — avisar é responsabilidade de quem retoma.

Resumo em 5 linhas

Documentação oficial

• Claude Agent SDK — Sessions
• Claude Code — Common workflows (resume)
• Claude Agent SDK overview

Questões de fixação