AGENTS.md: So machen Sie Ihre Codebasis KI-Agenten-freundlich (Copilot, Cursor, Codex, Claude Code)

Ihre README erklärt Ihr Projekt für Menschen. Ihre .gitignore sagt Git, was übersprungen werden soll. Ihre pyproject.toml sagt Python, wie gebaut werden soll.

Aber wer sagt Copilot, dass er Ihre generierten Migrationsdateien nicht anfassen soll? Wer sagt Claude Code, welchen Testbefehl er ausführen soll? Wer sagt Cursor, dass flush() in der Repository-Schicht passiert, nicht commit()?

Niemand. Und deshalb machen KI-Agenten immer wieder die gleichen Fehler in Ihrer Codebasis — sie überschreiben Dateien, die sie nicht sollten, verwenden Muster, von denen Sie abgerückt sind, und führen die falschen Befehle aus.

Die Lösung ist eine Datei, deren Erstellung 15 Minuten dauert. Das Ökosystem hat sich nur noch nicht auf den Namen geeinigt.

Das Problem: KI-Agenten sind mächtig, aber ahnungslos

Jedes große KI-Coding-Tool — GitHub Copilot, Cursor, OpenAI Codex, Claude Code — kann jetzt ganze Repositories lesen, verstehen und modifizieren. Es geht nicht mehr um die Autovervollständigung einzelner Zeilen. Es geht um das Refactoring von Modulen, das Schreiben von Tests, das Erstellen neuer Features aus natürlichsprachlichen Beschreibungen.

Aber hier ist die Lücke: Sie verstehen Code-Syntax perfekt und Projektkonventionen überhaupt nicht.

Ein KI-Agent kann Ihren FastAPI-Router lesen und einen neuen Endpoint generieren. Aber er wird nicht wissen, dass Ihr Team das Repository-Pattern verwendet, dass Datenbankoperationen durch eine Service-Schicht gehen, dass Schemas in Create-, Update- und Response-Varianten aufgeteilt sind. Er wird nicht wissen, dass alembic/versions/ automatisch generiert wird und niemals manuell bearbeitet werden sollte. Er wird nicht wissen, dass Ihr Projekt uv statt pip verwendet.

Das Ergebnis? Sie verbringen die Hälfte Ihrer Zeit damit, KI-generierten Code zu überprüfen und zu korrigieren, der syntaktisch korrekt, aber architektonisch falsch ist.

Die Landschaft: Verschiedene Tools, verschiedene Dateien

Was jedes große KI-Coding-Tool heute liest:

Jedes Tool hat sein eigenes Format erfunden. Wenn Ihr Team Copilot UND Cursor UND Claude Code verwendet (was immer häufiger vorkommt), bräuchten Sie drei separate Dateien, die dieselben Projektkonventionen beschreiben.

Hier kommt AGENTS.md ins Spiel. Es entwickelt sich zum Tool-agnostischen Standard — eine einzige Datei, die jeder KI-Agent lesen kann, um Ihre Codebasis zu verstehen. GitHub Copilot, Codex und Zed suchen bereits danach. Claude Code liest es ebenfalls (neben CLAUDE.md). Cursor kann so konfiguriert werden, dass es einbezogen wird.

Eine Datei. Jedes Tool.

Was gehört in AGENTS.md

Nach der Generierung von AGENTS.md-Dateien für Dutzende von Projekten hier die Struktur, die funktioniert:

1. Projektübersicht (2-3 Zeilen)

Was das Projekt ist. Was der Stack ist. Nicht mehr.

## Project Overview

**my-ai-app** — FastAPI-Anwendung.

**Stack:** FastAPI + Pydantic v2, PostgreSQL (async), JWT auth, Redis, PydanticAI, Next.js 15

2. Befehle (der wichtigste Abschnitt)

Welche Befehle zum Testen, Linting und Bauen ausgeführt werden sollen. Hier machen Agenten ohne Anleitung die meisten Fehler — sie führen pip install statt uv sync aus, oder npm statt bun.

# Backend
cd backend
uv run uvicorn app.main:app --reload --port 8000
pytest
ruff check . --fix && ruff format .

# Datenbank
uv run alembic upgrade head

# Frontend
cd frontend
bun dev

# Docker
docker compose up -d

3. Projektstruktur

Ein Baum, der zeigt, wo sich Dinge befinden. Nicht die vollständige tree-Ausgabe — nur die Verzeichnisse, die wichtig sind.

backend/app/
├── api/routes/v1/    # HTTP-Endpoints
├── services/         # Geschäftslogik
├── repositories/     # Datenzugriff
├── schemas/          # Pydantic-Modelle
├── db/models/        # Datenbankmodelle
├── agents/           # KI-Agenten
└── commands/         # CLI-Befehle

4. Wichtige Konventionen

Der Abschnitt, der die meiste Review-Zeit spart:

## Key Conventions

- `db.flush()` in Repositories verwenden (nicht `commit`)
- Services werfen Domain-Exceptions (`NotFoundError`, `AlreadyExistsError`)
- Schemas: separate `Create`-, `Update`-, `Response`-Modelle

5. Was NICHT modifiziert werden soll

Ebenso wichtig — sagen Sie Agenten, was tabu ist:

## Do Not Modify

