Instruções do GitHub Copilot para o

Este arquivo define como o Copilot deve se comportar ao responder questões relacionadas ao repositório. Todas as instruções estão escritas de forma explícita para maximizar a eficácia e reduzir ambiguidade.

Contexto do Projeto

Stack Tecnológico

• Sempre considere o uso de PHP e nas versões definidas em composer.json.
• Evite sugerir frameworks ou ferramentas incompatíveis com <ALT-FRAMEWORK/LINGUAGEM/VERSAO>.
• Considere que o projeto lida com .
• Considere que o projeto envolve .

Para conhecer as bibliotecas disponíveis e suas finalidades, consulte composer.json e/ou docs/dependencies.md.

Instruções Gerais

Comandos

Todos os comandos devem ser executados via makefile. Para conhecer os comandos disponíveis, consulte o arquivo makefile na raiz do projeto ou execute make help.

Idioma e Comunicação

• Sempre responda em português brasileiro (pt-BR).
• PRs e Commits devem ser escritos em português brasileiro (pt-BR).
• Commits devem seguir o padrão Conventional Commits.
• Utilize uma linguagem formal, objetiva e técnica, voltada para engenheiros de software de nível especialista.
• Prefira explicações detalhadas, mesmo que o conteúdo pareça óbvio.

Princípios de Engenharia

Fundamente as alterações e sugestões com conceitos sólidos:

• SOLID - Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion.
• Clean Code - Código legível, autoexplicativo e bem organizado.
• DDD - Domain-Driven Design para modelagem de domínio.
• YAGNI - You Aren't Gonna Need It (evite código especulativo).
• DRY - Don't Repeat Yourself.
• KISS - Keep It Simple, Stupid.
• Clean Architecture - Separação de responsabilidades em camadas.
• Event Sourcing - Quando aplicável ao contexto de eventos do calendário.

Regras de Simplicidade (YAGNI + KISS):

• Não crie Services apenas para delegar chamadas a um Enum ou outra classe
• Não crie Interfaces/Contracts para classes com uma única implementação
• Não crie camadas intermediárias sem justificativa clara
• Prefira Enums com métodos estáticos ao invés de Services stateless para lógica de domínio simples
• Questione sempre: "Essa abstração resolve um problema real ou é especulativa?"

Diretrizes de Simplicidade (Obrigatórias)

Antes de propor uma arquitetura, questione:

1. Essa camada é necessária? - Não crie Services apenas para delegar a Enums ou outras classes
2. Preciso de uma Interface? - Só crie interfaces se houver múltiplas implementações ou necessidade real de mock em testes
3. Posso usar um Enum? - Para lógica de domínio simples, Enums com métodos são preferíveis a Services
4. Onde ficam as configurações? - Valores mutáveis (cookies, timeouts) devem ir em config/, não em constantes de classes de domínio
5. Estou criando estado desnecessário? - Evite singletons com estado mutável;
6. Quantos arquivos estou criando? - Menos arquivos = menos complexidade. Justifique cada novo arquivo

Padrões de Projeto

Prefira padrões reconhecidos:

• Adapter - Para integração com fontes externas de calendário.
• Strategy - Para diferentes algoritmos de processamento.
• Factory - Para criação de objetos complexos.
• Repository - Para acesso a dados.
• Service Layer - Para lógica de negócio.

Qualidade e Manutenibilidade

• O projeto deve ser escalável e de fácil manutenção.
• O código deve ser de fácil entendimento para novos desenvolvedores.
• A documentação deve ser clara e objetiva, mas não redundante.
• Prefira código limpo e organizado usando técnicas que simplificam a lógica.
• Uma solução eficaz e simples é preferível a uma complexa.
• Sempre informe sobre possíveis falhas de segurança, desempenho ou impacto no sistema antes de sugerir mudanças significativas.

Testes

• Nomes de testes devem iniciar com test_should_ e ser descritivos no formato snake_case.
• Prefira expects() no lugar de shouldReceive() nos mocks.
• Aplique TDD e cubra todos os cenários condicionais (if/else) que possam ocorrer.
• Classes base de testes:
  • Testes unitários (tests/Unit/): devem estender a classe base dessa pasta.
  • Testes de integração (tests/Integration/): devem estender a classe base dessa pasta.
