Communitygithub.com

handoff-de-sessao

Use esta skill quando o uso do contexto se aproximar da capacidade (>60%), antes de executar /clear ou /compact, ao alternar tarefas ou ao encerrar uma sessão de codificação no Claude Code, Cursor ou Codex. Produz um artefato de handoff estruturado que transfere o estado de execução para uma nova sessão de agente sem perda de contexto ou desvio.

O que é handoff-de-sessao?

Esta skill padroniza a maneira como um agente captura o estado ativo de uma sessão de trabalho, transformando memória de trabalho efêmera em um documento de transição acionável e verificável para a próxima sessão. É útil quando o contexto se aproxima do limite de capacidade, antes de limpar a sessão, ao trocar de tarefas ou ao finalizar um dia de codificação, pois evita perda de informações, repetição de erros e alucinações de progresso. A skill suporta os principais agentes de codificação: Claude Code (terminal), Cursor (IDE) e Codex (VS Code). Seu funcionamento segue um fluxo de 6 etapas: auditar o estado do Git e do workspace, capturar a meta versus a realidade implementada, registrar decisões tomadas e caminhos descartados, catalogar arquivos e símbolos alterados, isolar loops abertos com responsáveis e verificações, e especificar a próxima ação imediata. A skill também define regras operacionais rigorosas, como separar fatos de especulação, exigir proprietários e critérios de verificação para loops abertos, proibir continuações vagas e exigir identificadores exatos do workspace. Inclui um exemplo detalhado de nota de handoff e descreve antipadrões comuns a evitar, como despejar transcrições de chat, marcar módulos como concluídos sem teste, omitir becos sem saída e definir próximos passos abstratos. Por fim, reconhece limitações: produz apenas um handoff escrito, não preserva estado ativo como processos em execução, saída de terminal não confirmada ou contexto de depuração na memória, e não substitui controle de versão ou rastreamento de issues.

Funciona com✓Claude Code✓Codex CLI✓Cursor
npx skills add https://github.com/alapha888/session-handoff-kit/tree/master

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Skill de Handoff de Sessão

Propósito

Janelas de contexto grandes degradam a adesão a instruções, a precisão do raciocínio e a exatidão das ferramentas à medida que o número de tokens se acumula. Sessões longas se enchem de planos obsoletos, rascunhos abortados e rastros de erro repetitivos. Reiniciar para uma sessão nova restaura o desempenho, mas descartar o contexto cegamente introduz perda de estado, progresso alucinado e erros repetidos.

A skill session-handoff padroniza como um agente captura o estado ativo. Ela traduz a memória de trabalho efêmera em um documento de ponte acionável e verificável para a próxima sessão.


Fluxo de Trabalho: Encerrando uma Sessão (6 Passos)

Execute esta sequência quando uma sessão de agente atingir os limites operacionais ou ao interromper o trabalho:

  1. Audite o Estado do Git e do Workspace Execute git status -s e git diff --stat para estabelecer a realidade fundamentada. Nunca confie na memória do chat para saber o que foi modificado. Identifique arquivos modificados, não rastreados e em staged.

  2. Capture a Meta vs. a Realidade Implementada Defina o objetivo original em uma frase. Documente precisamente o que foi verificado como funcional (com comandos de teste ou verificações em tempo de execução bem-sucedidos) versus o que permanece parcial ou não verificado.

  3. Registre Decisões Tomadas e Caminhos Descartados Liste as decisões arquiteturais e de design tomadas durante a sessão, juntamente com a justificativa concreta. Registre explicitamente decisões negativas (abordagens testadas e descartadas) para evitar que o próximo agente tente novamente soluções que falharam.

  4. Catalogue Arquivos Tocados e Símbolos Relevantes Liste os principais caminhos de arquivo, funções, classes e definições de esquema modificados ou referenciados. Inclua referências de linha quando relevante.

  5. Isole Loops Abertos com Responsáveis e Verificações Liste todos os casos extremos não tratados, testes com falha, tarefas adiadas e restrições de ambiente. Cada loop aberto deve especificar quem o resolve (Humano ou Agente) e como a conclusão é verificada.

  6. Especifique a Próxima Ação Imediata Elabore uma instrução única, atômica e inequívoca para o próximo agente executar no primeiro turno. Não forneça uma lista ampla; especifique o comando exato a ser executado ou o arquivo a ser editado primeiro.


