Anpassen von GitHub Copilot-Antworten mithilfe von Anweisungsdateien

  • 8 Minuten

Benutzerdefinierte Anweisungsdateien bieten eine Möglichkeit, die Codierungsstandards, Architekturentscheidungen und projektspezifischen Richtlinien Ihres Teams direkt in Ihr Repository einzubetten. Wenn GitHub Copilot Chat eine Anforderung verarbeitet, liest er diese Dateien und integriert deren Inhalte in seine Antworten, wodurch Vorschläge erstellt werden, die den Konventionen Ihres Projekts entsprechen, ohne dass Sie in jeder Aufforderung denselben Kontext wiederholen müssen.

Benutzerdefinierte Anweisungen für "Always-On"

Der primäre Mechanismus für Anweisungen auf Repositoryebene ist eine Markdown-Datei .github/copilot-instructions.md , die im Stammverzeichnis Ihres Repositorys oder Arbeitsbereichs platziert ist. Diese Datei stellt GitHub Copilot mit zusätzlichem Kontext und Regeln bereit, die für alle GitHub Copilot Chat-Interaktionen innerhalb dieses Projekts gelten. Die Anweisungen werden automatisch in jeder GitHub Copilot Chat-Eingabeaufforderung enthalten, die als always-on-Richtlinien für die KI fungiert.

Wenn Ihre .github/copilot-instructions.md Datei beispielsweise "Verwenden von PascalCase für Klassennamen und CamelCase für lokale Variablen" oder "Immer das Repositorymuster für Datenzugriffsklassen verwenden" angibt, enthält GitHub Copilot diese Konventionen in seine Vorschläge. Diese Funktion reduziert die Menge der manuellen Bearbeitung, die erforderlich ist, um KI-generierten Code mit Teamrichtlinien auszurichten, die Effizienz und Konsistenz in der gesamten Codebasis zu verbessern.

Die Anweisungen werden in natürlicher Sprache mit Markdown-Formatierung geschrieben. Jede Richtlinie kann ein eigener Aufzählungspunkt oder Absatz sein. Leerzeichen zwischen Anweisungen werden ignoriert, wenn sie an das Modell gesendet werden, sodass Sie die Datei zur Lesbarkeit formatieren können, ohne dass sich dies auf die Prozesse von GitHub Copilot auswirkt.

Sie können den /init Schrägstrichbefehl in GitHub Copilot Chat verwenden, um automatisch eine copilot-instructions.md Datei für Ihr Projekt zu generieren. GitHub Copilot analysiert Ihren Arbeitsbereich und erstellt eine Startanleitungsdatei, die auf die Sprache, das Framework und die Struktur Ihres Projekts zugeschnitten ist.

Hinweis

Visual Studio Code unterstützt AGENTS.md und CLAUDE.md dateien auch als always-on-Anweisungen. Eine AGENTS.md Datei, die sich im Stammverzeichnis Ihres Arbeitsbereichs befindet, funktioniert ähnlich copilot-instructions.md und ist nützlich, wenn Sie mit mehreren KI-Agents arbeiten und eine einzelne Gruppe von Anweisungen benötigen, die von allen erkannt werden. CLAUDE.md Dateien folgen demselben Muster. Darüber hinaus können geschachtelte AGENTS.md Dateien in Unterverzeichnissen platziert werden, um kontextspezifische Anweisungen bereitzustellen, die nur gelten, wenn GitHub Copilot auf Dateien innerhalb dieses Verzeichnisses oder seiner untergeordneten Elemente arbeitet.

Pfadspezifische Anweisungen

Für Projekte, bei denen verschiedene Teile der Codebasis unterschiedliche Richtlinien erfordern, können Sie dateibasierte Anweisungsdateien mithilfe der .instructions.md Erweiterung erstellen. Diese Dateien werden im .github/instructions/ Verzeichnis (oder in Ihrem Benutzerprofil für die arbeitsbereichübergreifende Verwendung) gespeichert und enthalten einen YAML-Frontmatterheader mit einem applyTo Feld, das angibt, auf welche Dateien oder Dateimuster sie angewendet werden.

Beispielsweise kann eine Datei, die benannt ist database.instructions.mdapplyTo: "DataAccess/**/*.cs" , Regeln enthalten, die nur für C#-Dateien im DataAccess-Ordner gelten, z. B. "Verwenden des Repositorymusters für Datenzugriffsklassen" oder "Parametrisierte Abfragen immer einschließen, um die SQL-Einfügung zu verhindern.". Wenn GitHub Copilot mit Dateien arbeitet, die dem angegebenen Muster entsprechen, werden sowohl die repositoryweiten Anweisungen als auch die relevanten pfadspezifischen Anweisungen zusammengeführt, um kontextbezogene Vorschläge zu erstellen.

