Introducció al Agentic Coding amb IA
L’Intel·ligència Artificial (IA) ha canviat la manera en què concebem el desenvolupament de programari. Ja no es tracta només de demanar a un sistema que completi una línia de codi: avui podem treballar amb agents que entenen objectius, segueixen convencions, mantenen documentació viva i col·laboren amb nosaltres de manera similar a un membre més de l’equip. A aquest enfocament el anomenarem “Agentic Coding”. Aquesta guia, extensa i pràctica, t’explicarà com passar de la idea a un flux professional on la IA s’integra en el teu dia a dia com a desenvolupador, centrant-nos en WordPress i en un procés real que podràs replicar en els teus projectes.
Trobaràs, d’una banda, la base conceptual necessària per entendre la IA moderna i el paper dels LLM (Large Language Models). D’altra banda, veuràs com organitzar la feina amb fitxers clau que articulen tot el procés: AGENTS.md (regles i abast), TODO.md (tauler que porta l’agent) i Documents.md (documentació viva). A més, incloem bones pràctiques, limitacions reals i una secció d’exemple pràctic que funcionarà com a esquelet de projecte, amb espais clarament marcats perquè més endavant incorporem contingut tècnic concret (codi, estructures, etc.) en col·laboració amb el teu agent d’implementació.
1. Introducció
1.1. Què és la Intel·ligència Artificial (IA) en el desenvolupament?
La IA és una disciplina àmplia que persegueix que les màquines realitzin tasques que associem amb la intel·ligència humana: comprendre llenguatge natural, raonar a partir de descripcions, aprendre de dades o planificar accions. Després de dècades d’avançaments, el salt qualitatiu recent arriba amb els Large Language Models (LLM). Aquests models s’entrenen amb volums massius de text, aprenen patrons de llenguatge i adquireixen la capacitat de generar instruccions, explicacions i, per extensió, codi coherent amb un context donat.
En l’àmbit del desenvolupament, això implica que ja no depenem d’eines que suggereixen tokens al vol. Podem descriure objectius d’alt nivell, imposar estàndards d’estil, demanar documentació consistent i coordinar tasques. El valor no està només en “autocompletar”, sinó en estructurar un treball tècnic sostingut en el temps amb ajuda d’un agent que entén el projecte.
1.2. Dels assistents puntuals als agents
El primer contacte de molts programadors amb la IA va venir de la mà d’assistents puntuals: motors de suggeriment en l’IDE, chatbots capaços de respondre dubtes o generar funcions soltes. Útils, sí, però limitats quan volem construir sistemes amb coherència al llarg de setmanes o mesos. En canvi, l’enfocament de Agentic Coding aprofita la capacitat dels models per seguir processos, mantenir memòria operativa (a través de fitxers i convencions) i moure’s per un backlog de manera planificada. És a dir, passem d’una assistència reactiva a una col·laboració proactiva guiada per artefactes de projecte.
1.3. Per què la IA no són “només chatbots”?
L’imatge del “chatbot que respon preguntes” es queda curta. Per al desenvolupament, la IA moderna pot:
- Generar i refactoritzar codi seguint patrons d’arquitectura, convencions de nomenclatura i estàndards (PHPCS, ESLint, etc.).
- Dissenyar i implementar proves (unitàries i d’integració) i proposar casos límit.
- Escriure i mantenir documentació tècnica i d’usuari mentre desenvolupa, no al final.
- Automatitzar tasques repetitives d’integració, migració d’APIs, traduccions i comentaris en codi.
- Explorar opcions tècniques amb comparatives argumentades (rendiment, seguretat, manteniment).
1.4. Definició operativa d’Agentic Coding
Anomenarem Agentic Coding a un flux de treball en el qual el desenvolupador humà defineix regles, objectius i estàndards, i un agent (p. ex. Codex) opera dins d’aquest marc per executar tasques, proposar subtasques, obrir Pull Requests, mantenir un tauler viu de treball i documentar el construït. El teu rol canvia: passes de codificar cada línia a dirigir el sistema, especificar criteris d’acceptació, revisar PRs, i resoldre bloquejos o ambigüitats amb l’ajuda d’un copilota d’idees (per exemple, ChatGPT per afinar el disseny del procés o redactar artefactes com AGENTS.md).
2. Ecosistema de treball amb IA per a desenvolupadors
2.1. Núvol, local i híbrid
Hi ha tres grans formes de consumir models:
- Núvol (OpenAI, Anthropic, Google): facilitat d’ús, escalat automàtic, latència raonable i models d’última generació utilitzant CLI si es vol en local. Inconvenients: cost variable i polítiques de dades. Existeix també la possibilitat d’ús de per exemple Codex d’OpenAI, que té un cost fix que depèn del que contractis, amb Plus ($20/mes) sol ser suficient. Aquí parlaré de Codex.
- Local (Llama.cpp, Ollama, vLLM): control i privadesa, dependència mínima de tercers i costos per ús molt baixos. Inconvenients: necessites GPU/CPU potents i manteniment de models.
- Híbrid: núvols per a producció i models locals per a experimentació, proves internes o dades sensibles. Sol ser l’equilibri més pràctic.
2.2. Criteris d’elecció
La teva decisió dependrà de:
- Privadesa: tractes dades sensibles? Local o híbrid poden ser preferibles, encara que en teoria ara s’assegura la privadesa al núvol si així ho configures.
- Cost: el projecte creixerà en ús? El cost per token al núvol pot augmentar; en local pagues la infraestructura.
- Velocitat d’arrencada: el núvol guanya si vols començar avui amb mínima fricció.
- Operació i manteniment: local exigeix més DevOps; núvol externalitza complexitat.
2.3. Eines complementàries
- Repositori: GitHub/GitLab/Bitbucket per a PRs, issues, revisions.
- Editor: VSCode, amb extensions per a estàndards (PHPCS, ESLint), formatadors (Prettier), i assistents.
- CI/CD: tests automàtics, linters i desplegament controlat.
- Gestió de tasques: encara que TODO.md ho mantindrà l’agent, és útil integrar senyals amb issues etiquetades per a auditoria.
3. Preparant la base del flux de treball
3.1. El trio que articula el sistema
En aquest enfocament, el teu procés es sosté en tres artefactes sincronitzats:
- AGENTS.md: regles del joc. Defineix propòsit, abast, estàndards, estructura, convencions, criteris de seguretat, requisits de qualitat i expectatives de documentació. Si vols més informació sobre AGENTS.md, pot obtenir aquí.
- TODO.md: tauler viu de tasques. Ho crea i manté l’agent. En ell es veu què farà, què està en curs i què ha donat per finalitzat. També afegeix noves tasques emergents.
- Documents.md: documentació viva del que ja s’ha construït: API pública, funcions, classes, hooks, esquemes de dades, fluxos i receptes d’ús. També ho manté l’agent conforme avança.
3.2. Rols clars
- Tu: arquitecte i responsable de qualitat. Fixes regles i objectius a AGENTS.md, revises PRs, dirimes ambigüitats, sol·licites correccions i noves tasques si detectes buits.
- Agent d’implementació (Codex): executa, decideix el desglaç operatiu a TODO.md, fa PRs incrementals i registra documentació a Documents.md.
- Copilot d’idees (ChatGPT): t’ajuda a afinar AGENTS.md, a raonar alternatives, a redactar criteris d’acceptació i a desbloquejar problemes complexos revisant el codi quan cal.
3.3. Iteració disciplinada
El èxit no depèn de “la IA que genera molt de codi”, sinó d’una iteració disciplinada amb cicles de: planificar (tu), executar (agent), revisar (tu), documentar (agent), i tornar a planificar. Com més petit i verificable sigui cada pas, millor respon el sistema, menor és el risc de deute tècnic i més fàcil és auditar el treball.
4. AGENTS.md: contracte i línia editorial del projecte
4.1. Funció estratègica d’AGENTS.md
AGENTS.md és la brúixola del projecte. Aquí fixes la intenció, l’abast i les limitacions. A més, estableixes la línia editorial del codi: estil, noms, estructura, seguretat i documentació. És el document que evita que l’agent improvvisi fora dels teus estàndards. Pensa en ell com el “Guide for contributors” adaptat a un col·laborador que és IA.
4.2. Contingut recomanat
- Objectiu i abast: quin problema resols, què no farà el projecte i el resultat esperat.
- Estàndards: WordPress Coding Standards, PHPCS, traduccions amb domini concret, docblocks obligatoris.
- Seguretat: sanitització, escaping, nonces, rols i capacitats mínimes, maneig de dades personals.
- Estructura de fitxers: arbre de directoris i responsabilitats per fitxer/classe.
- Convencions de noms: prefixos de funcions, classes, “handles” de scripts i estils.
- Criteris d’acceptació: què consideres “fet” en cada tasca, com es prova i quines evidències són vàlides.
- Expectatives de documentació: com es manté Documents.md i quan s’ha d’actualitzar.
4.3. Benefici directe
Amb un bon AGENTS.md, els PRs del teu agent mostren coherència extrema: mateixes convencions, mateixa estructura, mateixes pràctiques segures. La teva revisió és més ràpida, el projecte és més mantenible i la incorporació de tercers, més senzilla.
5. TODO.md: el tauler que gestiona l’agent
5.1. Un canvi de control fonamental
En aquest flux, NO escrius tu el TODO.md. Ho crea i manté l’agent des del primer commit. Això significa que l’agent:
- Defineix el desglaç de tasques i l’ordre d’execució.
- Mou ítems entre estats: pendent, en progrés, completat.
- Afegeix tasques emergents quan detecta noves necessitats o riscos.
Què fas tu llavors? Marques el rumb a AGENTS.md, revises PRs i, si detectes llacunes, demanes a Codex que afegeixi tasques al TODO.md. D’aquesta manera, el tauler reflecteix com l’agent comprèn i planifica la feina, sense que hagis de microgestionar-ho.
5.2. Avantatges d’aquest enfocament
- Autonomia operativa: delegues l’orquestració de tasques, conservant el control estratègic.
- Transparència: TODO.md es converteix en un registre auditable de les decisions de l’agent.
- Agilitat: noves tasques s’incorporen de seguida segons sorgeixen durant el desenvolupament.
6. Documents.md: memòria tècnica viva
6.1. Què és i per què importa
Documents.md no és un manual escrit al final. És una base de coneixement viva que l’agent actualitza conforme desenvolupa. Ha de registrar la superfície pública del projecte: classes i mètodes, funcions, shortcodes, hooks (actions/filters), esquemes de dades, fluxos clau i receptes pràctiques. La màxima és senzilla: si no està a Documents.md, és com si no existís per a tercers.
6.2. Ús quotidià
Quan tornes al projecte després de dies o setmanes, no necessites rastrejar codi. Obres Documents.md i trobes:
- Com es diu la funció que necessites i quins paràmetres accepta.
- Quin filtre has d’enganxar per modificar un comportament.
- Quines columnes hi ha en una taula i quins índexs estan definits.
- Com estendre o reutilitzar un flux amb un exemple mínim viable.
6.3. Política d’actualització
- Tot PR que canviï la superfície pública ha d’incloure actualització de Documents.md.
- Si s’afegeix una API, ha d’afegir-se un exemple d’ús reproduïble.
- Si es modifica l’esquema de dades, ha d’anotar-se la migració i la seva justificació.
7. Bones pràctiques d’Agentic Coding
7.1. Escrupolositat amb estàndards
Mantén consistència: WordPress Coding Standards amb PHPCS, docblocks clars, i18n en anglès (i traduccions on procedeixi), i nomenclatura previsible. Un agent rindeix millor quan les regles són clares i s’apliquen de manera uniforme.
7.2. Seguretat per defecte
- Sanitiza entrades amb funcions adequades (
sanitize_text_field,sanitize_email, etc.). - Escapa sortides en HTML (
esc_html,esc_attr,wp_ksessi hi ha HTML permès). - Nonces en formularis i verificació del costat del servidor.
- Principi de privilegi mínim en rols/capacitats.
7.3. Tasques petites i verificables
Desglossa treballs en unitats d’entrega que puguis revisar en minuts. Demana a l’agent PRs petites amb una sola intenció. Així redueixes errors, acceleres revisions i afavoreixes l’aprenentatge incremental del sistema.
7.4. Criteris d’acceptació clars
A AGENTS.md, defineix “Definition of Done” per tipus de tasques: per exemple, “una funcionalitat està llesta quan:
- Quan passa PHPCS.
- Inclou proves bàsiques o passos manuals de verificació.
- Actualitza Documents.md.
- Té i18n correcte.
7.5. Documentació paral·lela
Exigeix que l’agent actualitzi Documents.md en el mateix PR que introdueix canvis funcionals. Evites desincronització i redueixes fricció.
7.6. Auditoria contínua
Cada cert nombre de PRs, fes “fites” de revisió transversal: estructura del repo, dependències, rendiment, seguretat, cobertura de documentació. Si detectes degradació, reforça AGENTS.md i obre tasques correctives (que l’agent volcarà al TODO.md).
8. Limitacions i realisme operatiu
8.1. Dependència del context
Els LLM tenen límits contextals. L’agent no “veu” tot el repo a la vegada; el seu rendiment millora quan treballes en iteracions acotades, amb artefactes que fixen memòria (AGENTS.md, Documents.md) i amb PRs petites.
8.2. Ambigüitat i el seu cost
Si els teus requisits són vagos, l’agent tendirà a omplir buits amb suposicions. Resultat: reworks. Solució: defineix objectius, restriccions i exemples. La claredat inicial estalvia cicles sencers.
8.3. Errors plausibles
La IA pot generar codi “versemblant però incorrecte”. Redueix aquest risc amb linters, tests bàsics i revisions humanes. Recorda: el rol de l’humà no desapareix, s’eleva a curador i arquitecte.
8.4. Canvis d’abast
Projectes vius evolucionen. L’agent ho gestiona millor si el entrenes a proposar noves tasques a TODO.md quan detecti impactes col·laterals, i tu validis aquesta proposta abans d’executar.
9. Exemple pràctic: esquelet del projecte “Simple
Contacte Shortcode & Block
Per connectar la teoria amb una implementació real, anirem a anclar un projecte senzill a WordPress que servirà de demostració del flux Agentic Coding. En aquest punt no inclourem el codi final (ho treballarem més endavant amb el teu agent). Deixarem, en el seu lloc, els contenidors estructurals i els espais ben visibles on inserirem els artefactes i peces tècniques quan estiguin llestos. Així podràs publicar la guia avui i, pas a pas, anar completant l’exemple sense reescriure l’entrada.
9.1. Objectiu del plugin
El plugin “Simple Contact Shortcode & Block” proporcionarà un formulari de contacte molt bàsic (Nom i Correu electrònic) que es pugui afegir a qualsevol pàgina de dues maneres: mitjançant un shortcode i mitjançant un bloc de Gutenberg. En enviar el formulari, guardarà les dades en una taula pròpia a la base de dades i notificarà per correu electrònic a l’administrador del lloc.
9.2. Estructura de directoris esperada
/simple-contact/
├─ simple-contact.php # Bootstrap del plugin
├─ uninstall.php # Neteja a desinstal·lar
├─ includes/
│ ├─ class-sc-database.php # Esquema i CRUD
│ ├─ class-sc-form.php # Render + enviament
│ └─ class-sc-block.php # Registre del bloc
├─ assets/
│ ├─ css/style.css # Estils frontend
│ └─ js/block.js # Lògica del bloc
└─ languages/
└─ simple-contact.pot # Plantilla de traduccions
9.3. Artefactes del flux Agentic
- AGENTS.md fixarà les regles i expectatives d’implementació.
- TODO.md serà creat i mantingut per Codex. Aquí anirà apareixent el backlog i la priorització que el propi agent decideixi.
- Documents.md creixerà amb el catàleg d’APIs, hooks i fluxos a mesura que es vagi implementant.
9.4. Arxius
Com hem comentat, haurem de crear un arxiu AGENTS.md que serà el que seguirà Codex.
El que cal fer és tenir una idea clara del que es desitja, una vegada es té clar tot i s’ha estat «parlant» amb ChatGPT de tot el projecte, se li sol·licita que creï un AGENTS.md amb totes les regles i definint el projecte.
Val, ara anem a crear l’AGENTS.md amb tot el que hem parlat perquè Codex tingui una guia exacta del que ha de fer i com.
Necessito que em creïs de forma correcta i completa tot l’AGENTS.md per al projecte.
Has d’afegir tot l’esquema d’arxius, que segueixi tots els estàndards de seguretat de WordPress, totes les mesures de seguretat, noms d’arxius, prefixos en arxius, classes, funcions, etc. estandarditzats, capçaleres i comentaris en tots els arxius, funcions, rutes i mètodes tal com especifica WordPress. Totes les cadenes han d’estar en anglès, i traduïbles. És molt important que es passi sempre el PHPCS mantenint totes les alineacions amb les seves tabulacions i espais
També has de mencionar i explicar exactament l’ús de TODO.md i Documents.md perquè des del principi els utilitzi i no hagi de realitzar-ho més tard. Especificar-li que si un arxiu és molt gran, com pot succeir en arxius per exemple po de traducció, ha de crear-los en diferents PRs perquè pugui sempre crear PRs i no es trobi en la impossibilitat de fer-los pel tamany.
El repositori també ha de tenir els arxius .gitignore` (junk de desenvolupament i arxius del SO) .gitignore i
.gitattributes perquè només arribi el que ha d’estar en l’empaquetat final i no arribin al repo arxius que no són necessaris del propi SO sobre el qual s’està treballant.Crea l’AGENTS.md en anglès.
Després d’aquest prompt, ChatGPT em retorna el contingut que hauré de pegar a l’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.Fixa’t que en prompt no he fet menció a què vull que faci el plugin, ja que ChatGPT ja ho sap per tota la conversa anterior que he tingut amb ell i tot el que hem anat discutint ha redactat aquest AGENTS.md que és super complet, cosa que si ho volgués fer jo, em seria més complicat perquè ja no és perquè em deixi alguna cosa, sinó que ChatGPT també sap com se li han de dir les coses, així que redacta un AGENTS.md acord a les seves necessitats. Per això és tan important el parlar-ho amb ell, perquè també li quedi clar tot el que vols.
Ara ja hem de crear el repositori a Github si no el tenim. Així que ho crearem, Anem a Github i creem un nou repositori el qual pot ser públic o privat, en el meu cas aquest el crearé públic perquè tots tingueu accés a ell.
El primer que haurem de fer és portar-nos el repositori a local, podem utilitzar per exemple GitHub Desktop que hi ha per a tots els SO.
Una vegada ho tenim en local, crearem l’arxiu AGENTS.md enganxant-hi el que ens ha dit ChatGPT
i ho pujarem a Github, mitjançant Github Desktop.
Una vegada pujat, ja podem veure a Github que tenim l’arxiu AGENTS.md al nostre repositori. Ja no necessitem més per començar amb Codex.
Ara anirem a Codex i el primer que haurem de fer és afegir aquest repositori (si és la primera vegada que accedeixes a Codex, et demanarà abans que li donis permisos d’accés al teu compte de Github).
Només apretarem en crear entorn, i ho configurarem.
La part bàsica la configurarem així seleccionant el repositori.
Però fixeu-vos en aquesta última part. És necessari moltes vegades posar-ho així, ja que necessita paquets per exemple per compilar React que si no se li deixa qualsevol cosa, no podrà fer-ho, però sempre podeu anar activant i desactivant aquesta opció, ja que es pot canviar.
Ja només queda apretar en Crear entorn.
Una vegada hem creat l’entorn, ja només hem de començar a fer treballar a Codex. Seleccionem a Codex el repositori amb el qual volem treballar, l’altre ho podeu deixar com està
I una vegada seleccionat, només cal fer un prompt tan senzill com aquest
Desenvolupa tot el que hi ha a AGENTS.md i recorda utilitzar el TODO.md i el Documents.md
I premem a Programar, i començarà a treballar en el codi.
Passat un temps, això ja depèn de tot el que hagi fet, ens mostrarà tots els canvis que ha realitzat, que en aquest cas, tot és codi a afegir.
En prémer sobre la tasca, accedirem a ella i podrem veure tot el que ha fet, revisar-ho i crear el PR o demanar-li canvis.
En aquest cas no vaig a revisar res perquè això és una demo, així que premem en primer lloc a «Crear sol·licitud d’extracció» i després a «Veure PR» un cop aparegui el botó.
Això ens portarà a Github, on també podrem revisar els canvis i acceptar-los.
Premem a «Merge pull request» i ja tindrem tot el nou codi afegit al plugin.
Ara ja podem veure el TODO.md i el Documents.md on podrem fer un seguiment de tot i anar obtenint una documentació per al futur.
Si mirem el TODO.md, en aquest punt podem veure que encara hi ha moltes coses en Progrés i en Pending, així que Codex ha de continuar. Només haurem d’indicar-li a Codex que continuï amb la feina.
Això ho anirem repetint fins que no quedi tasques al TODO.md i estigui tot fet. Arribarà un moment en què a Pending i Progress ja no hi haurà res, i ja podrem provar el resultat final en un lloc de desenvolupament. Sobretot SEMPRE de desenvolupament.
Un cop instal·lat, potser funcionarà a la primera o no, en el meu cas ha sortit un error fatal
Així que el que faig és copiar l’error perquè Codex el corregeixi donant-li context.
Després d’acabar, crea un nou PR per arreglar-ho i el plugin ja es pot activar
Si ara creem una entrada/pàgina nova, veurem en els blocs que hi ha un que es diu «Simple Contact Form», i que es pot especificar el missatge d’èxit d’enviament. En aquest cas, com no hem especificat a AGENTS.md que hem de poder configurar el correu al qual s’ha d’enviar, ho enviarà sempre al correu de l’administrador de WordPress.
En el front veurem això (recorda que li havíem especificat que el formulari només tingués nom i correu)
Si ara volguessis afegir més camps, per exemple Assumpte i Comentaris, només se l’hauríem de demanar a Codex i dient-li que ell mateix actualitzés AGENTS.md, TODO.md i Documents.md.
Si omplo els camps i prem a Send, m’arriba això al correu
És a dir, només hem tingut un sol error fatal en el plugin que ens ha desenvolupat Codex, i que ha arreglat a la primera indicant-li quin era.
Aquest és un plugin molt senzill, però és un plugin que incorpora un bloc per Gutenberg que no és poc.
Si repassem tot el que li hem sol·licitat en un primer moment, veurem que falta algun tema, ja sigui perquè hi ha un bug i no es mostra, o perquè directament no ho ha fet, així que a partir d’aquest moment, és anar realitzant peticions de correccions fins arribar on desitgem.
10. Futur de l’Agentic Coding
10.1. Major autonomia, major traçabilitat
A mesura que evolucionin els models, veurem agents capaços de planificar iteracions més llargues, detectar dependències i coordinar canvis de major calat. La clau no serà només la potència bruta, sinó la traçabilitat: conservar un historial de decisions, supòsits i criteris d’acceptació que faci auditable els PRs generats per IA.
10.2. Testing i CI/CD integrats en el flux de l’agent
El futur immediat passa per agents que integren generació de proves i pipelines de CI/CD: linters, tests, cobertura bàsica, preview deploys i reportes de rendiment. El teu rol se centrarà a dissenyar les polítiques: què és acceptable, quins riscos no toleres i com s’han d’informar les regressions.
10.3. Especialització per dominis
Veurem agents “afinats” per ecosistemes concrets (WordPress, WooCommerce, plugins de pagament, frontends amb React/Blocks) amb convencions preaprenudes i catàlegs de millors pràctiques. Això reduirà encara més el temps de posada en marxa i l’esforç de revisió.
10.4. Documentació com a producte
La documentació deixarà de ser un apèndix per convertir-se en un producte paral·lel mantingut per l’agent. Documents.md evolucionarà a portals de coneixement navegables, amb snippets executables, esquemes visuals, diagrames i receptes versionades.
11. Conclusió
El Agentic Coding no és demanar a una IA que “faci un plugin”, sinó construir una relació de treball on tu marques el nord i la IA executa amb disciplina. L’ecosistema modern —nuvó, local, híbrid— et permet escollir la base tècnica; però el veritable diferencial està en com organitzes el procés: AGENTS.md per fixar regles, TODO.md gestionat per l’agent per orquestrar tasques, i Documents.md per capturar coneixement real del projecte mentre es crea.
Aquest enfocament et dóna velocitat sense sacrificar qualitat: redueixes temps en tasques repetitives, et centres en arquitectura i decisions importants, i mantens a ratlla el deute tècnic. Quina és la conseqüència? Projectes més coherents, fàcils de mantenir i amb una rampa d’incorporació suau per a qualsevol col·laborador futur.
Has vist, a més, com preparar un exemple pràctic que podràs completar amb el teu agent: “Simple Contact”.
El futur del desenvolupament és col·laboratiu: humans i agents treballant colze a colze amb processos clars, estàndards ferms i evidència constant. Comença avui pel teu flux i les teves regles; la IA farà la resta sota la teva direcció.
