npm package: @hotwyl/ai-api-php
Description: Automatize a configuração de agentes de IA (Copilot, Cursor, Claude) no seu projeto. Gere a documentação perfeita (Vibe Coding) para que a Inteligência Artificial entenda seu código e programe junto com você de forma fácil e estruturada.
Author: hotwyl
Latest version: 1.0.4

# @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:

```bash
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:

```bash
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](LICENSE) arquivo para obter detalhes.

## Developer

Developed by **HOTWYL**.

- **GitHub:** [https://github.com/hotwyl](https://github.com/hotwyl)
- **LinkedIn:** [https://www.linkedin.com/in/william-camargo-dev/](https://www.linkedin.com/in/william-camargo-dev/)