- `alembic/versions/` — automatisch generierte Migrationen
- `frontend/node_modules/` — verwaltet von bun
- `.env` — lokale Geheimnisse, niemals committen

6. Verweise auf tiefere Dokumentation

## More Info

- `docs/architecture.md` — Architekturdetails
- `docs/adding_features.md` — Wie man Features hinzufügt
- `docs/testing.md` — Testanleitung

Reales Beispiel: Automatisch generierte AGENTS.md

Hier wird es meta.

Unser full-stack-ai-agent-template ist ein CLI, das produktionsreife FastAPI + Next.js-Projekte mit über 75 Konfigurationsoptionen generiert — Datenbank, Auth, KI-Framework (Pydantic AI, LangChain, LangGraph, CrewAI, DeepAgents), Hintergrundaufgaben, Docker, CI/CD.

Jedes generierte Projekt enthält sowohl AGENTS.md als auch CLAUDE.md — automatisch generiert basierend auf Ihren Konfigurationsentscheidungen.

PostgreSQL gewählt? Der Befehle-Abschnitt enthält Alembic-Migrationsbefehle. KI-Agent aktiviert? Die Projektstruktur zeigt das agents/-Verzeichnis. JWT-Auth gewählt? Der Umgebungsvariablen-Abschnitt enthält SECRET_KEY.

Das Template verwendet Jinja2-Bedingungen zur Anpassung dieser Dateien:

**Stack:** FastAPI + Pydantic v2
{%- if cookiecutter.use_postgresql %}, PostgreSQL (async){%- endif %}
{%- if cookiecutter.use_jwt %}, JWT auth{%- endif %}
{%- if cookiecutter.enable_redis %}, Redis{%- endif %}
{%- if cookiecutter.enable_ai_agent and cookiecutter.use_pydantic_ai %}, PydanticAI{%- endif %}
{%- if cookiecutter.use_frontend %}, Next.js 15{%- endif %}

Sie bekommen kein generisches AGENTS.md — Sie bekommen eines, das auf Ihren exakten Stack zugeschnitten ist.

Wir bauen ein KI-Agenten-Template, das freundlich zu anderen KI-Agenten ist. Ein Template, das Apps mit KI-Frameworks generiert und gleichzeitig die Dateien generiert, die KI-Coding-Agenten helfen, mit diesen Apps zu arbeiten. Agenten auf jeder Ebene.

AGENTS.md vs. CLAUDE.md: Brauchen Sie beides?

Kurze Antwort: Ja, wenn Sie Claude Code verwenden.

AGENTS.md ist Tool-agnostisch. Es deckt ab, was jeder KI-Agent braucht: Befehle, Struktur, Konventionen.

CLAUDE.md ist Claude Code-spezifisch. Es kann Claude-spezifische Anweisungen wie Speichermuster, Tool-Präferenzen und Claude Codes spezielles Interaktionsmodell enthalten. Claude Code liest CLAUDE.md zuerst, dann AGENTS.md für zusätzlichen Kontext.

Die Überschneidung ist beabsichtigt. Wenn ein Agent nur eine Datei liest, bekommt er genug Kontext. Wenn er beide liest, bekommt er das vollständige Bild.

So fügen Sie AGENTS.md zu Ihrem bestehenden Projekt hinzu

Sie brauchen kein Template. Hier ist die Minimalversion für jedes Python-Projekt:

## Project Overview
[Projektname] — [Einzeiler-Beschreibung].
Stack: [Sprachen, Frameworks, Datenbanken]

## Commands
# Installations- / Test- / Lint-Befehle hier

## Structure
[vereinfachter Baum der wichtigsten Verzeichnisse]

## Conventions
- [Muster 1]
- [Muster 2]
- [Muster 3]

## Do Not Modify
- [generierte Dateien]
- [Lock-Dateien]
- [Geheimnisse]

Kopieren Sie dieses Template, füllen Sie die Lücken, committen Sie. Jedes KI-Coding-Tool, das Ihr Repo liest, wird sofort nützlicher.

Wichtige Erkenntnisse

• KI-Coding-Agenten lesen Ihr Repo, verstehen aber nicht Ihre Konventionen. AGENTS.md füllt diese Lücke — Projektstruktur, Befehle, Muster und was nicht angefasst werden soll.
• Verschiedene Tools verwenden verschiedene Dateien (.github/copilot-instructions.md, .cursor/rules/, CLAUDE.md), aber AGENTS.md entwickelt sich zum Tool-agnostischen Standard.
• Die wirkungsvollsten Abschnitte sind Commands und Conventions. Diese verhindern die häufigsten KI-Fehler: falsche Build-Tools und falsche Architekturmuster.
• Es dauert 15 Minuten zum Schreiben und spart Stunden beim Review von KI-generiertem Code, der Ihre Muster bricht.
• Auto-Generierung ist möglich — unser Template generiert AGENTS.md und CLAUDE.md, zugeschnitten auf die exakte Konfiguration jedes Projekts.

Ausprobieren: full-stack-ai-agent-template — generiert produktionsreife FastAPI + Next.js KI-Apps mit eingebauten AGENTS.md und CLAUDE.md

pip install fastapi-fullstack

Alle Vstorm Open-Source-Projekte | awesome-pydantic-ai | vstorm.co