O que 洁癖.skill faz?
Impedir que Agentes de IA poluam seu repositório com
plan.md,todo.md,summary.mde artefatos descartáveis. Não deixe o Agente de IA transformar a raiz do seu projeto em um aterro de Markdown.
Isso não é um deletador de Markdown. Esta Skill governa o ambiente local onde os agentes trabalham: artefatos de repositório, caches de espaço de trabalho, armazenamento WSL2/Docker, caches de gerenciadores de pacotes, caches de modelos e estado do agente/IDE.
Um arquivo ou cache não é lixo apenas por ser grande. Torna-se um risco de higiene quando não tem intenção, não tem dono, não tem leitor, não tem ciclo de vida e não tem caminho de recuperação. O objetivo não é deletar agressivamente — é garantir que cada artefato, cache e pegada do ambiente local tenha um propósito, um lugar e uma próxima ação segura.
1. Modelo de Higiene
Use um modelo de três camadas:
| Camada | Escopo | Exemplos | Ação padrão |
|---|---|---|---|
| Repositório | Artefatos criados pelo agente | plan.md, todo.md, .agent_tmp/, .agent_reports/ | classificar, relatar, limpeza DryRun |
| Espaço de trabalho | Caches de desenvolvimento entre projetos | node_modules, .venv, target, caches de build | auditar, pontuar, recomendar |
| Máquina local | Cadeias de ferramentas e ambientes virtualizados | WSL2, Docker Desktop, caches de pacotes, caches de modelo, estado do agente/IDE | mapa somente leitura, categoria de risco, orientação manual |
Relatórios devem separar:
Constatacoes— fatos observados localmente.Sugestoes Seguras— próximos passos de baixo risco, como executar DryRun ou mover relatórios futuros para.agent_reports/.Operacoes Manuais / Arriscadas— migração, compactação VHDX, realocação de dados Docker, realocação de cache de modelo ou edições de configuração. Nunca execute estas automaticamente.
2. Quando Usar Esta Skill
Invoque esta Skill quando o usuário perguntar sobre:
| Gatilho | Exemplos |
|---|---|
| Organizar / Arrumar | "organizar diretorio do projeto", "limpar este repositorio", "organizar meu projeto" |
| Gerar artefatos | "escrever um plano", "gerar relatorio", "criar um plano/tarefa/resumo/relatorio/auditoria" |
| Auditar | "auditar arquivos do projeto", "procurar artefatos de agente", "listar arquivos suspeitos" |
| Limpar | "limpar arquivos do agente", "limpar arquivos temporarios do agente", "deletar arquivos temporarios" |
| Decidir | "este arquivo deve ser gerado?", "devo criar este arquivo ou mante-lo no chat?" |
| Pontuar | "dar uma nota de higiene para meu repositorio", "pontuacao de higiene do repositorio", "quao limpo esta meu repositorio?" |
| Auditoria de espaço de trabalho | "escanear espaco de trabalho", "auditar meu espaco de trabalho", "encontrar artefatos de agente em varios repositorios" |
| Auditoria de ambiente local | "auditar meu ambiente local", "inspecionar ambiente local do agente", "onde estao meus caches de desenvolvimento" |
| Criar regras | "criar AGENTS.md / CLAUDE.md / Cursor Rules" |
| Conclusao de tarefa | Verificacao de higiene de encerramento antes de sair |
| Poluicao | "multiplos agentes escrevendo arquivos de qualquer jeito", "raiz do projeto e uma bagunca de markdown" |
| Reclamacao | "nao gere documentos inuteis", "limpar plan.md / todo.md" |
| Inspecionar ambiente | "inspecionar meu ambiente de programacao", "onde o node/python/go esta instalado?" |
| Crescimento de disco | "por que meu disco C esta crescendo?", "encontrar caches de pacotes/modelos" |
| WSL2 / Docker | "WSL2 esta ocupando muito espaco", "disco do Docker Desktop esta enorme", "onde esta ext4.vhdx" |
| Caches de modelo | "modelos Ollama/Hugging Face no disco C", "auditoria de cache de modelo de IA" |
| Estado do agente | "locais de estado do Claude/Codex/Cursor", "pegada de configuracao/cache do agente" |
3. Quando NAO Usar Esta Skill (Nunca Fazer)
Pare e pergunte ao usuário ou evite estritamente se a solicitação envolver:
- Deletar documentação formal do projeto
- Modificar anotações escritas pelo usuário
- Limpar código fonte (
src/,lib/,app/) - Mexer em diretórios de estado da ferramenta (
.codex/,.claude/,.cursor/,.vscode/,*.sqlite,state.json,session.json,workspaceStorage,globalStorage,auth-token) - Deleção em massa de Markdown não confirmada
- Forçar deleção de arquivos rastreados pelo Git
- Limpar Markdown desconhecido em pastas pessoais/de usuário
- Modificar configurações do sistema ou registro
- Registrar tarefas agendadas
- Enviar logs, relatórios, credenciais ou dados de ambiente
- Escanear o computador inteiro sem um escopo raiz explícito especificado pelo usuário
- Ler tokens de autenticação, arquivos de sessão, bancos de dados SQLite ou logs privados
- Deletar caches de ferramentas ou modelos apenas porque são grandes
- Mover ferramentas ou reescrever variáveis de ambiente sem uma solicitação de migração explícita separada
- Compactar arquivos VHDX do WSL/Docker
- Exportar/importar distribuições WSL
- Editar
.wslconfig, configurações do Docker, perfis de shell ou configuração do gerenciador de pacotes
4. Classificação de Artefatos
Cada arquivo que um agente cria pertence a uma das cinco classes. Classe — não extensão — determina o tratamento.
| Classe | Exemplos | Localização | Ciclo de vida | Auto-deletar? |
|---|---|---|---|---|
| A — Documentação Formal | README.md, CHANGELOG.md, LICENSE, docs/**, CONTRIBUTING.md, anotações do usuário | docs/, raiz do projeto | Permanente | Nunca |
| B — Entregáveis Solicitados pelo Usuário | relatório de auditoria, plano de migração, pesquisa (usuário pediu explicitamente) | .agent_reports/ | 30 dias | Após retenção |
| C — Artefatos de Trabalho Temporários | plano, tarefas, anotações, rascunho, progresso, lista_de_tarefas | .agent_tmp/ | 7 dias | Após retenção |
| D — Auto-elogiosos | resumo, relatorio_final, resumo_trabalho, licoes, resumo_mudancas | Não criar | N/A | N/A |
| E — Estado da Ferramenta (fora de escopo) | .codex/, .claude/, .cursor/, *.sqlite, arquivos de estado | Diretórios da ferramenta | N/A | Nunca |
Regras principais:
- Classe A → nunca deletar automaticamente, nunca reescrever automaticamente
- Classe B → nome de arquivo específico
<tarefa>_<data>.md, nunca na raiz do projeto - Classe C → somente
.agent_tmp/, nunca commitado, limpar ao final da tarefa - Classe D → não criar. O chat é o resumo.
- Classe E → ignorar completamente, nunca marcar como suspeito
5. Verificação de Intenção do Artefato (OBRIGATÓRIO)
Antes de criar qualquer novo arquivo, preencha esta verificação. Se você não puder responder a cada campo, não crie o arquivo.
Verificacao de Intencao do Artefato
─────────────────────
1. Usuario solicitou um arquivo? sim / nao
2. Proposito:
3. Leitor:
4. Vida util esperada: sessao / dias / persistente / doc-formal
5. Caminho de destino:
6. Por que uma resposta no chat nao e suficiente:
7. Classe: temporario / persistente / documentacao-formal
8. Deve estar em .gitignore? sim / nao
Regras de decisão:
| Cenário | Ação |
|---|---|
| #1 = não, classe ≠ A | Não criar. Responder no chat. |
| Propósito = plano/tarefa/resumo/progresso, leitor = este usuário | Apenas chat. Sem arquivo. |
| Deve criar, classe = C | .agent_tmp/<nome-especifico>.md |
| Deve criar, classe = B | .agent_reports/<tarefa_<AAAA-MM-DD>.md |
| Classe = A (documento formal) | Caminho docs/, usuário solicitou explicitamente |
| Arquivo reafirma este chat | Não criar |
| Nenhum leitor claro | Não criar |
| Nenhum ciclo de vida claro | Não criar |
| Nenhum uso de acompanhamento | Não criar |
6. Regras Rígidas para Geração de Arquivos
- Padrão: não escrever arquivos.
- Planos, tarefas, resumos, progresso → responder no chat.
- A raiz do projeto é proibida para Markdown de processo genérico, a menos que o usuário nomeie um arquivo explicitamente.
- Proibido na raiz do projeto (a menos que o usuário peça explicitamente por aquele arquivo exato):
todo.md, plan.md, notes.md, lessons.md, summary.md, report.md, final_report.md, implementation_plan.md, migration_plan.md, audit_report.md, cleanup_report.md, task_list.md, progress.md, work_summary.md, changes_summary.md, *_summary.md, *_report.md, *_plan.md - Arquivos temporários →
.agent_tmp/ - Relatórios persistentes →
.agent_reports/ - Documentos formais →
docs/(apenas quando solicitado explicitamente) - Não gere relatórios para "parecer profissional."
- Não crie arquivos de resumo automáticos no final da tarefa.
- Não duplique o chat em arquivos.
- Use nomes de arquivo específicos:
<tarefa>_<contexto>_<data>.md - Se o usuário pedir um arquivo, proponha o caminho + nome do arquivo primeiro.
- Se o usuário disser "me diga" / "resuma" / "planeje" → responda no chat.
7. Locais Permitidos e Proibidos
Permitidos
| Conteúdo | Local permitido |
|---|---|
| Arquivos de trabalho temporários | .agent_tmp/ |
| Relatórios solicitados pelo usuário | .agent_reports/ |
| Documentação formal | docs/ (requer solicitação explícita) |
| Caminho especificado pelo usuário | Qualquer caminho que o usuário nomeou explicitamente |
Proibidos
| Local | Porquê |
|---|---|
| Raiz do projeto (Markdown de processo genérico) | Reservado para arquivos formais do repositório |
src/, lib/, app/ | Diretórios de código fonte |
.codex/, .claude/, .cursor/, .vscode/ | Estado da ferramenta — não mexer |
8. Arquivos Protegidos (Nunca Deletar Automaticamente)
README.md, README.*.md
CHANGELOG.md
LICENSE, LICENSE.*
CONTRIBUTING.md
CODE_OF_CONDUCT.md
SECURITY.md
Tudo sob docs/
Qualquer arquivo rastreado pelo Git fora de .agent_tmp/ ou .agent_reports/
Anotacoes escritas a mao pelo usuario
9. Ciclo de Vida
| Local | Retenção padrão | Limpeza |
|---|---|---|
.agent_tmp/ | 7 dias | O agente deve limpar seus próprios ao final da tarefa |
.agent_reports/ | 30 dias | Mover para docs/ para manutenção de longo prazo |
docs/ | Permanente | Sem ciclo de vida automático |
10. Pontuação de Higiene do Repositório
Quando solicitado uma pontuação de higiene do repositório, prefira ${CLAUDE_SKILL_DIR}/scripts/score_repo_hygiene.py quando Python estiver disponível. Em ambientes somente Windows, use ${CLAUDE_SKILL_DIR}/scripts/score-repo-hygiene.ps1.
| Pontuação | Classificação (pt) | Classificação (en) |
|---|---|---|
| 90–100 | Limpo | Clean |
| 70–89 | Quase limpo | Mostly clean |
| 50–69 | Precisa de organização | Needs tidy-up |
| 0–49 | Aterro de artefatos | Artifact landfill |
Dimensões: limpeza da raiz, posicionamento de artefatos, clareza dos documentos protegidos, higiene do Git, isolamento do estado do agente, prontidão para limpeza. Fatores de peso opcionais: --weights references/score-weights.example.json.
Política de projeto opcional: colocar .tidy-skill.json (ou tidy-skill.policy.json) na raiz do repositório, ou passar --policy. Exemplo de esquema: references/tidy-skill.policy.example.json. A política pode estender padrões de raiz proibidos/protegidos, definir min_score, exigir .agent_tmp/ + .agent_reports/, e optar por nomes de raiz de planejamento intencional via planning_root_globs (veja references/tidy-skill.policy.pwf.example.json para coexistência planejamento-com-arquivos). .planning/** é reconhecido como memória de trabalho intencional Classe C sem uma política.
Doutor, reparo, classificar, instantâneos
| Necessidade | Script |
|---|---|
| Instalação única + doutor de higiene / porta CI | ${CLAUDE_SKILL_DIR}/scripts/tidy_doctor.py |
| Reparos seguros primeiro DryRun (diretórios de layout; movimentos de raiz opcionais) | ${CLAUDE_SKILL_DIR}/scripts/tidy_repair.py |
| Emissor de configuração de gancho de host DryRun | ${CLAUDE_SKILL_DIR}/scripts/tidy-install-hooks.py |
Classificar um caminho antes de escrever (Classes A–E); lote via --stdin --json | ${CLAUDE_SKILL_DIR}/scripts/classify_artifact.py |
Salvar/comparar histórico de pontuação; portão em min_score | ${CLAUDE_SKILL_DIR}/scripts/hygiene_snapshot.py |
Verbos de segurança (sempre com o mesmo significado):
- dryrun — apenas visualizar (padrão para reparo, limpeza, instalar-ganchos)
- careful — altera apenas arquivos de trabalho do agente (
tidy_repair.py --apply --move-root) - guard — recusa firmemente configurações de host, VHDX, dados Docker, arquivos rastreados pelo Git, documentos Classe A
tidy_repair.py é o companheiro de diagnóstico→próximo-passo para o doutor. O padrão é apenas um plano. --apply cria .agent_tmp/ + .agent_reports/ com .gitkeep. Movimentos de processo raiz precisam de --apply e --move-root, e ainda recusam nomes rastreados pelo Git / protegidos.
hygiene_snapshot.py save escreve sob .agent_reports/hygiene-history/ por padrão (histórico de entregáveis Classe B, não lixo na raiz). gate e doutor saem com código 2 em caso de falha de higiene/política.
11. Auditoria de Higiene do Espaço de Trabalho
Quando solicitado a escanear múltiplos repositórios, prefira ${CLAUDE_SKILL_DIR}/scripts/audit_workspace_hygiene.py para uma base portátil. Em fluxos de trabalho somente Windows, ${CLAUDE_SKILL_DIR}/scripts/audit-workspace-hygiene.ps1 também é aceitável. O usuário deve especificar explicitamente um diretório raiz. Nunca defina como padrão escanear unidades inteiras.
Para uma auditoria de artefatos de agente de repositório único, prefira ${CLAUDE_SKILL_DIR}/scripts/audit_agent_artifacts.py quando Python estiver disponível. Use ${CLAUDE_SKILL_DIR}/scripts/audit-agent-artifacts.ps1 quando estiver em um fluxo de trabalho PowerShell. Ambos auditoria e pontuação aceitam --policy opcional.
Verificação somente leitura opcional ao final da tarefa: ${CLAUDE_SKILL_DIR}/hooks/stop-hygiene-check.py (apenas relata; nunca deleta). Frases de gatilho estão em commands/TRIGGERS.md.
12. Auditoria de Higiene da Máquina Local
Quando perguntado sobre crescimento do disco C, WSL2, Docker Desktop, caches de modelo, caches de pacotes, estado do agente ou expansão do ambiente de desenvolvimento local, use ${CLAUDE_SKILL_DIR}/scripts/audit-dev-environment.ps1.
Para mapeamento portátil de cache de pacote/modelo em ambientes não Windows, use ${CLAUDE_SKILL_DIR}/scripts/audit_dev_environment.py. Use o script PowerShell para inspeção específica do Windows de VHDX do WSL2/Docker.
Regras:
- Peça raízes de varredura explícitas quando a varredura de projeto/espaço de trabalho for necessária.
- Use
-IncludeUserProfileapenas quando o usuário quiser incluir locais de cache de perfil de usuário padrão. - Use
-IncludeDrivesapenas quando o usuário pedir explicitamente por dicas no nível da unidade. - Trate migração WSL/Docker, compactação VHDX, realocação de dados Docker, edições
.wslconfige realocação de cache de modelo comoOperacoes Manuais / Arriscadas. - Nunca leia tokens, arquivos de sessão, bancos de dados SQLite, chaves de registro, logs privados ou armazenamentos de credenciais.
Para detalhes sobre WSL2 e Docker, leia references/wsl2-docker-hygiene.md.
13. Regras de Limpeza
Limpeza automática permitida:
.agent_tmp/— arquivos mais antigos que 7 dias.agent_reports/— arquivos mais antigos que 30 dias- Diretório temporário do agente especificado pelo usuário
- Arquivos de processo nomeados, expirados, criados pelo agente
Limpeza automática proibida:
- Documentos protegidos (Classe A)
- Código fonte
- Estado da ferramenta (Classe E)
- Markdown desconhecido em pastas de usuário
- Arquivos rastreados pelo Git
- Arquivos suspeitos no nível raiz → apenas relatar, perguntar ao usuário
14. Regras de Auditoria
- Somente leitura — nunca modifica arquivos
- Profundidade limitada, pula
.git/,node_modules/,dist/,build/,target/,.venv/,venv/ - Lista:
.agent_tmp/,.agent_reports/, arquivos suspeitos no nível raiz, documentos protegidos - Sugere ações, não realiza nenhuma
- Sem upload ou chamadas de rede
15. Lista de Verificação de Fim de Tarefa
Antes de relatar "concluído":
- Criei algum arquivo? Cada um foi justificado por uma Verificação de Intenção do Artefato?
- ...
[truncado para tradução]