KI-Clients und lokale Agenten richtig einsetzen: Projektstart mit AGENTS.md, PRDs, ADRs und Tasks

KI-gestützte Entwicklung funktioniert am besten, wenn Chat, lokale Agenten, Dokumentation und Tests klar zusammenspielen. Der entscheidende Unterschied liegt nicht nur im Modell, sondern darin, ob die KI lediglich berät oder direkt im Projektkontext arbeiten kann.

Online-Chat-UI oder lokal installierter Agent: Wo liegt der Unterschied?

Viele Diskussionen über künstliche Intelligenz in der Softwareentwicklung konzentrieren sich auf das verwendete Modell. In der Praxis ist aber oft eine andere Frage wichtiger: Über welche Arbeitsumgebung verfügt die KI? Eine Online-Chat-Oberfläche und ein lokal installierter Agent können theoretisch mit ähnlichen Modellen arbeiten, erfüllen aber unterschiedliche Aufgaben im Entwicklungsprozess.

Eine Online-Chat-UI eignet sich vor allem für Konzeption, Analyse, Textarbeit, technische Erklärungen, Architekturüberlegungen, Code-Reviews auf Ausschnittbasis und Planungsaufgaben. Der Chat ist besonders stark, wenn Anforderungen strukturiert, Probleme erklärt oder Lösungswege verglichen werden sollen. Sein Zugriff auf das konkrete Projekt ist jedoch meist begrenzt oder indirekt. Dateien, Testläufe, Git-Status, lokale Konfigurationen und Fehlermeldungen müssen häufig manuell bereitgestellt werden.

Ein lokal installierter Agent arbeitet näher am eigentlichen Repository. Er kann Projektdateien lesen und ändern, Tests ausführen, Fehlermeldungen auswerten, Git-Diffs prüfen und Änderungen iterativ verbessern. Dadurch wird er nicht nur zu einem Gesprächspartner, sondern zu einem kontrollierten Werkzeug im Entwicklungsprozess. Der lokale Agent kann eine Aufgabe lesen, relevante Dateien inspizieren, einen Patch erzeugen, Tests ausführen und anschließend berichten, was geändert wurde.

Als Faustregel gilt: Der Chat ist sehr gut für Planung, Klärung und strategische Arbeit. Der lokale Agent ist besser für konkrete Umsetzung im Repository geeignet. Besonders effektiv wird der Einsatz, wenn beide Rollen sauber getrennt werden: Zuerst wird im Chat das Vorhaben geklärt, anschließend erhält der lokale Agent eine kleine, überprüfbare Aufgabe.

Was ein Agent zusätzlich leistet

Ein Agent ist nicht einfach nur ein „besserer Chat“. Der eigentliche Mehrwert liegt in der Arbeitsschleife. Ein guter Agent liest den vorhandenen Kontext, trifft eine begrenzte Entscheidung, nimmt eine Änderung vor, führt Prüfungen aus und fasst das Ergebnis nachvollziehbar zusammen. Diese Schleife lässt sich mit folgendem Ablauf beschreiben:

lesen → entscheiden → ändern → testen → zusammenfassen

Damit diese Schleife zuverlässig funktioniert, braucht der Agent stabile Regeln. Ohne klare Projektstruktur neigt auch ein leistungsfähiges KI-System dazu, Annahmen zu treffen, zu große Änderungen vorzunehmen oder Entscheidungen nur aus dem aktuellen Chatverlauf abzuleiten. Genau hier helfen Dateien wie AGENTS.md, PRDs, ADRs, Task-Dateien, Testpläne und Runbooks.

AGENTS.md: Der Arbeitsvertrag für den Agenten

Die Datei AGENTS.md ist eine der wichtigsten Grundlagen für KI-gestützte Projektarbeit. Sie beschreibt, wie sich ein Agent innerhalb dieses Repositorys verhalten soll. Man kann sie als Betriebshandbuch oder Arbeitsvertrag für den lokalen Agenten verstehen.

In eine gute AGENTS.md gehören vor allem dauerhafte Regeln: Rolle des Agenten, Coding-Prinzipien, Sicherheitsregeln, Projektbefehle, Testkommandos, Dokumentationspflichten, Git-Konventionen und das gewünschte Antwortformat nach erledigten Aufgaben. Nicht hineingehören temporäre Einzelaufgaben, Zugangsdaten, lange Strategiedebatten oder Informationen, die nur für eine einzelne Chat-Sitzung relevant sind.

