Einführung in Agentic Coding mit IA
Künstliche Intelligenz (KI) hat die Art und Weise verändert, wie wir die Softwareentwicklung betrachten. Es geht nicht mehr nur darum, ein System zu bitten, eine Codezeile zu vervollständigen: Heute können wir mit Agenten arbeiten, die Ziele verstehen, Konventionen folgen, lebendige Dokumentation führen und ähnlich wie ein weiteres Teammitglied mit uns zusammenarbeiten. Diesen Ansatz nennen wir „Agentic Coding“. Dieser umfassende und praktische Leitfaden erklärt dir, wie du von der Idee zu einem professionellen Workflow übergehst, in dem KI in deinen Alltag als Entwickler integriert wird, wobei wir uns auf WordPress und einen realen Prozess konzentrieren, den du in deinen Projekten replizieren kannst.
Du wirst einerseits die konzeptionelle Basis finden, die notwendig ist, um moderne KI und die Rolle von LLMs (Large Language Models) zu verstehen. Andererseits wirst du sehen, wie du die Arbeit mit Schlüsseldateien organisierst, die den gesamten Prozess strukturieren: AGENTS.md (Regeln und Umfang), TODO.md (Tafel, die der Agent führt) und Documents.md (lebendige Dokumentation). Außerdem enthalten wir bewährte Praktiken, reale Einschränkungen und einen Abschnitt mit praktischen Beispielen, der als Projektskelett fungiert, mit klar gekennzeichneten Bereichen, in die wir später konkrete technische Inhalte (Code, Strukturen usw.) in Zusammenarbeit mit deinem Implementierungsagenten einfügen können.
1. Einführung
1.1. Was ist Künstliche Intelligenz (KI) in der Entwicklung?
KI ist ein breites Fachgebiet, das darauf abzielt, dass Maschinen Aufgaben ausführen, die wir mit menschlicher Intelligenz assoziieren: natürliche Sprache verstehen, aus Beschreibungen schlussfolgern, aus Daten lernen oder Handlungen planen. Nach Jahrzehnten des Fortschritts kommt der qualitative Sprung jüngst mit den Large Language Models (LLM). Diese Modelle werden mit massiven Textmengen trainiert, lernen Sprachmuster und erwerben die Fähigkeit, Anweisungen, Erklärungen und, im weiteren Sinne, Code zu generieren, der mit einem gegebenen Kontext übereinstimmt.
Im Bereich der Entwicklung bedeutet dies, dass wir nicht mehr auf Werkzeuge angewiesen sind, die im Handumdrehen Tokens vorschlagen. Wir können hochrangige Ziele beschreiben, Stilstandards durchsetzen, konsistente Dokumentation anfordern und Aufgaben koordinieren. Der Wert liegt nicht nur im „Autovervollständigen“, sondern im Strukturieren einer technischen Arbeit, die über die Zeit hinweg mit Hilfe eines Agenten, der das Projekt versteht, aufrechterhalten wird.
1.2. Von punktuellen Assistenten zu Agenten
Der erste Kontakt vieler Programmierer mit KI kam durch punktuelle Assistenten: Vorschlagsmotoren im IDE, Chatbots, die Fragen beantworten oder lose Funktionen generieren können. Nützlich, ja, aber begrenzt, wenn wir Systeme mit Kohärenz über Wochen oder Monate hinweg aufbauen wollen. Im Gegensatz dazu nutzt der Ansatz von Agentic Coding die Fähigkeit der Modelle, Prozesse zu verfolgen, operationale Erinnerungen (durch Dateien und Konventionen) zu bewahren und planmäßig durch ein Backlog zu navigieren. Das heißt, wir gehen von einer reaktiven Unterstützung zu einer proaktiven Zusammenarbeit über Projektartefakte.
1.3. Warum ist KI nicht nur „Chatbots“?
Das Bild des „Chatbots, der Fragen beantwortet“, ist unzureichend. Für die Entwicklung kann moderne KI:
- Code generieren und refaktorisieren unter Berücksichtigung von Architekturmustern, Namenskonventionen und Standards (PHPCS, ESLint usw.).
- Tests entwerfen und implementieren (Unit- und Integrationstests) und Grenzfälle vorschlagen.
- Technische und Benutzerdokumentation schreiben und pflegen während der Entwicklung, nicht am Ende.
- Wiederholbare Aufgaben automatisieren von Integration, API-Migrationen, Übersetzungen und Kommentaren im Code.
- Technische Optionen erkunden mit argumentierten Vergleichen (Leistung, Sicherheit, Wartung).
1.4. Operative Definition von Agentic Coding
Wir nennen Agentic Coding einen Workflow in dem der menschliche Entwickler Regeln, Ziele und Standards definiert, und ein Agent (z. B. Codex) innerhalb dieses Rahmens Aufgaben ausführt, Unteraufgaben vorschlägt, Pull Requests öffnet, ein lebendiges Arbeitstafel führt und das Gebaute dokumentiert. Deine Rolle ändert sich: Du gehst von der Codierung jeder Zeile zu der Leitung des Systems, spezifizierst Akzeptanzkriterien, überprüfst PRs und löst Blockaden oder Mehrdeutigkeiten mit Hilfe eines Ideen-Co-Piloten (zum Beispiel ChatGPT, um das Design des Prozesses zu verfeinern oder Artefakte wie AGENTS.md zu erstellen).
2. Arbeitsökosystem mit KI für Entwickler
2.1. Cloud, lokal und hybrid
Es gibt drei Hauptarten, Modelle zu konsumieren:
- Cloud (OpenAI, Anthropic, Google): Benutzerfreundlichkeit, automatische Skalierung, angemessene Latenz und modernste Modelle, die bei Bedarf lokal über CLI verwendet werden können. Nachteile: variable Kosten und Datenschutzrichtlinien. Es gibt auch die Möglichkeit, beispielsweise Codex von OpenAI zu nutzen, das feste Kosten hat, die von dem abhängen, was du buchst; mit Plus ($20/Monat) ist es in der Regel ausreichend. Hier werde ich über Codex sprechen.
- Lokal (Llama.cpp, Ollama, vLLM): Kontrolle und Privatsphäre, minimale Abhängigkeit von Dritten und sehr niedrige Nutzungskosten. Nachteile: du benötigst leistungsstarke GPU/CPU und Wartung der Modelle.
- Hybrid: Clouds für die Produktion und lokale Modelle für Experimente, interne Tests oder sensible Daten. Dies ist oft das praktischste Gleichgewicht.
2.2. Auswahlkriterien
Deine Entscheidung hängt von ab:
- Privatsphäre: Verarbeitest du sensible Daten? Lokal oder hybrid könnten bevorzugt werden, obwohl theoretisch jetzt die Privatsphäre in der Cloud sichergestellt ist, wenn du es so konfigurierst.
- Kosten: Wird das Projekt im Gebrauch wachsen? Die Kosten pro Token in der Cloud können steigen; lokal zahlst du für die Infrastruktur.
- Startgeschwindigkeit: die Cloud gewinnt, wenn du heute mit minimalem Aufwand starten möchtest.
- Betrieb und Wartung: lokal erfordert mehr DevOps; die Cloud lagert Komplexität aus.
2.3. Ergänzende Werkzeuge
- Repository: GitHub/GitLab/Bitbucket für PRs, Issues, Überprüfungen.
- Editor: VSCode, mit Erweiterungen für Standards (PHPCS, ESLint), Formatter (Prettier) und Assistenten.
- CI/CD: automatische Tests, Linter und kontrollierte Bereitstellung.
- Aufgabenmanagement: obwohl TODO.md vom Agenten verwaltet wird, ist es nützlich, Signale mit gekennzeichneten Issues für die Prüfung zu integrieren.
3. Vorbereitung der Grundlage des Workflows
3.1. Das Trio, das das System artikuliert
In diesem Ansatz stützt sich dein Prozess auf drei synchronisierte Artefakte:
- AGENTS.md: Spielregeln. Definiert Zweck, Umfang, Standards, Struktur, Konventionen, Sicherheitskriterien, Qualitätsanforderungen und Dokumentationserwartungen. Wenn du mehr Informationen über AGENTS.md möchtest, kannst du sie hier erhalten.
- TODO.md: lebendige Aufgabenliste. Wird vom Agenten erstellt und gepflegt. Darin sieht man, was getan wird, was in Arbeit ist und was abgeschlossen ist. Es fügt auch neue, aufkommende Aufgaben hinzu.
- Documents.md: lebendige Dokumentation des bereits Gebauten: öffentliche API, Funktionen, Klassen, Hooks, Datenschemata, Workflows und Nutzungshinweise. Wird ebenfalls vom Agenten gepflegt, während es voranschreitet.
3.2. Klare Rollen
- Du: Architekt und Qualitätsverantwortlicher. Legst Regeln und Ziele in AGENTS.md fest, überprüfst PRs, klärst Mehrdeutigkeiten, forderst Korrekturen und neue Aufgaben an, wenn du Lücken entdeckst.
- Implementierungsagent (Codex): führt aus, entscheidet über die operative Aufschlüsselung in TODO.md, erstellt inkrementelle PRs und dokumentiert in Documents.md.
- Ideen-Co-Pilot (ChatGPT): hilft dir, AGENTS.md zu verfeinern, Alternativen zu durchdenken, Akzeptanzkriterien zu formulieren und komplexe Probleme zu lösen, indem er den Code überprüft, wenn es nötig ist.
3.3. Disziplinierte Iteration
Der Erfolg hängt nicht von „der KI ab, die viel Code generiert“, sondern von einer disziplinierten Iteration mit Zyklen von: planen (du), ausführen (Agent), überprüfen (du), dokumentieren (Agent) und erneut planen. Je kleiner und überprüfbarer jeder Schritt ist, desto besser reagiert das System, desto geringer ist das Risiko technischer Schulden und desto einfacher ist es, die Arbeit zu prüfen.
4. AGENTS.md: Vertrag und redaktionelle Linie des Projekts
4.1. Strategische Funktion von AGENTS.md
AGENTS.md ist der Kompass des Projekts. Hier legst du die Absicht, den Umfang und die Einschränkungen fest. Außerdem legst du die redaktionelle Linie des Codes fest: Stil, Namen, Struktur, Sicherheit und Dokumentation. Es ist das Dokument, das verhindert, dass der Agent außerhalb deiner Standards improvisiert. Denke daran, es als den „Guide for contributors“ angepasst an einen Mitwirkenden, der KI ist.
4.2. Empfohlener Inhalt
- Ziel und Umfang: welches Problem löst du, was wird das Projekt nicht tun und welches Ergebnis wird erwartet.
- Standards: WordPress Coding Standards, PHPCS, Übersetzungen mit spezifischem Fokus, obligatorische Docblocks.
- Sicherheit: Sanitärmaßnahmen, Escaping, Nonces, minimale Rollen und Berechtigungen, Umgang mit persönlichen Daten.
- Dateistruktur: Verzeichnisbaum und Verantwortlichkeiten pro Datei/Klasse.
- Namenskonventionen: Funktionspräfixe, Klassen, „Handles“ von Skripten und Stilen.
- Akzeptanzkriterien: was du in jeder Aufgabe als „fertig“ betrachtest, wie getestet wird und welche Nachweise gültig sind.
- Dokumentationserwartungen: wie Documents.md gepflegt wird und wann es aktualisiert werden sollte.
4.3. Direkter Nutzen
Mit einem guten AGENTS.md zeigen die PRs deines Agenten extreme Kohärenz: dieselben Konventionen, dieselbe Struktur, dieselben sicheren Praktiken. Deine Überprüfung ist schneller, das Projekt ist wartungsfreundlicher und die Einbindung Dritter ist einfacher.
5. TODO.md: das Tafel, das der Agent verwaltet
5.1. Ein grundlegender Kontrollwechsel
In diesem Workflow schreibst du das TODO.md nicht.Es wird vom Agenten seit dem ersten Commit erstellt und gepflegt. Das bedeutet, dass der Agent:
- Die Aufschlüsselung der Aufgaben und die Reihenfolge der Ausführung definiert.
- Bewege Elemente zwischen Zuständen: ausstehend, in Bearbeitung, abgeschlossen.
- Füge dringende Aufgaben hinzu, wenn neue Bedürfnisse oder Risiken erkannt werden.
Was machst du dann? Du markierst den Kurs in AGENTS.md, überprüfst PRs und, wenn du Lücken entdeckst, bittest du Codex, Aufgaben zu TODO.md hinzuzufügen.. Auf diese Weise spiegelt das Board wider wie der Agent selbst die Arbeit versteht und plant, ohne dass du es mikromanagen musst.
5.2. Vorteile dieses Ansatzes
- Betriebliche Autonomie: Du delegierst die Orchestrierung von Aufgaben und behältst die strategische Kontrolle.
- Transparenz: TODO.md wird zu einem prüfbaren Protokoll der Entscheidungen des Agenten.
- Agilität: Neue Aufgaben werden sofort hinzugefügt, sobald sie während der Entwicklung entstehen.
6. Documents.md: lebendiges technisches Gedächtnis
6.1. Was es ist und warum es wichtig ist
Documents.md ist kein am Ende geschriebenes Handbuch. Es ist ein lebendiges Wissensbasis die der Agent aktualisiert, während er entwickelt. Es sollte die öffentliche Oberfläche des Projekts dokumentieren: Klassen und Methoden, Funktionen, Shortcodes, Hooks (Aktionen/Filter), Datenschemata, Schlüsselabläufe und praktische Rezepte. Die Maxime ist einfach: Wenn es nicht in Documents.md steht, ist es für Dritte, als ob es nicht existiert..
6.2. Alltägliche Nutzung
Wenn du nach Tagen oder Wochen zum Projekt zurückkehrst, musst du keinen Code verfolgen. Du öffnest Documents.md und findest:
- Wie die Funktion heißt, die du benötigst und welche Parameter sie akzeptiert.
- Welchen Filter du einhaken musst, um ein Verhalten zu ändern.
- Welche Spalten in einer Tabelle vorhanden sind und welche Indizes definiert sind.
- Wie man einen Ablauf mit einem minimalen tragfähigen Beispiel erweitert oder wiederverwendet.
6.3. Aktualisierungspolitik
- Jeder PR, der die öffentliche Oberfläche ändert, muss die Aktualisierung von Documents.md beinhalten.
- Wenn eine API hinzugefügt wird, muss ein reproduzierbares Anwendungsbeispiel hinzugefügt werden.
- Wenn das Datenschema geändert wird, muss die Migration und ihre Begründung dokumentiert werden.
7. Gute Praktiken des Agentic Coding
7.1. Genauigkeit bei Standards
Halte Konsistenz: WordPress Coding Standards mit PHPCS, klare Docblocks, i18n in Englisch (und Übersetzungen wo nötig) und vorhersehbare Benennung. Ein Agent arbeitet besser, wenn die Regeln klar sind und einheitlich angewendet werden.
7.2. Sicherheit als Standard
- Bereinige Eingaben mit geeigneten Funktionen (
sanitize_text_field,sanitize_email, usw.). - Entkomme Ausgaben in HTML (
esc_html,esc_attr,wp_kseswenn HTML erlaubt ist). - Nonces in Formularen und serverseitige Überprüfung.
- Prinzip der minimalen Berechtigung in Rollen/Fähigkeiten.
7.3. Kleine und überprüfbare Aufgaben
Zerlege Arbeiten in Liefer-Einheiten, die du in Minuten überprüfen kannst. Bitte den Agenten um kleine PRs mit nur einer Absicht. So reduzierst du Fehler, beschleunigst Überprüfungen und förderst das inkrementelle Lernen des Systems.
7.4. Klare Akzeptanzkriterien
Definiere in AGENTS.md die “Definition of Done” für Aufgabentypen: zum Beispiel, “eine Funktionalität ist bereit, wenn:
- Wenn sie PHPCS besteht.
- Sie grundlegende Tests oder manuelle Überprüfungsschritte enthält.
- Documents.md aktualisiert.
- Sie hat korrekte i18n.
7.5. Parallel-Dokumentation
Fordere den Agenten auf, Documents.md im selben PR zu aktualisieren, der funktionale Änderungen einführt. So vermeidest du Desynchronisation und reduzierst Reibung.
7.6. Kontinuierliche Prüfung
Nach einer bestimmten Anzahl von PRs, mache „Meilensteine“ der Querschnittsprüfung: Repo-Struktur, Abhängigkeiten, Leistung, Sicherheit, Dokumentationsabdeckung. Wenn du eine Verschlechterung feststellst, verstärke AGENTS.md und öffne Korrekturaufgaben (die der Agent in TODO.md übertragen wird).
8. Einschränkungen und operationale Realität
8.1. Abhängigkeit vom Kontext
LLMs haben kontextuelle Grenzen. Der Agent „sieht“ nicht das gesamte Repo auf einmal; seine Leistung verbessert sich, wenn du in begrenzten Iterationen arbeitest, mit Artefakten, die das Gedächtnis festigen (AGENTS.md, Documents.md) und mit kleinen PRs.
8.2. Mehrdeutigkeit und ihre Kosten
Wenn deine Anforderungen vage sind, wird der Agent dazu tendieren, Lücken mit Annahmen zu füllen. Ergebnis: Nacharbeiten. Lösung: Definiere Ziele, Einschränkungen und Beispiele. Die anfängliche Klarheit spart ganze Zyklen.
8.3. Plausible Fehler
KI kann „glaubwürdigen, aber falschen“ Code generieren. Reduziere dieses Risiko mit Lintern, grundlegenden Tests und menschlichen Überprüfungen. Denk daran: Die Rolle des Menschen verschwindet nicht, sie wird zum Kurator und Architekten erhoben.
8.4. Änderungen des Umfangs
Lebende Projekte entwickeln sich weiter. Der Agent verwaltet es besser, wenn du ihn trainierst, um neue Aufgaben in TODO.md vorzuschlagen, wenn er collateral impacts erkennt, und du diese Vorschläge validierst, bevor du sie ausführst. 9. Praktisches Beispiel: Skelett des Projekts „Einfacher Kontakt-Shortcode & Block“
Um die Theorie mit einer realen Implementierung zu verbinden, werden wir ein einfaches Projekt in WordPress verankern, das als Demonstration des Agentic Coding-Flusses dient. An diesem Punkt
werden wir den endgültigen Code nicht einfügen (wir werden ihn später mit deinem Agenten bearbeiten). Stattdessen lassen wir die strukturellen Container und die gut sichtbaren Plätze, an denen wir die Artefakte und technischen Teile einfügen werden, wenn sie bereit sind. So kannst du die Anleitung heute veröffentlichen und Schritt für Schritt das Beispiel vervollständigen, ohne den Beitrag neu zu schreiben.
9.1. Ziel des Plugins
Das Plugin „Einfacher Kontakt-Shortcode & Block“ wird ein sehr einfaches Kontaktformular (Name und E-Mail) bereitstellen, das auf jede Seite auf zwei Arten hinzugefügt werden kann: über einen Shortcode und über einen Gutenberg-Block.Beim Absenden des Formulars werden die Daten in einer eigenen Tabelle in der Datenbank gespeichert und der Administrator der Website per E-Mail benachrichtigt.
9.2. Erwartete Verzeichnisstruktur
/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. Artefakte des Agentic-Flusses
- AGENTS.md wird die Regeln und Erwartungen der Implementierung festlegen.
- TODO.md wird von Codex erstellt und gepflegt. Hier wird der Backlog und die Priorisierung erscheinen, die der Agent selbst entscheidet.
- Documents.md wird mit dem Katalog von APIs, Hooks und Abläufen wachsen, während sie implementiert werden.
9.4. Dateien
Wie bereits erwähnt, müssen wir eine Datei AGENTS.md erstellen, die Codex folgen wird.
Was zu tun ist, ist eine klare Vorstellung davon zu haben, was gewünscht wird, sobald alles klar ist und man mit ChatGPT über das gesamte Projekt „gesprochen“ hat, wird er gebeten, ein AGENTS.md mit allen Regeln zu erstellen und das Projekt zu definieren.
Okay, jetzt werden wir das AGENTS.md mit allem, was wir besprochen haben, erstellen, damit Codex eine genaue Anleitung hat, was er tun und wie er es tun soll.
Ich brauche, dass du mir das AGENTS.md korrekt und vollständig für das Projekt erstellst.
Du musst das gesamte Dateischema hinzufügen, das alle Sicherheitsstandards von WordPress einhält, alle Sicherheitsmaßnahmen, Dateinamen, Präfixe in Dateien, Klassen, Funktionen usw. standardisiert, Header und Kommentare in allen Dateien, Funktionen, Straßen und Methoden, wie es WordPress vorschreibt. Alle Zeichenfolgen müssen in Englisch sein und übersetzbar. Es ist sehr wichtig, dass PHPCS immer bestanden wird, wobei alle Ausrichtungen mit ihren Einrückungen und Abständen beibehalten werden.
Du musst auch genau den Gebrauch von TODO.md und Documents.md erwähnen und erklären, damit sie von Anfang an genutzt werden und nicht später gemacht werden müssen. Erkläre ihm, dass, wenn eine Datei sehr groß ist, wie es beispielsweise bei einer Übersetzungsdatei der Fall sein kann, sie in verschiedenen PRs erstellt werden muss, damit er immer PRs erstellen kann und nicht in der Unmöglichkeit ist, dies aufgrund der Größe zu tun.
Das Repository muss auch die Dateien .gitignore (Entwicklungsabfälle und OS-Dateien) .gitignore und
.gitattributes enthalten, damit nur das, was im endgültigen Paket sein soll, ankommt und keine unnötigen Dateien des eigenen OS, auf dem gearbeitet wird, ins Repo gelangen.Erstelle das AGENTS.md auf Englisch.
Nach diesem Prompt gibt mir ChatGPT den Inhalt zurück, den ich in das AGENTS.md einfügen soll.
# 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.Beachte, dass ich im Prompt nicht erwähnt habe, was ich möchte, dass das Plugin tut, da ChatGPT das bereits weiß durch das gesamte vorherige Gespräch, das ich mit ihm hatte, und alles, was wir diskutiert haben, hat dieses AGENTS.md verfasst, das super umfassend ist, was ich, wenn ich es selbst tun wollte, komplizierter wäre, weil es nicht nur darum geht, dass ich etwas vergesse, sondern auch, dass ChatGPT weiß, wie man die Dinge sagen muss, also verfasst es ein AGENTS.md, das seinen Bedürfnissen entspricht. Deshalb ist es so wichtig, es mit ihm zu besprechen, damit ihm auch alles klar wird, was du willst.
Jetzt müssen wir das Repository auf Github erstellen, falls wir es nicht haben. Also werden wir es erstellen, gehen wir zu Github und erstellen ein neues Repository, das öffentlich oder privat sein kann, in meinem Fall werde ich dieses öffentlich erstellen, damit ihr alle Zugang zu haben..
Das erste, was wir tun müssen, ist, das Repository lokal zu holen, wir können zum Beispiel GitHub Desktop verwenden, das für alle OS verfügbar ist.
Sobald wir es lokal haben, erstellen wir die Datei AGENTS.md, indem wir das einfügen, was uns ChatGPT gesagt hat,
und wir werden es über Github Desktop zu Github hochladen.
Sobald es hochgeladen ist, können wir auf Github sehen, dass wir die Datei AGENTS.md in unserem Repository haben. Wir brauchen nicht mehr, um mit Codex zu beginnen.
Jetzt gehen wir zu Codex und das erste, was wir tun müssen, ist, dieses Repository hinzuzufügen (wenn du zum ersten Mal auf Codex zugreifst, wird es dich vorher bitten, deiner Github-Konto Zugriff zu gewähren). Wir drücken einfach auf Umgebung erstellen und konfigurieren es.
Den grundlegenden Teil konfigurieren wir so, indem wir das Repository auswählen.
Aber achte auf diesen letzten Teil. Es ist oft notwendig, es so zu machen, da es Pakete benötigt, um beispielsweise React zu kompilieren, und wenn du ihm nicht alles lässt, kann es das nicht tun, aber du kannst diese Option immer aktivieren und deaktivieren, da sie geändert werden kann.
Es bleibt nur noch, auf Umgebung erstellen zu drücken.
Sobald wir die Umgebung erstellt haben, müssen wir nur noch beginnen, Codex arbeiten zu lassen. Wähle in Codex das Repository aus, mit dem du arbeiten möchtest, das andere kannst du so lassen, wie es ist.
Und sobald du es ausgewählt hast, musst du nur einen so einfachen Prompt wie diesen machen:
Entwickle alles, was in AGENTS.md steht, und denke daran, TODO.md und Documents.md zu verwenden.
Und wir drücken auf Programmieren, und es wird beginnen, am Code zu arbeiten.
Nach einer Weile, das hängt von allem ab, was er gemacht hat, wird er uns alle Änderungen zeigen, die er vorgenommen hat, die in diesem Fall alle Code zum Hinzufügen sind.
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.
Wenn wir auf die Aufgabe klicken, gelangen wir zu ihr und können alles sehen, was gemacht wurde, es überprüfen und den PR erstellen oder Änderungen anfordern.
In diesem Fall werde ich nichts überprüfen, da dies eine Demo ist, also klicke ich zuerst auf „Pull-Anfrage erstellen“ und dann auf „PR anzeigen“, sobald der Button erscheint.
Das wird uns zu Github führen, wo wir auch die Änderungen überprüfen und akzeptieren können.
Wir werden auf „Pull-Anfrage zusammenführen“ klicken und schon haben wir den gesamten neuen Code im Plugin hinzugefügt.
Jetzt können wir sehen, dass TODO.md und Documents.md wo wir alles nachverfolgen und eine Dokumentation für die Zukunft erstellen können.
Wenn wir uns das TODO.md ansehen, können wir an diesem Punkt sehen, dass noch viele Dinge in Progress und Pending sind, also muss Codex weitermachen. Wir müssen Codex nur anweisen, mit der Arbeit fortzufahren.
Wir werden dies wiederholen, bis keine Aufgaben mehr im TODO.md stehen und alles erledigt ist. Es wird einen Punkt geben, an dem in Pending und Progress nichts mehr sein wird, und dann können wir das Endergebnis auf einer Entwicklungsseite testen. Vor allem IMMER in der Entwicklung.
Sobald es installiert ist, kann es beim ersten Mal funktionieren oder nicht, in meinem Fall gab es einen fatalen Fehler.
Also kopiere ich den Fehler, damit Codex ihn mit Kontext beheben kann.
Nachdem wir fertig sind, erstellen wir einen neuen PR um es zu beheben, und das Plugin kann aktiviert werden.
Wenn wir jetzt einen neuen Beitrag/eine neue Seite erstellen, sehen wir in den Blöcken einen, der „Einfaches Kontaktformular“ heißt, und wir können die Erfolgsmeldung für die Übermittlung angeben. In diesem Fall, da wir in AGENTS.md nicht angegeben haben, dass wir die E-Mail konfigurieren müssen, an die sie gesendet werden soll, wird sie immer an die E-Mail des WordPress-Administrators gesendet.
Im Frontend werden wir dies sehen (denk daran, dass wir angegeben hatten, dass das Formular nur Name und E-Mail haben sollte).
Wenn du jetzt weitere Felder hinzufügen möchtest, zum Beispiel Betreff und Kommentare, müssten wir nur Codex darum bitten und ihm sagen, dass er AGENTS.md, TODO.md und Documents.md aktualisieren soll.
Wenn ich die Felder ausfülle und auf Send klicke, bekomme ich dies per E-Mail.
Das heißt, wir hatten nur einen einzigen fatalen Fehler im Plugin, das Codex für uns entwickelt hat, und der wurde beim ersten Mal behoben, indem ich ihm gesagt habe, was es war.
Dies ist ein sehr einfaches Plugin, aber es ist ein Plugin, das einen Block für Gutenberg integriert, was nicht wenig ist.
Wenn wir alles, was wir ihm zunächst angefordert haben, durchgehen, werden wir sehen, dass ein Thema fehlt, sei es, weil es einen Bug gibt und nicht angezeigt wird, oder weil es einfach nicht gemacht wurde, also ist es ab diesem Moment notwendig, Anfragen zur Behebung zu stellen, bis wir dort ankommen, wo wir wollen.
10. Zukunft des Agentic Coding
10.1. Mehr Autonomie, mehr Nachverfolgbarkeit
Wenn sich die Modelle weiterentwickeln, werden wir Agenten sehen, die in der Lage sind, längere Iterationen zu planen, Abhängigkeiten zu erkennen und tiefere Änderungen zu koordinieren. Der Schlüssel wird nicht nur rohe Leistung sein, sondern die Nachverfolgbarkeit: einen Verlauf von Entscheidungen, Annahmen und Akzeptanzkriterien zu bewahren, der die von KI generierten PRs prüfbar macht.
10.2. Testing und CI/CD integriert in den Agentenfluss
Die unmittelbare Zukunft liegt in Agenten, die die Generierung von Tests und CI/CD-Pipelines integrieren: Linter, Tests, grundlegende Abdeckung, Vorschau-Deploys und Leistungsberichte. Deine Rolle wird darin bestehen, die Richtlinien zu entwerfen: was akzeptabel ist, welche Risiken du nicht tolerierst und wie Regressionen gemeldet werden müssen.
10.3. Spezialisierung nach Domänen
Wir werden „feingetunte“ Agenten für spezifische Ökosysteme (WordPress, WooCommerce, Zahlungs-Plugins, Frontends mit React/Blocks) sehen, mit vorab gelernten Konventionen und Katalogen bewährter Praktiken. Dies wird die Einrichtungszeit und den Überprüfungsaufwand weiter reduzieren.
10.4. Dokumentation als Produkt
Die Dokumentation wird aufhören, ein Anhang zu sein, und sich in ein paralleles Produkt verwandeln, das vom Agenten gepflegt wird. Documents.md wird sich zu durchsuchbaren Wissensportalen entwickeln, mit ausführbaren Snippets, visuellen Schemen, Diagrammen und versionierten Rezepten. 11. Fazit
Agentic Coding bedeutet nicht, einer KI zu sagen, dass sie „ein Plugin machen soll“, sondern
eine Arbeitsbeziehung aufzubauen in der du den Kurs vorgibst und die KI diszipliniert ausführt. Das moderne Ökosystem — Cloud, lokal, hybrid — ermöglicht es dir, die technische Basis auszuwählen; aber der wahre Unterschied liegt darin, wie du den Prozess organisierst: AGENTS.md um Regeln festzulegen, TODO.md vom Agenten verwaltet, um Aufgaben zu orchestrieren, und Documents.md um echtes Wissen über das Projekt während der Erstellung festzuhalten. Dieser Ansatz gibt dir Geschwindigkeit, ohne die Qualität zu opfern: du reduzierst die Zeit für wiederholende Aufgaben, konzentrierst dich auf Architektur und wichtige Entscheidungen und hältst die technische Schulden in Schach. Was ist das Ergebnis? Kohärentere, leichter wartbare Projekte und eine sanfte Einarbeitungsphase für zukünftige Mitwirkende.
Du hast außerdem gesehen, wie man ein praktisches Beispiel vorbereitet, das du mit deinem Agenten vervollständigen kannst: „Einfaches Kontaktformular“.
Die Zukunft der Entwicklung ist kollaborativ: Menschen und Agenten arbeiten Hand in Hand mit klaren Prozessen, festen Standards und ständiger Evidenz. Beginne heute mit deinem Workflow und deinen Regeln; die KI wird den Rest unter deiner Anleitung erledigen.