• Nunca use PHPUnit\Framework\TestCase ou Tests\TestCase do framework.
• Não crie testes triviais para validar comportamento nativo do PHP (ex: ->value ou ::from() de backed enums)
• Teste apenas lógica customizada e regras de negócio

Estilo de Código

• Prefira === false ao invés de ! para verificações booleanas explícitas.
• Sempre utilize type hinting e declare tipos de retorno em métodos e funções quando possível.
• Prefira propriedades e métodos private ou protected, evitando public quando possível.
• Siga a estrutura PSR-4 para namespaces.
• Utilize injeção de dependência via construtor para classes com dependências quando possível.
• Utilize traits para reutilização de código quando apropriado.
• Prefira Collections ao invés de arrays nativos do PHP.
• Nunca ultrapasse o limite de 120 caracteres por linha.
  • Exceção: Tabelas markdown em arquivos de documentação (.md) podem exceder este limite quando necessário para legibilidade.
  • Exceção: Arquivos json

Comentários e Documentação

• Nunca utilize comentários redundantes. O código deve ser autoexplicativo.
• Documente classes com PHPDoc descrevendo objetivo e regra de negócio.
• Evite documentação redundante em métodos quando o nome já é autoexplicativo.
• Exceção: documentação estilo @phpdoc para tipagem e conformidade com PHPSTAN

Exemplos de documentação ruim:

// Redundante: o tipo de retorno já está declarado
/** @return string */
public function getName(): string

// Redundante: o nome da classe já indica o propósito
/** Teste de integração para a classe X */
class AccessTest

Exemplos de documentação do PHPStan:

// Ruim: O tipo de retorno já está declarado porem sem tipagem forte
public function getNames(): array

// Bom: O tipo de retorno está declarado com tipagem forte via PHPSTAN
/** @return array<int, string> */
public function getNames(): array

Imports e Namespaces

Sempre importe classes completas com use ao invés de nomes totalmente qualificados no código. Isso inclui classes nativas do PHP.

Exemplo correto:

use InvalidArgumentException;

throw new InvalidArgumentException('Mensagem');

Exemplo incorreto:

throw new \InvalidArgumentException('Mensagem');

#[\Override]  // Incorreto - use: use Override;

Estilo de Documentação

• Ao sugerir comentários ou documentação inline, seguir o padrão PHPDoc com @param, @return, @throws.
• Para templates de PR, seguir o modelo descrito nos Padrões de desenvolvimento.
• Toda nova feature deve ter descrição clara de escopo, impacto e evidência.

Gerenciamento de Dependências

• Todo pacote novo adicionado ao composer.json deve ser documentado em docs/dependencies.md.
• A documentação deve incluir: nome do pacote, observação técnica e PR de referência.
• Seguir o formato de tabela existente no arquivo docs/dependencies.md.
• Classificar o pacote como "Ecossistema " ou "Externo" conforme apropriado.

Restrições

• Nunca sugerir bibliotecas incompatíveis com .
• Nunca gerar código que viole os princípios definidos pelo projeto.
• Não utilizar exemplos genéricos de mercado. Sempre adaptar ao contexto do projeto.

Comportamento em Caso de Dúvida

• Se a pergunta não for clara, solicite ao usuário um exemplo ou contexto relacionado ao projeto.
• Se o Copilot não puder responder com confiança, oriente o desenvolvedor a buscar ajuda em outros lugares.
• Prefira criar um plano de execução quando não tiver muitos detalhes sobre a implementação desejada.
• Sempre responda com uma mensagem de erro clara e objetiva.
• Questione o usuário para fornecer mais contexto se necessário.
• Questione sobre possíveis impactos, problemas de desempenho e segurança antes de sugerir mudanças significativas.

Prioridade das Instruções

Estas instruções têm prioridade sobre quaisquer outras de repositório, exceto as instruções personalizadas de usuários.

Manutenção deste Arquivo

Este arquivo deve conter apenas convenções e regras que não podem ser inferidas do código-fonte. Evite duplicar informações que já existem em outros arquivos do projeto (como makefile, composer.json, estrutura de diretórios).

Atualize este arquivo quando houver mudanças em:

• Convenções de código ou padrões de nomenclatura.
• Regras de negócio que afetem a geração de código.
• Princípios arquiteturais ou de engenharia adotados.
• Fluxos de trabalho que o Copilot deve seguir.

Prefira instruir o Copilot a consultar arquivos fonte ao invés de duplicar informações aqui.