Ein kurzer Ausschnitt kann zum Beispiel so aussehen:

# AGENTS.md 
  ## Agent role 
  Act as a senior software engineer for this repository. Prioritize correctness, maintainability, security and small verified changes.
  ## Required workflow 
  1. Inspect the relevant files first. 
  2. Make the smallest coherent patch. 
  3. Run the required checks. 
  4. Update documentation when behavior changes. 
  5. Report changed files, tests run and remaining risks. 
  ## Commands 
  - Format: <format command> 
  - Lint: <lint command> 
  - Test: <test command> 
  - Build: <build command>

Der wichtigste Punkt ist die Dauerhaftigkeit. Eine AGENTS.md sollte nicht ständig für einzelne Aufgaben umgeschrieben werden. Sie legt die allgemeinen Spielregeln fest, an denen sich der Agent bei jeder Aufgabe orientieren kann.

PRDs: Produktziel und Projektgrenzen definieren

Ein Product Requirements Document, kurz PRD, beschreibt, welches Produkt gebaut werden soll, für wen es gedacht ist und woran Erfolg gemessen wird. Für KI-gestützte Entwicklung ist ein PRD besonders wichtig, weil es verhindert, dass der Agent aus einzelnen Aufgaben falsche Produktziele ableitet.

In größeren Projekten ist es sinnvoll, zwischen einem Master-PRD und mehreren Phase-PRDs zu unterscheiden. Das Master-PRD beschreibt das Gesamtziel, die Zielgruppen, Nicht-Ziele, Systemgrenzen und Erfolgskriterien. Ein Phase-PRD beschreibt dagegen einen konkreten Umsetzungsschritt.

Ein Master-PRD könnte beispielsweise so aufgebaut sein:

# Master PRD: CMS Security Statistics 
  ## Problem Site owners need a neutral fact sheet to compare CMS security disclosure trends over time. 
  ## Goals 
  - Collect public disclosure data for CMS cores. 
  - Normalize events by project, date, severity and source. 
  - Render diagrams for long-term comparison. 
  ## Non-goals 
  - No "CMS versus CMS" marketing language. 
  - No private vulnerability intelligence. 
  ## Success criteria 
  - Reproducible monthly import. 
  - Source traceability for every data point. 
  - More CMS types can be added later.

Das Master-PRD bleibt strategisch. Es beschreibt nicht jeden einzelnen Implementierungsschritt. Diese Detailarbeit gehört in Phase-PRDs und Task-Dateien.

Phase-PRDs: Große Ziele in kontrollierte Abschnitte zerlegen

Ein Phase-PRD macht aus der Gesamtvision einen umsetzbaren Projektabschnitt. Es ist konkreter als das Master-PRD, aber noch breiter als eine einzelne Aufgabe. Eine Phase kann zum Beispiel Datenimport, Authentifizierung, Export, Benutzeroberfläche oder Deployment betreffen.

Ein Phase-PRD sollte Ziel, Umfang, Nicht-Ziele, Akzeptanzkriterien und erforderliche Prüfungen enthalten. Dadurch weiß der Agent, welche Aufgaben zur aktuellen Phase gehören und welche Änderungen besser zurückgestellt werden sollten.

# Phase 01 PRD: Public Disclosure Ingestion 
  ## Objective 
  Import public disclosure records from selected public sources. 
  ## Scope 
  - Source connectors 
  - Raw event table 
  - Normalized event table 
  - Monthly aggregation command 
  ## Acceptance criteria 
  - Imports can run repeatedly without duplicates. 
  - Every normalized row keeps source URL and source type. 
  - Failed fetches are logged without corrupting data. 
  ## Required checks 
  - Unit tests for parsers 
  - Integration test with fixture files

Der Vorteil liegt in der klaren Begrenzung. Der Agent muss nicht „das ganze System“ bauen, sondern kann eine Phase Schritt für Schritt abarbeiten.

ADRs: Architekturentscheidungen nachvollziehbar machen

Architecture Decision Records, kurz ADRs, dokumentieren wichtige technische Entscheidungen. Sie sind besonders nützlich, wenn Entscheidungen später schwer rückgängig zu machen sind oder viele Folgeaufgaben beeinflussen. Beispiele sind Datenbankwahl, API-Stil, Queue-Modell, Authentifizierungsgrenzen, Speicherformat oder Abhängigkeitsstrategie.

