Coding Agents Guide

AI-Vorgehensmodelle, Interaction-Pattern und semantische Grounding-Prinzipien für das gesamte IIO-Team. Wer versteht wie Coding Agents denken, spart Monate — nicht Stunden.

1. Wie Coding Agents denken — das Fundament1. How Coding Agents Think — The Foundation

Ein Coding Agent ist kein klassisches Programm das Befehle ausführt. Er ist ein probabilistisches Reasoning-System, das aus Kontext Bedeutung ableitet und dann Aktionen plant. Das hat konkrete Konsequenzen für die Zusammenarbeit.

Kern-Einsicht Ein Agent hat kein "Gedächtnis" im menschlichen Sinn. Er hat nur den Kontext-Fenster-Inhalt zum Zeitpunkt der Anfrage. Was nicht im Kontext steht, existiert für ihn nicht. Gute Zusammenarbeit bedeutet: relevanten Kontext explizit liefern.

Das Reasoning-ModellThe Reasoning Model

Input

Kontext-Aufbau

System-Prompt, Dateien, Konversation, Tool-Ergebnisse — alles im Kontext-Fenster

Reasoning

Planung & Ableitung

Agent leitet Ziel, Vorgehen und nächste Aktion aus dem Kontext ab

Tool-Aufruf

Execution

File-Read, Code-Edit, Bash, Web-Fetch — deterministische Aktionen

Beobachtung

Output → neuer Input

Tool-Ergebnisse fließen zurück in den Kontext → nächster Reasoning-Schritt

Praktische Konsequenz Je klarer die Dateinamen, Kommentare, Verzeichnisstruktur und Variablen-Namen sind, desto präziser und effizienter arbeitet der Agent — ohne Rückfragen. Das nennt sich Semantic Grounding (siehe Kapitel 4).

2. AI-Vorgehensmodelle — wann was2. AI Methodology Models — When to Use What

Es gibt kein universelles "bestes" Vorgehen. Je nach Ziel ist ein anderes Modell überlegen. Die folgende Matrix hilft bei der Wahl:

ModellModel	ZielGoal	Wann anwendenWhen to Apply	StärkeStrength	GrenzeLimit
Exploratives Vorgehen Explore-First	Unbekanntes Terrain verstehen	Neue Codebase, unbekanntes System, Aufwandsschätzung	Breites Bild ohne Investition	Kein Output, nur Analyse
Plan-Execute-Review PER-Loop	Komplexe Multi-Step-Aufgabe	Features, Refactoring, Migrations — wenn Reihenfolge wichtig	Nachvollziehbar, rollback-fähig	Langsamer als direktes Vorgehen
Iteratives Vorgehen Iterate	Ziel ist klar, Weg unklar	UI-Feinschliff, Performance, Bugfixing	Schnelle Feedback-Loops	Kann in lokale Minima laufen
Parallele Agenten Multi-Agent	Unabhängige Teilaufgaben gleichzeitig	Mehrere Dateien, verschiedene Module, Research + Implement parallel	Hohe Geschwindigkeit	Koordination erfordert Disziplin
HITL-gestütztes Vorgehen HITL-Loop	Hohe Risiko-Entscheidungen	Production-Deploy, IP-Entscheide, Datenlöschung, Architektur-Änderungen	Volle Kontrolle + Audit-Trail	Langsam, erfordert Operator
Fail-Closed Automation Pipeline	Wiederholbare deterministische Prozesse	CI/CD, Validierung, Ingestion, Code-Generation	Reproduzierbar, skalierbar	Braucht klare Spezifikation vorab
Agentic Autonomous Agentic	Langer Horizont, eigenständige Planung	Komplexe Tasks die Stunden oder Tage dauern würden	Maximale Effizienz	Benötigt vertrauenswürdige Guardrails

Empfehlung für kleine Teams (wie Intelego) Startet mit PER-Loop für alle nicht-trivialen Aufgaben. Wechselt zu Parallelen Agenten sobald ihr die Muster kennt. Nutzt Fail-Closed Pipelines für alles was wiederholt wird. Spart HITL für echte Risiko-Entscheidungen — nicht für jede Kleinigkeit.

3. Interaction-Pattern — die tägliche Praxis3. Interaction Patterns — Daily Practice

🎯

Context-First Prompting

Immer anwenden

Was: Kontext vor dem eigentlichen Auftrag liefern.

Beispiel:
Schlecht: "Mach die Seite schneller."
Gut: "Wir haben governance-depth-map.html, die Seite lädt 3s. Das Theme-CSS ist 900 Zeilen. Optimiere die CSS-Ladezeit ohne das Erscheinungsbild zu ändern."

Warum: Der Agent kann ohne Kontext nur raten. Mit Kontext plant er präzise.

📋

Constraint Declaration

Bei jeder bedeutenden Aufgabe

Was: Explizit sagen was NICHT erlaubt ist.

Beispiel:
"Optimiere nur Dateien in iio/manual/. Ändere NICHTS in iio/theme/. Lösche KEINE Dateien."

