AGENTS.md für Codex: Projektregeln verständlich festhalten

Das Problem

Jedes Mal, wenn Sie Codex eine Aufgabe geben, müssen Sie dasselbe erklären: Wie startet man die Tests? Welche Programmiersprache und welche Regeln gelten? Welche Ordner darf man nicht anfassen? Welche Namen verwenden wir? Ohne diese Angaben macht die KI Annahmen, und die passen nicht immer zu Ihrem Projekt.

Das Ergebnis sind Änderungen im falschen Stil, in der falschen Datei oder mit einem Werkzeug, das Sie gar nicht einsetzen. Das kostet Zeit in der Nachbesserung und erhöht die Gefahr von Fehlern.

Dafür gibt es eine einfache Lösung: eine Textdatei namens AGENTS.md im Hauptordner des Projekts. Sie ist eine Art Dienstanweisung für KI-Programmierwerkzeuge. Codex und weitere Werkzeuge lesen sie, bevor sie loslegen. Wie genau die Datei verwendet wird, hängt vom Werkzeug und seiner Version ab; prüfen Sie die aktuelle Dokumentation. Für Frau Müller und ihr Team heisst das: Einmal sauber festhalten, wie das Projekt funktioniert, und alle künftigen Aufträge profitieren.

So lösen Sie es mit KI – Schritt für Schritt

1. Projekt in drei Sätzen beschreiben. Was ist es, wofür ist es da, welche Technik wird verwendet? Das gibt der KI den Rahmen.
2. Ordnerstruktur erklären. Nennen Sie, wo Quellcode, Tests, Dokumentation und Konfiguration liegen und welche Bereiche tabu sind (zum Beispiel automatisch erzeugte Dateien).
3. Befehle festhalten. Wie werden das Projekt gestartet, getestet und geprüft? Schreiben Sie die genauen Befehle auf, damit die KI sie selbst ausführen kann.
4. Stilvorgaben notieren. Namensregeln, Formatierung, Sprache der Kommentare und Texte (zum Beispiel Schweizer Schreibweise mit «ss»), Fehlerbehandlung.
5. Grenzen und Verbote setzen. Was darf die KI nie tun? Zum Beispiel keine Zugangsdaten anfassen, keine Abhängigkeiten ohne Rückfrage hinzufügen, keine Dateien löschen, keine Änderungen an der Datenbankstruktur. Siehe Codex-Berechtigungen.
6. Arbeitsweise vorgeben. Zum Beispiel: kleine Schritte, zuerst Plan, dann Änderung, Tests ausführen, am Schluss Zusammenfassung mit Liste der geänderten Dateien.
7. Testen, ob die Datei wirkt. Geben Sie Codex eine kleine Aufgabe und prüfen Sie, ob die Regeln eingehalten werden. Passen Sie unklare Stellen an.
8. Pflegen. Tragen Sie Änderungen nach und streichen Sie Überholtes. Legen Sie fest, wer die Datei verantwortet, und versionieren Sie sie wie Code.

Vorlage zum Kopieren

Diese Vorlage können Sie als AGENTS.md speichern und anpassen:

# AGENTS.md – Projektregeln

## Projekt
[Name]: [1–2 Sätze, was das Projekt macht, für wen]. Technik: [Sprache, Framework, Datenbank].

## Ordner
- src/: Quellcode
- tests/: Tests
- docs/: Dokumentation
- Nicht ändern: [z. B. vendor/, generierte Dateien, config/ mit Zugangsdaten]

## Befehle
- Starten: [Befehl]
- Tests ausführen: [Befehl]
- Stilprüfung: [Befehl]

