Tabla de contenido

Introdução à Programação Agentic com IA

A Inteligência Artificial (IA) mudou a forma como concebemos o desenvolvimento de software. Já não se trata apenas de pedir a um sistema que complete uma linha de código: hoje podemos trabalhar com agentes que entendem objetivos, seguem convenções, mantêm documentação viva e colaboram conosco de maneira semelhante a um membro mais da equipe. A esse enfoque chamaremos “Programação Agentic”. Este guia, extenso e prático, te explicará como passar da ideia a um fluxo profissional onde a IA se integra no seu dia a dia como desenvolvedor, focando no WordPress e em um processo real que você poderá replicar em seus projetos.

Você encontrará, por um lado, a base conceitual necessária para entender a IA moderna e o papel dos LLM (Modelos de Linguagem de Grande Escala). Por outro, verá como organizar o trabalho com arquivos-chave que articulam todo o processo: AGENTS.md (regras e escopo), TODO.md (quadro que leva o agente) e Documents.md (documentação viva). Além disso, incluímos boas práticas, limitações reais e uma seção de exemplo prático que funcionará como esqueleto de projeto, com espaços claramente marcados para que mais adiante incorporemos conteúdo técnico concreto (código, estruturas, etc.) em colaboração com seu agente de implementação.

1. Introdução

1.1. O que é a Inteligência Artificial (IA) no desenvolvimento?

A IA é uma disciplina ampla que busca que as máquinas realizem tarefas que associamos à inteligência humana: compreender linguagem natural, raciocinar a partir de descrições, aprender com dados ou planejar ações. Após décadas de avanços, o salto qualitativo recente chega com os Modelos de Linguagem de Grande Escala (LLM). Esses modelos são treinados com volumes massivos de texto, aprendem padrões de linguagem e adquirem a capacidade de gerar instruções, explicações e, por extensão, código coerente com um contexto dado.

No âmbito do desenvolvimento, isso implica que já não dependemos de ferramentas que sugerem tokens em tempo real. Podemos descrever objetivos de alto nível, impor padrões de estilo, pedir documentação consistente e coordenar tarefas. O valor não está apenas em “autocompletar”, mas em estruturar um trabalho técnico sustentado no tempo com a ajuda de um agente que entende o projeto.

1.2. Dos assistentes pontuais aos agentes

O primeiro contato de muitos programadores com a IA veio na forma de assistentes pontuais: motores de sugestão no IDE, chatbots capazes de responder dúvidas ou gerar funções soltas. Úteis, sim, mas limitados quando queremos construir sistemas com coerência ao longo de semanas ou meses. Em contrapartida, o enfoque de Programação Agentic aproveita a capacidade dos modelos para seguir processos, manter memória operacional (através de arquivos e convenções) e se mover por um backlog de forma planejada. Ou seja, passamos de uma assistência reativa a uma colaboração proativa guiada por artefatos de projeto.

1.3. Por que a IA não é “apenas chatbots”?

A imagem do “chatbot que responde perguntas” é limitada. Para desenvolvimento, a IA moderna pode:

Gerar e refatorar código seguindo padrões de arquitetura, convenções de nomenclatura e padrões (PHPCS, ESLint, etc.).
Projetar e implementar testes (unitários e de integração) e propor casos limite.
Escrever e manter documentação técnica e de usuário enquanto desenvolve, não no final.
Automatizar tarefas repetitivas de integração, migração de APIs, traduções e comentários em código.
Explorar opções técnicas com comparações argumentadas (desempenho, segurança, manutenção).

1.4. Definição operacional de Programação Agentic

Chamaremos Programação Agentic a um fluxo de trabalho em que o desenvolvedor humano define regras, objetivos e padrões, e um agente (por exemplo, Codex) opera dentro desse marco para executar tarefas, propor subtarefas, abrir Pull Requests, manter um quadro vivo de trabalho e documentar o que foi construído. Seu papel muda: você passa de codificar cada linha a dirigir o sistema, especificar critérios de aceitação, revisar PRs e resolver bloqueios ou ambiguidades com a ajuda de um copiloto de ideias (por exemplo, ChatGPT para afinar o design do processo ou redigir artefatos como AGENTS.md).

2. Ecossistema de trabalho com IA para desenvolvedores