Warum: Agents suchen effiziente Wege — auch durch unerwartete Abkürzungen. Explizite Grenzen verhindern ungewollte Kollateralschäden.

✅

Checkpoint-Driven Development

Bei langen Aufgaben

Was: Aufgaben in explizite Checkpoints unterteilen lassen.

Beispiel:
"Mach Schritt 1 und zeig mir das Ergebnis bevor du weitermachst."

Warum: Fehler früh erkennen. Kurskorrektur kostet wenig wenn man früh eingreift, viel wenn man am Ende zurückrollen muss.

🔄

Verify-Before-Proceed

Bei kritischen Operationen

Was: Agent soll eigene Arbeit prüfen bevor er fortfährt.

Beispiel:
"Führe validate-manual-css.sh aus. Wenn PASS: projiziere. Wenn FAIL: zeig mir die Fehler und warte."

Warum: Agents machen Fehler. Selbst-Verifikation reduziert Fehler-Propagation. In IIO: Validator als Gate vor jeder Projektion.

📁

File-Anchored Reasoning

Immer bevorzugen

Was: Entscheidungen an Dateien verankern, nicht an mündlichen Beschreibungen.

Beispiel:
Schlecht: "Du weißt ja wie das Theme aussieht."
Gut: "Schau in iio/theme/families/b2b/solution-provider/assets/style.css — dort sind alle Token definiert."

Warum: Dateien sind für Agents wie Dokumente für Menschen. Was in Dateien steht ist verlässlich; was "bekannt" ist, ist uncertain.

🚦

Explicit GO/NO-GO Gates

IIO-Kernprinzip

Was: Jede kritische Aktion hat ein explizites GO-Kriterium.

Beispiel:
"Lösche die Datei ONLY IF delete-guard.sh PASS zurückgibt. Sonst STOP und berichte."

Warum: Agents sind optimistisch — sie vervollständigen Aufgaben. Ohne explizite Gates überspringen sie Sicherheitschecks. IIO-Prinzip: fail-closed by design.

🔀

Parallel Task Batching

Für Erfahrene

Was: Unabhängige Aufgaben parallel statt sequenziell.

Beispiel:
"Lese gleichzeitig: die 5 Theme-CSS-Dateien, den stream-contract der lynäar-Familie und die theme-families.json. Dann berichte Widersprüche."

Warum: Moderner Agents können parallel Tool-Calls ausführen. 5× schneller bei unabhängigen Lesevorgängen.

📊

Evidence-Driven Decisions

Immer wenn möglich

Was: Entscheidungen auf messbaren Befunden statt Intuition basieren.

Beispiel:
"Prüfe alle 66 HTML-Dateien mit validate-manual-css.sh. Entscheide dann welche Fixes nötig sind — nicht vorher."

Warum: Agents neigen dazu Annahmen als Fakten zu behandeln. Explizite Prüfschritte erzeugen verlässliche Basis für Entscheidungen.

4. Semantic Grounding — warum Naming entscheidend ist4. Semantic Grounding — Why Naming is Critical

Semantic Grounding ist das Prinzip, dass Agents aus Benennung und Struktur von Code/Dateien direkt Bedeutung ableiten — ohne Dokumentation lesen zu müssen. Ein Agent der execute-stream-contract.sh sieht, versteht sofort was das Script tut. Ein Agent der script2.sh sieht, muss erraten.

IIO Semantic Grounding — Konkrete Regeln

Datei-Namen

kebab-case-lowercase.html — keine Abkürzungen, keine Großbuchstaben außer README/AGENTS/LICENSE. Agents lesen Dateinamen als Semantik.

CSS-Variablen

--iio-accent statt --color1. Prefix + semantischer Name. Agent weiß: das ist ein IIO-Token, kein manuell gesetzter Wert.

Script-Namen

execute-stream-contract.sh, validate-manual-css.sh — Verb-Objekt-Muster. Was macht das Script? Sofort klar.

Verzeichnis-Struktur

base/{skill}/scripts/ — konsistentes Schema. Agent findet Scripts ohne Suche, weil die Struktur vorhersagbar ist.

YAML-Felder

source_verified: false statt sv: 0. Selbstdokumentierende Felder. Agent liest Meaning aus dem Namen.

Kommentare

Kommentare erklären Warum, nicht Was. Was ist aus dem Code ersichtlich. Warum nicht immer. Agents nutzen Kommentare als Reasoning-Input.

SKILL.md

Jeder Skill hat eine SKILL.md die sagt: Use When, Inputs, Workflow, Output Contract. Agent kann Skill selbst einschätzen ob er passt.

AGENTS.md

Kontextualisierung pro Verzeichnis. Agent liest AGENTS.md zuerst — es setzt den Scope für alles darunter.

AI-Pattern: Self-Documenting Systems Das IIO-System ist so designed dass ein Agent der es zum ersten Mal sieht, sofort navigieren kann — nur durch Lesen von Dateinamen, Verzeichnisstruktur und SKILL.md-Dateien. Das ist kein Zufall. Es ist eine Design-Entscheidung die monatliche Einarbeitungszeiten auf Stunden reduziert — für Menschen UND Agents.