Das folgende Beispiel zeigt eine pfadspezifische Anleitungsdatei mit YAML-Frontmatter:

---
name: 'C# Backend Standards'
description: 'Coding conventions for C# backend files'
applyTo: 'src/Backend/**/*.cs'
---
# C# backend coding standards
- Use PascalCase for public members and camelCase for private fields.
- Prefix private fields with an underscore (e.g., _orderService).
- Use async/await for all I/O-bound operations.
- Include XML documentation comments on all public methods.

Der YAML-Frontmatter unterstützt die folgenden Felder:

  • applyTo: Ein Glob-Muster, das bestimmt, welche Dateien die Anweisungen auslösen. Allgemeine Muster umfassen **/*.cs zum Abgleichen aller C#-Dateien, src/Frontend/**/*.ts für TypeScript-Dateien in einem bestimmten Verzeichnis oder **/Tests/**/*.cs für Testdateien im gesamten Projekt. Wenn der Pfad einer Datei mit einem applyTo Muster übereinstimmt, enthält GitHub Copilot diese Anweisungen automatisch zusammen mit den allgemeinen Repository-Anweisungen.

  • Beschreibung: Eine Beschreibung in natürlicher Sprache dessen, was die Anweisungen abdecken. GitHub Copilot verwendet dieses Feld für semantischen Abgleich – wenn Sie eine Frage im Chat stellen, wertet GitHub Copilot die Beschreibung aus, um festzustellen, ob die Anweisungen für den aktuellen Kontext relevant sind, auch wenn keine Datei geöffnet ist, die dem applyTo Muster entspricht. Eine Beschreibung von "Richtlinien für Datenbankmigrationsskripts" hilft GitHub Copilot beispielsweise, diese Anweisungen einzufügen, wenn Sie nach Datenbankmigrationen fragen.

  • name: Ein Anzeigename für den Anweisungssatz, der im Menü "Chatanweisungen" und in der Diagnoseansicht angezeigt wird.

Anweisungen auf Organisationsebene

Für Unternehmen, die Codierungsstandards über mehrere Repositorys hinweg verwalten, unterstützt GitHub Anweisungen auf Organisationsebene. Diese Anweisungen werden auf GitHub-Organisationsebene definiert und in allen Repositorys innerhalb der Organisation angewendet. Dieses Verhalten sorgt für Konsistenz in allen Teams – z. B. kann ein gemeinsamer Standard für sicheres Codieren oder architekturbezogene Richtlinien organisationsweit erzwungen werden, sodass alle Projekte mit demselben Basisplan beginnen.

In Visual Studio Code werden Anweisungen auf Organisationsebene automatisch erkannt, wenn Sie bei einem GitHub-Konto angemeldet sind, das Zugriff auf eine Organisation mit konfigurierten benutzerdefinierten Anweisungen hat. Diese Anweisungen werden zusammen mit Ihren persönlichen und Arbeitsbereichsanweisungen im Menü "Chatanweisungen" angezeigt.

Hinweis

Wenn mehrere Arten von benutzerdefinierten Anweisungen vorhanden sind, umfasst GitHub Copilot alle, folgt jedoch einer Prioritätsreihenfolge, wenn Konflikte gelöst werden. Die vollständige Anweisungsprioritätskette, von der höchsten zur niedrigsten, lautet:

  1. Anweisungen, die manuell im Menü "Chatanweisungen" eingegeben oder an die Unterhaltung angeheftet wurden.
  2. .instructions.md Dateien mit pfadspezifischen Anweisungen.
  3. .github/copilot-instructions.md (repositoryweite Anweisungen).
  4. AGENTS.md oder CLAUDE.md Dateien.
  5. Anweisungen auf Organisationsebene, die von einem GitHub-Organisationsadministrator konfiguriert wurden.

Anweisungen mit höherer Priorität haben Vorrang, wenn Konflikte auftreten.

Erstellen von Anweisungsdateien

Das Erstellen von benutzerdefinierten Anweisungsdateien umfasst einige einfache Schritte.

Die Funktion aktivieren

Stellen Sie sicher, dass benutzerdefinierte Anweisungen aus .github-Dateien in den GitHub Copilot-Chateinstellungen von Visual Studio Code aktiviert sind. Diese Einstellung ist standardmäßig aktiviert. Sie können dies bestätigen, indem Sie die chat.includeApplyingInstructions Einstellung in Visual Studio Code überprüfen.