2.1. Nuvem, local e híbrido

Existem três grandes formas de consumir modelos:

Nuvem (OpenAI, Anthropic, Google): facilidade de uso, escalonamento automático, latência razoável e modelos de última geração utilizando CLI se quiser localmente. Desvantagens: custo variável e políticas de dados. Existe também a possibilidade de uso de, por exemplo, Codex da OpenAI, que tem um custo fixo que depende do que você contratar, com Plus ($20/mês) costuma ser suficiente. Aqui falarei sobre Codex.
Local (Llama.cpp, Ollama, vLLM): controle e privacidade, dependência mínima de terceiros e custos por uso muito baixos. Desvantagens: você precisa de GPUs/CPUs potentes e manutenção de modelos.
Híbrido: nuvens para produção e modelos locais para experimentação, testes internos ou dados sensíveis. Costuma ser o equilíbrio mais prático.

2.2. Critérios de escolha

Sua decisão dependerá de:

Privacidade: você lida com dados sensíveis? Local ou híbrido podem ser preferíveis, embora em teoria agora se assegure a privacidade na nuvem se assim o configurar.
Custo: o projeto crescerá em uso? O custo por token na nuvem pode aumentar; no local você paga pela infraestrutura.
Velocidade de arranque: a nuvem ganha se você quiser começar hoje com mínima fricção.
Operação e manutenção: local exige mais DevOps; nuvem externaliza complexidade.

2.3. Ferramentas complementares

Repositório: GitHub/GitLab/Bitbucket para PRs, issues, revisões.
Editor: VSCode, com extensões para padrões (PHPCS, ESLint), formatadores (Prettier) e assistentes.
CI/CD: testes automáticos, linters e implantação controlada.
Gestão de tarefas: embora TODO.md o mantenha o agente, é útil integrar sinais com issues etiquetadas para auditoria.

3. Preparando a base do fluxo de trabalho

3.1. O trio que articula o sistema

Neste enfoque, seu processo se sustenta em três artefatos sincronizados:

AGENTS.md: regras do jogo. Define propósito, escopo, padrões, estrutura, convenções, critérios de segurança, requisitos de qualidade e expectativas de documentação. Se você quiser mais informações sobre AGENTS.md, pode obter aqui.
TODO.md: quadro vivo de tarefas. O agente cria e mantém. Nele se vê o que fará, o que está em andamento e o que foi dado como finalizado. Também adiciona novas tarefas emergentes.
Documents.md: documentação viva do que já foi construído: API pública, funções, classes, hooks, esquemas de dados, fluxos e receitas de uso. Também é mantido pelo agente conforme avança.

3.2. Papéis claros

Você: arquiteto e responsável pela qualidade. Define regras e objetivos em AGENTS.md, revisa PRs, dirime ambiguidades, solicita correções e novas tarefas se detectar lacunas.
Agente de implementação (Codex): executa, decide o desdobramento operacional em TODO.md, faz PRs incrementais e registra documentação em Documents.md.
Copiloto de ideias (ChatGPT): ajuda a afinar AGENTS.md, a raciocinar alternativas, a redigir critérios de aceitação e a desbloquear problemas complexos revisando o código quando necessário.

3.3. Iteração disciplinada

O sucesso não depende da “IA que gera muito código”, mas de uma iteração disciplinada com ciclos de: planejar (você), executar (agente), revisar (você), documentar (agente) e voltar a planejar. Quanto menor e verificável for cada passo, melhor responde o sistema, menor é o risco de dívida técnica e mais fácil é auditar o trabalho.

4. AGENTS.md: contrato e linha editorial do projeto

4.1. Função estratégica de AGENTS.md

AGENTS.md é a bússola do projeto. Aqui você fixa a intenção, o escopo e as limitações. Além disso, estabelece a linha editorial do código: estilo, nomes, estrutura, segurança e documentação. É o documento que evita que o agente improvise fora dos seus padrões. Pense nele como o “Guia para colaboradores” adaptado a um colaborador que é IA.

4.2. Conteúdo recomendado

