Agent Lean Safe Coding
Use esta habilidade para manter agentes de código menores e mais seguros: construa apenas o comportamento necessário, reutilize o que já existe e proteja repositórios Windows/com muito texto de edições frágeis.
O modo padrão é full.
lite: triagem rápida, contexto estreito, menor patch seguro.full: escada de triagem, envelope de segurança para Windows/texto, verificação de dependências, orçamento de patch, verificação.audit: sem edições; revise um plano ou diff para superconstrução, lógica duplicada, risco de dependências, risco Windows/texto e verificação fraca.
Loop de Execução
- Classifique a tarefa.
- Coloque arquivos arriscados dentro do envelope de segurança.
- Percorra a escada de triagem antes de escrever código.
- Defina um orçamento de patch.
- Edite localmente e preserve o estilo.
- Verifique o portão objetivo mais restrito.
- Relate o resultado com notas de reuso e risco.
1. Classifique
Nomeie o tipo de tarefa antes de editar:
bugfix: encontre a causa compartilhada; inspecione chamadores irmãos antes de espalhar guards.feature: verifique se o comportamento solicitado já é fornecido pela plataforma, framework ou repositório.refactor: exija uma simplificação concreta ou redução de risco; evite reorganizar código por gosto.review: aponte exclusões, oportunidades de reuso, operações inseguras de shell/texto e verificações ausentes.docs/text: proteja codificação, quebras de linha, estrutura Markdown e exemplos.
Se a solicitação não for clara, mas um padrão conservador for seguro, prossiga com esse padrão e declare a suposição brevemente.
2. Envelope de Segurança
Use o envelope de segurança quando algum destes estiver presente: caminhos Windows, PowerShell ou cmd, texto não ASCII, texto chinês, emoji, Markdown, prompts, modelos, arquivos de localização, substituições exatas, codificação incerta, arquivos sensíveis a CRLF/LF ou saída gerada que possa ser confundida com código fonte.
Dentro do envelope:
- Prefira ferramentas de patch para pequenas edições.
- Evite passar conteúdo não ASCII por pipelines de shell ou strings inline do PowerShell.
- Preserve o estilo de nova linha existente, a menos que um formatador seja dono do arquivo.
- Use APIs de caminho ou caminhos literais entre aspas para scripts.
- Trate mojibake no console apenas como evidência de exibição; inspecione bytes ou leituras UTF-8 antes de reescrever.
- Não edite pastas geradas, pastas de dependências, caches, binários, capturas de tela ou arquivos mortos, a menos que o usuário peça explicitamente.
Leia references/windows-text-safety.md apenas quando a tarefa tiver risco de codificação, nova linha, caminho ou fragilidade de shell.
3. Escada de Triagem
Antes do código personalizado, pare no primeiro nível que resolver a tarefa de forma limpa:
- Remova a necessidade: a solicitação pode ser satisfeita deletando, configurando ou documentando um caminho existente?
- Reutilize código do projeto: helper, componente, hook, validador, utilitário de teste, comando, esquema ou padrão estabelecido.
- Use comportamento da linguagem ou biblioteca padrão.
- Use comportamento da plataforma ou framework: controles de navegador, CSS, restrições de banco de dados, roteamento de framework, validação, cache, serialização ou ferramentas de build.
- Use uma dependência já instalada.
- Adicione uma implementação local minúscula.
- Proponha uma nova dependência ou implementação maior apenas com um motivo claro, risco e necessidade de aprovação.
Nunca adicione uma dependência de produção automaticamente. Se uma nova dependência parecer justificada, explique o que ela substitui, por que as opções instaladas não se encaixam, o risco de manutenção e o comando exato de instalação.
Leia references/reuse-ladder.md apenas quando a decisão de dependência/reuso não for óbvia.
4. Orçamento de Patch
Antes de editar, escolha um orçamento pequeno:
- Arquivos que devem ser alterados.
- Arquivos intencionalmente deixados de lado.
- Código existente ou recurso da plataforma a ser reutilizado.
- Comando de verificação mínimo ou motivo pelo qual nenhum comando é útil.
Prefira menos arquivos, menos abstrações e mudanças diretas perto do comportamento. Não adicione interfaces, fábricas, camadas de serviço, chaves de configuração, pontos de extensão futuros ou wrappers, a menos que a tarefa atual precise deles.
5. Regras de Patch
- Corrija o caminho raiz uma vez, em vez de adicionar soluções alternativas repetidas no lado do chamador.
- Exclua código redundante quando o comportamento permanecer correto.
- Mantenha a formatação fora do diff.
- Mantenha comentários raros; use um comentário conciso apenas quando um limite intencional precisar ser visível posteriormente.
- Se um atalho tiver um teto conhecido, nomeie o teto e o gatilho de upgrade nesse comentário.
- Não transforme uma pequena função em um subsistema.
6. Verificação
Execute o portão novo mais restrito que prova a mudança:
- Teste existente para o comportamento alterado.
- Teste unitário focado ou autoverificação para lógica nova não trivial.
- Verificação de sintaxe/tipo/lint para arquivos de linguagem editados quando testes não estão disponíveis.
- Revisão de diff para alterações apenas de documentação ou uma linha trivial.
Ramos, parsers, caminhos de dinheiro/segurança ou caminhos de perda de dados não triviais precisam de uma verificação executável quando prático. Alterações triviais de uma linha não precisam de novo arcabouço de teste.
7. Relatório Final
Mantenha o relatório final curto:
Alterado - ...
Triagem - reuso/biblioteca padrão/plataforma/dependência instalada/código local/proposta de nova dependência
Segurança - riscos de Windows/texto tratados ou irrelevantes
Verificado - comando/resultado ou motivo
Riscos - limite restante, se houver
Para modo audit, retorne descobertas primeiro com referências de arquivo/linha quando disponíveis, depois uma lista de exclusão/reuso e a menor lacuna de verificação.