Add .github/copilot-instructions.md

Erstellen Sie im Stammverzeichnis Ihres Repositorys einen .github Ordner, falls noch kein Ordner vorhanden ist. Erstellen Sie in diesem Ordner eine Datei mit dem Namen copilot-instructions.md. Schreiben Sie Ihre Richtlinien in natürlicher Sprache mithilfe der Markdown-Formatierung. Beispiel:

# Project coding guidelines
- Use PascalCase for class names and public members.
- Prefix private fields with an underscore (e.g., _logger).
- Follow the repository pattern for all data access operations.
- Use async/await for I/O-bound operations.
- Include error handling with try-catch blocks for all external API calls.
- Add XML documentation comments on all public methods and classes.

Diese Anweisungen werden automatisch an jede GitHub Copilot Chat-Eingabeaufforderung im Repository angefügt, sodass sie alle Antworten ohne zusätzliche Aktion des Entwicklers beeinflussen.

Hinzufügen von INSTRUCTIONS.MD-Dateien (falls erforderlich)

Um bestimmte Dateitypen oder Abschnitte des Projekts als Ziel zu verwenden, erstellen Sie einen instructions Unterordner unter .github. Fügen Sie eine oder mehrere Markdown-Dateien mit Namen hinzu, die auf .instructions.md (z. B logging.instructions.md . oder sql.instructions.md) enden. Fügen Sie oben in jeder Datei einen YAML-Header mit einem applyTo Feld ein, in dem die Dateipfadmuster (Globmuster) aufgeführt sind, auf die die Anweisungen angewendet werden sollen. Schreiben Sie dann die speziellen Anweisungen im Markdown-Textkörper.

Beispielsweise könnte eine logging.instructions.md Datei applyTo: "**/*Logger.cs" spezifizieren und einen Leitfaden zur Nutzung eines bestimmten Protokollierungsframeworks in diesen Dateien enthalten. Wenn der Pfad einer aktiven Datei mit dem applyTo Muster übereinstimmt, kombiniert GitHub Copilot sowohl die allgemeinen Repositoryanweisungen als auch die entsprechenden pfadspezifischen Anweisungen für diesen Kontext.

Verifizierung

Um zu bestätigen, dass GitHub Copilot Ihre Anweisungen verwendet, überprüfen Sie den Abschnitt "Verweise " einer GitHub Copilot Chat-Antwort. Wenn benutzerdefinierte Anweisungen angewendet werden, wird die Anweisungendatei als zitierte Referenz angezeigt. Wenn die Anweisungen nicht übernommen werden, vergewissern Sie sich, dass das Feature in den Einstellungen aktiviert ist und dass der Dateipfad und die Benennung den erwarteten Konventionen entsprechen.

Sie können auch die Diagnoseansicht der Chatanpassung verwenden, um alle geladenen Anweisungsdateien und alle Fehler anzuzeigen. Klicken Sie mit der rechten Maustaste in die Chatansicht, und wählen Sie "Diagnose" aus, um den aktuellen Zustand zu überprüfen.

Vorteile von benutzerdefinierten Anweisungen

Anweisungen auf Repositoryebene richten die KI-Ausgabe an Teamkonventionen aus und reduzieren die manuelle Bearbeitung, die für jeden Vorschlag erforderlich ist. Im Folgenden finden Sie verschiedene Möglichkeiten, wie benutzerdefinierte Anweisungen die Entwicklungsumgebung verbessern:

  • Benennungskonventionen: Erzwingen von Mustern wie "private C#-Felder müssen mit einem Unterstrich beginnen" oder "PascalCase für öffentliche Eigenschaften verwenden" in allen GitHub Copilot-Vorschlägen.

  • Bibliotheks- und Framework-Nutzung: Geben Sie bevorzugte Bibliotheken an, z. B. "Zur Protokollierung verwenden Serilog " oder "Zur FluentValidation Eingabeüberprüfung verwenden", sodass GitHub Copilot keine Alternativen vorschlägt, die Ihr Team nicht verwenden möchte.

  • Formatvorlagen für Codekommentare: Bestimmte Dokumentationsformate sind erforderlich, wie z. B. "XML-Dokumentationskommentare für alle öffentlichen Methoden einschließen" oder "// für Inlinekommentare verwenden, nicht /* */."

  • Architekturmuster: Betten Sie Entscheidungen wie "Alle Datenzugriffsklassen müssen die IRepository<T> Schnittstelle implementieren" oder "Verwenden der Abhängigkeitseinfügung für alle Dienstabhängigkeiten" ein.

  • Sicherheit und Compliance: Schließen Sie Regeln wie "Immer parametrisierte Abfragen für den Datenbankzugriff verwenden" oder "Überprüfen aller Benutzereingaben an API-Grenzen" ein.

