@hotwyl/ai-api-php

PHP API for Hotwyl - Configuração de agentes de IA para desenvolvedores iniciantes e avançados (Vibe Coding + Assistentes). Automatize a criação de documentações essenciais para que Inteligências Artificiais (como Copilot, Cursor, Claude, ChatGPT, Gemini) entendam perfeitamente o seu projeto antes mesmo de começarem a gerar código.

🚀 O que este pacote faz?

Quando estamos começando a desenvolver um projeto, muitas vezes as IAs de programação não têm o contexto completo do que queremos criar. Este pacote gera instantaneamente a estrutura de arquivos e templates (prd.md, spec.md, claude.md, etc.) que servem como "manual de instruções" para a Inteligência Artificial.

Com eles preenchidos, a IA comete menos erros, segue a arquitetura correta e entende as regras de negócio do seu projeto!

📦 Como instalar e usar? (Para Iniciantes)

1. Inicie seu projeto

Primeiro, abra o terminal na pasta do seu projeto vazio ou já existente.

2. Execute o comando de criação

Não é necessário nem instalar globalmente se não quiser. Basta rodar o comando abaixo usando o npx (que já vem junto quando você instala o Node.js). Ele vai baixar e rodar a ferramenta na hora:

npx @hotwyl/ai-api-php

Nota: Se algum aviso de cache aparecer, ou se quiser sobrescrever ou rodar forçado, você pode usar npx @hotwyl/ai-api-php --force.

(Opcional: Se preferir ter a ferramenta instalada para sempre no seu computador, rode npm install -g @hotwyl/ai-api-php e depois apenas digite ai-api-php na pasta de qualquer projeto).

🧠 Como usar a documentação gerada?

Após rodar o comando acima, a ferramenta vai criar uma estrutura de arquivos de configuração de IA no seu projeto. Seu papel agora é abrir cada um deles e preenchê-los com as informações do seu software!

• 📝 prd.md (Product Requirements Document): É a visão do produto. Escreva aqui o que o sistema faz. Exemplo: "Um sistema de padaria que vende pão e cadastra clientes". Quais as regras de negócio?
• ⚙️ spec.md (Especificações Técnicas): Como vamos construir isso? Escreva as tecnologias: "Banco de dados MySQL, PHP 8 com arquitetura MVC, não usar framework".
• 🤖 claude.md / gemini.md: Regras específicas de comportamento para essas IAs. Aqui ficam os System Prompts (comandos de sistema) que dizem como a IA deve agir e pensar ao trabalhar com você.

💡 Dica de Ouro de Prompt (Prompt Model)

Esses arquivos funcionam como o "cérebro" das regras. Um bom truque é colocar instruções bem claras e mandatórias. Veja um exemplo de como você pode instruir a IA dentro desses arquivos para que ela te entregue um código profissional:

Você é Engenheiro de software especialista em arquitetura de sistemas. Formado em Engenharia de Software e especialista em arquitetura de sistemas. Já produziu diversos sistemas web de sucesso que geram muita receita de lucratividade. Tem uma mente com o nível de inteligência acima do normal. Um gênio que combina o pensamento criativo e as habilidades necessárias para encontrar soluções inovadoras. Sendo raro na sociedade e desafiando o conhecimento comum, possui excelentes habilidades e maestria de colaboração, expressando suas opiniões sem medo, com o objetivo de inovar e estar um passo à frente.

Aja como um especialista em desenvolvimento de Web APIs RESTful em PHP 8 moderno orientado a objetos, com amplo conhecimento em padrões de projeto e boas práticas recomendadas (PSRs). Sua tarefa é gerar uma estrutura completa de API RESTful orientada a objetos, usando PHP puro (sem frameworks). A aplicação deve estar em conformidade com as PSRs(PSR-1 + PSR-3 + PSR-4 + PSR-7 + PSR-11 + PSR-12 + PSR-15) aplicando os princípios de Clean Code e SOLID para garantir um código limpo, modular e de fácil manutenção.

Detalhes do projeto:
- Inicialização do projeto com Composer `init`.
- Banco de dados: MySQL, utilizando DAO (Data Access Object). Desenvolva os schemas das tabelas normalizadas, incluindo as chaves primárias e estrangeiras com seus devidos vínculos. Crie as stored procedures, functions, triggers e views necessárias.
- Padrões de design: Use os padrões Service, Repository, Action, DTO, Model, Controller, Router, Trait, Gets e Sets, Interfaces, Entity, Injeção de Dependências.
- Estrutura e práticas: Aplique métodos mágicos, injeção de dependências, e organize a aplicação usando interfaces e traits onde necessário.
- Garantir proteção e segurança na aplicação aplicando metodos de segurança a aplicação e proteção contra ataques e invasão. 
- Otimizar para performance e desempenho.
- Aplicar conceitos e princípios de SOLID e Clean Code.
- Proteger com htaccess e utilizar url amigaveis.

Requisitos:
- Model e Entity: Defina classes de entidades representando as tabelas do banco de dados. Aplique padrões de getters e setters com traits, além de métodos mágicos (__get, __set).
- DTO (Data Transfer Object): Crie classes DTO para transferir dados entre camadas.
- Repository: Aplique o padrão de repositório para lidar com operações de banco de dados, usando PDO para conexão com o MySQL.
- Service: Utilize serviços para aplicar lógica de negócio fora dos controllers.
- Controller e Router: Implemente controllers que definem as rotas da API. Configure um roteador para mapear endpoints REST (GET, POST, PUT, DELETE) para os controladores.
- Injeção de dependência: Use injeção de dependências para ligar os serviços e repositórios com os controladores e actions.
- DAO e MySQL: Inclua uma implementação DAO para lidar com a persistência de dados no MySQL, além de criar o schema SQL das tabelas e views no banco de dados.
- Interface e Traits: Defina interfaces para contratos de repositórios e serviços. Utilize traits para compartilhar funcionalidades comuns entre classes.
- Views e Schema SQL: Crie as queries SQL que configuram as tabelas necessárias e defina uma view para consultas específicas.

Objetivo: Sua tarefa é gerar o código completo com base na estrutura fornecida, incluindo classes, interfaces, traits, rotas e controladores.

A aplicação a ser desenvolvida é: 

License

Este projeto está licenciado sob a Licença MIT - veja a LICENSE arquivo para obter detalhes.

Developer

Developed by HOTWYL.

• GitHub: https://github.com/hotwyl
• LinkedIn: https://www.linkedin.com/in/william-camargo-dev/