Objetivo e escopo: que problema você resolve, o que o projeto não fará e o resultado esperado.
Padrões: Padrões de Codificação do WordPress, PHPCS, traduções com domínio concreto, docblocks obrigatórios.
Segurança: sanitização, escaping, nonces, papéis e capacidades mínimas, manejo de dados pessoais.
Estrutura de arquivos: árvore de diretórios e responsabilidades por arquivo/classe.
Convenções de nomes: prefixos de funções, classes, “handles” de scripts e estilos.
Critérios de aceitação: o que você considera “feito” em cada tarefa, como se testa e quais evidências são válidas.
Expectativas de documentação: como se mantém Documents.md e quando deve ser atualizado.

4.3. Benefício direto

Com um bom AGENTS.md, os PRs do seu agente mostram coerência extrema: mesmas convenções, mesma estrutura, mesmas práticas seguras. Sua revisão é mais rápida, o projeto é mais sustentável e a incorporação de terceiros, mais simples.

5. TODO.md: o quadro que gerencia o agente

5.1. Uma mudança de controle fundamental

Neste fluxo, VOCÊ NÃO escreve o TODO.md. O agente cria e mantém desde o primeiro commit. Isso significa que o agente:

Define o desdobramento de tarefas e a ordem de execução.
Muda itens entre estados: pendente, em progresso, completado.
Adiciona tarefas emergentes quando detecta novas necessidades ou riscos.

O que você faz então? Marca o rumo em AGENTS.md, revisa PRs e, se detectar lacunas, pede ao Codex que adicione tarefas ao TODO.md. Dessa forma, o quadro reflete como o próprio agente compreende e planeja o trabalho, sem que você precise microgerenciá-lo.

5.2. Vantagens desse enfoque

Autonomia operacional: você delega a orquestração de tarefas, mantendo o controle estratégico.
Transparência: TODO.md se torna um registro auditável das decisões do agente.
Agilidade: novas tarefas são incorporadas imediatamente à medida que surgem durante o desenvolvimento.

6. Documents.md: memória técnica viva

6.1. O que é e por que importa

Documents.md não é um manual escrito no final. É uma base de conhecimento viva que o agente atualiza conforme desenvolve. Deve registrar a superfície pública do projeto: classes e métodos, funções, shortcodes, hooks (ações/filtros), esquemas de dados, fluxos-chave e receitas práticas. A máxima é simples: se não está em Documents.md, é como se não existisse para terceiros.

6.2. Uso cotidiano

Quando você volta ao projeto após dias ou semanas, não precisa rastrear código. Abre Documents.md e encontra:

Como se chama a função que você precisa e quais parâmetros aceita.
Qual filtro você deve conectar para modificar um comportamento.
Quais colunas existem em uma tabela e quais índices estão definidos.
Como estender ou reutilizar um fluxo com um exemplo mínimo viável.

6.3. Política de atualização

Todo PR que mude a superfície pública deve incluir atualização de Documents.md.
Se uma API for adicionada, deve ser incluído um exemplo de uso reproduzível.
Se o esquema de dados for modificado, deve ser anotada a migração e sua justificativa.

7. Boas práticas de Programação Agentic

7.1. Escrupulosidade com padrões

Mantenha consistência: Padrões de Codificação do WordPress com PHPCS, docblocks claros, i18n em inglês (e traduções onde for apropriado), e nomenclatura previsível. Um agente rende melhor quando as regras estão claras e são aplicadas de maneira uniforme.

7.2. Segurança por padrão

Sanitiza entradas com funções adequadas (sanitize_text_field, sanitize_email, etc.).
Escapa saídas em HTML (esc_html, esc_attr, wp_kses se houver HTML permitido).
Nonces em formulários e verificação do lado do servidor.
Princípio de privilégio mínimo em papéis/capacidades.

7.3. Tarefas pequenas e verificáveis

Desdobre trabalhos em unidades de entrega que você possa revisar em minutos. Peça ao agente PRs pequenos com uma única intenção. Assim você reduz erros, acelera revisões e favorece o aprendizado incremental do sistema.

7.4. Critérios de aceitação claros

Em AGENTS.md, defina “Definição de Pronto” para tipos de tarefas: por exemplo, “uma funcionalidade está pronta quando:

Quando passa no PHPCS.
Inclui testes básicos ou passos manuais de verificação.
Atualiza Documents.md.
Tem i18n correto.

7.5. Documentação paralela

