📚 Guia Completo: Como Utilizar o Template de Instruções GitHub Copilot

🎯 Visão Geral

Este template foi criado para automatizar e padronizar o desenvolvimento com GitHub Copilot, usando suas funcionalidades nativas (Instructions, Chat Modes, Prompts) para garantir consistência e qualidade em projetos de desenvolvimento.

📁 Estrutura do Template

templates/
├── project-template.instructions.md      # 📋 Template genérico de instruções
├── chat-modes.md                         # 🎛️ Modos de chat personalizados
├── copilot-prompts.md                    # 🎯 Prompts reutilizáveis
├── vscode-config.md                      # ⚙️ Configurações VS Code
└── documentation.md                      # 📚 Este guia de uso

🚀 Setup Inicial

1. Para um Novo Projeto

Passo 1: Copie o Template

# Clone ou copie os arquivos template
cp templates/project-template.instructions.md [NOME_DO_PROJETO].instructions.md

# Exemplo para um projeto React
cp templates/project-template.instructions.md my-react-app.instructions.md

Passo 2: Customize para seu Projeto

Edite o arquivo [NOME_DO_PROJETO].instructions.md substituindo:

# SUBSTITUIR:

[PROJECT_NAME] → Nome real do projeto
[STACK_TECH] → Stack tecnológico (Python/FastAPI, React/TypeScript, etc.)
[ARCHITECTURE] → Arquitetura (domain-driven, clean architecture, etc.)
[BUILD_SYSTEM] → Sistema de build (Makefile, npm scripts, etc.)
[TEST_FRAMEWORK] → Framework de testes (pytest, jest, etc.)
[VERSION_CONTROL] → Versão de dependências específicas

Passo 3: Configure VS Code

# Copie configurações VS Code
mkdir -p .vscode
cp templates/vscode-settings.json .vscode/settings.json
cp templates/vscode-tasks.json .vscode/tasks.json
cp templates/vscode-launch.json .vscode/launch.json

# Ajuste conforme seu projeto

2. Para um Projeto Existente

Análise Profunda do Projeto

Use este prompt inicial:

@workspace Seguindo o template de instruções, analise este projeto:

1. Examine pyproject.toml/package.json para stack tecnológico
2. Identifique arquitetura e padrões de código
3. Mapeie estrutura de pastas e convenções
4. Analise Makefile/scripts para comandos
5. Identifique integrações e dependências críticas

Gere arquivo de instruções personalizado baseado na análise.

🎛️ Configurando Chat Modes

Método 1: VS Code Settings Global

// settings.json (User Settings)
{
  "github.copilot.chat.customInstructions": {
    "project-analyzer": {
      "title": "🔍 Project Analyzer",
      "description": "Analisa profundamente a estrutura e padrões do projeto",
      "instruction": "Analise a estrutura, dependências, padrões de código e arquitetura..."
    }
    // ... outros modes
  }
}

Método 2: Workspace Settings

// .vscode/settings.json (Project Settings)
{
  "github.copilot.chat.instructionFiles": ["my-project.instructions.md"],
  "github.copilot.chat.customInstructions": {
    // Project-specific modes
  }
}

Método 3: Diretamente no Chat

Act as Project Analyzer: Você é um especialista em análise de projetos...

Now analyze this codebase following the instruction template.

🎯 Usando os Prompts Reutilizáveis

Análise Inicial (Obrigatório)

@workspace Analise este projeto seguindo o template de instruções:

1. Stack tecnológico e dependências (pyproject.toml/package.json)
2. Arquitetura e padrões de código existentes
3. Comandos disponíveis (Makefile/scripts)
4. Estrutura de pastas e convenções
5. Integrações externas e dependências críticas

Formate como checklist e gere resumo executivo.

Implementação de Features

/mode pattern-follower

Implemente [FEATURE] seguindo EXATAMENTE os padrões do projeto:

1. Analise implementações similares existentes
2. Identifique padrões de estrutura de arquivos
3. Siga convenções de nomenclatura
4. Implemente logs estruturados conforme padrão
5. Crie testes com coverage >= [X]%
6. Valide com ferramentas do projeto (Makefile)

Debug e Troubleshooting

/mode debug-expert

Debug este problema: [DESCRIÇÃO]

1. Analise logs e stack traces
2. Reproduza o problema sistematicamente
3. Identifique root cause
4. Implemente correção seguindo padrões
5. Execute testes para validar correção
6. Confirme que não quebrou outras funcionalidades

🔄 Workflows Recomendados

🆕 Novo Feature

1. **Análise**: /mode project-analyzer

   - Entender contexto do projeto
   - Identificar padrões relevantes

2. **Implementação**: /mode pattern-follower

   - Seguir padrões existentes exatamente
   - Manter consistência

3. **Testes**: /mode test-master

   - Criar testes abrangentes
   - Atingir coverage target

4. **Revisão**: /mode code-reviewer

   - Review qualidade e padrões
   - Identificar melhorias

5. **Documentação**: /mode documentation-generator
   - Atualizar documentação
   - Exemplos de uso

🐛 Bug Fix

1. **Debug**: /mode debug-expert

   - Identificar e corrigir problema
   - Análise de root cause

2. **Testes**: /mode test-master

   - Adicionar testes de regressão
   - Validar correção

3. **Segurança**: /mode security-auditor

   - Verificar implicações de segurança
   - Validar não introduziu vulnerabilidades

4. **Performance**: /mode performance-optimizer
   - Confirmar que não impactou performance
   - Otimizar se necessário

🔧 Refatoração

1. **Análise**: /mode code-reviewer

   - Identificar áreas de melhoria
   - Planejar refatoração

