Wie Engineering-Teams benutzerdefinierte Repository-Anweisungen in GitHub Copilot für Coding-Standards und Architekturkonventionen einrichten

Wenn Entwicklerteams GitHub Copilot im größeren Maßstab einführen, stoßen sie schnell auf ein Problem: mangelnde Konsistenz im generierten Code. Ohne projektspezifische Leitplanken stützt sich die KI lediglich auf allgemeine Trainingsdaten und fragmentierte Snippets aus aktuell geöffneten Dateien. Das führt dazu, dass in einem TypeScript-Projekt veraltete Callback-Muster vorgeschlagen werden, Schichtenarchitekturen durchbrochen werden oder nicht genehmigte Abhängigkeiten in Pull Requests (PRs) landen.

GitHub Copilot löst dieses Problem über benutzerdefinierte Repository-Anweisungen (Repository Custom Instructions). Durch versionierte Markdown-Dateien im Git-Repository – vor allem .github/copilot-instructions.md auf Wurzelebene sowie modulare Dateien unter .github/instructions/**/*.instructions.md – können Teams Architekturrichtlinien, Typisierungsregeln, Teststandards und Sicherheitsanforderungen direkt in jede Copilot-Interaktion und in automatisierte PR-Reviews einspeisen.

Dieser Leitfaden beschreibt die Funktionsweise und Priorisierung benutzerdefinierter Anweisungen, die Konfiguration auf Repository- und Pfadebene, die Aktivierung für automatisierte Code-Reviews und die Best Practices, um Kontextfenster nicht unnötig zu überlasten.

Geltungsbereich: Wo Anweisungen greifen (und wo nicht)

Bevor Regeln formuliert werden, muss geklärt sein, welche Oberflächen von GitHub Copilot diese Anweisungen tatsächlich verarbeiten.

Benutzerdefinierte Anweisungen werden automatisch dem System-Prompt vorangestellt, wenn der Nutzer anspruchsvollere Denk- und Dialogprozesse anstößt:

• Copilot Chat in IDEs: VS Code, Visual Studio, JetBrains-Entwicklungsumgebungen (IntelliJ IDEA, PyCharm, WebStorm etc.), Xcode und Eclipse.
• GitHub.com-Oberflächen: Web-Chat im Repository, Copilot Cloud Agent für autonome Programmieraufgaben und automatische PR-Erstellung.
• Copilot Code Review: Automatisierte Pull-Request-Reviews auf GitHub.com, bei denen Copilot Code-Diffs anhand der Repository-Anweisungen prüft.
• Copilot CLI: Terminal-basierte Unterstützung in Shell-Umgebungen.

Abgrenzung zur Inline-Vervollständigung (Ghost-Text)

Benutzerdefinierte Anweisungen steuern nicht die latenzkritische Inline-Autovervollständigung (den grauen Ghost-Text beim Tippen). Um Antwortzeiten im Millisekundenbereich zu garantieren, stützt sich der Ghost-Text primär auf unmittelbare Nachbartokens und geöffnete Tabs. Die Repository-Anweisungen wurden für Chat, Refactorings (/fix, /explain), autonome Agenten und PR-Reviews konzipiert. Für strikte Formatierungsregeln (Semikolons, Einrückungen, Anführungszeichen) sollten Teams weiterhin deterministische Linter und Formatierer wie ESLint, Biome oder Prettier einsetzen.

Rangfolge der Anweisungen (Precedence Hierarchy)

Treffen mehrere Anweisungsebenen aufeinander, kombiniert GitHub Copilot diese nach einer festen Priorität (von höchster zu niedrigster):

1. Persönliche Anweisungen (Personal instructions): Individuelle Einstellungen des Entwicklers im Copilot-Profil.
2. Pfadspezifische Anweisungen (Path-specific instructions): Regeln in .github/instructions/**/*.instructions.md, die über Glob-Muster zur bearbeiteten Datei passen.
3. Repository-weite Anweisungen (Repository-wide instructions): Die zentrale Datei .github/copilot-instructions.md im Repository-Root.
4. Agenten-Anweisungen: Dateien wie AGENTS.md, CLAUDE.md oder GEMINI.md.
5. Organisationsweite Anweisungen (Organization instructions): Richtlinien, die von GitHub-Administratoren für die gesamte Organisation definiert wurden.

Schritt 1: Globale Repository-Anweisungen erstellen (.github/copilot-instructions.md)

Die grundlegende Konfigurationsdatei wird im Verzeichnis .github im Root des Git-Repositories angelegt:

mkdir -p .github
touch .github/copilot-instructions.md

Um die Treffsicherheit des Modells zu maximieren, sollte die Datei mit präzisen Markdown-Überschriften, Listen und bejahenden Handlungsanweisungen strukturiert sein.

Empfohlene Kernabschnitte

