AGENTS.md

Das Vorhandensein einer AGENTS.md-Datei geht mit einem geringeren Token-Verbrauch und einer schnelleren Aufgabenbearbeitung bei realen Pull-Requests einher.

– On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents

Cross-Agent-Konfiguration

Wenn ihr in euren Projekten mehrere Agenten unterstützen wollt, könnt ihr einfach in der CLAUDE.md mit @AGENTS.md auf die Konfiguration in eurer AGENTS.md verweisen.

Siehe auch

Claude Code Docs: AGENTS.md

Allgemeine Vorgehensweise

Ich lasse mir üblicherweise gerne zunächst fünf Lösungsvorschläge machen, bevor der mutmaßlich effektivste umgesetzt wird:

AGENTS.md
# General procedure
- Before creating code, brainstorm 5 different approaches to solve the problem and sort them by their probable effectiveness. Then, choose the best approach and implement it.

uv

Viele Agenten verwenden üblicherweise pip, wenn Pakete installiert oder Skripte ausgeführt werden sollen. Eine CLAUDE.md- oder AGENTS.md-Datei im Stammverzeichnis eures Projekts überschreibt diese Standardeinstellung, sodass in jeder Sitzung stattdessen uv verwendet wird. Eine mögliche Konfiguration für eine AGENTS.md-Datei ist:

AGENTS.md
- Use `uv` to manage Python environments and dependencies.
- Use `uv run` to execute Python scripts and commands.
- Don't edit `pyproject.toml` directly. Instead, use `uv add` and `uv add --dev` to manage dependencies.

Siehe auch

Code-Qualität und Linting

Üblicherweise lassen wir die Code-Qualität und Syntax z. B. überprüfen mit Ruff, ty, prek und Wily.

AGENTS.md
# Code quality and linting
- Use ruff, ty, prek, wily for code quality and linting.
- Run appropriate tooling after making changes to your code to ensure it meets quality standards.

Typisierung

Vermeidet übermäßige Typ-Umwandlungen. Wenn ihr feststellt, dass im Code häufig Typumwandlungen vorkommen, sollte der Code so umgestaltet werden, dass geeignetere Typen verwendet werden. Typumwandlungen sollten idealerweise nur an Schnittstellen zu externen Systemen vorgenommen werden. Verwendet Type Hints für alle Funktionsparameter und Rückgabetypen.

AGENTS.md
# Typing
- Don't use excessive casting. If you find yourself needing to cast types frequently, consider refactoring your code to use more appropriate types. Casting should only be done in boundary layers where you are interfacing with external systems.
- Use type hints for all function parameters and return types.

Testen

Viele unserer Projekte sind Testgetriebene Entwicklung mit pytest und Hypothesis. Darüberhinaus sollte Mocking und monkeypatch vermieden werden.

AGENTS.md
# Testing
- Use `pytest` for testing your code.
- Collect pytest fixtures in a `conftest.py` file to avoid duplication.
- Use the `hypothesis` library for property-based testing when you have complex input spaces or need to test edge cases.
- Favor pytest monkeypatch to mock.
- When a test fails, run the last failed test first using `uv run pytest --last-failed`.
- Use Test Driven Development (TDD) for all code you write. Write tests before writing the implementation code.
- When you come across a bug or regression, think hard about writing a test and also how to create code that will prevent this from a happening again in the future.
- Prefer testing real code where possible. Use mocks and `monkeypatch` when absolute necessary. Try to avoid mocking as much as possible.

Dokumentation

Wir verwenden in allen Funktionen und Klassen Docstrings im Google-Stil. Außerdem schreiben wir üblicherweise Doctests um die Dokumentation zu überprüfen.

AGENTS.md
# Documentation
- Use google-style docstrings for all functions and classes you create.
- Include doctests in the docstrings of your functions to provide examples

Logging

Üblicherweise nutzen wir Logging um Einblicke in Fehler zu erhalten. Wir wollen im Code keine print-Statements zum Debuggen. Wir verwenden Logging jedoch nicht, um Stack-Traces zu verbergen, wenn der Fehler ohnehin auftritt. Auch sollen Exceptions nicht verborgen werden. Wenn eine Exception doch abgefangen werden soll, sollte sie zumindest geloggt werden.

AGENTS.md
# Logging
- Use logging to provide insight into failures. Don’t use print for debugging. Don’t use logging to hide stack traces if you are going to fail anyway.
- Don't hide exceptions. Let them propagate up to the caller. If you need to catch an exception, log it and re-raise it.

Kommandozeilenwerkzeuge

Bei Kommandozeilenwerkzeugen wollen wir üblicherweise ein –verbose-Flag, das Log-Ausgaben liefert, die für die Fehlerbehebung nützlich sind.

AGENTS.md
# Command line interface
- When creating a command line interface, add `--verbose` flag that provides logging output useful for debugging issues.

Überladene Agentenanweisungen

Kontextdateien neigen dazu, im Laufe der Zeit, Übersichten über den Code, Erläuterungen zur Architektur, Konventionen und Regeln anzusammeln. Auch wenn jede einzelne Ergänzung für sich genommen nützlich sein mag, führt dies oft zu einem Übermaß an Anweisungen für den Coding-Agenten. Die Anweisungen werden länger und geraten manchmal in Widerspruch zueinander. Modelle neigen dann dazu, solchen Inhalten weniger Beachtung zu schenken. Mit zunehmendem Umfang der Anweisungen steigt die Wahrscheinlichkeit, dass wichtige Regeln ignoriert werden. Anthropic empfiehlt daher 200 Zeilen als Obergrenze, siehe Meine CLAUDE.md ist zu groß. Ihr könnt Anweisungen auch optimieren, indem ihr Hervorhebungen, z. B. IMPORTANT oder YOU MUST hinzufügt, um die Einhaltung zu verbessern.

Wir beobachten, dass viele Teams die Coding-Agenten auch zur Erstellung von AGENTS.md-Dateien einsetzen. Unsere Erfahrungen deuten jedoch darauf hin, dass handgeschriebene Versionen effektiver zu sein scheinen als solche, die generiert wurden. Am besten erscheinen solche Anweisungen, die selektiv hinzugefügt werden und schrittweise den Kontext offenlegen, um nur die Anweisungen und Fähigkeiten anzuzeigen, die ein Agent für seine aktuelle Aufgabe benötigt.

Siehe auch