licao
Skill0 starsChanged 3 days agoMITView on GitHub
Registra uma armadilha técnica ou erro de diagnóstico em docs/licoes/, no formato do projeto, e regera o índice das lições. Use quando uma hipótese sua foi refutada por evidência, uma premissa do projeto se revelou falsa, um defeito custou mais de uma rodada para diagnosticar, ou o usuário corrigiu um entendimento seu — e também quando ele disser "registre essa lição", "isso vale uma lição" ou invocar /licao.
In this repository15 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- adrSkill
- auditar-specsSkill
- changelogSkill
- configurarSkill
- constituicaoSkill
- diagnosticoSkill
- implementar-faseSkill
- iniciar-conversaSkill
- iniciar-sddSkill
- replanejar-roadmapSkill
- sessao-gerenteSkill
- spec-de-faseSkill
- validar-faseSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 130
Commit em português, com a lição no corpo da mensagem e o licoes.yaml regerado junto: os dois no mesmo commit, senão o índice chega …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Registrar uma lição
Lê: docs/licoes/ (para não duplicar) e docs/licoes/README.md (o formato).
Escreve: docs/licoes/<id>.md; e obrigatoriamente .claude/indice/licoes.yaml, pelo
--gerar. Lição fora do índice não é encontrada por ninguém. Se a lição implicar ação
obrigatória, escreve também a regra no AGENTS.md.
Decide: se é lição mesmo: os quatro motivos abaixo, e nada além deles.
Antes de escrever: isto é mesmo uma lição?
Responda "o que se achava" em uma frase. Se não conseguir, pare: não é lição, é
documentação, e o lugar é outro (AGENTS.md, docs/adr/, specs/ ou o CHANGELOG.md; a tabela
está em docs/licoes/README.md).
Os quatro motivos, e só eles:
- uma hipótese foi refutada por evidência;
- uma premissa do projeto se revelou falsa;
- um defeito custou mais de uma rodada para diagnosticar;
- o usuário corrigiu um entendimento seu.
Escrever demais estraga o acervo. Na dúvida, não escreva.
1. Conferir se já existe
grep -ril "<palavra-chave do assunto>" docs/licoes/Se existir uma lição próxima, atualize-a em vez de criar outra: acrescente a nova evidência e a data. Duas lições sobre a mesma armadilha valem menos que uma.
2. Escrever docs/licoes/<id>.md
O formato que vale é o de docs/licoes/README.md. O esqueleto típico:
---
id: kebab-case-curto-e-descritivo # igual ao nome do arquivo
data: AAAA-MM-DD
area: <uma das áreas listadas no README>
tipo: premissa-falsa | armadilha | erro-de-diagnostico | custo-escondido
custo: "uma linha: tempo, rodada, deploy, dinheiro"
gatilho: "em que circunstância apareceu"
refs:
- caminho/do/arquivo.py:123
gatilhos: # opcional: em que ação o gancho entrega
- '\bpytest\b'
---
**O que se achava:** duas a quatro linhas.
**O que é:** duas a quatro linhas, com a evidência: número medido, saída real, linha de código.
**Como perceber da próxima vez:** o sinal observável.Regras de escrita:
refscom linha, sempre que houver código.agenda.pynão ajuda;agenda.py:142ajuda.- Evidência, não impressão. "Ficou lento" não; "a busca de horários foi de 120 ms para 3,1 s com 10 mil consultas no banco" sim.
- "Como perceber" é a seção que vale. Um sinal observável, não um conselho. "Tome cuidado com fuso horário" não serve; "se a consulta marcada aparece uma hora adiantada só nas datas depois da mudança de horário, o servidor está gravando em hora local" serve.
- Vocabulário controlado de
areaetipo: use os valores do README. Valor novo exige atualizar odocs/licoes/README.mde oAREAS_VALIDASou oTIPOS_VALIDOSdo.claude/regua.pyno mesmo commit.
gatilho: e gatilhos: são campos diferentes
Os nomes se parecem; o papel não.
gatilho:(singular, obrigatório na prática): a circunstância, em prosa, em que a armadilha apareceu. É para quem lê a lição. O gancho não o usa.gatilhos:(plural, opcional): a lista de expressões regulares que dizem em que ação o gancho entrega a lição. Cada uma é testada, sem diferenciar maiúsculas, contra o caminho do arquivo que o agente vai editar e contra o comando que ele vai rodar; basta uma casar. Semgatilhos:, a lição chega por área (toda ação que toca aareadela). Com eles, chega só quando um casa, e na frente das outras.- Lista em bloco, um item por linha, entre aspas simples (
- '\bgit\s+push\b'): entre aspas duplas,\bvira outro caractere e a regex nunca casa (a régua acusa). - O gatilho descreve a ação em que o erro acontece:
\bgit\s+push\b, nãogit. Antes de gravar, pense em três ações comuns que não deveriam receber a lição e confira que nenhuma casa. - O detalhe está em
docs/licoes/README.md, "gatilhos:— em que ação a lição chega".
- Lista em bloco, um item por linha, entre aspas simples (
E nenhum dos dois é um dos quatro motivos (o que justifica escrever a lição, acima): os motivos
decidem se a lição existe; o gatilho: conta onde ela nasceu; os gatilhos: decidem
quando ela chega.
3. Propagar, se for o caso
- Implica ação obrigatória daqui para frente? Acrescente a regra no
AGENTS.md, curta e imperativa, citando a lição. A regra manda; a lição explica. - Contradiz uma spec ou um ADR? Diga ao usuário. Não corrija spec fechada por conta própria.
- É preferência do usuário ou estado do projeto? Não é lição: vai para a memória do agente.
4. Regerar o índice: sem isto a lição não é encontrada
Primeiro o git add da lição, depois o --gerar. Se o índice só vê o que o git rastreia, sem o
git add a lição fica de fora sem erro nenhum.
git add docs/licoes/<id>.md
python3 .claude/regua.py --gerar # no Windows, python ou py -3
python3 .claude/regua.py --conferirNão é opcional. Quem consulta as lições (a skill iniciar-conversa, um gancho, outra conversa)
lê .claude/indice/licoes.yaml, não a pasta. Lição escrita e índice não regerado = lição que
existe no repositório e nunca chega a quem toca a área.
Se o comando recusar o arquivo (id fora de [a-z0-9-], id diferente do nome do arquivo), o
problema está no frontmatter, não no comando.
Sem Python nesta máquina (nenhum Python 3.8+ que rode, conferido como na skill diagnostico):
pule o --gerar e o --conferir e diga ao usuário que pulou. A lição já vale para quem a busca
em docs/licoes/; o índice fica defasado até alguém rodar a régua numa máquina com Python, e esse
alguém faz o commit do índice.
5. Fechar
Commit em português, com a lição no corpo da mensagem e o licoes.yaml regerado junto: os dois
no mesmo commit, senão o índice chega defasado na main. Sem Python, o commit leva só a lição, e a
mensagem diz que o índice ficou para depois. Se a lição nasceu de uma correção do
usuário, cite a frase dele: é o que torna o registro verificável depois.
Restrições
- Nada de segredo, token, identificador interno, endereço de e-mail, hostname de cliente ou conteúdo de documento de cliente.
- Nunca registre como lição algo que você não verificou. Suspeita não confirmada vira pendência no roadmap, não lição.
- Não reescreva lição antiga para parecer que já se sabia. O acervo vale pelo registro honesto do erro.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