Pfadspezifische Anweisungen ermöglichen noch gezieltere Anleitungen. Unterschiedliche Regeln können für Frontend- und Back-End-Code, Testdateien und Produktionscode oder bestimmte Module mit eindeutigen Anforderungen gelten. Diese Granularität stellt sicher, dass Vorschläge für den spezifischen Bereich der Codebasis relevant sind, in der der Entwickler arbeitet.

Tipps zum Schreiben effektiver Anweisungen

Gut gestaltete Anweisungen liefern deutlich bessere Ergebnisse. Hier sind Tipps, um das Beste aus kundenspezifischen Anweisungsdateien herauszuholen:

  • Erläutern sie die Gründe für Regeln. Statt nur "präfix private Felder mit _" zu schreiben, sollten Sie "Präfix private Felder mit _, um sie von Parametern und lokalen Variablen auf einen Blick zu unterscheiden" verwenden. Wenn GitHub Copilot versteht, warum eine Regel vorhanden ist, wendet es diese Regel konsistenter an und kann das Prinzip auf ähnliche Situationen erweitern.

  • Schließen Sie kurze Codebeispiele ein. Kombinieren Sie Richtlinien mit kurzen Codeausschnitten, die das erwartete Muster zeigen sollen. Folgen Sie beispielsweise "„Verwenden Sie das Factory-Muster für die komplexe Objekterstellung“ mit einem zweizeiligen Beispiel. Konkrete Beispiele reduzieren Mehrdeutigkeit.

  • Konzentrieren Sie sich auf nicht offensichtliche Regeln. Wiederholen Sie nicht, was Linter und Formatierer bereits erzwingen. Dokumentieren Sie stattdessen die Konventionen, die nur Ihr Team kennt – z. B. welche Bibliotheken bevorzugt werden sollen, welche Muster für die Fehlerbehandlung befolgt werden sollen oder welche Architekturgrenzen zwischen Modulen bestehen.

  • Halten Sie Anweisungen präzise und spezifisch. Übermäßig lange oder vage Anweisungsdateien verdünnen GitHub Copilots Aufmerksamkeit. Jede Anweisung sollte eine klare Regel ausdrücken. Entfernen Sie Anweisungen, die sich überschneiden oder einander widersprechen.

  • Trennen Sie Belange mithilfe pfadspezifischer Dateien. Verwenden Sie .instructions.md Dateien mit applyTo Mustern, um Backend- und Frontend-Regeln getrennt zu halten, die Testlogik von Produktionscode zu trennen und Infrastrukturskripte vom Anwendungscode zu isolieren.

Eingabeaufforderungsdateien

Zusätzlich zu Anweisungsdateien, die always-on-Kontext bereitstellen, unterstützt Visual Studio Code Eingabeaufforderungsdateien – wiederverwendbare Eingabeaufforderungsvorlagen, die als Dateien gespeichert sind .prompt.md , die Sie als Schrägstrichbefehle in GitHub Copilot Chat aufrufen können.

Während Anweisungsdateien gestalten, wie GitHub Copilot antwortet, definieren Eingabeaufforderungsdateien, was sie fragen sollen. Eine Eingabeaufforderungsdatei enthält eine vordefinierte Eingabeaufforderung mit optionalen Variablenplatzhaltern, die Sie bei Bedarf ausführen können, um eine gemeinsame Aufgabe konsistent auszuführen. Sie können beispielsweise eine Eingabeaufforderungsdatei erstellen, die eine Prüfliste für die Codeüberprüfung generiert, einen Komponententest für die aktuelle Datei erstellt oder API-Dokumentation in einem bestimmten Format erstellt.

Funktionsweise von Eingabeaufforderungsdateien

Prompt-Dateien verwenden die .prompt.md-Erweiterung und können im .github/prompts/-Ordner Ihres Arbeitsbereichs gespeichert werden (freigegeben mit Ihrem Team über Versionskontrolle) oder in Ihrem persönlichen Visual Studio Code-Benutzerprofil, das in allen Arbeitsbereichen verfügbar ist. Jede Datei enthält einen optionalen YAML-Frontmatter-Header und einen Markdown-Text mit dem Text des Prompts.

