Verbesserung des generierten Codes mit copilot-instructions.md und AGENTS.md (Github Copilot)

Wie in den vorherigen Beiträgen beschrieben, habe ich begonnen, AI-Coding-Assistenten wie GitHub Copilot und Vibe Coding intensiv zu nutzen. Dabei habe ich festgestellt, dass die Qualität des generierten Codes stark von der Art und Weise abhängt, wie ich den Kontext für diese Tools bereitstelle. Dabei spielt es natürlich eine wichtige Rolle, wie ich meinen Prompt formuliere, aber auch die Bereitstellung von zusätzlichen Kontextdateien, welche für die Erfüllung der Aufgabe relevant sind. Darüber hinaus möchte ich ja auch, dass der generierte Code zu meiner Codebase und meiner Softwarearchitektur passt. Jedes Mal diese Informationen zu schreiben bzw. im Prompt zu erwähnen ist sehr aufwendig und fehleranfällig (da man es gerne mal vergisst).

Um dieses Problem zu lösen, habe ich begonnen, zwei spezielle Dateien in meinen Projekten zu verwenden: copilot-instructions.md und AGENTS.md. Diese Dateien enthalten wichtige Informationen und Anweisungen, die den AI-Coding-Assistenten helfen, den Kontext besser zu verstehen und qualitativ hochwertigen Code zu generieren, der zum Projekt passt.

Diese beiden Dateien möchte ich euch gerne mal vorstellen, damit auch ihr Code generiert bekommt, der besser zu euren Projekten passt und ihr weniger Zeit mit Korrekturen verbringen müsst.

Was ist copilot-instructions.md?

Bei der copilot-instruction handelt es sich um eine Markdown-Datei, mit der du GitHub Copilot (Chat und Inline) projektspezifische Custom Instructions gibst, z.B. Coding-Guidelines, Architekturregeln, bevorzugte Libraries, Test-Strategien.

Sie wird typischerweise unter .github/copilot-instructions.md im Projekt abgelegt und automatisch als Kontext für Copilot in diesem Projekt geladen.

Wenn diese Datei im Projekt vorhanden ist, liest Copilot deren Inhalt und verwendet sie bei jeder Anfrage, die du an Copilot stellst als zusätzlichen Kontext. Ob die von dir angelegte copilot-instructions.md Datei verwendet wird, erkennt man im Chat an dieser Information:

Falls das nicht auftaucht, dann kann man die Datei über das Zahnrad-Icon im Chat-Fenster über das Menü "Chat Instructions" aktivieren. Dazu muss man dann die passende Datei auswählen.

Die Datei startet mit einem Header-Bereich, der Metadaten bereitstellt. Hier kann man den name, eine description und applyTo setzen. Letzteres ist optional, doch falls es gesetzt ist, gibt es an, welche Dateien die Anweisungen automatisch anwenden sollen, relativ zum Arbeitsbereichs-Stammverzeichnis. Verwende **, um alle Dateien anzuwenden.

Anschließend folgt in der Markdown-Datei eine Beschreibung, was die Kernaufgabe des Assistenten in diesem Projekt ist. Als nächster Absatz folgt der Projektkontext, wie das Framework, die Sprache, das Build-Tooling usw. Anschließend folgen die Coding-Guidelines, also wie der Code aussehen soll, welche Patterns und Libraries verwendet werden sollen (gerne mit konkreten Beispielen). Man kann auch angeben, wie der Entwicklungsprozess aussehen soll, und natürlich auch weitere Richtlinien und generelle Patterns, die eingehalten werden sollen.

Je spezifischer und konkreter für euer Projekt ihr diese Informationen bereitstellt, desto besser wird der generierte Code zu eurem Projekt passen.

Um euch den Einstieg zu erleichtern, gibt es auf GitHub das Repo awesome-copilot mit passenden Instructions, so hier z. B. eine Vue3 copilot-instruction