2. **Implementação**: /mode pattern-follower

   - Refatorar mantendo padrões
   - Preservar compatibilidade

3. **Testes**: /mode test-master

   - Validar que comportamento foi preservado
   - Melhorar coverage se possível

4. **Performance**: /mode performance-optimizer
   - Verificar melhorias de performance
   - Benchmarks antes/depois

🛠️ Customização por Stack

Python/FastAPI

# Adicione ao arquivo de instruções:

## Python/FastAPI Specific Patterns

- Use type hints em todas as funções
- Async/await para I/O bound operations
- Pydantic models para validação
- FastAPI dependency injection
- Pytest para testes com fixtures
- Black + isort para formatação
- Logs com estrutura JSON

React/TypeScript

# Adicione ao arquivo de instruções:

## React/TypeScript Specific Patterns

- Functional components com hooks
- Custom hooks para lógica reutilizável
- TypeScript strict mode
- Testing Library para testes
- ESLint + Prettier para formatação
- Props interface bem definidas

Node.js/Express

# Adicione ao arquivo de instruções:

## Node.js/Express Specific Patterns

- ES Modules ou CommonJS conforme projeto
- Middleware pattern para Express
- Validation com Joi/Yup
- Jest/Mocha para testes
- ESLint para code quality
- Async/await para operações assíncronas

📊 Monitoramento e Melhoria Contínua

Checklist de Qualidade

Após cada implementação, validar:

- [ ] Seguiu padrões identificados na análise inicial
- [ ] Coverage de testes >= target definido
- [ ] Passou em todas as validações (lint, format, security)
- [ ] Documentação atualizada
- [ ] Logs estruturados implementados
- [ ] Performance não degradou
- [ ] Compatibilidade mantida

Atualização do Template

Periodicidade: A cada sprint/release

1. **Revisar padrões**: Identificar novos padrões no projeto
2. **Atualizar instruções**: Incorporar aprendizados
3. **Melhorar prompts**: Otimizar com base na experiência
4. **Validar chat modes**: Testar efetividade dos modes
5. **Documentar mudanças**: Manter histórico de evolução

🎓 Treinamento da Equipe

Onboarding Novos Membros

1. **Setup**: Configurar VS Code com template
2. **Análise**: Executar análise profunda do projeto
3. **Prática**: Implementar feature simples seguindo padrões
4. **Review**: Code review usando chat modes
5. **Autonomia**: Uso independente das ferramentas

Best Practices para Equipe

✅ **SEMPRE**:

- Começar com análise do projeto usando templates
- Usar chat modes apropriados para cada tarefa
- Validar ambiente antes de implementar
- Seguir padrões identificados, nunca inventar novos
- Executar checklist de qualidade

❌ **NUNCA**:

- Implementar sem analisar código existente
- Usar conhecimento genérico ignorando padrões locais
- Pular validações de ambiente
- Misturar padrões de diferentes projetos
- Ignorar ferramentas de qualidade (lint, test, etc.)

🔧 Troubleshooting

Copilot não reconhece instruções

**Problema**: Copilot ignora arquivo de instruções

**Soluções**:

1. Verificar se arquivo está em `instructionFiles` no settings.json
2. Reiniciar VS Code completamente
3. Verificar sintaxe do arquivo Markdown
4. Confirmar que extensão GitHub Copilot está ativa
5. Testar com prompt direto primeiro

Chat Modes não aparecem

**Problema**: Modes customizados não disponíveis

**Soluções**:

1. Verificar syntax JSON no customInstructions
2. Reiniciar VS Code após mudanças
3. Verificar se está na versão mais recente do Copilot
4. Usar método direto "Act as [MODE]" temporariamente
5. Verificar logs da extensão

Prompts genéricos demais

**Problema**: Respostas muito genéricas

**Soluções**:

1. Melhorar especificidade no arquivo de instruções
2. Incluir mais exemplos de código do projeto
3. Usar @workspace para contexto completo
4. Combinar múltiplos chat modes
5. Iterar e refinar prompts baseado nos resultados

🎉 Resultados Esperados

Benefícios Mensuráveis

📈 **Produtividade**:

- 40-60% redução no tempo de setup de novos projetos
- 30-50% redução no tempo de onboarding de desenvolvedores
- 20-40% redução no tempo de implementação de features

🎯 **Qualidade**:

- 90%+ consistência na aplicação de padrões
- Redução significativa de bugs por inconsistência
- Melhoria na cobertura de testes
- Padronização automática de documentação

🚀 **Eficiência da Equipe**:

- Menor curva de aprendizado em novos projetos
- Decisões técnicas mais consistentes
- Code reviews mais eficientes
- Conhecimento compartilhado automaticamente

Métricas de Sucesso

🔍 **Acompanhar**:

- Tempo médio de setup de novo projeto
- Tempo médio de onboarding de desenvolvedor
- Coverage de testes por feature
- Número de bugs relacionados a padrões
- Satisfação da equipe com ferramentas
- Velocidade de delivery de features

🎯 Próximos Passos

  1. Implementar: Setup inicial seguindo este guia
  2. Testar: Usar em projeto real por 1-2 sprints
  3. Iterar: Melhorar baseado na experiência prática
  4. Expandir: Criar templates para outros stacks/projetos
  5. Compartilhar: Documentar aprendizados e best practices

Lembre-se: Este template é vivo e deve evoluir com seus projetos e equipe. O objetivo é automatizar o que é repetitivo para focar no que é realmente importante: resolver problemas e criar valor.

💡 Dica Final: Comece simples, use consistentemente, e melhore incrementalmente. A magia acontece na consistência de uso, não na perfeição inicial!