A skill lessons-learned do Archgate captura padrões e erros de uma sessão de codificação e os codifica em ADRs ou na memória do projeto, de modo que a governança melhore com o tempo.
A skill lessons-learned é a etapa CAPTURE — a etapa final do fluxo de desenvolvimento do Archgate. Ela revisa o que aconteceu durante uma sessão de codificação e transforma padrões duradouros em governança: Architecture Decision Records (ADRs) novos ou ampliados, ou entradas no arquivo de instruções de IA do projeto. É assim que o ciclo de governança do Archgate se fecha — cada sessão pode tornar a próxima melhor.
O que ela faz
Seção intitulada “O que ela faz”A skill captura aprendizados para que sejam transmitidos a todas as sessões e agentes futuros. Concretamente, ela:
- Captura aprendizados da sessão — padrões, erros, contornos e melhorias descobertos durante a codificação
- Padroniza decisões — transforma padrões recorrentes em ADRs documentados para que sejam aplicados de forma consistente
- Amplia ADRs existentes — adiciona novos Do’s/Don’ts, exemplos ou esclarecimentos
- Cria novos ADRs — quando um aprendizado cobre um tópico distinto que nenhum ADR existente abrange
- Atualiza a memória do projeto — registra conhecimento operacional no arquivo de instruções de IA do projeto
Como funciona
Seção intitulada “Como funciona”-
Reúne o contexto da sessão. Sessões longas são compactadas, então erros e decisões anteriores podem se perder. A skill lê a transcrição completa da sessão a partir do disco via
archgate session-context claude-code. Como ela roda como um sub-agente com sua própria sessão, usa--skip 1para ler a sessão pai que contém o trabalho de desenvolvimento real. Se nenhuma transcrição estiver disponível, ela recorre a fazer perguntas direcionadas sobre o problema que mais consumiu tempo, os erros que um ADR poderia ter prevenido e os padrões que valem a pena padronizar. -
Revisa o panorama de governança. Ela executa
archgate review-context --run-checkspara ver quais domínios foram afetados, os briefings de ADR aplicáveis e os resultados atuais das verificações automatizadas — substituindo várias chamadas manuais por uma só. -
Classifica cada aprendizado em uma categoria que mapeia para um destino (veja abaixo).
-
Decide: ampliar, criar ou pular. Ela prefere ampliar um ADR existente quando o aprendizado adiciona um Do/Don’t, exemplo ou esclarecimento; cria um novo ADR apenas para um tópico distinto, um ADR que de outra forma ultrapassaria ~200 linhas, ou um padrão visto em 3+ lugares; atualiza a memória do projeto para dicas operacionais; e não toma nenhuma ação para trivialidades já cobertas.
-
Escreve os aprendizados — delegando o trabalho de ADR ao adr-author, ou editando o arquivo de instruções de IA do projeto para conhecimento operacional.
-
Gera um relatório-resumo de tudo o que foi capturado.
Classificação
Seção intitulada “Classificação”Cada aprendizado é organizado em uma categoria, que determina onde ele é registrado:
| Categoria | Destino | Quando usar |
|---|---|---|
| Padrão de Arquitetura | ADR (architecture) | Estrutura de módulos, limites de dependência, nomenclatura, organização de arquivos |
| Padrão de Backend | ADR (backend) | Design de API, middleware, validação, padrões de serviço |
| Padrão de Frontend | ADR (frontend) | Padrões de componente, gerenciamento de estado, convenções de UI |
| Padrão de Dados | ADR (data) | Design de schema, migrações, padrões de acesso a dados |
| Convenção Geral | ADR (general) | Preocupações transversais: testes, tratamento de erros, formatação, dependências |
| Padrão de Domínio Customizado | ADR (domínio customizado) | Aprendizados que não se encaixam em nenhuma categoria interna — confirmados com você antes de registrar um novo domínio |
| Conhecimento Operacional | Arquivo de instruções de IA do projeto | Dicas rápidas, peculiaridades do ambiente, solução de problemas, caminhos de API |
O arquivo de instruções de IA difere por editor — CLAUDE.md para o Claude Code, .cursor/rules/*.mdc ou .cursorrules para o Cursor, .github/copilot-instructions.md para VS Code / Copilot, agents.md para o OpenCode.
Formato de saída
Seção intitulada “Formato de saída”A skill produz um relatório estruturado cobrindo o que ela capturou e o que deliberadamente pulou:
## Lessons Learned Report
### Session Summary<Brief description of the task completed>
### Learnings Captured**New ADRs Created:**- <ADR-ID> <Title> (domain: <domain>) — <one-line description>
**Existing ADRs Updated:**- <ADR-ID> <Title> — Added: <what was added>
**Project Memory Updated:**- <instruction file> — Added: <what was added>
### No Action Needed- <Learnings already documented or not worth capturing>Se nada valer a pena ser capturado, ela diz isso claramente em vez de forçar documentação para alterações triviais. Um bom aprendizado é acionável, repetível, específico e não óbvio — “arquivos de comando não devem conter lógica de negócio” se qualifica; “escreva código limpo” não.
Como se encaixa no fluxo
Seção intitulada “Como se encaixa no fluxo”UNDERSTAND → PLAN → WRITE → VALIDATE → CAPTURE (reviewer) (lessons-learned)O agente desenvolvedor invoca lessons-learned após archgate check e a skill reviewer confirmarem a conformidade, na conclusão da tarefa inicial. Ela é pulada para pequenos ajustes de acompanhamento. A skill é intencionalmente conservadora: ela propõe ADRs apenas para padrões claros e repetidos respaldados por evidência concreta de código, prefere ampliar ADRs existentes a criar ADRs sobrepostos e sinaliza — em vez de alterar silenciosamente — qualquer coisa que contradiga um ADR existente.