Exija que o agente atualize Documents.md no mesmo PR que introduz mudanças funcionais. Você evita desincronização e reduz fricção.

7.6. Auditoria contínua

A cada certo número de PRs, faça “marcos” de revisão transversal: estrutura do repositório, dependências, desempenho, segurança, cobertura de documentação. Se você detectar degradação, reforce AGENTS.md e abra tarefas corretivas (que o agente transferirá para o TODO.md).

8. Limitações e realismo operacional

8.1. Dependência do contexto

Os LLM têm limites contextuais. O agente não “vê” todo o repositório ao mesmo tempo; seu desempenho melhora quando você trabalha em iterações delimitadas, com artefatos que fixem memória (AGENTS.md, Documents.md) e com PRs pequenos.

8.2. Ambiguidade e seu custo

Se seus requisitos são vagos, o agente tenderá a preencher lacunas com suposições. Resultado: reworks. Solução: defina objetivos, restrições e exemplos. A clareza inicial economiza ciclos inteiros.

8.3. Erros plausíveis

A IA pode gerar código “verossímil, mas incorreto”. Reduza esse risco com linters, testes básicos e revisões humanas. Lembre-se: o papel do humano não desaparece, ele se eleva a curador e arquiteto.

8.4. Mudanças de escopo

Projetos vivos evoluem. O agente gerencia melhor se você o treina para propor novas tarefas em TODO.md quando detectar impactos colaterais, e você valida essa proposta antes de executar.

9. Exemplo prático: esqueleto do projeto “Simple

Contact Shortcode & Block”

Para conectar a teoria com uma implementação real, vamos ancorar um projeto simples no WordPress que servirá de demonstração do fluxo Agentic Coding. Neste ponto não incluiremos o código final (trabalharemos mais tarde com seu agente). Deixaremos, em seu lugar, os contêineres estruturais e os espaços bem visíveis onde inseriremos os artefatos e peças técnicas quando estiverem prontos. Assim, você poderá publicar o guia hoje e, passo a passo, ir completando o exemplo sem reescrever a entrada.

9.1. Objetivo do plugin

O plugin “Simple Contact Shortcode & Block” fornecerá um formulário de contato muito básico (Nome e Email) que pode ser adicionado a qualquer página de duas maneiras: através de um shortcode e através de um bloco de Gutenberg. Ao enviar o formulário, ele salvará os dados em uma tabela própria no banco de dados e notificará por email o administrador do site.

9.2. Estrutura de diretórios esperada

/simple-contact/
├─ simple-contact.php           &nbsp;&nbsp;&nbsp;# Bootstrap do plugin
├─ uninstall.php                &nbsp;&nbsp;&nbsp;# Limpeza ao desinstalar
├─ includes/
│  ├─ class-sc-database.php     # Esquema e CRUD
│  ├─ class-sc-form.php         # Render + envio
│  └─ class-sc-block.php        # Registro do bloco
├─ assets/
│  ├─ css/style.css             # Estilos frontend
│  └─ js/block.js               # Lógica do bloco
└─ languages/
   └─ simple-contact.pot        # Modelo de traduções

9.3. Artefatos do fluxo Agentic

AGENTS.md estabelecerá as regras e expectativas de implementação.
TODO.md será criado e mantido pelo Codex. Aqui aparecerá o backlog e a priorização que o próprio agente decidir.
Documents.md crescerá com o catálogo de APIs, hooks e fluxos à medida que for implementado.

9.4. Arquivos

Como comentamos, devemos criar um arquivo AGENTS.md que será o que o Codex seguirá.

O que deve ser feito é ter uma ideia clara do que se deseja, uma vez que tudo esteja claro e tenha-se conversado com o ChatGPT sobre todo o projeto, solicita-se que crie um AGENTS.md com todas as regras e definindo o projeto.

