Introdución ao Agentic Coding con IA
A Intelixencia Artificial (IA) cambiou a forma en que concebimos o desenvolvemento de software. Xa non se trata só de pedirlle a un sistema que complete unha liña de código: hoxe podemos traballar con axentes que entenden obxectivos, seguen convencións, manteñen documentación viva e colaboran connosco de maneira similar a un membro máis do equipo. A este enfoque chamaremos “Agentic Coding”. Esta guía, extensa e práctica, explicará como pasar da idea a un fluxo profesional onde a IA se integra na túa día a día como desenvolvedor, centrando a atención en WordPress e nun proceso real que poderás replicar nos teus proxectos.
Encontrarás, por un lado, a base conceptual necesaria para entender a IA moderna e o papel dos LLM (Large Language Models). Por outro, verás como organizar o traballo con arquivos clave que articulan todo o proceso: AGENTS.md (reglas e alcance), TODO.md (taboleiro que leva o axente) e Documents.md (documentación viva). Ademais, incluímos boas prácticas, limitacións reais e unha sección de exemplo práctico que funcionará como esqueleto de proxecto, con espazos claramente marcados para que máis adiante incorporemos contido técnico concreto (código, estruturas, etc.) en colaboración co teu axente de implementación.
1. Introdución
1.1. ¿Que é a Intelixencia Artificial (IA) no desenvolvemento?
A IA é unha disciplina ampla que persegue que as máquinas realicen tarefas que asociamos coa intelixencia humana: comprender linguaxe natural, razonar a partir de descricións, aprender de datos ou planificar accións. Tras décadas de avances, o salto cualitativo recente chega cos Large Language Models (LLM). Estes modelos adestran con volumes masivos de texto, aprenden patróns de linguaxe e adquiren a capacidade de xerar instrucións, explicacións e, por extensión, código coherente cun contexto dado.
No ámbito do desenvolvemento, isto implica que xa non dependemos de ferramentas que suxiren tokens ao voo. Podemos describir obxectivos de alto nivel, impor estándares de estilo, pedir documentación consistente e coordinar tarefas. O valor non está só en “autocompletar”, senón en estructurar un traballo técnico sostido no tempo coa axuda dun axente que entende o proxecto.
1.2. Dos asistentes puntuais aos axentes
O primeiro contacto de moitos programadores coa IA veu da man de asistentes puntuais: motores de suxestión no IDE, chatbots capaces de responder dúbidas ou xerar funcións soltas. Útiles, si, pero limitados cando queremos construir sistemas con coherencia ao longo de semanas ou meses. En cambio, o enfoque de Agentic Coding aproveita a capacidade dos modelos para seguir procesos, manter memoria operacional (a través de arquivos e convencións) e moverse por un backlog de forma planificada. É dicir, pasamos dunha asistencia reactiva a unha colaboración proactiva guiada por artefactos de proxecto.
1.3. ¿Por que a IA non son “só chatbots”?
A imaxe do “chatbot que responde preguntas” queda curta. Para desenvolvemento, a IA moderna pode:
- Xerar e refactorizar código seguindo patróns de arquitectura, convencións de nomenclatura e estándares (PHPCS, ESLint, etc.).
- Deseñar e implementar probas (unitarias e de integración) e propor casos límite.
- Escribir e manter documentación técnica e de usuario mentres desenvolve, non ao final.
- Automatizar tarefas repetitivas de integración, migración de APIs, traduccións e comentarios en código.
- Explorar opcións técnicas con comparativas argumentadas (rendemento, seguridade, mantemento).
1.4. Definición operativa de Agentic Coding
Chamaremos Agentic Coding a un fluxo de traballo no que o desenvolvedor humano define regras, obxectivos e estándares, e un axente (p. ex. Codex) opera dentro dese marco para executar tarefas, propor subtarefas, abrir Pull Requests, manter un taboleiro vivo de traballo e documentar o construido. O teu rol cambia: pasas de codificar cada liña a dirixir o sistema, especificar criterios de aceptación, revisar PRs, e resolver bloqueos ou ambigüedades coa axuda dun copiloto de ideas (por exemplo, ChatGPT para afinar o deseño do proceso ou redactar artefactos como AGENTS.md).
2. Ecosistema de traballo con IA para desenvolvedores
2.1. Nube, local e híbrido
Existen tres grandes formas de consumir modelos:
- Nube (OpenAI, Anthropic, Google): facilidade de uso, escalado automático, latencia razoable e modelos de última xeración utilizando CLI se se quere en local. Inconvenientes: custo variable e políticas de datos. Existe tamén a posibilidade de uso de por exemplo Codex de OpenAI, que ten un custo fixo que depende de que contrates, con Plus ($20/mes) adoita ser suficiente. Aquí falaré de Codex.
- Local (Llama.cpp, Ollama, vLLM): control e privacidade, dependencia mínima de terceiros e custos por uso moi baixos. Inconvenientes: necesitas GPU/CPU potentes e mantemento de modelos.
- Híbrido: nubes para produción e modelos locais para experimentación, probas internas ou datos sensibles. Suele ser o equilibrio máis práctico.
2.2. Criterios de elección
A túa decisión dependerá de:
- Privacidade: ¿tratas datos sensibles? Local ou híbrido poden ser preferibles, aínda que en teoría agora se asegura a privacidade na nube se así o configuras.
- Custo: ¿o proxecto crecerá en uso? O custo por token na nube pode aumentar; en local pagas a infraestrutura.
- Velocidade de arranque: a nube gaña se queres comezar hoxe con mínima fricción.
- Operación e mantemento: local esixe máis DevOps; nube externaliza complexidade.
2.3. Ferramentas complementarias
- Repositorio: GitHub/GitLab/Bitbucket para PRs, issues, revisións.
- Editor: VSCode, con extensións para estándares (PHPCS, ESLint), formateadores (Prettier), e asistentes.
- CI/CD: test automáticos, linters e despregue controlado.
- Gestión de tarefas: aínda que TODO.md o manterá o axente, é útil integrar sinais con issues etiquetadas para auditoría.
3. Preparando a base do fluxo de traballo
3.1. O trío que articula o sistema
Neste enfoque, o teu proceso sostense en tres artefactos sincronizados:
- AGENTS.md: regras do xogo. Define propósito, alcance, estándares, estrutura, convencións, criterios de seguridade, requisitos de calidade e expectativas de documentación. Se queres máis información sobre AGENTS.md, pode obter aquí.
- TODO.md: taboleiro vivo de tarefas. Créao e mantén o axente. Nel vése que fará, que está en curso e que deu por finalizado. Tamén engade novas tarefas emerxentes.
- Documents.md: documentación viva do xa construido: API pública, funcións, clases, hooks, esquemas de datos, fluxos e receitas de uso. Tamén o mantén o axente conforme avanza.
3.2. Roles claros
- Ti: arquitecto e responsable de calidade. Fixas regras e obxectivos en AGENTS.md, revisas PRs, dirimes ambigüedades, solicitas correccións e novas tarefas se detectas buratos.
- Axente de implementación (Codex): executa, decide o desglose operativo en TODO.md, fai PRs incrementais e rexistra documentación en Documents.md.
- Copiloto de ideas (ChatGPT): axúdache a afinar AGENTS.md, a razonar alternativas, a redactar criterios de aceptación e a desbloquear problemas complexos revisando o código cando fai falta.
3.3. Iteración disciplinada
O éxito non depende de “a IA que xera moito código”, senón dunha iteración disciplinada con ciclos de: planificar (ti), executar (axente), revisar (ti), documentar (axente), e volver a planificar. Canto máis pequeno e verificable sexa cada paso, mellor responde o sistema, menor é o risco de débeda técnica e máis fácil é auditar o traballo.
4. AGENTS.md: contrato e liña editorial do proxecto
4.1. Función estratéxica de AGENTS.md
AGENTS.md é a brúxula do proxecto. Aquí fixas a intención, o alcance e as limitacións. Ademais, estableces a liña editorial do código: estilo, nomes, estrutura, seguridade e documentación. É o documento que evita que o axente improvise fóra dos teus estándares. Pensa nel como o “Guide for contributors” adaptado a un colaborador que é IA.
4.2. Contido recomendado
- Obxectivo e alcance: que problema resolves, que non fará o proxecto e o resultado esperado.
- Estándares: WordPress Coding Standards, PHPCS, traduccións con dominio concreto, docblocks obrigatorios.
- Seguridade: sanitización, escaping, nonces, roles e capacidades mínimas, manexo de datos persoais.
- Estructura de arquivos: árbore de directorios e responsabilidades por arquivo/clase.
- Convencións de nomes: prefixos de funcións, clases, “handles” de scripts e estilos.
- Criterios de aceptación: que consideras “feito” en cada tarefa, como se proba e que evidencias son válidas.
- Expectativas de documentación: como se mantén Documents.md e cando se debe actualizar.
4.3. Beneficio directo
Con un bo AGENTS.md, os PRs do teu axente amosan coherencia extrema: mesmas convencións, mesma estrutura, mesmas prácticas seguras. A túa revisión é máis rápida, o proxecto é máis mantenible e a incorporación de terceiros, máis sinxela.
5. TODO.md: o taboleiro que xestiona o axente
5.1. Un cambio de control fundamental
Neste fluxo, NON escribes ti o TODO.md. Créao e mantén o axente desde o primeiro commit. Iso significa que o axente:
- Define o desglose de tarefas e o orde de execución.
- Moe ítems entre estados: pendente, en progreso, completado.
- Añade tarefas emerxentes cando detecta novas necesidades ou riscos.
¿Que fas ti entón? Marcas o rumbo en AGENTS.md, revisas PRs e, se detectas lagunas, pides a Codex que añada tarefas ao TODO.md. Deste xeito, o taboleiro reflicte como o propio axente comprende e planifica o traballo, sen que teñas que microxestionalo.
5.2. Ventaxes deste enfoque
- Autonomía operativa: delegas a orquestración de tarefas, conservando o control estratéxico.
- Transparencia: TODO.md convértese nun rexistro auditable das decisións do axente.
- Agilidade: novas tarefas incorpóranse de inmediato segundo xurden durante o desenvolvemento.
6. Documents.md: memoria técnica viva
6.1. Qué é e por que importa
Documents.md non é un manual escrito ao final. É unha base de coñecemento viva que o axente actualiza conforme desenvolve. Debe rexistrar a superficie pública do proxecto: clases e métodos, funcións, shortcodes, hooks (actions/filters), esquemas de datos, fluxos clave e receitas prácticas. A máxima é sinxela: se non está en Documents.md, é como se non existise para terceiros.
6.2. Uso cotián
Cando volves ao proxecto tras días ou semanas, non necesitas rastrexar código. Abres Documents.md e atopas:
- Como se chama a función que necesitas e que parámetros acepta.
- Que filtro debes enganchar para modificar un comportamento.
- Que columnas hai nunha táboa e que índices están definidos.
- Como estender ou reutilizar un fluxo cun exemplo mínimo viable.
6.3. Política de actualización
- Todo PR que cambie a superficie pública debe incluír actualización de Documents.md.
- Se se engade unha API, debe engadirse un exemplo de uso reproducible.
- Se se modifica o esquema de datos, debe anotarse a migración e a súa xustificación.
7. Boas prácticas de Agentic Coding
7.1. Escrupulosidade con estándares
Mantén consistencia: WordPress Coding Standards con PHPCS, docblocks claros, i18n en inglés (e traduccións onde proceda), e nomenclatura predecible. Un axente rende mellor cando as regras están claras e aplícanse de maneira uniforme.
7.2. Seguridade por defecto
- Sanitiza entradas con funcións adecuadas (
sanitize_text_field,sanitize_email, etc.). - Escapa saídas en HTML (
esc_html,esc_attr,wp_ksesse hai HTML permitido). - Nonces en formularios e verificación do lado do servidor.
- Principio de privilexio mínimo en roles/capacidades.
7.3. Tarefas pequenas e verificables
Desglosa traballos en unidades de entrega que poidas revisar en minutos. Pide ao axente PRs pequenos cunha soa intención. Así reduces erros, aceleras revisións e favoreces o aprendizaxe incremental do sistema.
7.4. Criterios de aceptación claros
En AGENTS.md, define “Definition of Done” para tipos de tarefas: por exemplo, “unha funcionalidade está lista cando:
- Cando pasa PHPCS.
- Inclúe probas básicas ou pasos manuais de verificación.
- Actualiza Documents.md.
- Ten i18n correcto.
7.5. Documentación paralela
Exixe que o axente actualice Documents.md no mesmo PR que introduce cambios funcionais. Evitas desincronización e reduces fricción.
7.6. Auditoría continua
Cada certo número de PRs, fai “marcos” de revisión transversal: estrutura do repo, dependencias, rendemento, seguridade, cobertura de documentación. Se detectas degradación, refuerza AGENTS.md e abre tarefas correctivas (que o axente volcará ao TODO.md).
8. Limitacións e realismo operativo
8.1. Dependencia do contexto
Os LLM teñen límites contextuais. O axente non “ve” todo o repo á vez; o seu rendemento mellora cando traballas en iteracións acoutadas, con artefactos que fijen memoria (AGENTS.md, Documents.md) e con PRs pequenos.
8.2. Ambigüidade e o seu custo
Se os teus requisitos son vagos, o axente tenderá a encher buratos con suposicións. Resultado: reworks. Solución: define obxectivos, restricións e exemplos. A claridade inicial aforra ciclos enteros.
8.3. Erros plausibles
A IA pode xerar código “verosímil pero incorrecto”. Reduce este risco con linters, tests básicos e revisións humanas. Lembra: o rol do humano non desaparece, elévase a curador e arquitecto.
8.4. Cambios de alcance
Proxectos vivos evolucionan. O axente xestiona mellor se o adestras a propoñer novas tarefas en TODO.md cando detecte impactos colaterais, e ti validas esa proposta antes de executar.
9. Exemplo práctico: esqueleto do proxecto “Simple Contact Shortcode & Block”
Para conectar a teoría cunha implementación real, imos anclar un proxecto sinxelo en WordPress que servirá de demostración do fluxo Agentic Coding. Neste punto non incluiremos o código final (traballaremos máis adiante co teu axente). Deixaremos, no seu lugar, os contedores estruturais e os espazos ben visibles onde inseriremos os artefactos e pezas técnicas cando estean listos. Así poderás publicar a guía hoxe e, paso a paso, ir completando o exemplo sen reescribir a entrada.
9.1. Obxectivo do plugin
O plugin “Simple Contact Shortcode & Block” proporcionará un formulario de contacto moi básico (Nome e Email) que se poida engadir a calquera páxina de dúas maneiras: mediante un shortcode e mediante un bloque de Gutenberg. Ao enviar o formulario, gardará os datos nunha táboa propia na base de datos e notificará por email ao administrador do sitio.
9.2. Estructura de directorios esperada
/simple-contact/
├─ simple-contact.php # Bootstrap do plugin
├─ uninstall.php # Limpeza ao desinstalar
├─ includes/
│ ├─ class-sc-database.php # Esquema e CRUD
│ ├─ class-sc-form.php # Render + submission
│ └─ class-sc-block.php # Rexistro do bloque
├─ assets/
│ ├─ css/style.css # Estilos frontend
│ └─ js/block.js # Lógica do bloque
└─ languages/
└─ simple-contact.pot # Plantilla de traduccións
9.3. Artefactos do fluxo Agentic
- AGENTS.md fixará as regras e expectativas de implementación.
- TODO.md será creado e mantido por Codex. Aquí irá aparecendo o backlog e a priorización que o propio axente decida.
- Documents.md crecerá co catálogo de APIs, hooks e fluxos segundo se vaia implementando.
9.4. Arquivos
Como comentamos, deberemos crear un arquivo AGENTS.md que será o que seguirá Codex.
O que hai que facer é ter unha idea clara do que se desexa, unha vez se ten claro todo e se estivo «falando» con ChatGPT de todo o proxecto, pídese que cree un AGENTS.md con todas as regras e definindo o proxecto.
Vale, agora imos crear o AGENTS.md con todo o que falamos para que Codex teña unha guía exacta do que ten que facer e como.
Necesito que me crees de forma correcta e completa todo o AGENTS.md para o proxecto.
Debes engadir todo o esquema de arquivos, que siga todos os estándares de seguridade de WordPress, todas as medidas de seguridade, nomes de arquivos, prefixos en arquivos, clases, funcións, etc. estandarizados, cabeceiras e comentarios en todos os arquivos, funcións, chamadas e métodos tal e como especifica WordPress. Todas as cadeas deben estar en inglés, e traducibles. É moi importante que se pase sempre o PHPCS mantendo todas as alineacións coas súas tabulacións e espazos.
Tamén debes mencionar e explicar exactamente o uso de TODO.md e Documents.md para que desde o principio os utilice e non deba realizalo máis tarde. Especificarlle que se un arquivo é moi grande, como pode suceder en arquivos por exemplo po de traducción, debe crealos en diferentes PRs para que poida sempre crear PRs e non se atope na imposibilidade de facelos polo tamaño.
O repositorio tamén debe ter os arquivos .gitignore` (development junk and OS files) .gitignore e
.gitattributes para que só chegue o que debe estar no empaquetado final e non cheguen ao repo arquivos que non son necesarios do propio OS sobre o que se está traballando.Crea o AGENTS.md en inglés.
Tras este prompt, ChatGPT devolveume o contido que deberei pegar en 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.Fíxate que no prompt non fixen mención a que quero que faga o plugin, xa que ChatGPT xa o sabe por toda a conversación anterior que tiven con el e todo o que fomos discutindo redactou este AGENTS.md que é super completo, cousa que se quixese facer eu, sería máis complicado porque xa non é porque me deixe algo, senón que ChatGPT tamén sabe como se lle teñen que dicir as cousas, así que redacta un AGENTS.md acorde as súas necesidades. Por iso é tan importante o falalo con el, para que tamén lle quede claro todo o que queres.
Agora xa debemos crear o repositorio en Github se non o temos. Así que o crearemos, Imos a Github e creamos un novo repositorio o cal pode ser público ou privado, no meu caso este o vou crear público para que todos teñades acceso a el.
O primeiro que deberemos facer é traernos o repositorio a local, podemos utilizar por exemplo GitHub Desktop que hai para todos os OS.
Uan vez o temos en local, crearemos o arquivo AGENTS.md pegando en el o que nos dixo ChatGPT
<!– wp:image {