1. Projektübersicht und Architekturgrenzen: Zweck des Dienstes, Architekturmuster (Clean Architecture, Modular Monolith, Hexagonal Architecture) und strikte Trennungsregeln (z. B. „Die Domänenschicht darf keine Datenbanktreiber oder UI-Komponenten importieren“).
2. Sprachversionen und Kern-Tooling: Feste Versionen des Tech-Stacks (z. B. Node.js 22 LTS, TypeScript 5.5, Next.js 15 App Router).
3. Coding-Standards und Fehlerbehandlung: Namenskonventionen, Handhabung asynchroner Fehler (z. B. „Result-Typen statt unbehandelter Ausnahmen verwenden“).
4. Testvorgaben: Test-Framework (Vitest, Jest), Testaufbau (Arrange-Act-Assert, AAA) und verpflichtende Abdeckung für Geschäftslogik.
5. Sicherheit und Validierung: Pflicht zur Schemavalidierung (Zod, Pydantic), parametrisierte SQL-Abfragen und Verbot hartcodierter Zugangsdaten.

Beispielvorlage (TypeScript / Next.js-Service)

# Repository-Architektur und Coding-Standards

## Projektübersicht
Dieses Repository enthält den Core Billing Service, entwickelt als modularer Microservice auf Basis von Next.js und Node.js mit PostgreSQL und Stripe.

## Architekturgrenzen
- Strikte Schichtentrennung: UI-Komponenten (`/app`, `/components`) -> Anwendungsdienste (`/src/services`) -> Domänenmodelle (`/src/domain`) -> Daten-Repositories (`/src/infrastructure`).
- Die Domänenschicht muss framework-unabhängig bleiben. Importe von `next/*` oder Datenbanktreibern in `/src/domain` sind untersagt.
- Alle Datenbankzugriffe müssen über Prisma-Repositories unter `/src/infrastructure/repositories` erfolgen. Direktes SQL außerhalb von Migrationen ist verboten.

## TypeScript-Standards
- TypeScript 5.x im Strict-Modus. Die Verwendung von `any` ist untersagt; nutzen Sie `unknown` mit Type Narrowing oder Zod-Validierung.
- Bevorzugen Sie `type`-Aliase für Objekt- und Union-Definitionen; nutzen Sie `interface` nur für erweiterbare Verträge.
- Asynchrone Fehler müssen über `Result<T, E>`-Typen oder strukturierte Fehlerklassen abgefangen werden. Keine unhandled Promise rejections.
- Guard Clauses und Early Returns verwenden, um verschachtelte if/else-Blöcke zu minimieren.

## State Management und Datenabruf
- Client-seitiger Datenabruf muss über TanStack Query (`@tanstack/react-query`) erfolgen. Keine ungemerkten `useEffect`-Hooks für API-Aufrufe.
- Server Actions müssen eingehende Payloads vor dem Aufruf von Domänendiensten mit Zod validieren.

## Test-Standards
- Test-Runner: Vitest mit React Testing Library.
- Unit-Tests müssen direkt neben der jeweiligen Quelldatei liegen (`*.spec.ts` oder `*.spec.tsx`).
- Arrange-Act-Assert (AAA)-Struktur in allen Test-Suites verpflichtend.
- Netzwerkgrenzen mit Mock Service Worker (MSW) isolieren; keine internen Sprachwerkzeuge mocken.

## Befehlsreferenz
- Tests ausführen: `pnpm test`
- Typprüfung: `pnpm typecheck`
- Linter-Prüfung: `pnpm lint`

Schritt 2: Pfadspezifische Anweisungen konfigurieren (.github/instructions/)

In Monorepos oder Full-Stack-Projekten führt eine einzige globale Datei dazu, dass die KI mit irrelevanten Details überflutet wird. Ein Entwickler, der an einem Go-Backend arbeitet, benötigt keine React- und Tailwind-Regeln.

Pfadspezifische Anweisungen lösen dies, indem sie Anweisungen gezielt an Glob-Muster koppeln.

Verzeichnisstruktur

Organisieren Sie modulare Anweisungsdateien unter .github/instructions/:

.github/
  ├── copilot-instructions.md
  └── instructions/
      ├── frontend.instructions.md
      ├── backend.instructions.md
      └── migrations.instructions.md

Dateisyntax mit Frontmatter

Jede pfadgebundene Datei muss auf .instructions.md enden und zu Beginn einen YAML-Frontmatter-Block mit dem Schlüssel applyTo enthalten:

---
applyTo: "apps/web/**/*.{ts,tsx}"
---

# Frontend-Komponentenstandards

- Komponenten müssen als funktionale Komponenten mit Named Exports exportiert werden.
- Tailwind CSS-Utility-Klassen verwenden; Inline-CSS-Objekte vermeiden.
- Alle interaktiven Elemente müssen barrierefreie `aria-*`-Attribute und Tastaturnavigation unterstützen.
- Icons ausschließlich aus `lucide-react` importieren.

Typische Glob-Muster