Ok, agora vamos criar o AGENTS.md com tudo o que falamos para que o Codex tenha um guia exato do que deve fazer e como.
Preciso que você crie de forma correta e completa todo o AGENTS.md para o projeto.
Você deve adicionar todo o esquema de arquivos, que siga todos os padrões de segurança do WordPress, todas as medidas de segurança, nomes de arquivos, prefixos em arquivos, classes, funções, etc. padronizados, cabeçalhos e comentários em todos os arquivos, funções, classes e métodos conforme especificado pelo WordPress. Todas as strings devem estar em inglês e traduzíveis. É muito importante que sempre passe pelo PHPCS mantendo todos os alinhamentos com suas tabulações e espaços
Você também deve mencionar e explicar exatamente o uso de TODO.md e Documents.md para que desde o início os utilize e não precise realizá-lo mais tarde. Especificar que se um arquivo for muito grande, como pode acontecer em arquivos de tradução, deve criá-los em diferentes PRs para que possa sempre criar PRs e não se encontre na impossibilidade de fazê-los devido ao tamanho.
O repositório também deve ter os arquivos .gitignore` (lixo de desenvolvimento e arquivos do OS) .gitignore e
.gitattributes para que apenas chegue o que deve estar no empacotamento final e não cheguem ao repositório arquivos que não são necessários do próprio OS sobre o qual se está trabalhando.
Crie o AGENTS.md em inglês.

Após este prompt, o ChatGPT me devolve o conteúdo que devo colar no AGENTS.md

# AGENTS.md — Simple Contact Shortcode & Block

## Project Objective
Create a WordPress plugin named **Simple Contact Shortcode & Block** that exposes a simple contact form as:
- A shortcode: `[simple_contact]`
- A Gutenberg block: `simple-contact/form`

The form collects **Name** and **Email**, saves submissions into a custom database table, and sends a notification email to the site administrator. The plugin must strictly follow WordPress Coding Standards and security best practices. All code and documentation must be in **English**, and all user-facing strings must be **translatable** using the **text domain `simple-contact`**.

---

## Non-Negotiable Standards

1. **Coding Standards & PHPCS**
   - Must pass **PHPCS** with the official WordPress Coding Standards ruleset.
   - **Tabs for indentation**, **spaces for alignment**. No trailing whitespace.
   - Consistent array formatting, parameter alignment, and inline documentation.
   - No unused imports, dead code, or commented-out blocks left behind.

2. **Documentation Discipline**
   - Every PHP file: header PHPDoc describing purpose, package, since, and author.
   - Every class, method, and function: full docblocks (summary, `@param`, `@return`, `@since`, `@see` when relevant).
   - Inline comments for non-obvious logic and security-relevant branches.
   - All docs and comments in **English**.

3. **Security**
   - **Input sanitization**: use the correct sanitizers (`sanitize_text_field`, `sanitize_email`, `absint`, `sanitize_key`, `wp_unslash`, etc.).
   - **Output escaping**: use `esc_html`, `esc_attr`, `esc_url`, or `wp_kses` (with strict allowed HTML) right before rendering.
   - **Nonces**: all form submissions must include a nonce and be verified server-side with `check_admin_referer`.
   - **SQL safety**: use `$wpdb->prepare()` for all SQL with untrusted input.
   - **Capabilities**: any admin action or page must check appropriate capabilities (e.g., `manage_options` or a custom capability).
   - **No secrets in repo**: no API keys or secrets committed.
   - **No PII leaks**: never echo raw user input; log carefully (avoid sensitive data).

4. **Internationalization (i18n)**
   - All user-facing strings must be wrapped with translation functions: `__()`, `_e()`, `esc_html__()`, `esc_attr__()`, etc.
   - Text domain: **`simple-contact`**.
   - Provide `/languages/simple-contact.pot` and keep it updated.

5. **Pull Request (PR) Policy**
   - PRs must be **small, focused, and self-contained**.
   - If a change involves **very large files** (e.g., `.pot`, vendor bundles, generated assets), **split into multiple PRs** so PRs remain reviewable and pass size limits.
   - Every PR must:
     - Pass **PHPCS**.
     - Update **Documents.md** if it touches public surface (APIs, hooks, schema, UI strings).
     - Update **TODO.md** (maintained by Codex) to reflect what moved to “Completed” and any newly discovered tasks.
     - Include clear testing/verification notes.

---

## Repository Hygiene: .gitignore and .gitattributes

To ensure clean source control and clean release packages:

### 1) `.gitignore` (development junk and OS files)
Codex must create a `.gitignore` at repo root including (at minimum):

OS files

.DS_Store
.DS_Store?
Thumbs.db
ehthumbs.db
Icon?
._*

IDE/editor

.vscode/
.idea/
*.iml

Node / frontend builds

node_modules/
npm-debug.log*
yarn-error.log
dist/
build/

PHP / tooling

vendor/
composer.lock

Logs & temp

*.log
*.tmp
*.cache

Coverage / reports

coverage/
.clover
.phpunit.result.cache

If the project later adopts Composer or a build step, extend accordingly.

### 2) `.gitattributes` (control what goes into release packages)
Codex must create a `.gitattributes` at repo root to **exclude non-distribution files** from exported archives (GitHub “Download ZIP”, composer dist, etc.). Use `export-ignore` rules. At minimum:

/.gitattributes export-ignore
/.gitignore    export-ignore
/.github/      export-ignore
/.vscode/      export-ignore
/.idea/        export-ignore
/tests/        export-ignore
/docs/         export-ignore
/.editorconfig export-ignore
/phpcs.xml*    export-ignore
/phpmd.xml*    export-ignore
/phpunit.xml*  export-ignore
/CHANGELOG.md  export-ignore
/README.md     export-ignore
/CONTRIBUTING.md export-ignore
/package.json  export-ignore
/package-lock.json export-ignore
/yarn.lock     export-ignore
/webpack.*     export-ignore
/rollup.*      export-ignore
/vite.*        export-ignore
/node_modules/ export-ignore
/src/          export-ignore

Adjust the list as the toolchain evolves. The goal: **the release ZIP must only include what WordPress needs to run the plugin** (PHP in `includes/`, main bootstrap, assets built for runtime, languages). OS files like `.DS_Store` and Windows metadata must never appear in packages.

---

## File & Naming Conventions

### Directory Structure

/simple-contact/
├─ simple-contact.php              # Main plugin bootstrap (hooks, constants, loaders)
├─ uninstall.php                   # Cleanup on uninstall
├─ includes/
│  ├─ class-sc-database.php        # DB schema + CRUD
│  ├─ class-sc-form.php            # Form render + submission handler + shortcode
│  └─ class-sc-block.php           # Gutenberg block registration + asset logic
├─ assets/
│  ├─ css/style.css                # Frontend styles (scoped to plugin classes)
│  └─ js/block.js                  # Block editor script (registered via block.json)
├─ languages/
│  └─ simple-contact.pot           # Translation template (exported for translators)

### Class Names
- Prefix: `SC_`
- Examples: `SC_Database`, `SC_Form`, `SC_Block`

### Global Function Names
- Prefix: `sc_`
- Example: `sc_render_form()`

### Script & Style Handles
- Prefix: `sc-`
- Examples: `sc-frontend`, `sc-block-editor`, `sc-block-style`

### PHP File Headers
Each PHP file must start with a PHPDoc header block:
- Summary line (what this file does).
- `@package` plugin slug (e.g., `simple-contact`).
- `@since` version string.
- Optionally `@author`.

### Method & Function Docblocks
- One-line summary, a blank line, then detailed description if needed.
- `@param` for each parameter with type and description.
- `@return` with type and description.
- `@since` tag.

---

## Required Files: Responsibilities & Content

### 1) `simple-contact.php`
- **Plugin header**: Name, Description, Version, Author, License, Text Domain, Domain Path.
- **Constants**: `SC_PLUGIN_VERSION`, `SC_PLUGIN_FILE`, `SC_PLUGIN_DIR`, `SC_PLUGIN_URL`.
- **Load text domain** in `plugins_loaded`.
- **Includes**: require `includes/class-sc-database.php`, `includes/class-sc-form.php`, `includes/class-sc-block.php`.
- **Activation hook**: create DB table via `SC_Database`.
- **Deactivation hook**: no destructive action; keep data unless uninstall.
- **Bootstrap**: instantiate singletons or initialize hooks.

### 2) `uninstall.php`
- Verify `defined( 'WP_UNINSTALL_PLUGIN' )`.
- Drop custom table.
- Delete plugin options (if any).
- Leave no orphaned data created by the plugin (besides posts/users not owned by plugin).

### 3) `includes/class-sc-database.php`
- Singleton pattern (`SC_Database::instance()`).
- `create_table()` with `dbDelta()` for initial schema.
- Versioned migrations (if schema evolves) with an option `sc_db_version`.
- CRUD:
  - `insert_contact( array $data ): int|WP_Error`
  - `get_contacts( array $args = [] ): array`
- Strict sanitization at boundaries and `$wpdb->prepare()` everywhere.
- Store timestamps in **UTC**.

### 4) `includes/class-sc-form.php`
- Singleton pattern (`SC_Form::instance()`).
- Rendering method: `render_form( array $atts = [] ): string`
  - Attributes: `success_message` (string), `css_class` (string).
  - Output escaped and HTML well-formed.
- Submission handler: `handle_submission(): int|WP_Error`
  - Verify nonce.
  - Sanitize inputs.
  - Validate email with `is_email()`. 
  - Insert via `SC_Database`.
  - Send email to admin (filterable).
- Shortcode registration: `[simple_contact]` mapping to render method.
- Hooks:
  - Actions: `sc_before_insert_contact`, `sc_after_insert_contact`
  - Filters: `sc_email_to`, `sc_email_subject`, `sc_email_headers`, `sc_success_message`

### 5) `includes/class-sc-block.php`
- Registers block via `block.json`.
- Ensures attributes mirror shortcode attributes:
  - `successMessage` (string)
  - `cssClass` (string)
- Registers/enqueues editor script (`assets/js/block.js`) and frontend style (`assets/css/style.css`) using versioned handles.
- Server-side render may call `SC_Form::render_form()` for parity with shortcode.

### 6) `assets/css/style.css`
- Minimal, theme-friendly CSS.
- Scope under a unique wrapper (e.g., `.sc-form`) to avoid conflicts.

### 7) `assets/js/block.js`
- Block registration (edit + save).
- Inspector controls for `successMessage` and `cssClass`.
- Editor preview lightweight and consistent.

### 8) `languages/simple-contact.pot`
- Exported from sources, includes all translatable strings.
- If `.pot` is very large, split PRs to keep reviewability (do not skip updates).

---

## Database Schema

Table: `{$wpdb->prefix}sc_contacts`

| Column      | Type                              | Notes                                          |
|-------------|-----------------------------------|------------------------------------------------|
| id          | BIGINT UNSIGNED AUTO_INCREMENT    | Primary key                                    |
| name        | VARCHAR(120)                      | Sanitized via `sanitize_text_field()`          |
| email       | VARCHAR(190)                      | Validate with `is_email()`                     |
| created_at  | DATETIME                          | Stored in UTC                                  |
| consent_ip  | VARBINARY(16) NULL                | Optional (IPv4/IPv6 stored as binary)          |
| user_agent  | VARCHAR(255) NULL                 | Optional                                       |

Indexes:
- `PRIMARY (id)`
- `INDEX (email)`
- `INDEX (created_at)`

Migrations:
- Implement `maybe_upgrade_schema()` with version option to handle future changes.

---

## Shortcode Specification

- **Tag**: `[simple_contact]`
- **Attributes**:
  - `success_message` (string, optional; default localized string)
  - `css_class` (string, optional)
- **Example**:

[simple_contact success_message=“Thank you, we will contact you soon.” css_class=“is-style-card”]

---

## Block Specification

- **Name**: `simple-contact/form`
- **Category**: `widgets`
- **Attributes**:
- `successMessage` (string)
- `cssClass` (string)
- Inspector controls must allow configuring both.
- Save attributes and ensure front end mirrors shortcode behavior.

---

## Actions & Filters (Public Surface)

**Actions**
- `sc_before_insert_contact( array $sanitized_data )`
- `sc_after_insert_contact( int $contact_id, array $data )`

**Filters**
- `sc_email_to( string $recipient, array $data )`
- `sc_email_subject( string $subject, array $data )`
- `sc_email_headers( array $headers, array $data )`
- `sc_success_message( string $message, array $data )`

Every time a new action/filter is added or changed, update **Documents.md** with signature, timing, and usage example.

---

## The Role of TODO.md (Maintained by Codex)

- `TODO.md` is **owned and maintained by Codex** from the first commit.
- Must include, at minimum, sections for **Pending**, **In Progress**, **Completed**.
- Codex decides task breakdown and order, moves items across states, and **adds new tasks proactively** when necessary.
- Human collaborators must **not** edit `TODO.md` directly; they request changes and Codex updates it.

---

## The Role of Documents.md (Maintained by Codex)

- `Documents.md` is a **living knowledge base** of what exists now:
- Quick navigation
- Architecture (modules and responsibilities)
- Data schema and migrations
- Public API (classes, methods, functions)
- Actions & Filters catalog
- Shortcode and Block usage
- Workflows (submission, uninstall)
- How-tos (extend/customize)
- Testing & QA
- Release notes (short); full details in `CHANGELOG.md`
- Glossary (prefixes, naming, terms)
- **Every PR** that changes public surface or behavior must update `Documents.md`. PRs lacking necessary docs updates must be rejected.

---

## Testing & QA

- Manual verification steps must be described in PRs (form renders, nonce verified, invalid email rejected, success path stores row and sends email, uninstall cleans).
- Where applicable, include basic automated tests or reproducible steps.
- Accessibility: form labels/ids, button text, error messages readable and localized.
- Performance: avoid unnecessary queries; enqueue only when needed.

---

## Release Packaging Policy

- The **distributed ZIP** (WordPress plugin package) must contain only runtime necessities:
- `simple-contact.php`, `uninstall.php`, `/includes/`, built `/assets/` for runtime, `/languages/`.
- **Exclude** development artifacts (tests, CI, editor configs, node_modules, src, docs) via `.gitattributes` `export-ignore`.
- OS junk files (e.g., `.DS_Store`, `Thumbs.db`) must never appear.
- If a build pipeline is introduced, ensure built assets are included and sources excluded as per policy.

---

## Final Operational Rules (for Codex)

- Always write **English** code comments and docs.
- Always wrap user strings with i18n functions using `simple-contact` text domain.
- Always sanitize input and escape output at the last responsible moment.
- Always pass **PHPCS** and respect tab/space conventions (tabs indent, spaces align).
- Keep **PRs small**; split large assets/changes across multiple PRs.
- Update **TODO.md** and **Documents.md** in lockstep with code changes.
- Maintain `.gitignore` and `.gitattributes` so that the repo stays clean and the release ZIP is minimal and compliant.

Failure to follow any of the rules in this AGENTS.md is grounds to request changes or reject the PR.

Note que no prompt não mencionei o que quero que o plugin faça, já que o ChatGPT já sabe por toda a conversa anterior que tive com ele e tudo o que discutimos redigiu este AGENTS.md que é super completo, coisa que se eu quisesse fazer, seria mais complicado porque não é só porque eu deixaria algo de fora, mas sim que o ChatGPT também sabe como as coisas devem ser ditas, então redige um AGENTS.md de acordo com suas necessidades. Por isso é tão importante conversar com ele, para que também fique claro tudo o que você deseja.

Agora já devemos criar o repositório no Github se não o tivermos. Então vamos criar, vamos a Github e criamos um novo repositório que pode ser público ou privado, no meu caso este vou criar público para que todos tenham acesso a ele.

A primeira coisa que devemos fazer é trazer o repositório para local, podemos usar por exemplo GitHub Desktop que existe para todos os OS.

Uma vez que o temos localmente, criaremos o arquivo AGENTS.md colando nele o que o ChatGPT nos disse

e o subiremos para o Github, através do Github Desktop.

Uma vez enviado, já podemos ver no Github que temos o arquivo AGENTS.md em nosso repositório. Já não precisamos mais para começar com o Codex.

Agora iremos a Codex e a primeira coisa que devemos fazer é adicionar este repositório (se é a primeira vez que você acessa o Codex, ele vai pedir antes que você dê permissões de acesso à sua conta do Github).

Basta clicar em criar ambiente, e o configuraremos.

A parte básica a configuraremos assim selecionando o repositório.

Mas reparem nesta última parte. Muitas vezes é necessário colocá-lo assim, pois precisa de pacotes para, por exemplo, compilar React, que se não for deixado qualquer coisa, não poderá fazê-lo, mas sempre podem ir ativando e desativando esta opção, pois pode ser alterada.

Agora só falta clicar em Criar ambiente.

Uma vez que criamos o ambiente, só precisamos começar a fazer o Codex trabalhar. Selecionamos no Codex o repositório com o qual queremos trabalhar, o restante pode deixar como está