Ein ADR sollte nicht jede kleine Überlegung dokumentieren. Es geht um Entscheidungen, die künftige Entwickler und Agenten kennen müssen. Ein guter ADR beantwortet: Welches Problem gab es? Welche Entscheidung wurde getroffen? Welche Konsequenzen hat sie? Welche Alternativen wurden verworfen?

# ADR 0002: Use SQLite for local storage 
  ## Status 
  Accepted 
  ## Context 
  The first release must run as a local compiled binary without a managed database server. 
  ## Decision 
  Use SQLite as the embedded storage backend. 
  ## Consequences 
  + Easy local setup and backups. 
  + Good fit for single-user ingestion jobs. 
  - Limited concurrency compared with PostgreSQL. 
  - A later server edition may need a migration path. 
  ## Alternatives 
  considered PostgreSQL, MySQL, JSON files.

Für KI-Agenten sind ADRs besonders wertvoll, weil sie verhindern, dass alte Entscheidungen immer wieder neu diskutiert oder versehentlich rückgängig gemacht werden.

Tasks: Die richtige Arbeitseinheit für Agenten

Eine Task-Datei ist die kleinste sinnvolle Einheit für die konkrete Umsetzung. Sie sollte so klein sein, dass der Agent sie in einem kontrollierten Arbeitsdurchlauf umsetzen, testen und erklären kann. Große Aufgaben wie „baue das komplette Modul“ sind ungeeignet. Besser sind zehn kleine, überprüfbare Aufgaben als ein riesiger Prompt.

Eine gute Task-Datei enthält Ziel, Scope, Nicht-Ziele, Akzeptanzkriterien, erforderliche Prüfungen und Hinweise zu Risiken oder Folgearbeiten.

# Phase 01 
  Task 003: Normalize disclosure events 
  ## Goal 
  Transform raw source records into normalized events. 
  ## Scope 
  - Add NormalizedEvent model 
  - Add severity mapping 
  - Add duplicate detection by source id + URL 
  ## Non-goals 
  - No diagrams in this task 
  - No live network fetch changes 
  ## Acceptance criteria 
  - [ ] Fixture records normalize consistently 
  - [ ] Duplicate fixture rows are ignored 
  - [ ] Invalid dates return structured errors 
  ## Required checks 
  - cargo test normalize_events 
  - cargo clippy 
  --all-targets 
  -- -D warnings

Diese Struktur gibt dem Agenten eine klare Grenze. Er weiß, was geändert werden soll, was ausdrücklich nicht geändert werden soll und welche Prüfungen das Ergebnis bestätigen müssen.

Testpläne und Runbooks: Korrektheit und Betrieb trennen

Testpläne und Runbooks werden häufig vermischt, erfüllen aber unterschiedliche Aufgaben. Ein Testplan beschreibt, wie Korrektheit geprüft wird. Ein Runbook beschreibt, wie ein wiederkehrender Betriebsvorgang sicher ausgeführt wird.

Ein Testplan kann automatisierte und manuelle Prüfungen enthalten. Er ist vor allem während Entwicklung, Review und Release relevant. Ein Runbook ist dagegen für den späteren Betrieb gedacht, zum Beispiel für monatliche Importe, Backups, Deployments oder Fehlerbehebung.

# Test Plan: Phase 01 
  ## Automated checks 
  - Unit: parser fixtures 
  - Unit: normalization edge cases 
  - Integration: import command with local fixtures 
  ## Manual checks 
  - Run monthly aggregation on fixture data 
  - Confirm source URLs are retained 
  - Confirm duplicate imports do not change counts

# Runbook: Monthly import 
  ## Steps 
  1. Back up the database. 
  2. Run: app import --month YYYY-MM 
  3. Run: app aggregate --month YYYY-MM 
  4. Export diagram data. 
  5. Review warnings in logs. 
  ## Rollback 
  Restore the database backup created in step 1.

Für professionelle Projekte ist diese Trennung wichtig. Tests beweisen, dass eine Änderung korrekt ist. Runbooks helfen, einen Vorgang später zuverlässig und wiederholbar durchzuführen.

Empfohlene Startstruktur für ein neues Repository

