Introducción al Agentic Coding con IA
La Inteligencia Artificial (IA) ha cambiado el modo en que concebimos el desarrollo de software. Ya no se trata solo de pedirle a un sistema que complete una línea de código: hoy podemos trabajar con agentes que entienden objetivos, siguen convenciones, mantienen documentación viva y colaboran con nosotros de manera similar a un miembro más del equipo. A este enfoque lo llamaremos “Agentic Coding”. Esta guía, extensa y práctica, te explicará cómo pasar de la idea a un flujo profesional donde la IA se integra en tu día a día como desarrollador, centrándonos en WordPress y en un proceso real que podrás replicar en tus proyectos.
Encontrarás, por un lado, la base conceptual necesaria para entender la IA moderna y el papel de los LLM (Large Language Models). Por otro, verás cómo organizar el trabajo con archivos clave que articulan todo el proceso: AGENTS.md (reglas y alcance), TODO.md (tablero que lleva el agente) y Documents.md (documentación viva). Además, incluimos buenas prácticas, limitaciones reales y una sección de ejemplo práctico que funcionará como esqueleto de proyecto, con espacios claramente marcados para que más adelante incorporemos contenido técnico concreto (código, estructuras, etc.) en colaboración con tu agente de implementación.
1. Introducción
1.1. ¿Qué es la Inteligencia Artificial (IA) en el desarrollo?
La IA es una disciplina amplia que persigue que las máquinas realicen tareas que asociamos con la inteligencia humana: comprender lenguaje natural, razonar a partir de descripciones, aprender de datos o planificar acciones. Tras décadas de avances, el salto cualitativo reciente llega con los Large Language Models (LLM). Estos modelos se entrenan con volúmenes masivos de texto, aprenden patrones de lenguaje y adquieren la capacidad de generar instrucciones, explicaciones y, por extensión, código coherente con un contexto dado.
En el ámbito del desarrollo, esto implica que ya no dependemos de herramientas que sugieren tokens al vuelo. Podemos describir objetivos de alto nivel, imponer estándares de estilo, pedir documentación consistente y coordinar tareas. El valor no está solo en “autocompletar”, sino en estructurar un trabajo técnico sostenido en el tiempo con ayuda de un agente que entiende el proyecto.
1.2. De los asistentes puntuales a los agentes
El primer contacto de muchos programadores con la IA vino de la mano de asistentes puntuales: motores de sugerencia en el IDE, chatbots capaces de responder dudas o generar funciones sueltas. Útiles, sí, pero limitados cuando queremos construir sistemas con coherencia a lo largo de semanas o meses. En cambio, el enfoque de Agentic Coding aprovecha la capacidad de los modelos para seguir procesos, mantener memoria operacional (a través de archivos y convenciones) y moverse por un backlog de forma planificada. Es decir, pasamos de una asistencia reactiva a una colaboración proactiva guiada por artefactos de proyecto.
1.3. ¿Por qué la IA no son “solo chatbots”?
La imagen del “chatbot que responde preguntas” se queda corta. Para desarrollo, la IA moderna puede:
- Generar y refactorizar código siguiendo patrones de arquitectura, convenciones de nomenclatura y estándares (PHPCS, ESLint, etc.).
- Diseñar e implementar pruebas (unitarias y de integración) y proponer casos límite.
- Escribir y mantener documentación técnica y de usuario mientras desarrolla, no al final.
- Automatizar tareas repetitivas de integración, migración de APIs, traducciones y comentarios en código.
- Explorar opciones técnicas con comparativas argumentadas (rendimiento, seguridad, mantenimiento).
1.4. Definición operativa de Agentic Coding
Llamaremos Agentic Coding a un flujo de trabajo en el que el desarrollador humano define reglas, objetivos y estándares, y un agente (p. ej. Codex) opera dentro de ese marco para ejecutar tareas, proponer subtareas, abrir Pull Requests, mantener un tablero vivo de trabajo y documentar lo construido. Tu rol cambia: pasas de codificar cada línea a dirigir el sistema, especificar criterios de aceptación, revisar PRs, y resolver bloqueos o ambigüedades con la ayuda de un copiloto de ideas (por ejemplo, ChatGPT para afinar el diseño del proceso o redactar artefactos como AGENTS.md).
2. Ecosistema de trabajo con IA para desarrolladores
2.1. Nube, local e híbrido
Existen tres grandes formas de consumir modelos:
- Nube (OpenAI, Anthropic, Google): facilidad de uso, escalado automático, latencia razonable y modelos de última generación utilizando CLI si se quiere en local. Inconvenientes: coste variable y políticas de datos. Exsiste también la posibilidad de uso de por ejemplo Codex de OpenAI, que tiene un coste fijo que depende de lo que contrates, con Plus ($20/mes) suele ser suficiente. Aquí hablare de Codex.
- Local (Llama.cpp, Ollama, vLLM): control y privacidad, dependencia mínima de terceros y costes por uso muy bajos. Inconvenientes: necesitas GPU/CPU potentes y mantenimiento de modelos.
- Híbrido: nubes para producción y modelos locales para experimentación, pruebas internas o datos sensibles. Suele ser el equilibrio más práctico.
2.2. Criterios de elección
Tu decisión dependerá de:
- Privacidad: ¿tratas datos sensibles? Local o híbrido pueden ser preferibles, aunque en teoría ahora se asegura la privacidad en la nube si así lo configuras.
- Coste: ¿el proyecto crecerá en uso? El coste per token en nube puede alzarse; en local pagas la infraestructura.
- Velocidad de arranque: la nube gana si quieres empezar hoy con mínima fricción.
- Operación y mantenimiento: local exige más DevOps; nube externaliza complejidad.
2.3. Herramientas complementarias
- Repositorio: GitHub/GitLab/Bitbucket para PRs, issues, revisiones.
- Editor: VSCode, con extensiones para estándares (PHPCS, ESLint), formateadores (Prettier), y asistentes.
- CI/CD: test automáticos, linters y despliegue controlado.
- Gestión de tareas: aunque TODO.md lo mantendrá el agente, es útil integrar señales con issues etiquetadas para auditoría.
3. Preparando la base del flujo de trabajo
3.1. El trío que articula el sistema
En este enfoque, tu proceso se sostiene en tres artefactos sincronizados:
- AGENTS.md: reglas del juego. Define propósito, alcance, estándares, estructura, convenciones, criterios de seguridad, requisitos de calidad y expectativas de documentación. Si quieres más información sobre AGENTS.md, puede obtener aquí.
- TODO.md: tablero vivo de tareas. Lo crea y mantiene el agente. En él se ve qué hará, qué está en curso y qué ha dado por finalizado. También añade nuevas tareas emergentes.
- Documents.md: documentación viva de lo ya construido: API pública, funciones, clases, hooks, esquemas de datos, flujos y recetas de uso. También lo mantiene el agente conforme avanza.
3.2. Roles claros
- Tú: arquitecto y responsable de calidad. Fijas reglas y objetivos en AGENTS.md, revisas PRs, dirimes ambigüedades, solicitas correcciones y nuevas tareas si detectas huecos.
- Agente de implementación (Codex): ejecuta, decide el desglose operativo en TODO.md, hace PRs incrementales y registra documentación en Documents.md.
- Copiloto de ideas (ChatGPT): te ayuda a afinar AGENTS.md, a razonar alternativas, a redactar criterios de aceptación y a desbloquear problemas complejos revisando el código cuando hace falta.
3.3. Iteración disciplinada
El éxito no depende de “la IA que genera mucho código”, sino de una iteración disciplinada con ciclos de: planificar (tú), ejecutar (agente), revisar (tú), documentar (agente), y volver a planificar. Cuanto más pequeño y verificable sea cada paso, mejor responde el sistema, menor es el riesgo de deuda técnica y más fácil es auditar el trabajo.
4. AGENTS.md: contrato y línea editorial del proyecto
4.1. Función estratégica de AGENTS.md
AGENTS.md es la brújula del proyecto. Aquí fijas la intención, el alcance y las limitaciones. Además, estableces la línea editorial del código: estilo, nombres, estructura, seguridad y documentación. Es el documento que evita que el agente improvise fuera de tus estándares. Piensa en él como el “Guide for contributors” adaptado a un colaborador que es IA.
4.2. Contenido recomendado
- Objetivo y alcance: qué problema resuelves, qué no hará el proyecto y el resultado esperado.
- Estándares: WordPress Coding Standards, PHPCS, traducciones con dominio concreto, docblocks obligatorios.
- Seguridad: sanitización, escaping, nonces, roles y capacidades mínimas, manejo de datos personales.
- Estructura de archivos: árbol de directorios y responsabilidades por archivo/clase.
- Convenciones de nombres: prefijos de funciones, clases, “handles” de scripts y estilos.
- Criterios de aceptación: qué consideras “hecho” en cada tarea, cómo se prueba y qué evidencias son válidas.
- Expectativas de documentación: cómo se mantiene Documents.md y cuándo se debe actualizar.
4.3. Beneficio directo
Con un buen AGENTS.md, los PRs de tu agente muestran coherencia extrema: mismas convenciones, misma estructura, mismas prácticas seguras. Tu revisión es más rápida, el proyecto es más mantenible y la incorporación de terceros, más sencilla.
5. TODO.md: el tablero que gestiona el agente
5.1. Un cambio de control fundamental
En este flujo, NO escribes tú el TODO.md. Lo crea y mantiene el agente desde el primer commit. Eso significa que el agente:
- Define el desglose de tareas y el orden de ejecución.
- Mueve ítems entre estados: pendiente, en progreso, completado.
- Añade tareas emergentes cuando detecta nuevas necesidades o riesgos.
¿Qué haces tú entonces? Marcas el rumbo en AGENTS.md, revisas PRs y, si detectas lagunas, pides a Codex que añada tareas al TODO.md. De este modo, el tablero refleja cómo el propio agente comprende y planifica el trabajo, sin que tengas que microgestionarlo.
5.2. Ventajas de este enfoque
- Autonomía operativa: delegas la orquestación de tareas, conservando el control estratégico.
- Transparencia: TODO.md se convierte en un registro auditable de las decisiones del agente.
- Agilidad: nuevas tareas se incorporan de inmediato según surgen durante el desarrollo.
6. Documents.md: memoria técnica viva
6.1. Qué es y por qué importa
Documents.md no es un manual escrito al final. Es una base de conocimiento viva que el agente actualiza conforme desarrolla. Debe registrar la superficie pública del proyecto: clases y métodos, funciones, shortcodes, hooks (actions/filters), esquemas de datos, flujos clave y recetas prácticas. La máxima es sencilla: si no está en Documents.md, es como si no existiera para terceros.
6.2. Uso cotidiano
Cuando vuelves al proyecto tras días o semanas, no necesitas rastrear código. Abres Documents.md y encuentras:
- Cómo se llama la función que necesitas y qué parámetros acepta.
- Qué filtro debes enganchar para modificar un comportamiento.
- Qué columnas hay en una tabla y qué índices están definidos.
- Cómo extender o reusar un flujo con un ejemplo mínimo viable.
6.3. Política de actualización
- Todo PR que cambie la superficie pública debe incluir actualización de Documents.md.
- Si se añade una API, debe añadirse un ejemplo de uso reproducible.
- Si se modifica el esquema de datos, debe anotarse la migración y su justificación.
7. Buenas prácticas de Agentic Coding
7.1. Escrupulosidad con estándares
Mantén consistencia: WordPress Coding Standards con PHPCS, docblocks claros, i18n en inglés (y traducciones donde proceda), y nomenclatura predecible. Un agente rinde mejor cuando las reglas están claras y se aplican de manera uniforme.
7.2. Seguridad por defecto
- Sanitiza entradas con funciones adecuadas (
sanitize_text_field,sanitize_email, etc.). - Escapa salidas en HTML (
esc_html,esc_attr,wp_ksessi hay HTML permitido). - Nonces en formularios y verificación del lado del servidor.
- Principio de privilegio mínimo en roles/capacidades.
7.3. Tareas pequeñas y verificables
Desglosa trabajos en unidades de entrega que puedas revisar en minutos. Pide al agente PRs pequeños con una sola intención. Así reduces errores, aceleras revisiones y favoreces el aprendizaje incremental del sistema.
7.4. Criterios de aceptación claros
En AGENTS.md, define “Definition of Done” para tipos de tareas: por ejemplo, “una funcionalidad está lista cuando:
- Cuando pasa PHPCS.
- Incluye pruebas básicas o pasos manuales de verificación.
- Actualiza Documents.md.
- Tiene i18n correcto.
7.5. Documentación paralela
Exige que el agente actualice Documents.md en el mismo PR que introduce cambios funcionales. Evitas desincronización y reduces fricción.
7.6. Auditoría continua
Cada cierto número de PRs, haz “hitos” de revisión transversal: estructura del repo, dependencias, rendimiento, seguridad, cobertura de documentación. Si detectas degradación, refuerza AGENTS.md y abre tareas correctivas (que el agente volcará al TODO.md).
8. Limitaciones y realismo operativo
8.1. Dependencia del contexto
Los LLM tienen límites contextuales. El agente no “ve” todo el repo a la vez; su rendimiento mejora cuando trabajas en iteraciones acotadas, con artefactos que fijen memoria (AGENTS.md, Documents.md) y con PRs pequeños.
8.2. Ambigüedad y su coste
Si tus requisitos son vagos, el agente tenderá a rellenar huecos con suposiciones. Resultado: reworks. Solución: define objetivos, restricciones y ejemplos. La claridad inicial ahorra ciclos enteros.
8.3. Errores plausibles
La IA puede generar código “verosímil pero incorrecto”. Reduce este riesgo con linters, tests básicos y revisiones humanas. Recuerda: el rol del humano no desaparece, se eleva a curador y arquitecto.
8.4. Cambios de alcance
Proyectos vivos evolucionan. El agente lo gestiona mejor si lo entrenas a proponer nuevas tareas en TODO.md cuando detecte impactos colaterales, y tú validas esa propuesta antes de ejecutar.
9. Ejemplo práctico: esqueleto del proyecto “Simple Contact Shortcode & Block”
Para conectar la teoría con una implementación real, vamos a anclar un proyecto sencillo en WordPress que servirá de demostración del flujo Agentic Coding. En este punto no incluiremos el código final (lo trabajaremos más adelante con tu agente). Dejaremos, en su lugar, los contenedores estructurales y los espacios bien visibles donde insertaremos los artefactos y piezas técnicas cuando estén listos. Así podrás publicar la guía hoy y, paso a paso, ir completando el ejemplo sin reescribir la entrada.
9.1. Objetivo del plugin
El plugin “Simple Contact Shortcode & Block” proporcionará un formulario de contacto muy básico (Nombre y Email) que se pueda añadir a cualquier página de dos maneras: mediante un shortcode y mediante un bloque de Gutenberg. Al enviar el formulario, guardará los datos en una tabla propia en la base de datos y notificará por email al administrador del sitio.
9.2. Estructura de directorios esperada
/simple-contact/
├─ simple-contact.php # Bootstrap del plugin
├─ uninstall.php # Limpieza a desinstalar
├─ includes/
│ ├─ class-sc-database.php # Esquema y CRUD
│ ├─ class-sc-form.php # Render + submission
│ └─ class-sc-block.php # Registro del bloque
├─ assets/
│ ├─ css/style.css # Estilos frontend
│ └─ js/block.js # Lógica del bloque
└─ languages/
└─ simple-contact.pot # Plantilla de traducciones
9.3. Artefactos del flujo Agentic
- AGENTS.md fijará las reglas y expectativas de implementación.
- TODO.md será creado y mantenido por Codex. Aquí irá apareciendo el backlog y la priorización que el propio agente decida.
- Documents.md crecerá con el catálogo de APIs, hooks y flujos según se vaya implementando.
9.4. Archivos
Como hemos comentado, deberemos crear un archivo AGENTS.md que será lo que seguirá Codex.
Lo que hay que hacer es tener una idea clara de lo que se desea, una vez se tiene claro todo y se ha estado «hablando» con ChatGPT de todo el proyecto, se le solicita que cree un AGENTS.md cn todas las reglas y definiendo el proyecto.
Vale, ahora vamos a crear el AGENTS.md con todo lo que hemos hablado para que Codex tenga un guía exacta de lo que tiene que hacer y como.
Necesito que me crees de forma correcta y completa todo el AGENTS.md para el el proyecto.
Debes añadir todo el esquema de archivos, que siga todos los estándares de seguridad de WordPress, todas las medidas de seguridad, nombres de archivos, prefijos en archivos, clases, funciones, etc estandarizados, cabeceras y comentarios en todos los archivos, funciones, calles y métodos tal y como especifica WordPress. Todas las cadenas deben estar en inglés, y traducibles. Es muy importante que se pase siempre el PHPCS manteniendo todas las alineaciones con sus tabulaciones y espacios
También debes mencionar y explicar exactamente el uso el uso de TODO.md y Documents.md para que desde el principio los utilice y no deba realizarlo más tarde. Especificarle que si un archivo en muy grande, como puede suceder en archivo por ejemplo po de traducción, debe crearlos en diferentes PRs para que pueda siempre crear PRs y no se encuentre en la imposibilidad de hacerlos por el tamaño.
El repositorio también debe tener los archivos .gitignore` (development junk and OS files) .gitignore y
.gitattributes para que solo llegue lo que debe estar en el empaquetado final y no lleguen al repo archivos que no son necesarios del propio OS sobre el que se está trabajando.Crea el AGENTS.md en inglés.
Tras este prompt, ChatGPT me devuelve el contenido que deberé pegar en el 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íjate que en prompt no he hecho mención a lo que quiero que haga el plugin, ya que ChatGPT ya lo sabe por toda la conversación anterior que he tenido con él y todo lo que hemos ido discutiendo ha redactado este AGENTS.md que es super completo, cosa que si lo quisiera hacer yo, me sería más complicado porque ya no es porque me deje algo, si no que ChatGPT también sabe como se le tienen que decir las cosas, así que redacta un AGENTS.md acorde sus necesidades. Por eso es tan importante el hablarlo con él, para que también le quede claro todo lo que quieres.
Ahora ya debemos crear el repositorio en Github si no lo tenemos. Así que lo crearemos, Vamos a Github y creamos un nuevo repositorio el cual puede ser público o privado, en mi caso este lo voy a crear público para que todos tengáis acceso a él.
Lo primero que deberemos hacer es traernos el repositorio a local, podemos utilizar por ejemplo GitHub Desktop que hay para todos los OS.
Uan vez lo tenemos en local, crearemos el archivo AGENTS.md pegando en él lo que nos ha dicho ChatGPT
y lo subiremos a Github, mediante Github Desktop.
Una vez subido, ya podemos ver en Github que tenemos el archivo AGENTS.md en nuestro repositorio. Ya no necesitamos más para comenzar con Codex.
Ahora iremos a Codex y lo primero que deberemos hacer es añadir este repositorio (si es la primera vez que accedes a Codex, te va a pedir antes que le des permisos de acceso a tu cuenta de Github).
Solo apretaremos en crear entorno, y lo configuraremos.
La parte básica la configuraremos así seleccionando el repositorio.
Pero fijaros en esta última parte. Es necesario muchas veces ponerlo así, ya que necesita paquetes para por ejemplo compilar React que si no se le deja cualquier cosa, no podrá hacerlo, pero siempre podeis ir activando y desactivando esta opción, ya que se puede cambiar.
Ya solo queda apretar en Crear entorno.
Una vez hemos creado el entorno, ya solo debemos comenzar a hacer trabajar a Codex. Seleccionamos en Codex el repositorio con el que queremos trabajar, lo otro lo podéis dejar como está
Y una vez seleccionado, solo hay que hacer un prompt tan sencillo como este
Desarrolla todo lo que hay en AGENTS.md y recuerda utilizar el TODO.md y el Documents.md
Y apretaremos en Programar, y comenzará a trabajar en el código.
Pasado un rato, eso ya depende de todo lo que haya hecho, nos mostrará todos los cambios que ha realizado, que en este caso, todo es código a añadir.
Al presionar sobre la tarea, accederemos a ella y podremos ver todo lo que ha hecho, revisarlo y crear el PR o solicitarle cambios.
En este caso no voy a revisar nada porque esto es una demo, así que aprieto en primer lugar en «Crear solicitud de extracción» y luego en «Ver PR» una vez que aparezca el botón.
Esto nos llevará a Github, donde también podremos revisar los cambios y aceptarlos.
Apretaremos en «Merge pull request» y ya tendremos todo el nuevo código añadido al plugin.
Ahora ya podemos ver el TODO.md y el Documents.md donde podremos realizar un seguimiento de todo e ir obteniendo una documentación para el futuro.
Si miramos el TODO.md, en este punto podemos ver que aun hay muchas cosas en Progress y en Pending, así que Codex debe continuar. Solo deberemos indicarle a Codex que continue con el trabajo.
Esto lo iremos repitiendo hasta que no quede tareas en el TODO.md y esté todo hecho. Llegará un momento en que en Pending y Progress ya no habrá nada, y ya podremos probar el resultado final en un sitio de desarrollo. Sobre todo SIEMPRE de desarrollo.
Una vez instalado, puede que funcione a la primera o no, en mi caso ha salido un error fatal
Así que lo que hago es copiar el error para que Codex lo corrija dándole contexto.
Tras acabar, crea un nuevo PR para arreglarlo y el plugin ya se puede activar
Si ahora creamos una entrada/pagina nueva, veremos en los bloques que hay uno que se llama «Simple Contact Form», y que se puede especificar el mensaje de éxito de envío. En este caso, como no hemos especificado en AGENTS.md que debemos poder configurar el correo al que se debe enviar, lo va a enviar siempre al correo del administrador de WordPress.
En el front veremos esto (recuerda que le habíamos especificado que el formulario solo tuviera nombre y correo)
Si ahora quisieras añadir más campos, por ejemplo Asunto y Cometarios, solo se lo tendríamos que pedir a Codex y diciéndole que el miso actualizara AGENTS.md, TODO.md y Documents.md.
Si relleno los campos y aprieto en Send, me llega esto al correo
Es decir, solo hemos tenido un solo error fatal en el plugin que nos ha desarrollado Codex, y que ha arreglado a la primera indicándole cual era.
Este es un plugin muy sencillo, pero es un plugin que incorpora un bloque para Gutenberg que no es poco.
Si repasamos todo lo que le hemos solicitado en un primer momento, veremos que falta algun tema, ya sea porque hay nu bug y no se muestra, o porque directamente no lo ha hecho, así que a partir de este momento, es ir realizando peticiones de arreglos hasta llegar donde deseemos.
10. Futuro del Agentic Coding
10.1. Mayor autonomía, mayor trazabilidad
A medida que evolucionen los modelos, veremos agentes capaces de planificar iteraciones más largas, detectar dependencias y coordinar cambios de mayor calado. La clave no será solo la potencia bruta, sino la trazabilidad: conservar un historial de decisiones, supuestos y criterios de aceptación que haga auditables los PRs generados por IA.
10.2. Testing y CI/CD integrados en el flujo del agente
El futuro inmediato pasa por agentes que integran generación de pruebas y pipelines de CI/CD: linters, tests, cobertura básica, preview deploys y reportes de rendimiento. Tu rol se centrará en diseñar las políticas: qué es aceptable, qué riesgos no toleras y cómo deben informarse regresiones.
10.3. Especialización por dominios
Veremos agentes “afinados” para ecosistemas concretos (WordPress, WooCommerce, plugins de pago, frontends con React/Blocks) con convenciones preaprendidas y catálogos de mejores prácticas. Esto reducirá aún más el tiempo de puesta en marcha y el esfuerzo de revisión.
10.4. Documentación como producto
La documentación dejará de ser un apéndice para convertirse en un producto paralelo mantenido por el agente. Documents.md evolucionará a portales de conocimiento navegables, con snippets ejecutables, esquemas visuales, diagramas y recetas versionadas.
11. Conclusión
El Agentic Coding no es pedirle a una IA que “haga un plugin”, sino construir una relación de trabajo donde tú marcas el norte y la IA ejecuta con disciplina. El ecosistema moderno —nube, local, híbrido— te permite escoger la base técnica; pero el verdadero diferencial está en cómo organizas el proceso: AGENTS.md para fijar reglas, TODO.md gestionado por el agente para orquestar tareas, y Documents.md para capturar conocimiento real del proyecto mientras se crea.
Este enfoque te da velocidad sin sacrificar calidad: reduces tiempo en tareas repetitivas, te centras en arquitectura y decisiones importantes, y mantienes a raya la deuda técnica. ¿El resultado? Proyectos más coherentes, fáciles de mantener y con una rampa de incorporación suave para cualquier colaborador futuro.
Has visto, además, cómo preparar un ejemplo práctico que podrás completar con tu agente: “Simple Contact”.
El futuro del desarrollo es colaborativo: humanos y agentes trabajando codo a codo con procesos claros, estándares firmes y evidencia constante. Empieza hoy por tu flujo y tus reglas; la IA hará el resto bajo tu dirección.
