Viele Freiburger Teams nutzen Claude Code, Codex oder Cursor schon täglich, haben aber keine oder nur eine automatisch erzeugte Projektanleitung. Die Folge sind wiederkehrende Fehler, die jedes Mal im Review auffallen. Wir helfen Ihnen, CLAUDE.md und AGENTS.md zu erstellen, die Ihr Teamwissen tatsächlich abbilden, und testen sie gemeinsam an echten Aufgaben. Da jocapps in Freiburg sitzt, arbeiten wir dafür gerne einen halben oder ganzen Tag direkt bei Ihnen.
Was CLAUDE.md und AGENTS.md leisten
Coding-Agenten starten jede Sitzung ohne Gedächtnis. Was sie über Ihr Projekt wissen, stammt aus dem Code selbst und aus Projektanleitungen, die sie automatisch lesen. Claude Code liest die Datei CLAUDE.md, OpenAI Codex und eine wachsende Zahl weiterer Werkzeuge lesen AGENTS.md, Cursor nutzt zusätzlich eigene Rules. Diese Dateien sind das Playbook für den Agenten: Sie erklären, wie das Projekt aufgebaut ist, wie es gebaut und getestet wird und welche Regeln gelten.
Eine gute Projektanleitung ist einer der größten Hebel für die Qualität von Agenten-Ergebnissen. Ohne sie rät der Agent, welche Testbefehle es gibt, welche Bibliotheken bevorzugt sind oder welche Ordner generierten Code enthalten. Mit ihr arbeitet er so, wie es ein erfahrenes Teammitglied tun würde.
Was hineingehört und was nicht
Hinein gehören konkrete, überprüfbare Informationen: Befehle für Build, Tests, Linter und lokale Entwicklung, ein knapper Überblick über die Architektur, Namens- und Strukturkonventionen, Hinweise auf Stolperfallen sowie klare Verbote, etwa keine Änderungen an Migrationsdateien oder keine neuen Abhängigkeiten ohne Rückfrage. Hilfreich sind außerdem Hinweise, wie eine fertige Aufgabe aussieht, zum Beispiel dass Tests grün sein und Typprüfungen fehlerfrei laufen müssen.
Nicht hinein gehören Geheimnisse, lange Fließtexte, veraltete Informationen und allgemeine Programmierweisheiten, die der Agent ohnehin kennt. Jede Zeile kostet Kontext. In großen Repositories lohnt sich eine Aufteilung: eine Datei auf oberster Ebene mit allgemeinen Regeln und weitere in Unterordnern für einzelne Pakete oder Dienste. Ergänzend kann die Hauptdatei auf weiterführende Dokumente verweisen, die der Agent nur bei Bedarf liest, etwa eine Beschreibung des Datenmodells oder eine Anleitung für Datenbankmigrationen. So bleibt die tägliche Grundlast klein, und spezielles Wissen ist trotzdem erreichbar.
So entsteht ein belastbares Playbook
In Workshop oder Beratung gehen wir in klaren Schritten vor:
- Wir analysieren Repository, Build-System und vorhandene Dokumentation und sammeln mit dem Team typische Fehler, die Agenten bisher gemacht haben.
- Wir schreiben eine erste, kurze Fassung mit Befehlen, Architekturüberblick, Konventionen und Verboten.
- Wir testen die Anleitung an echten Aufgaben und beobachten, wo der Agent Regeln ignoriert oder falsch versteht.
- Wir schärfen nach, streichen Überflüssiges und ergänzen Hooks oder automatische Prüfungen dort, wo Regeln zwingend eingehalten werden müssen.
- Wir legen fest, wer die Datei pflegt und wie Änderungen wie normaler Code im Review landen.
Eine Quelle für mehrere Werkzeuge
Viele Teams nutzen mehr als einen Agenten. Damit nicht drei Dateien auseinanderlaufen, empfiehlt sich eine gemeinsame Basis, meist in AGENTS.md, auf die CLAUDE.md und Cursor Rules verweisen. Werkzeugspezifisches wie Berechtigungen oder Hooks bleibt in der jeweiligen Konfiguration. Wichtig ist, dass die gemeinsame Basis gepflegt wird: Ändert sich ein Build-Befehl oder eine Konvention, gehört die Anpassung der Projektanleitung in denselben Pull Request wie die Codeänderung. Sonst veraltet das Playbook schnell und der Agent folgt Regeln, die längst nicht mehr gelten.
neooutput erstellt solche Playbooks gemeinsam mit Ihrem Team, als Teil eines Workshops oder als eigenständige Beratung, inklusive Vorlagen für weitere Repositories. Ein kostenloses 15-Minuten-Erstgespräch genügt für eine erste Einschätzung.
Playbooks für Freiburger Projekte
Freiburger Repositories sind vielfältig: Web-Plattformen von Startups, Dateninfrastruktur für Projekte rund um Energie und Nachhaltigkeit, Forschungssoftware aus dem Umfeld der Universität und der Fraunhofer-Institute oder Branchensoftware südbadischer Mittelständler. Gerade Forschungscode hat oft ungewöhnliche Build-Schritte und wenig Dokumentation. Eine gute Projektanleitung hilft hier doppelt, weil sie neben dem Agenten auch neuen Mitarbeitenden den Einstieg erleichtert.
Wir erarbeiten das Playbook bei Ihnen vor Ort in Freiburg oder im Umland und testen es noch am selben Tag mit dem Team. Auf Wunsch entstehen die Dateien auf Englisch, wenn Kolleginnen aus der Schweiz oder Frankreich mitarbeiten. Nach einigen Wochen Praxis lohnt ein kurzer Folgetermin, um Regeln anhand der Review-Erfahrungen nachzuschärfen. Dank kurzer Wege in Freiburg lässt sich dieser Termin unkompliziert und ohne lange Vorlaufzeit planen.
Häufige Fragen
Wie lang sollte eine CLAUDE.md oder AGENTS.md sein?
So kurz wie möglich, so lang wie nötig. Für viele Projekte reichen ein bis zwei Bildschirmseiten. Wird die Datei deutlich länger, lohnt sich eine Aufteilung auf Unterordner oder ein Verweis auf separate Dokumente, die der Agent nur bei Bedarf liest.
Kann der Agent die Datei nicht selbst schreiben?
Er kann einen guten Entwurf erstellen, etwa mit dem init-Befehl von Claude Code. Dieser Entwurf beschreibt aber nur, was im Code sichtbar ist. Teamwissen, Verbote und Erfahrungen mit früheren Fehlern muss ein Mensch ergänzen, sonst fehlt der wertvollste Teil.
Woran erkenne ich, ob unser Playbook wirkt?
Daran, dass wiederkehrende Fehler seltener werden: falsche Testbefehle, ungewollte Abhängigkeiten oder Änderungen in gesperrten Bereichen. Sammeln Sie solche Fälle im Review und prüfen Sie nach jeder Anpassung, ob der Agent die neue Regel befolgt.
Lohnt sich eine Projektanleitung auch für kleine Freiburger Teams?
Gerade dort. In kleinen Teams steckt viel Wissen in wenigen Köpfen. Eine CLAUDE.md oder AGENTS.md macht dieses Wissen für Agenten und neue Kolleginnen verfügbar und spart Zeit, die sonst in wiederholte Erklärungen und Review-Korrekturen fließt.