Introduction au Agentic Coding avec IA
L'intelligence artificielle (IA) a changé la façon dont nous concevons le développement de logiciels. Il ne s'agit plus seulement de demander à un système de compléter une ligne de code : aujourd'hui, nous pouvons travailler avec des agents qui comprennent des objectifs, suivent des conventions, maintiennent une documentation vivante et collaborent avec nous de manière similaire à un membre de l'équipe. Cet approche sera appelée « Agentic Coding ». Ce guide, vaste et pratique, vous expliquera comment passer de l'idée à un flux professionnel où l'IA s'intègre dans votre quotidien en tant que développeur, en nous concentrant sur WordPress et sur un processus réel que vous pourrez reproduire dans vos projets.
Vous trouverez, d'une part, la base conceptuelle nécessaire pour comprendre l'IA moderne et le rôle des LLM (Large Language Models). D'autre part, vous verrez comment organiser le travail avec des fichiers clés qui articulent tout le processus : AGENTS.md (règles et portée), TODO.md (tableau qui gère l'agent) et Documents.md (documentation vivante). De plus, nous incluons de bonnes pratiques, des limitations réelles et une section d'exemple pratique qui fonctionnera comme un squelette de projet, avec des espaces clairement marqués pour que nous puissions plus tard incorporer du contenu technique concret (code, structures, etc.) en collaboration avec votre agent d'implémentation.
1. Introduction
1.1. Qu'est-ce que l'intelligence artificielle (IA) dans le développement ?
L'IA est une discipline vaste qui vise à ce que les machines accomplissent des tâches que nous associons à l'intelligence humaine : comprendre le langage naturel, raisonner à partir de descriptions, apprendre à partir de données ou planifier des actions. Après des décennies de progrès, le saut qualitatif récent arrive avec les Large Language Models (LLM). Ces modèles sont entraînés avec des volumes massifs de texte, apprennent des motifs de langage et acquièrent la capacité de générer des instructions, des explications et, par extension, du code cohérent avec un contexte donné.
Dans le domaine du développement, cela implique que nous ne dépendons plus d'outils qui suggèrent des tokens à la volée. Nous pouvons décrire des objectifs de haut niveau, imposer des normes de style, demander une documentation cohérente et coordonner des tâches. La valeur ne réside pas seulement dans « l'autocomplétion », mais dans structurer un travail technique soutenu dans le temps avec l'aide d'un agent qui comprend le projet.
1.2. Des assistants ponctuels aux agents
Le premier contact de nombreux programmeurs avec l'IA est venu de la main d'assistants ponctuels : moteurs de suggestion dans l'IDE, chatbots capables de répondre à des questions ou de générer des fonctions isolées. Utile, oui, mais limité lorsque nous voulons construire des systèmes avec cohérence sur des semaines ou des mois. En revanche, l'approche de l'Agentic Coding tire parti de la capacité des modèles à suivre des processus, à maintenir une mémoire opérationnelle (à travers des fichiers et des conventions) et à naviguer dans un backlog de manière planifiée. Autrement dit, nous passons d'une assistance réactive à une collaboration proactive guidée par des artefacts de projet.
1.3. Pourquoi l'IA n'est-elle pas « juste des chatbots » ?
L'image du « chatbot qui répond à des questions » est réductrice. Pour le développement, l'IA moderne peut :
- Générer et refactoriser du code en suivant des motifs d'architecture, des conventions de nommage et des normes (PHPCS, ESLint, etc.).
- Concevoir et mettre en œuvre des tests (unitaires et d'intégration) et proposer des cas limites.
- Écrire et maintenir la documentation technique et utilisateur pendant le développement, pas à la fin.
- Automatiser des tâches répétitives d'intégration, de migration d'APIs, de traductions et de commentaires dans le code.
- Explorer des options techniques avec des comparaisons argumentées (performance, sécurité, maintenance).
1.4. Définition opérationnelle de l'Agentic Coding
Nous appellerons Agentic Coding un flux de travail dans lequel le développeur humain définit des règles, des objectifs et des normes, et un agent (par exemple, Codex) opère dans ce cadre pour exécuter des tâches, proposer des sous-tâches, ouvrir des Pull Requests, maintenir un tableau de travail vivant et documenter ce qui a été construit. Votre rôle change : vous passez de coder chaque ligne à diriger le système, spécifier des critères d'acceptation, examiner les PRs et résoudre des blocages ou des ambiguïtés avec l'aide d'un copilote d'idées (par exemple, ChatGPT pour affiner la conception du processus ou rédiger des artefacts comme AGENTS.md).
2. Écosystème de travail avec IA pour les développeurs
2.1. Cloud, local et hybride
Il existe trois grandes façons de consommer des modèles :
- Cloud (OpenAI, Anthropic, Google) : facilité d'utilisation, mise à l'échelle automatique, latence raisonnable et modèles de dernière génération utilisant CLI si vous le souhaitez en local. Inconvénients : coût variable et politiques de données. Il existe également la possibilité d'utiliser par exemple Codex d'OpenAI, qui a un coût fixe qui dépend de ce que vous souscrivez, avec Plus (20 $/mois) cela suffit généralement. Ici, je parlerai de Codex.
- Local (Llama.cpp, Ollama, vLLM) : contrôle et confidentialité, dépendance minimale aux tiers et coûts d'utilisation très bas. Inconvénients : vous avez besoin de GPU/CPU puissants et de maintenance des modèles.
- Hybride: clouds pour la production et modèles locaux pour expérimentation, tests internes ou données sensibles. C'est généralement l'équilibre le plus pratique.
2.2. Critères de choix
Votre décision dépendra de :
- Confidentialité: traitez-vous des données sensibles ? Local ou hybride peuvent être préférables, bien qu'en théorie, la confidentialité soit maintenant assurée dans le cloud si vous le configurez ainsi.
- Coût: le projet va-t-il croître en utilisation ? Le coût par token dans le cloud peut augmenter ; en local, vous payez l'infrastructure.
- Vitesse de démarrage: le cloud gagne si vous voulez commencer aujourd'hui avec une friction minimale.
- Opération et maintenance: le local exige plus de DevOps ; le cloud externalise la complexité.
2.3. Outils complémentaires
- Dépôt: GitHub/GitLab/Bitbucket pour les PRs, les problèmes, les révisions.
- Éditeur: VSCode, avec des extensions pour les normes (PHPCS, ESLint), des formateurs (Prettier), et des assistants.
- CI/CD: tests automatiques, linters et déploiement contrôlé.
- Gestion des tâches: bien que TODO.md soit maintenu par l'agent, il est utile d'intégrer des signaux avec des problèmes étiquetés pour l'audit.
3. Préparer la base du flux de travail
3.1. Le trio qui articule le système
Dans cette approche, votre processus repose sur trois artefacts synchronisés :
- AGENTS.md: règles du jeu. Définit le but, la portée, les normes, la structure, les conventions, les critères de sécurité, les exigences de qualité et les attentes en matière de documentation. Si vous voulez plus d'informations sur AGENTS.md, vous pouvez l'obtenir ici.
- TODO.md: tableau vivant des tâches. Il est créé et maintenu par l'agent. Il montre ce qui sera fait, ce qui est en cours et ce qui a été terminé. Il ajoute également de nouvelles tâches émergentes.
- Documents.md: documentation vivante de ce qui a déjà été construit : API publique, fonctions, classes, hooks, schémas de données, flux et recettes d'utilisation. Il est également maintenu par l'agent au fur et à mesure de l'avancement.
3.2. Rôles clairs
- Vous: architecte et responsable de la qualité. Vous fixez des règles et des objectifs dans AGENTS.md, examinez les PRs, résolvez les ambiguïtés, demandez des corrections et de nouvelles tâches si vous détectez des lacunes.
- Agent d'implémentation (Codex): exécute, décide du découpage opérationnel dans TODO.md, fait des PRs incrémentales et enregistre la documentation dans Documents.md.
- Copilote d'idées (ChatGPT): vous aide à affiner AGENTS.md, à raisonner des alternatives, à rédiger des critères d'acceptation et à débloquer des problèmes complexes en examinant le code lorsque cela est nécessaire.
3.3. Itération disciplinée
Le succès ne dépend pas de « l'IA qui génère beaucoup de code », mais d'une itération disciplinée avec des cycles de : planifier (vous), exécuter (agent), examiner (vous), documenter (agent), et replanifier. Plus chaque étape est petite et vérifiable, mieux le système répond, moins il y a de risque de dette technique et plus il est facile d'auditer le travail.
4. AGENTS.md : contrat et ligne éditoriale du projet
4.1. Fonction stratégique de AGENTS.md
AGENTS.md est la boussole du projet. Ici, vous fixez l'intention, la portée et les limitations. De plus, vous établissez la ligne éditoriale du code : style, noms, structure, sécurité et documentation. C'est le document qui empêche l'agent d'improviser en dehors de vos normes. Pensez-y comme le «Guide for contributors» adapté à un collaborateur qui est IA.
4.2. Contenu recommandé
- Objectif et portée: quel problème résolvez-vous, ce que le projet ne fera pas et le résultat attendu.
- Normes: WordPress Coding Standards, PHPCS, traductions avec domaine concret, docblocks obligatoires.
- Sécurité: assainissement, échappement, nonces, rôles et capacités minimales, gestion des données personnelles.
- Structure des fichiers: arbre des répertoires et responsabilités par fichier/classe.
- Conventions de noms: préfixes de fonctions, classes, « handles » de scripts et styles.
- Critères d'acceptation: ce que vous considérez comme « fait » dans chaque tâche, comment cela est testé et quelles preuves sont valides.
- Attentes en matière de documentation: comment Documents.md est maintenu et quand il doit être mis à jour.
4.3. Bénéfice direct
Avec un bon AGENTS.md, les PRs de votre agent montrent une cohérence extrême : mêmes conventions, même structure, mêmes pratiques sûres. Votre révision est plus rapide, le projet est plus maintenable et l'intégration de tiers, plus simple.
5. TODO.md : le tableau qui gère l'agent
5.1. Un changement de contrôle fondamental
Dans ce flux, VOUS ne rédigez pas le TODO.md.Il est créé et maintenu par l'agent depuis le premier commit. Cela signifie que l'agent :
- Définit le découpage des tâches et l'ordre d'exécution.
- Déplacez des éléments entre les états : en attente, en cours, terminé.
- Ajoutez des tâches émergentes lorsque de nouveaux besoins ou risques sont détectés.
Que fais-tu alors ? Tu marques la direction dans AGENTS.md, tu examines les PRs et, si tu détectes des lacunes, tu demandes à Codex d'ajouter des tâches au TODO.md.. De cette manière, le tableau reflète comment l'agent lui-même comprend et planifie le travail, sans que tu aies à le microgérer.
5.2. Avantages de cette approche
- Autonomie opérationnelle: tu délègues l'orchestration des tâches, tout en conservant le contrôle stratégique.
- Transparence: TODO.md devient un registre auditable des décisions de l'agent.
- Agilité: de nouvelles tâches sont immédiatement intégrées au fur et à mesure qu'elles apparaissent pendant le développement.
6. Documents.md : mémoire technique vivante
6.1. Qu'est-ce que c'est et pourquoi est-ce important
Documents.md n'est pas un manuel écrit à la fin. C'est une base de connaissances vivante que l'agent met à jour au fur et à mesure de son développement. Il doit enregistrer la surface publique du projet : classes et méthodes, fonctions, shortcodes, hooks (actions/filtres), schémas de données, flux clés et recettes pratiques. Le principe est simple : si ce n'est pas dans Documents.md, c'est comme si cela n'existait pas pour les tiers..
6.2. Utilisation quotidienne
Lorsque tu reviens au projet après des jours ou des semaines, tu n'as pas besoin de traquer le code. Tu ouvres Documents.md et tu trouves :
- Comment s'appelle la fonction dont tu as besoin et quels paramètres elle accepte.
- Quel filtre tu dois accrocher pour modifier un comportement.
- Quelles colonnes il y a dans une table et quels index sont définis.
- Comment étendre ou réutiliser un flux avec un exemple minimum viable.
6.3. Politique de mise à jour
- Tout PR qui change la surface publique doit inclure une mise à jour de Documents.md.
- Si une API est ajoutée, un exemple d'utilisation reproductible doit être ajouté.
- Si le schéma de données est modifié, la migration et sa justification doivent être notées.
7. Bonnes pratiques de codage Agentic
7.1. Scrupuleux avec les normes
Maintiens la cohérence : WordPress Coding Standards avec PHPCS, docblocks clairs, i18n en anglais (et traductions si nécessaire), et nomenclature prévisible. Un agent fonctionne mieux lorsque les règles sont claires et appliquées de manière uniforme.
7.2. Sécurité par défaut
- Sanitise les entrées avec des fonctions appropriées (
sanitize_text_field,sanitize_email, etc.). - Échappe les sorties en HTML (
esc_html,esc_attr,wp_ksessi du HTML est autorisé). - Nonces dans les formulaires et vérification côté serveur.
- Principe de privilège minimum dans les rôles/capacités.
7.3. Tâches petites et vérifiables
Décompose les travaux en unités de livraison que tu peux examiner en quelques minutes. Demande à l'agent des PRs petits avec une seule intention. Ainsi, tu réduis les erreurs, accélères les révisions et favorises l'apprentissage incrémental du système.
7.4. Critères d'acceptation clairs
Dans AGENTS.md, définis “Définition de Terminé” pour les types de tâches : par exemple, “une fonctionnalité est prête quand :
- Quand elle passe PHPCS.
- Inclut des tests de base ou des étapes manuelles de vérification.
- Met à jour Documents.md.
- A une i18n correcte.
7.5. Documentation parallèle
Exige que l'agent mette à jour Documents.md dans le même PR qui introduit des changements fonctionnels. Tu évites la désynchronisation et réduis la friction.
7.6. Audit continu
Après un certain nombre de PRs, fais des “jalons” de révision transversale : structure du repo, dépendances, performance, sécurité, couverture de documentation. Si tu détectes une dégradation, renforce AGENTS.md et ouvre des tâches correctives (que l'agent transférera au TODO.md).
8. Limitations et réalisme opérationnel
8.1. Dépendance du contexte
Les LLM ont des limites contextuelles. L'agent ne “voit” pas tout le repo à la fois ; sa performance s'améliore lorsque tu travailles par itérations limitées, avec des artefacts qui fixent la mémoire (AGENTS.md, Documents.md) et avec des PRs petites.
8.2. Ambiguïté et son coût
Si tes exigences sont vagues, l'agent aura tendance à combler les lacunes avec des suppositions. Résultat : reworks. Solution : définis des objectifs, des contraintes et des exemples. La clarté initiale fait économiser des cycles entiers.
8.3. Erreurs plausibles
L'IA peut générer du code “plausible mais incorrect”. Réduis ce risque avec des linters, des tests de base et des révisions humaines. Souviens-toi : le rôle de l'humain ne disparaît pas, il s'élève à celui de curateur et d'architecte.
8.4. Changements de portée
Les projets vivants évoluent. L'agent le gère mieux si tu l'entraînes à proposer de nouvelles tâches dans TODO.md lorsqu'il détecte des impacts collatéraux, et tu valides cette proposition avant d'exécuter.
9. Exemple pratique : squelette du projet “Simple Contact Shortcode & Block”
Pour connecter la théorie à une mise en œuvre réelle, nous allons ancrer un projet simple dans WordPress qui servira de démonstration du flux de codage Agentic. À ce stade, nous n inclurons pas le code final (nous y travaillerons plus tard avec ton agent). Nous laisserons, à la place, les conteneurs structurels et les espaces bien visibles où nous insérerons les artefacts et pièces techniques lorsqu'ils seront prêts. Ainsi, tu pourras publier le guide aujourd'hui et, étape par étape, compléter l'exemple sans réécrire l'entrée.
9.1. Objectif du plugin
Le plugin “Simple Contact Shortcode & Block” fournira un formulaire de contact très basique (Nom et Email) qui pourra être ajouté à n'importe quelle page de deux manières : via un shortcode et via un bloc Gutenberg.En envoyant le formulaire, il enregistrera les données dans une table propre dans la base de données et notifiera par email l'administrateur du site.
9.2. Structure des répertoires attendue
/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. Artefacts du flux Agentic
- AGENTS.md fixera les règles et attentes d'implémentation.
- TODO.md sera créé et maintenu par Codex. Ici apparaîtra le backlog et la priorisation que l'agent lui-même décidera.
- Documents.md grandira avec le catalogue d'APIs, hooks et flux au fur et à mesure de leur implémentation.
9.4. Fichiers
Comme nous l'avons mentionné, nous devrons créer un fichier AGENTS.md qui sera ce que suivra Codex.
Ce qu'il faut faire, c'est avoir une idée claire de ce que l'on souhaite, une fois que tout est clair et que l'on a “parlé” avec ChatGPT de tout le projet, on lui demande de créer un AGENTS.md avec toutes les règles et définissant le projet.
D'accord, maintenant nous allons créer l'AGENTS.md avec tout ce dont nous avons parlé pour que Codex ait un guide exact de ce qu'il doit faire et comment.
J'ai besoin que tu me crées correctement et complètement tout l'AGENTS.md pour le projet.
Tu dois ajouter tout le schéma de fichiers, respecter toutes les normes de sécurité de WordPress, toutes les mesures de sécurité, noms de fichiers, préfixes dans les fichiers, classes, fonctions, etc. standardisés, en-têtes et commentaires dans tous les fichiers, fonctions, routes et méthodes comme spécifié par WordPress. Toutes les chaînes doivent être en anglais et traduisibles. Il est très important que le PHPCS soit toujours passé en maintenant tous les alignements avec leurs tabulations et espaces.
Tu dois également mentionner et expliquer exactement l'utilisation de TODO.md et Documents.md pour qu'il les utilise dès le début et ne doive pas le faire plus tard. Précise-lui que si un fichier est très grand, comme cela peut arriver avec un fichier par exemple po de traduction, il doit les créer dans différents PRs pour qu'il puisse toujours créer des PRs et ne se retrouve pas dans l'impossibilité de le faire à cause de la taille.
Le dépôt doit également avoir les fichiers .gitignore (fichiers de développement et fichiers OS) .gitignore et
.gitattributes pour que seul ce qui doit être dans le paquet final arrive et que des fichiers non nécessaires de l'OS sur lequel on travaille n'arrivent pas dans le dépôt.Crée l'AGENTS.md en anglais.
Après cette invite, ChatGPT me renvoie le contenu que je devrai coller dans 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.Note que dans l'invite, je n'ai pas mentionné ce que je veux que le plugin fasse, car ChatGPT le sait déjà par toute la conversation précédente que j'ai eue avec lui et tout ce que nous avons discuté a rédigé cet AGENTS.md qui est super complet, ce qui serait plus compliqué si je devais le faire moi-même, car ce n'est pas seulement que je pourrais oublier quelque chose, mais aussi que ChatGPT sait comment les choses doivent être dites, donc rédige un AGENTS.md en accord avec ses besoins. C'est pourquoi il est si important d'en discuter avec lui, pour qu'il ait également une idée claire de tout ce que tu veux.
Nous devons maintenant créer le dépôt sur Github si nous ne l'avons pas. Donc, nous allons Github et créons un nouveau dépôt qui peut être public ou privé, dans mon cas je vais le créer public pour que vous ayez tous accès à lui..
La première chose que nous devrons faire est de récupérer le dépôt en local, nous pouvons utiliser par exemple GitHub Desktop qui est disponible pour tous les OS.
Une fois que nous l'avons en local, nous créerons le fichier AGENTS.md en collant ce que ChatGPT nous a dit
et nous le téléchargerons sur Github, via Github Desktop.
Une fois téléchargé, nous pouvons déjà voir sur Github que nous avons le fichier AGENTS.md dans notre dépôt. Nous n'avons plus besoin de plus pour commencer avec Codex.
Maintenant, nous allons Codex et la première chose que nous devrons faire est d'ajouter ce dépôt (si c'est la première fois que tu accèdes à Codex, il te demandera d'abord de lui donner des permissions d'accès à ton compte Github). Il suffit d'appuyer sur créer un environnement, et nous le configurerons.
La partie de base sera configurée ainsi en sélectionnant le dépôt.
Mais fais attention à cette dernière partie. Il est souvent nécessaire de le mettre ainsi, car il a besoin de paquets pour par exemple compiler React, sinon il ne pourra pas le faire, mais vous pouvez toujours activer et désactiver cette option, car elle peut être changée.
Il ne reste plus qu'à appuyer sur Créer un environnement.
Une fois que nous avons créé l'environnement, nous devons juste commencer à faire travailler Codex. Sélectionne dans Codex le dépôt avec lequel tu veux travailler, le reste peut rester tel quel.
Et une fois sélectionné, il suffit de faire une invite aussi simple que celle-ci :
Développe tout ce qu'il y a dans AGENTS.md et souviens-toi d'utiliser le TODO.md et le Documents.md.
Et nous appuierons sur Programmer, et il commencera à travailler sur le code.
Après un certain temps, cela dépend de tout ce qu'il a fait, il nous montrera tous les changements qu'il a réalisés, qui dans ce cas, tout est du code à ajouter.
{{AITR_249}}
En appuyant sur la tâche, nous y accéderons et pourrons voir tout ce qu'il a fait, le réviser et créer la PR ou lui demander des modifications.
Dans ce cas, je ne vais rien réviser car c'est une démo, donc je clique d'abord sur « Créer une demande de tirage » puis sur « Voir la PR » une fois que le bouton apparaît.
Cela nous mènera à Github, où nous pourrons également réviser les modifications et les accepter.
Nous cliquerons sur « Fusionner la demande de tirage » et nous aurons déjà tout le nouveau code ajouté au plugin.
Nous pouvons maintenant voir le TODO.md et le Documents.md où nous pourrons suivre tout et obtenir une documentation pour l'avenir.
Si nous regardons le TODO.md, à ce stade, nous pouvons voir qu'il y a encore beaucoup de choses en cours et en attente, donc Codex doit continuer. Nous devrons simplement indiquer à Codex de continuer le travail.
Nous répéterons cela jusqu'à ce qu'il n'y ait plus de tâches dans le TODO.md et que tout soit fait. Il viendra un moment où il n'y aura plus rien en attente et en cours, et nous pourrons tester le résultat final sur un site de développement. Surtout TOUJOURS de développement.
Une fois installé, cela peut fonctionner du premier coup ou non, dans mon cas, une erreur fatale est survenue.
Donc, ce que je fais, c'est copier l'erreur pour que Codex la corrige en lui donnant du contexte.
Après avoir terminé, créez une nouvelle PR pour le corriger et le plugin peut déjà être activé.
Si nous créons maintenant un nouvel article/page, nous verrons dans les blocs qu'il y en a un qui s'appelle « Formulaire de contact simple », et que nous pouvons spécifier le message de succès de l'envoi. Dans ce cas, comme nous n'avons pas spécifié dans AGENTS.md que nous devions pouvoir configurer l'email auquel il doit être envoyé, il l'enverra toujours à l'email de l'administrateur de WordPress.
À l'avant, nous verrons cela (rappelez-vous que nous avions spécifié que le formulaire ne devait avoir que le nom et l'email).
Si maintenant vous vouliez ajouter plus de champs, par exemple Sujet et Commentaires, il suffirait de le demander à Codex en lui disant que cela met à jour AGENTS.md, TODO.md et Documents.md.
Si je remplis les champs et clique sur Envoyer, je reçois cela par email.
C'est-à-dire que nous n'avons eu qu'une seule erreur fatale dans le plugin que Codex a développé pour nous, et qu'il a corrigée du premier coup en lui indiquant laquelle c'était.
C'est un plugin très simple, mais c'est un plugin qui incorpore un bloc pour Gutenberg, ce qui n'est pas rien.
Si nous récapitulons tout ce que nous lui avons demandé au départ, nous verrons qu'il manque un certain sujet, soit parce qu'il y a un bug et qu'il ne s'affiche pas, soit parce qu'il ne l'a tout simplement pas fait, donc à partir de ce moment, il s'agit de faire des demandes de corrections jusqu'à atteindre ce que nous souhaitons.
10. Avenir du codage agentique
10.1. Plus d'autonomie, plus de traçabilité
À mesure que les modèles évolueront, nous verrons des agents capables de planifier des itérations plus longues, de détecter des dépendances et de coordonner des changements plus profonds. La clé ne sera pas seulement la puissance brute, mais la traçabilité: conserver un historique des décisions, des hypothèses et des critères d'acceptation qui rendent les PR générés par l'IA audités.
10.2. Tests et CI/CD intégrés dans le flux de l'agent
L'avenir immédiat passe par des agents qui intègrent la génération de tests et des pipelines de CI/CD : linters, tests, couverture de base, déploiements de prévisualisation et rapports de performance. Votre rôle se concentrera sur la conception des politiques : ce qui est acceptable, quels risques vous ne tolérez pas et comment les régressions doivent être rapportées.
10.3. Spécialisation par domaines
Nous verrons des agents « affinés » pour des écosystèmes spécifiques (WordPress, WooCommerce, plugins de paiement, frontends avec React/Blocks) avec des conventions pré-apprises et des catalogues de meilleures pratiques. Cela réduira encore le temps de mise en route et l'effort de révision.
10.4. Documentation comme produit
La documentation cessera d'être un appendice pour devenir un produit parallèle maintenu par l'agent. Documents.md évoluera vers des portails de connaissance navigables, avec des extraits exécutables, des schémas visuels, des diagrammes et des recettes versionnées.
11. Conclusion
Le codage agentique n'est pas de demander à une IA de « faire un plugin », mais de construire une relation de travail où vous fixez le cap et l'IA exécute avec discipline. L'écosystème moderne —cloud, local, hybride— vous permet de choisir la base technique ; mais le véritable différentiel réside dans la manière dont vous organisez le processus : AGENTS.md pour établir des règles, TODO.md géré par l'agent pour orchestrer les tâches, et Documents.md pour capturer le savoir réel du projet pendant qu'il se crée.
Cette approche vous donne de la vitesse sans sacrifier la qualité : vous réduisez le temps consacré aux tâches répétitives, vous vous concentrez sur l'architecture et les décisions importantes, et vous gardez la dette technique sous contrôle. Quel est le résultat ? Des projets plus cohérents, faciles à maintenir et avec une courbe d'incorporation douce pour tout futur collaborateur.
Vous avez également vu comment préparer un exemple pratique que vous pourrez compléter avec votre agent : « Formulaire de contact simple ».
L'avenir du développement est collaboratif : humains et agents travaillant côte à côte avec des processus clairs, des normes solides et une preuve constante. Commencez dès aujourd'hui par votre flux et vos règles ; l'IA fera le reste sous votre direction.