Regras Operacionais

  • Separe Fatos de Especulação: Um teste que passou é um fato; supor que o código funciona porque compilou é especulação. Rotule suposições não testadas explicitamente como [NÃO VERIFICADO].
  • Exija Responsáveis e Verificações para Loops Abertos: Cada loop aberto deve declarar um responsável (Humano ou Agente) e um critério de verificação determinístico (ex.: pytest tests/auth/test_token.py:test_refresh_rotation passa).
  • Proíba Continuações Vagas: Nunca escreva "continue trabalhando em auth" ou "finalize componentes do frontend." Indique o símbolo, arquivo e modo de falha exatos.
  • Referencie Identificadores Reais do Workspace: Todas as referências a código devem usar caminhos de arquivo e nomes de símbolos exatos. Não use descrições de pseudocódigo generalizado.

Exemplo de Uso: Nota de Handoff de Sessão

# Handoff de Sessão: Implementação de Rotação de JWT

### Meta e Estado Atual
- **Meta Alvo**: Implementar rotação e revogação de refresh token no serviço de autenticação FastAPI.
- **Estado Atual**: Migração do banco de dados de refresh token aplicada e endpoint de rotação criado. A geração de tokens e a persistência no banco de dados funcionam. O cache da lista de revogação ainda não está conectado ao validador de dependência.
- **Verificação**: `pytest tests/test_auth_tokens.py` passa (4/4 testes).

### Decisões Tomadas (Com Motivos)
- **Usamos Redis para a Lista de Revogação de Tokens**: Selecionamos Redis em vez de consultas ao Postgres para tokens JTI revogados, a fim de manter a latência abaixo de 5ms em rotas protegidas.
- **Rejeitamos Refresh Tokens Stateless**: Inicialmente avaliamos a expiração deslizante em claims JWT sem persistência, mas descartamos porque tokens comprometidos não poderiam ser revogados antes da expiração natural.
- **Formato do Token**: Escolhemos UUIDv4 para o claim `jti` para manter compatibilidade com os esquemas de armazenamento de sessão existentes.

### Arquivos Alterados
- `src/services/auth.py`: Adicionada função `rotate_refresh_token(old_token: str)` e chamada de invalidação no Redis.
- `src/models/tokens.py`: Adicionada tabela `RefreshTokenRecord` (SQLModel) para rastrear famílias de tokens.
- `alembic/versions/20261005_add_token_families.py`: Migração criando a tabela `token_records`.
- `tests/test_auth_tokens.py`: Adicionados testes unitários para geração de famílias de tokens e rotação.

### Loops Abertos
- [Agente] Conectar `verify_token_not_revoked` em `src/api/deps.py` -> Verificar verificando se `tests/test_auth_deps.py` falha em token na lista negra.
- [Agente] Tratar rollback do banco de dados se o Redis estiver inacessível durante a rotação -> Verificar simulando falha de conexão Redis em teste unitário.
- [Humano] Definir o segredo `REDIS_AUTH_URL` em `.env.test` para execução em CI.

### Próxima Ação
Abra `src/api/deps.py` e importe `is_token_blacklisted` de `src.services.auth`. Insira a verificação em `get_current_user` imediatamente após a verificação de decodificação do JWT.

### Cuidados
- Não modifique o tempo de expiração do `access_token` existente (atualmente 15 minutos) em `src/core/config.py`.
- A migração Alembic `20261005_add_token_families.py` deve ser executada antes de iniciar o servidor da API localmente (`alembic upgrade head`).

Antipadrões

  • O Despejo de Transcrição do Chat: Colar logs de conversa brutos na nota de handoff. A janela de contexto da próxima sessão é imediatamente poluída com o próprio ruído de conversação do qual você pretendia escapar.
  • A Aprovação Fantasma: Marcar um módulo como "concluído" quando ele foi apenas escrito, não executado ou testado.
  • O Beco Sem Saída Omitido: Deixar de fora soluções que falharam. O próximo agente lerá o código, verá o mesmo caminho aparente e reimplementará a abordagem que falhou.
  • O Próximo Passo Abstrato: Terminar com "Próximo: Implementar testes restantes." O novo agente gasta de 3 a 5 turnos desnecessários descobrindo o que precisa ser testado.

Limitações

  • Esta skill produz apenas um handoff escrito; ela não pode preservar estado ativo, como processos em execução, saída de terminal não confirmada ou contexto de depuração na memória — registre qualquer coisa importante explicitamente na nota.
  • A qualidade do handoff é limitada pelo que a sessão de saída registra: decisões, becos sem saída ou alterações de arquivo que não são escritas não podem ser recuperadas pela próxima sessão.
  • Ela não substitui o controle de versão ou o rastreamento de issues; faça commit do trabalho primeiro e referencie commits ou tickets na nota em vez de duplicá-los.

Habilidades Relacionadas