• **/*.py: Gilt für alle Python-Dateien im gesamten Repository.
• services/billing/**/*.go: Gilt ausschließlich für Go-Dateien des Billing-Services.
• **/*.test.ts,**/*.spec.ts: Kommagetrennte Liste mehrerer Dateiendungen.

Bestimmte Agenten ausschließen (excludeAgent)

Soll eine Anweisung nur für autonome Cloud-Agenten gelten und nicht bei Pull-Request-Reviews ausgelöst werden, lässt sich excludeAgent definieren:

---
applyTo: "**"
excludeAgent: "code-review"
---

# Build-Leitfaden für autonome Cloud-Agenten
- Vor dem Ausführen von Integrationstests immer `pnpm db:migrate` ausführen.
- Beim Hinzufügen neuer Konfigurationen stets `.env.example` aktualisieren.

Schritt 3: Automatisierte Code-Reviews für Pull Requests aktivieren

Benutzerdefinierte Anweisungen unterstützen nicht nur den Entwickler beim Schreiben, sondern dienen auch als Bewertungsmaßstab für automatische PR-Reviews durch Copilot.

Aktivierung in GitHub

1. Navigieren Sie auf GitHub.com zum Repository.
2. Klicken Sie auf den Reiter Settings (Einstellungen).
3. Öffnen Sie in der linken Navigation Code, planning, and automation -> Copilot -> Code review.
4. Aktivieren Sie den Schalter Use custom instructions when reviewing pull requests.

Auswertung auf dem Feature-Branch (Head Branch)

Bei einem PR-Review liest GitHub Copilot die Anweisungsdateien vom Head Branch (PR-Branch) und nicht vom Ziel-Branch (main).

Das bietet einen entscheidenden Vorteil im Entwicklungsworkflow: Wenn das Architekturteam Richtlinien anpassen möchte, kann ein PR erstellt werden, der sowohl die neuen Anweisungsdateien als auch den daran angepassten Beispielcode enthält. Copilot bewertet das Diff sofort auf Basis der neuen Regeln, sodass Teams die Wirksamkeit der Richtlinien vor dem Merge in main testen können.

Schritt 4: Laden der Anweisungen in der IDE prüfen

Um sicherzustellen, dass die IDEs der Entwickler die Anweisungen laden:

1. IDE-Einstellungen überprüfen:
   • In VS Code: Öffnen Sie die Einstellungen (Strg+, bzw. Cmd+,), suchen Sie nach instruction file und vergewissern Sie sich, dass Code Generation: Use Instruction Files aktiviert ist (standardmäßig aktiv).
   • In JetBrains-IDEs: Klicken Sie im Copilot-Chat-Panel auf das Zahnrad-Symbol und wählen Sie Customizations, um geladene Anweisungsdateien einzusehen.
2. References-Bereich im Chat prüfen:
   • Stellen Sie eine technische Frage im Copilot Chat (z. B. „Erstelle einen Authentifizierungsdienst“).
   • Klappen Sie das Menü References über der generierten Antwort auf.
   • Bei korrekter Konfiguration wird .github/copilot-instructions.md (und ggf. die passende .instructions.md) verlinkt. Dies bestätigt, dass die KI die Teamstandards eingelesen hat.

Best Practices und typische Fehler

Ergänzung durch Prompt-Dateien (.github/prompts/*.prompt.md)

Während Repository-Anweisungen dauerhafte architektonische Leitplanken bilden, gibt es wiederkehrende Standardaufgaben: das Anlegen eines neuen API-Endpunkts, Datenbank-Migrationen oder Unit-Test-Gerüste.

Für solche Aufgaben bieten sich Copilot Prompt-Dateien (.github/prompts/*.prompt.md) an. Entwickler können vordefinierte Vorlagen im Chat aufrufen, während .github/copilot-instructions.md im Hintergrund sicherstellt, dass der erzeugte Code den übergeordneten Standards entspricht.

Checkliste für Team-Leads

1. .github/copilot-instructions.md im Repository-Root mit Architekturübersicht, Tool-Versionen und Kernstandards anlegen.
2. Bei heterogenen Stacks modulare Dateien unter .github/instructions/ mit passenden applyTo-Globs erstellen.
3. In den GitHub-Repository-Einstellungen die Option für PR-Reviews mit benutzerdefinierten Anweisungen aktivieren.
4. Im IDE-Chat über den Bereich References verifizieren, dass die Dateien aktiv geladen werden.
5. Anweisungen bei Architekturänderungen und Bibliotheksupdates kontinuierlich per PR pflegen.

Referenzen

• Adding repository custom instructions for GitHub Copilot - GitHub Docs
• Adding repository custom instructions for GitHub Copilot in your IDE - GitHub Docs
• Support for different types of custom instructions - GitHub Docs
• About customizing GitHub Copilot responses - GitHub Docs
• 5 tips for writing better custom instructions for Copilot - The GitHub Blog