## Regeln
- Kleine, überprüfbare Änderungen. Pro Auftrag nur die nötigen Dateien anfassen.
- Vor Änderungen kurz den Plan nennen. Nach Änderungen Tests ausführen und das Ergebnis berichten.
- Texte für Menschen auf Deutsch (Schweiz), «ss» statt «ß», Anrede «Sie».
- Keine neuen Abhängigkeiten ohne vorherige Rückfrage.
- Keine Zugangsdaten, Schlüssel oder Kundendaten lesen, schreiben oder ausgeben.
- Keine Dateien löschen und keine Datenbankänderungen ohne ausdrückliche Freigabe.
- Bei Unklarheit nachfragen statt raten.

## Abschluss jeder Aufgabe
Liste der geänderten Dateien, kurze Begründung, Testergebnis, offene Punkte.

Ersetzen Sie die Platzhalter und streichen Sie, was nicht zutrifft. Legen Sie keine Geheimnisse in diese Datei, denn sie liegt im Projekt und oft in der Versionsverwaltung.

Was hineingehört und was nicht

Worauf Sie achten müssen

• Keine Garantie auf Befolgung. KI-Werkzeuge halten sich meist, aber nicht immer an die Anweisungen. Prüfen Sie Ergebnisse trotzdem. Siehe Codex-Code prüfen.
• Kurz und konkret. Lange, widersprüchliche Regeln werden schlechter befolgt. Beginnen Sie mit zehn Zeilen.
• Geheimnisse draussen. Die Datei kann mit dem Projekt weitergegeben werden. Siehe Passwörter und Kundendaten schützen.
• Aktualität. Veraltete Befehle führen zu Fehlern. Prüfen Sie die Datei bei jeder grösseren Änderung am Projekt.
• Werkzeugspezifisches. Andere Werkzeuge nutzen eigene Dateien, etwa CLAUDE.md oder Cursor-Regeln. Siehe CLAUDE.md erstellen und Cursor-Regeln.

Ein Beispiel aus der Praxis

Ein Beispiel: Ein Treuhandbüro in Luzern betreibt ein kleines Tool zur Mandatsverwaltung. Der externe Entwickler Herr Lang nutzt Codex für Anpassungen, doch jedes Mal landen Änderungen im falschen Ordner und die Tests werden nicht ausgeführt.

Vorher: Er erklärt Struktur und Regeln in jedem Auftrag neu und vergisst gelegentlich Punkte. Nachher: Er legt eine AGENTS.md an, mit Ordnerstruktur, Testbefehl, dem Verbot, Konfigurationsdateien anzufassen, und der Pflicht zur Abschlusszusammenfassung. Nach einem Testauftrag passt er zwei Stellen an. Künftig sind die Änderungen klein, geordnet und lassen sich leichter prüfen.

So hilft Ihnen Alpasana

Wer lernen möchte, KI-Programmierwerkzeuge mit klaren Regeln zu führen, findet bei absofort den Kurs KI für Developer mit Claude und Codex: Aufgaben delegieren und Ergebnisse verifizieren, Entwickler-Playbook mit Prompts, Review-Regeln, Tests und Datenschutzgrenzen, Praxisprojekt und verifizierbares Zertifikat.

Häufige Fragen

Muss die Datei genau AGENTS.md heissen?

Für Werkzeuge, die diesen Namen erwarten, ja. Schreibweise und Ort (Hauptordner des Projekts) sind wichtig. Prüfen Sie die aktuelle Dokumentation Ihres Werkzeugs.

Darf ich dieselben Regeln für mehrere Werkzeuge nutzen?

Teilweise. Der Inhalt lässt sich oft übernehmen, die Dateinamen und Formate sind aber unterschiedlich. Halten Sie die Regeln an einer Stelle und kopieren Sie sie bei Bedarf.

Wer soll die Datei schreiben?

Am besten die Person, die das Projekt kennt und verantwortet, mit Rückmeldungen aus dem Team. Eine Leitung kann Vorgaben zu Sicherheit und Datenschutz beisteuern.

Wie erkenne ich, ob sie wirkt?

Geben Sie Codex einen kleinen Testauftrag und prüfen Sie, ob Regeln wie Ordner, Tests und Abschlussbericht eingehalten werden. Wiederholen Sie das nach Änderungen.