5. IIO-spezifische Patterns — unser System5. IIO-Specific Patterns — Our System

Das IIO Actor-Model und AgentsThe IIO Actor Model and Agents

In IIO gibt es keinen ontologischen Unterschied zwischen menschlichen und KI-Aktoren. Beide sind Intelligent Actors mit Rollen, Fähigkeiten und Stories. Das hat praktische Konsequenzen:

IIO-KonzeptIIO Concept	Für menschliche AktorenFor Human Actors	Für AI-AktorenFor AI Actors
Rolle	Team Lead, Operator, Reviewer	backend-agent, explore-agent, infra-agent
Skill	Code Review, Deployment, Design	SKILL.md definiert Capability und Use-When
HITL-Gate	Freigabe-Unterschrift, Approval	Explizites GO im Konversations-Flow
Evidence	Unterschriebenes Dokument, Foto	Script-Output, Validator-PASS, Hash
Fail-Closed	Eskalation bei Unsicherheit	STOP wenn Bedingung nicht erfüllt — nie raten
Audit-Trail	Transaction-Log, Meeting-Notes	ingestion-log.yml, assets-manifest.yml

Publish-Chain als AI-nativer ProzessPublish Chain as an AI-Native Process

Die IIO-Publish-Chain ist so gebaut dass ein Agent sie selbst ausführen kann:

Source

iio/manual/*.html

Autor schreibt, Agent validiert

Gate

validate-manual-css.sh

PASS = proceed, FAIL = STOP

Transform

project-seed-to-node.sh

CSS-Pfade rewritten, Manifest erzeugt

Output

intelego/manual/seed/

Rendering-ready, via URL erreichbar

6. Anti-Pattern — was nicht funktioniert6. Anti-Patterns — What Doesn't Work

Anti-Pattern: "Du weißt ja was ich meine" Agents wissen es nicht. Sie schätzen. Impliziter Kontext führt zu impliziten Fehlern. Immer explizit — auch wenn es redundant wirkt.

Anti-Pattern: Zu langer Task ohne Checkpoint Ein Agent der 2 Stunden ohne Feedback arbeitet kann in die falsche Richtung gelaufen sein. Checkpoints nach jedem bedeutenden Schritt sind kein Overhead — sie sind Fehlerkorrektur.

Anti-Pattern: "Fix it" ohne Scope "Fix the bugs" ohne Angabe welche Dateien, welches Verhalten, welche Constraints gibt dem Agent maximalen Spielraum — oft mit unerwarteten Ergebnissen. Scope-Definition ist Pflicht.

Anti-Pattern: Copy-Paste aus Legacy ohne Prüfung In IIO: migrate/ ist UNTRUSTED. Kein Code ohne semantische Prüfung. Agents können Legacy-Patterns übernehmen die im neuen System falsch sind.

Anti-Pattern: Agent als Oracle Agents antworten immer — auch wenn sie unsicher sind. "Ich weiß es nicht" ist seltener als man denkt. Kritische Architektur-Entscheidungen müssen an File-Evidenz verankert sein, nicht an Agent-Antworten.

7. Tool-Übersicht — IIO Coding Agent Stack7. Tool Overview — IIO Coding Agent Stack

Tool/Agent	ZweckPurpose	Wann nutzenWhen to Use
OpenCode (lokal) Primär	Coding Agent mit direktem Dateisystem-Zugriff	Code schreiben, Dateien ändern, Scripts ausführen — alles im Workspace
backend-agent Spezialisiert	Node.js/Express API, Docker, DB-Migrationen	Backend-Entwicklung, Server-seitige Logik
explore-agent Spezialisiert	Codebase-Exploration, Suche, Analyse	Schnelle Recherche ohne Code-Änderungen
infra-agent Spezialisiert	Ansible, Docker Swarm, Netzwerk, VPN	Infrastruktur-Aufgaben, Server-Setup
general-agent Allgemein	Multi-Step Tasks, Recherche, Planung	Wenn kein spezialisierter Agent passt
validate-manual-css.sh Gate	CSS-Drift-Validator für Manual-Seiten	Vor jeder Projektion — automatisch als Pre-Check eingebaut
validate-stream-contract.sh Gate	Stream-Contract-Validator für alle Themes	Vor jeder Theme-Ingestion
execute-stream-contract.sh Pipeline	ETL-Executor für Theme-Ingestion	Wenn neues Theme oder Brand-Update eingepflegt wird
execute-asset-transform.sh Pipeline	Asset-Transform-Pipeline (SVG, PNG, ICO, Sprite)	Nach Source-Extraktion für Bild- und Icon-Verarbeitung
project-seed-to-node.sh Pipeline	Seed → Node Projektion mit CSS-Pfad-Rewriting	Nach jeder Änderung in iio/manual/ die publiziert werden soll

Goldene Regel Ein gut benanntes Script ist besser als 10 Seiten Dokumentation. Ein gut gebauter Validator ist besser als 10 Code-Reviews. Ein deterministischer Prozess ist besser als 10 Konventionen ohne Enforcement. IIO ist so designed.