Probiert es gerne mal aus und schaut, ob ihr so die Qualität des generierten Codes verbessern könnt.

Was ist AGENTS.md?

Ähnlich wie die copilot-instructions.md Datei, handelt es sich bei AGENTS.md um eine offene Format/Standard-Datei am Projekt-Root („README für AI-Agents“), die von mehreren Tools gelesen werden kann (Copilot-Agent, Cursor, Zed, OpenAI/Codeium-ähnliche Agents etc.).

Sie beschreibt primär, wie ein „Agent“ in diesem Repo arbeiten soll: Projektkontext, Build-/Test-Befehle, Rollen (z.B. „Refactorer“, „Test Writer“), Workflow-Regeln und Qualitätsanforderungen.​

Typische Inhalte einer AGENTS.md-Datei sind Inhalte, die einem Agenten helfen, effektiv mit deinem Projekt zu arbeiten. Beliebte Optionen:

• Projektübersicht
• Build- und Test-Befehle
• Code-Stil-Richtlinien
• Test-Anweisungen
• Sicherheitsüberlegungen

Hier ist ein simples Beispiel einer AGENTS.md Datei:

# Sample AGENTS.md file

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
- Run `pnpm install --filter <project_name>` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
- Use `pnpm create vite@latest <project_name> -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready.
- Check the name field inside each package's package.json to confirm the right name—skip the top-level one.

## Testing instructions
- Find the CI plan in the .github/workflows folder.
- Run `pnpm turbo run test --filter <project_name>` to run every check defined for that package.
- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
- To focus on one step, add the Vitest pattern: `pnpm vitest run -t "<test name>"`.
- Fix any test or type errors until the whole suite is green.
- After moving files or changing imports, run `pnpm lint --filter <project_name>` to be sure ESLint and TypeScript rules still pass.
- Add or update tests for the code you change, even if nobody asked.

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing.

Weitere Beispiele könnt ihr auch auf Agents.md finden. Hier ein weiteres Beispiel einer AGENTS.md vom zuvor genannten awesome-copilot Repo.

Vergleich copilot-instructions.md vs. AGENTS.md

Beide Dateien dienen dem Zweck, AI-Coding-Assistenten kontextuelle Informationen bereitzustellen, um die Qualität des generierten Codes zu verbessern. Dennoch gibt es einige Unterschiede in ihrem Fokus und ihrer Anwendung. Ob ihr nur eine der beiden Dateien einsetzt oder beide kombiniert, hängt von euch ab. Wichtig ist nur, dass sich die Dateien nicht widersprechen, sondern sich ergänzen.

Hier eine kleine Übersicht der Unterschiede:

Ausblick

Ich habe in diesem Post nur die Grundlagen zu copilot-instructions.md und AGENTS.md vorgestellt. Es gibt auch noch die Möglichkeit, mehrere Instructions-Dateien in einem Projekt zu verwenden, um verschiedene Kontexte für unterschiedliche Module oder Bereiche bereitzustellen. Auch der Einsatz von Custom Agents ist möglich. Hierzu werde ich in einem zukünftigen Beitrag mehr schreiben.

Fazit

Ich selbst habe durch den Einsatz beider Dateien die Qualität des generierten Codes deutlich verbessern können. Indem ich den AI-Coding-Assistenten klarere Anweisungen und Kontext gebe, erhalte ich Code, der besser zu meinen Projekten passt und weniger Nacharbeit erfordert. Ich kann jedem, der AI-Coding-Assistenten nutzt, nur empfehlen, diese Dateien in seinen Projekten zu verwenden und so das Thema "Context Engineering" zu verbessern.

Auch wenn ihr durch den Einsatz dieser Dateien besseren Code generiert bekommt, solltet ihr den generierten Code immer noch überprüfen und testen, um sicherzustellen, dass er sowohl euren Qualitätsstandards als auch euren Anforderungen entspricht.