Das folgende Beispiel zeigt eine Eingabeaufforderungsdatei, die Komponententests generiert:

---
description: 'Generate unit tests for the current file'
agent: 'copilot'
tools: ['search', 'read']
---
# Generate Unit Tests

Analyze the code in the active file and generate comprehensive unit tests.

For each public method or function:
1. Write a test for the expected behavior (happy path).
2. Write tests for edge cases and error conditions.
3. Use the project's existing test framework and naming conventions.

Output the tests as a complete, runnable test file.

Der YAML-Frontmatter für Eingabeaufforderungsdateien unterstützt die folgenden Felder:

Feld Description
description Eine beschreibung der Funktion der Eingabeaufforderung in natürlicher Sprache. Wird in der Schrägstrich-Befehlsauswahl angezeigt.
name Optionaler Anzeigename. Wenn dieser Parameter nicht angegeben wird, wird der Dateiname verwendet.
agent Der Agent, der die Eingabeaufforderung behandeln soll (z. B. copilot).
model Eine optionale Modellpräferenz für diese Eingabeaufforderung.
tools Tools, auf die die Eingabeaufforderung zugreifen sollte, wenn sie ausgeführt wird.

Verwenden von Promptdateien

Nach der Erstellung werden Prompt-Dateien im Eingabefeld des GitHub Copilot Chats als Schrägstrichbefehle angezeigt. Geben Sie / gefolgt vom Namen der Eingabedatei (ohne die .prompt.md-Erweiterung) ein, um sie auszuwählen und auszuführen. Beispielsweise wird eine Datei mit dem Namen generate-tests.prompt.md zum /generate-tests Befehl.

Eingabeaufforderungsdateien unterstützen Platzhaltervariablen mit der Syntax ${variable}. Die Variable ${file} bezieht sich auf die derzeit aktive Datei und ${selection} verweist auf die aktuelle Textauswahl. Sie können auch benutzerdefinierte Variablen definieren, die den Benutzer zur Eingabe auffordern, wenn die Eingabeaufforderungsdatei ausgeführt wird.

Hinweis

Um Eingabeaufforderungsdateien zu aktivieren, stellen Sie sicher, dass die chat.promptFiles Einstellung in Visual Studio Code aktiviert ist. Wenn diese Option aktiviert ist, werden Ihre .prompt.md Dateien automatisch erkannt und als verfügbare Schrägstrichbefehle registriert.

Einschränkungen

Benutzerdefinierte Anweisungsdateien weisen einige wichtige Einschränkungen auf, um Folgendes zu beachten:

  • Keine Auswirkung auf die Inline-Autovervollständigung: Benutzerdefinierte Anweisungen gelten für GitHub Copilot Chat und andere übergeordnete Anfragen. Sie beeinflussen nicht die grundlegenden Inlinecode-Fertigstellungen, die während der Eingabe im Editor angezeigt werden.

  • Prägnanz ist wichtig: Große, nicht fokussierte Anweisungsdateien können zu verdünnten oder unvorhersehbaren Ergebnissen führen. Halten Sie Anweisungen kurz und relevant für die wichtigsten Richtlinien. Konzentrieren Sie sich auf Regeln, die noch nicht von Lintern oder Formatierern erzwungen werden.

  • Keine garantierte Compliance: Anleitungen zum Verhalten von GitHub Copilot, erzwingen jedoch keine strengen Regeln. Die KI betrachtet die Anweisungen zusammen mit anderen Kontexten, sodass die Ergebnisse manchmal von den Erwartungen abweichen können.

Zusammenfassung

Benutzerdefinierte Anweisungsdateien und Eingabeaufforderungsdateien bieten eine strukturierte Möglichkeit, das Verhalten von GitHub Copilot auf Repository-, Pfad- und Organisationsebene zu leiten. Indem Sie eine .github/copilot-instructions.md Datei für projektweite Standards, optionale .instructions.md Dateien für pfadspezifische Regeln und .prompt.md Dateien für wiederverwendbare Eingabeaufforderungsvorlagen erstellen, können Sie KI-generierte Vorschläge an den Codierungskonventionen Ihres Teams ausrichten. Wenn Sie effektive Anweisungen schreiben – mit Gründen, Beispielen und fokussierten Bereichen – maximiert sie den Wert dieser Anpassungsfeatures. Zusammen reduzieren diese Tools manuelle Korrekturen, verbessern die Codekonsistenz und betten das Wissen Ihres Teams direkt in den Entwicklungsworkflow ein.