{"meta":{"title":"Usando instruções personalizadas para desbloquear o poder da revisão de código Copilot","intro":"Saiba como escrever instruções personalizadas eficazes que ajudam a GitHub Copilot fornecer revisões de código mais relevantes e acionáveis.","product":"GitHub Copilot","breadcrumbs":[{"href":"/pt/copilot","title":"GitHub Copilot"},{"href":"/pt/copilot/tutorials","title":"Tutoriais"},{"href":"/pt/copilot/tutorials/customize-code-review","title":"Personalizar revisão de código"}],"documentType":"article"},"body":"# Usando instruções personalizadas para desbloquear o poder da revisão de código Copilot\n\nSaiba como escrever instruções personalizadas eficazes que ajudam a GitHub Copilot fornecer revisões de código mais relevantes e acionáveis.\n\n## Introdução\n\nGitHub Copilot A revisão de código pode ser personalizada usando arquivos de instrução para adaptar a experiência de revisão às necessidades e aos padrões de codificação da sua equipe. No entanto, escrever instruções personalizadas eficazes requer entender como Copilot processar essas instruções e quais abordagens funcionam melhor.\n\nNeste tutorial, você aprenderá a escrever instruções personalizadas claras e eficazes que ajudam a Copilot fornecer revisões de código mais relevantes. Você descobrirá as práticas recomendadas para estruturar suas instruções, armadilhas comuns a serem evitadas e estratégias para organizar instruções em arquivos diferentes.\n\nEste tutorial é sobre como usar instruções personalizadas para Copilot code review. Para obter uma introdução mais geral ao uso de instruções personalizadas, consulte [Adicionar instruções personalizadas para Copilot](/pt/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions).\n\n### O que você aprenderá\n\nAo final deste tutorial, você entenderá:\n\n* Como escrever instruções personalizadas concisas e eficazes para revisão de código.\n* A diferença entre instruções para todo o repositório e específicas para o caminho.\n* Padrões comuns que funcionam bem com Copilot code review.\n* No momento, não há suporte para quais tipos de instruções.\n* Como estruturar e organizar suas instruções para obter melhores resultados.\n\n### Pré-requisitos\n\n* Acesso a Copilot code review.\n* Um GitHub repositório em que você pode criar arquivos de instrução personalizados.\n* Familiaridade básica com a sintaxe markdown.\n\n## Noções básicas sobre como GitHub Copilot a revisão de código processa instruções\n\nAntes de escrever instruções personalizadas, é útil entender como o Copilot code review as utiliza. Ao revisar uma solicitação de pull, Copilot lê seus arquivos de instrução e os usa para orientar sua análise. No entanto, como qualquer sistema de IA, ele tem limitações:\n\n* **Comportamento não determinístico**: Copilot pode não seguir todas as instruções perfeitamente todas as vezes.\n* **Limites de contexto**: arquivos de instrução muito longos podem resultar em algumas instruções sendo ignoradas.\n* **Questões de especificidade**: instruções claras e específicas funcionam melhor do que diretivas vagas.\n\nTenha esses fatores em mente ao escrever suas instruções: eles ajudarão você a definir expectativas realistas e escrever diretrizes mais eficazes.\n\n> \\[!NOTE]\n> Ao examinar uma pull request, Copilot leia instruções personalizadas de repositório, instruções de agente e habilidades de agente da ramificação principal (a ramificação com as alterações), e não a ramificação base. Por exemplo, ao mesclar `my-feature-branch` em `main`, Copilot usa as instruções e habilidades em `my-feature-branch`, para que você possa testar alterações nelas no mesmo pull request sem mesclá-las primeiro.\n\n## Como escrever instruções personalizadas eficazes\n\nA chave para instruções personalizadas bem-sucedidas é ser clara, concisa e específica. Aqui estão os princípios fundamentais a seguir:\n\n### Manter as instruções curtas e focadas\n\nArquivos de instrução mais curtos são mais propensos a serem totalmente processados por Copilot. Comece com um conjunto mínimo de instruções e adicione de forma mais iterativa com base no que funciona.\n\n**Prática recomendada**: limite qualquer arquivo de instrução única a um máximo de cerca de 1.000 linhas. Além disso, a qualidade das respostas pode se deteriorar.\n\n### Usar estrutura e formatação claras\n\nCopilot se beneficia de instruções bem estruturadas com:\n\n* **Títulos distintos** que separam tópicos diferentes.\n* **Itens em lista** para verificação e referência fáceis.\n* **Diretivas imperativas e curtas** em vez de longos parágrafos narrativos.\n\nPor exemplo, em vez de escrever:\n\n```markdown\nWhen you're reviewing code, it would be good if you could try to look for\nsituations where developers might have accidentally left in sensitive\ninformation like passwords or API keys, and also check for security issues.\n```\n\nGravação:\n\n```markdown\n## Security Critical Issues\n\n- Check for hardcoded secrets, API keys, or credentials\n- Look for SQL injection and XSS vulnerabilities\n- Verify proper input validation and sanitization\n```\n\n### Fornecer exemplos concretos\n\nAssim como quando você explica um conceito para um colega, os exemplos ajudam a Copilot entender o que você quer dizer. Inclua snippets de código mostrando padrões corretos e incorretos.\n\nPor exemplo:\n\n````markdown\n## Naming Conventions\n\nUse descriptive, intention-revealing names.\n\n```javascript\n// Avoid\nconst d = new Date();\nconst x = users.filter(u => u.active);\n\n// Prefer\nconst currentDate = new Date();\nconst activeUsers = users.filter(user => user.isActive);\n```\n````\n\n## Organizando instruções entre arquivos\n\nCopilot code review dá suporte a vários tipos de arquivos de instrução:\n\n1. \\*\\*\n   `copilot-instructions.md`\n   \\*\\*: instruções em todo o repositório que se aplicam a todos os arquivos.\n2. \\*\\*\n   `*.instructions.md`\n   \\*\\*: instruções específicas do caminho que se aplicam a determinados arquivos ou diretórios.\n3. \\*\\*\n   `AGENTS.md`\n   \\*\\*: instruções específicas do agente no nível do repositório.\n\nUse instruções específicas do caminho para manter o Copilot focado e evitar que ele aplique regras específicas do idioma aos arquivos incorretos.\n\n### Quando utilizar instruções para todo o repositório\n\nUse `copilot-instructions.md` para:\n\n* Padrões e diretrizes gerais da equipe\n* Requisitos de segurança universal\n* Questões transversais, como filosofia de tratamento de erros\n* Expectativas de documentação\n\n**Estrutura de exemplo para `copilot-instructions.md`**:\n\n```markdown copy\n# General Code Review Standards\n\n## Code Quality Essentials\n\n- Functions should be focused and appropriately sized\n- Use clear, descriptive naming conventions\n- Ensure proper error handling throughout\n\n## Security Standards\n\n- Never hardcode credentials or API keys\n- Validate all user inputs\n- Use parameterized queries to prevent SQL injection\n\n## Documentation Expectations\n\n- All public functions must include doc comments\n- Complex algorithms should have explanatory comments\n- README files must be kept up to date\n```\n\n### Quando usar instruções de caminho específicas\n\nUse `*.instructions.md` arquivos com a `applyTo` propriedade frontmatter para:\n\n* Padrões de codificação específicos do idioma\n* Padrões específicos do framework\n* Preocupações de segurança específicas à tecnologia\n* Regras diferentes para diferentes partes da base de código\n\n**Example: instruções específicas Python**\n\nCrie um arquivo chamado `python.instructions.md` no `.github/instructions` diretório:\n\n````text copy\n---\napplyTo: \"**/*.py\"\n---\n\n# Python Coding Conventions\n\n## Naming Conventions\n\n- Use snake_case for variables and functions\n- Use PascalCase for class names\n- Use UPPERCASE for constants\n\n## Code Style\n\n- Follow PEP 8 style guidelines\n- Limit line length to 88 characters (Black formatter standard)\n- Use type hints for function signatures\n\n## Best Practices\n\n- Use list comprehensions for simple transformations\n- Prefer f-strings for string formatting\n- Use context managers (with statements) for resource management\n\n```python\n# Avoid\nfile = open('data.txt')\ncontent = file.read()\nfile.close()\n\n# Prefer\nwith open('data.txt') as file:\n    content = file.read()\n```\n````\n\n**Exemplo: instruções específicas do front-end**\n\nCrie um arquivo chamado `frontend.instructions.md` no `.github/instructions` diretório:\n\n```text copy\n---\napplyTo: \"src/components/**/*.{tsx,jsx}\"\n---\n\n# React Component Guidelines\n\n## Component Structure\n\n- Use functional components with hooks\n- Keep components small and focused (under 200 lines)\n- Extract reusable logic into custom hooks\n\n## State Management\n\n- Use useState for local component state\n- Use useContext for shared state across components\n- Avoid prop drilling beyond 2-3 levels\n\n## Accessibility\n\n- All interactive elements must be keyboard accessible\n- Include appropriate ARIA labels\n- Ensure color contrast meets WCAG AA standards\n```\n\n### Quando usar instruções específicas do agente\n\nUse `AGENTS.md` para instruções aplicáveis a custom agents específicos em seu repositório. Isso permite que você adapte o comportamento de diferentes agentes para diferentes tarefas, incluindo a formatação Copilot code review de comentários para refletir melhor as convenções e as expectativas do repositório.\n\n**Exemplo: instruções específicas do agente**\n\nCrie um arquivo chamado `AGENTS.md` na raiz do repositório:\n\n```markdown copy\n# AGENTS.md\n\n## Code Review\n\nYour primary goal is to validate that incoming code changes are secure, performant, and match this repository's engineering standards.\n\n### Code Style & Anti-Patterns\n\nEnforce these strict patterns for code inspection:\n\n- **Asynchronous Code:** Prefer `async/await` syntax over explicit `.then()` chains.\n- **Error Handling:** Every API call must be wrapped in a structured `try/catch` block.\n- **State Management:** React components must keep local UI state completely isolated from global stores.\n```\n\n### Separando conjuntos de instruções complexos\n\nPara repositórios grandes com muitas preocupações, divida as instruções em vários arquivos focados:\n\n```text\nAGENTS.md                          # Agent-specific\n\n.github/\n  copilot-instructions.md          # General standards\n\n.github/instructions/\n  python.instructions.md           # Python-specific\n  javascript.instructions.md       # JavaScript-specific\n  security.instructions.md         # Security-specific\n  api.instructions.md              # API-specific\n```\n\nCada arquivo deve ter uma finalidade clara e específica e um frontmatter `applyTo` apropriado quando necessário.\n\n## Estrutura de arquivo de instrução recomendada\n\nCom base no que funciona bem com Copilot code review, aqui está um modelo recomendado para estruturar suas instruções:\n\n````text copy\n---\napplyTo: \"**/*.{js,ts}\"  # If this is a path-specific file\n---\n\n# [Title: Technology or Domain Name] Guidelines\n\n## Purpose\n\nBrief statement of what this file covers and when these instructions apply.\n\n## Naming Conventions\n\n- Rule 1\n- Rule 2\n- Rule 3\n\n## Code Style\n\n- Style rule 1\n- Style rule 2\n\n```javascript\n// Example showing correct pattern\n```\n\n## Error Handling\n\n- How to handle errors\n- What patterns to use\n- What to avoid\n\n## Security Considerations\n\n- Security rule 1\n- Security rule 2\n\n## Testing Guidelines\n\n- Testing expectation 1\n- Testing expectation 2\n\n## Performance\n\n- Performance consideration 1\n- Performance consideration 2\n````\n\nAdapte essa estrutura às suas necessidades específicas, mas mantenha o seccionamento claro e o formato de lista com marcadores.\n\n## O que não incluir em instruções personalizadas\n\nEntender o que Copilot code review atualmente não dá suporte ajuda você a evitar perda de tempo em instruções que não funcionarão.\n\n### Tipos de instrução sem suporte\n\nCopilot code review Atualmente, não há suporte para instruções que tentam:\n\n**Altere a experiência ou a formatação do usuário**:\n\n* `Use bold text for critical issues`\n* `Change the format of review comments`\n* `Add emoji to comments`\n\n**Modifique o comentário de visão geral da solicitação de pull**:\n\n* `Include a summary of security issues in the PR overview`\n* `Add a testing checklist to the overview comment`\n\n**Alterar GitHub Copilota função principal:**\n\n* `Block a PR from merging unless all Copilot code review comments are addressed`\n* `Generate a changelog entry for every PR`\n\n**Siga links externos**:\n\n* `Review this code according to the standards at https://example.com/standards`\n\n  Solução alternativa: copie o conteúdo relevante diretamente no arquivo de instrução\n\n**Melhorias de qualidade vagas**:\n\n* `Be more accurate`\n* `Don't miss any issues`\n* `Be consistent in your feedback`\n\nEsses tipos de instruções adicionam ruído sem melhorar a eficácia de Copilot, pois já está otimizado para fornecer revisões precisas e consistentes.\n\n## Testando e iterando sobre suas instruções\n\nA melhor abordagem para criar instruções personalizadas eficazes é começar pequeno e iterar com base nos resultados.\n\n### Comece com um conjunto de instruções mínimo\n\nComece com instruções específicas de 10 a 20 que abordam suas necessidades de revisão mais comuns e teste se elas estão influenciando Copilot code review da maneira desejada.\n\n### Testar com solicitações de pull reais\n\nDepois de criar suas instruções:\n\n1. Abra uma solicitação pull no repositório.\n2. Solicite uma revisão de Copilot.\n3. Observe quais instruções ele segue efetivamente.\n4. Anote quaisquer instruções que são frequentemente perdidas ou mal interpretadas.\n\n### Iterar com base nos resultados\n\nAdicione novas instruções uma de cada vez ou em grupos pequenos:\n\n1. Identifique um padrão que Copilot poderia examinar melhor.\n2. Adicione uma instrução específica para esse padrão.\n3. Teste com uma nova solicitação de pull.\n4. Refinar a instrução com base nos resultados.\n\nEssa abordagem iterativa ajuda você a entender o que funciona e mantém seus arquivos de instrução focados.\n\n## Exemplo: concluir instruções personalizadas para revisão de código\n\nAqui está um exemplo completo que incorpora todas as práticas recomendadas deste tutorial:\n\n**Arquivo: `.github/copilot-instructions.md`**\n\n```markdown copy\n# General Code Review Standards\n\n## Purpose\n\nThese instructions guide Copilot code review across all files in this repository.\nLanguage-specific rules are in separate instruction files.\n\n## Security Critical Issues\n\n- Check for hardcoded secrets, API keys, or credentials\n- Look for SQL injection and XSS vulnerabilities\n- Verify proper input validation and sanitization\n- Review authentication and authorization logic\n\n## Performance Red Flags\n\n- Identify N+1 database query problems\n- Spot inefficient loops and algorithmic issues\n- Check for memory leaks and resource cleanup\n- Review caching opportunities for expensive operations\n\n## Code Quality Essentials\n\n- Functions should be focused and appropriately sized (under 50 lines)\n- Use clear, descriptive naming conventions\n- Ensure proper error handling throughout\n- Remove dead code and unused imports\n\n## Review Style\n\n- Be specific and actionable in feedback\n- Explain the \"why\" behind recommendations\n- Acknowledge good patterns when you see them\n- Ask clarifying questions when code intent is unclear\n\n## Testing Standards\n\n- New features require unit tests\n- Tests should cover edge cases and error conditions\n- Test names should clearly describe what they test\n\nAlways prioritize security vulnerabilities and performance issues that could impact users.\n```\n\n**Arquivo: `.github/instructions/typescript.instructions.md`**\n\n````text copy\n---\napplyTo: \"**/*.{ts,tsx}\"\n---\n\n# TypeScript Development Standards\n\n## Type Safety\n\n- Avoid using `any` type—use `unknown` or specific types instead\n- Use strict null checks (no `null` or `undefined` without explicit handling)\n- Define interfaces for all object shapes\n\n```typescript\n// Avoid\nfunction processData(data: any) {\n    return data.value;\n}\n\n// Prefer\ninterface DataShape {\n    value: string;\n}\n\nfunction processData(data: DataShape): string {\n    return data.value;\n}\n```\n\n## Naming Conventions\n\n- Use PascalCase for types, interfaces, and classes\n- Use camelCase for variables, functions, and methods\n- Use UPPER_CASE for constants\n\n## Modern TypeScript Patterns\n\n- Use optional chaining (`?.`) and nullish coalescing (`??`)\n- Prefer `const` over `let`; never use `var`\n- Use arrow functions for callbacks and short functions\n\n## React-Specific (for .tsx files)\n\n- Use functional components with TypeScript props interfaces\n- Type all props and state explicitly\n- Use proper event types (e.g., `React.ChangeEvent<HTMLInputElement>`)\n````\n\n## Solução de problemas comuns\n\nSe Copilot code review não estiver seguindo suas instruções conforme o esperado, experimente estas soluções:\n\n### Problema: as instruções são ignoradas\n\n**Causas possíveis**:\n\n* O arquivo de instrução é muito longo (mais de 1.000 linhas).\n* As instruções são vagas ou ambíguas.\n* As instruções entram em conflito entre si.\n\n**Soluções**:\n\n* Reduza o arquivo removendo instruções menos importantes.\n* Reescreva instruções vagas para serem mais específicas e acionáveis.\n* Examine as instruções conflitantes e priorize as mais importantes.\n\n### Problema: regras específicas do idioma aplicadas a arquivos incorretos\n\n**Causas possíveis**:\n\n* Frontmatter `applyTo` ausente ou incorreto.\n* Regras em um arquivo aplicável ao repositório inteiro ao invés de um arquivo específico do caminho.\n\n**Soluções**:\n\n* Adicione o frontmatter `applyTo` aos arquivos de instruções para caminhos específicos.\n* Mover regras específicas de idioma de `copilot-instructions.md` para os arquivos apropriados `*.instructions.md`.\n\n### Problema: Comportamento inconsistente entre revisões\n\n**Causas possíveis**:\n\n* As instruções são numerosas demais.\n* As instruções não têm especificidade.\n* Variabilidade natural em respostas de IA.\n\n**Soluções**:\n\n* Concentre-se nas instruções de prioridade mais alta.\n* Adicione exemplos concretos para esclarecer a intenção.\n* Aceite que alguma variabilidade é normal para sistemas de IA.\n\n## Conclusion\n\nInstruções personalizadas eficazes ajudam a Copilot code review fornecer comentários mais relevantes e acionáveis adaptados aos padrões da sua equipe. Seguindo os princípios neste tutorial, mantendo instruções concisas, fornecendo estrutura clara, usando exemplos concretos e organizando vários arquivos, você pode melhorar significativamente sua experiência de revisão de código.\n\nLembre-se de que criar instruções efetivas é um processo iterativo. Comece com um pequeno conjunto de instruções focadas, teste-as com solicitações de pull reais e expanda gradualmente com base no que funciona bem para sua equipe.\n\n## Próximas Etapas \n\n* Dê uma olhada em algumas das [instruções personalizadas de exemplo](https://github.com/github/awesome-copilot/tree/main/instructions) no repositório Awesome GitHub Copilot para se inspirar.\n* Leia [Sobre a personalização das respostas do GitHub Copilot](/pt/copilot/concepts/prompting/response-customization) para saber mais sobre a gama completa de opções de personalização.\n* Explore o [Adicionar instruções personalizadas para Copilot](/pt/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions) para obter detalhes técnicos sobre como configurar arquivos de instrução."}