Ein neues KI-gestütztes Projekt sollte nicht mit einem großen Implementierungsprompt beginnen. Besser ist es, zuerst stabile Projektanker zu schaffen. Eine sinnvolle Minimalstruktur sieht so aus:

repo/ 
  ├─ AGENTS.md 
  ├─ README.md 
  ├─ docs/ 
  │ ├─ prd/ 
  │ │ ├─ master-prd.md 
  │ │ └─ phase-01.md 
  │ ├─ adr/ 
  │ └─ 0001-record-architecture-decisions.md 
  │ ├─ tasks/ 
  │ │ ├─ phase-01-task-001-project-bootstrap.md 
  │ │ ├─ phase-01-task-002-core-models.md 
  │ │ └─ phase-01-task-003-first-import.md 
  │ ├─ test-plans/ 
  │ │ └─ phase-01.md 
  │ └─ runbooks/ 
  ├─ src/ 
  ├─ tests/ 
  └─ scripts/

Diese Struktur gibt menschlichen Entwicklern und KI-Agenten denselben Bezugsrahmen. Das Repository enthält nicht nur Code, sondern auch Ziel, Entscheidungen, Aufgaben und Prüfregeln.

Die beste Reihenfolge für den Projektstart

In der Praxis hat sich folgende Reihenfolge bewährt:

1. README.md erstellen: Kurzer menschlicher Einstieg in Zweck, Installation und Nutzung des Projekts.
2. AGENTS.md erstellen: Regeln für Agenten definieren: Rolle, Befehle, Sicherheit, Tests und Berichtformat.
3. Master-PRD schreiben: Produktziel, Zielgruppe, Systemgrenzen, Nicht-Ziele und Erfolgskriterien festlegen.
4. Erstes Phase-PRD schreiben: Den ersten sinnvollen Meilenstein definieren.
5. ADR 0001 anlegen: Architekturentscheidungen künftig nachvollziehbar dokumentieren.
6. Tasks 001 bis 005 erstellen: Kleine, ausführbare Arbeitspakete mit klaren Checks formulieren.
7. Testplan ergänzen: Festlegen, wie die Phase verifiziert wird.
8. Runbook ergänzen: Erst dann, wenn es einen wiederkehrenden Betriebsablauf gibt.

Erst danach sollte der lokale Agent mit der Implementierung beginnen. Eine gute erste Anweisung lautet zum Beispiel:

Implement Phase 01 Task 001 only. 
Inspect the relevant files first. 
Make the smallest coherent patch. Run the required checks. 
Report changed files, tests run and remaining risks.

Warum diese Struktur bessere Ergebnisse liefert

KI-Agenten arbeiten am besten, wenn sie klare Grenzen haben. Ohne Projektstruktur wird der Chatverlauf zur einzigen Quelle der Wahrheit. Das ist riskant, weil Chatverläufe lang, unvollständig oder widersprüchlich werden können. Dateien im Repository sind dagegen versionierbar, überprüfbar und für alle Beteiligten sichtbar.

AGENTS.md definiert das Verhalten des Agenten. PRDs definieren das Produktziel. ADRs dokumentieren dauerhafte technische Entscheidungen. Tasks übersetzen Ziele in konkrete Arbeit. Testpläne sichern die Qualität. Runbooks machen wiederkehrende Abläufe beherrschbar. Zusammen entsteht daraus ein Arbeitsmodell, das KI nicht als magische Abkürzung behandelt, sondern als kontrollierbares Entwicklungswerkzeug.

Fazit

Der Unterschied zwischen einer Online-Chat-UI und einem lokalen Agenten liegt vor allem im Zugriff auf Kontext, Werkzeuge und Ausführungsumgebung. Der Chat ist ideal für Denken, Strukturieren und Erklären. Der lokale Agent ist ideal für kontrollierte Änderungen im Repository.

Der beste Start in ein KI-Agenten-Projekt ist daher nicht der direkte Auftrag „baue die Software“, sondern der Aufbau eines belastbaren Projektrahmens. Mit AGENTS.md, PRDs, ADRs, Tasks, Testplänen und Runbooks entsteht eine Arbeitsweise, bei der Mensch und KI nachvollziehbar zusammenarbeiten. Das Ergebnis sind kleinere Änderungen, bessere Tests, weniger Missverständnisse und ein Projekt, das auch nach vielen Agentenläufen verständlich bleibt.

Empfohlene Dateien im Überblick