Cody Custom Commands mit .vscode/cody.json konfigurieren: Team-Prompts und Codegenerierung standardisieren

Wenn Software-Engineering-Teams KI-Coding-Assistenten einführen, entsteht schnell eine spürbare Qualitätslücke im Entwickleralltag. Während Senior-Entwickler und Architekten strukturierte, kontextbewusste Prompts verfassen, begnügen sich andere Teammitglieder oft mit vagen Anweisungen wie „Fixe diesen Fehler“ oder „Schreibe einen Test“. Das Resultat ist fragmentierter Code: uneinheitliche Test-Frameworks, abweichende Assertions, variierende Fehlerbehandlungsmuster und verloren gegangene Best Practices des Teams.

Sourcegraph Cody bietet einen direkten Mechanismus, um diese Diskrepanz auf Repository-Ebene zu lösen: Custom Commands (benutzerdefinierte Befehle), die in .vscode/cody.json konfiguriert werden. Indem erprobte Prompt-Vorlagen, Ausführungsmodi und präzise Kontextgrenzen in einer versionierten Konfigurationsdatei festgeschrieben werden („Prompts as Code“), wird Prompt-Engineering zu wiederverwendbarer Team-Infrastruktur. Jeder Entwickler, der das Repository klont, erhält sofort Zugriff auf dieselben Slash-Befehle, was konsistente Codegenerierung, Refactorings und Tests im gesamten Projekt sicherstellt.

Architektur und Funktionsweise von .vscode/cody.json

Cody unterscheidet zwischen benutzerbezogenen globalen Befehlen und Workspace-Befehlen auf Repository-Ebene. Durch das Ablegen der Datei cody.json im Verzeichnis .vscode/ an der Wurzel des Projekts werden die Befehle direkt an den Tech-Stack, die Abhängigkeiten und die Konventionen der Codebasis gebunden:

repository-root/
├── .vscode/
│   ├── cody.json          <-- Definition der Team-Befehle
│   └── settings.json
├── src/
├── tests/
└── package.json

Sobald diese Datei in Git eingecheckt ist, lädt die Cody-Erweiterung in VS Code die Konfiguration automatisch beim Öffnen des Arbeitsbereichs. Entwickler können die Befehle über die Befehlspalette (Option + C unter macOS oder Alt + C unter Windows/Linux) oder als Slash-Befehl (z. B. /unit-test) direkt im Cody-Chat aufrufen.

Das JSON-Schema im Überblick

Die Datei .vscode/cody.json strukturiert alle Befehle unter einem übergeordneten commands-Objekt:

{
  "commands": {
    "command-identifier": {
      "prompt": "Detaillierte Anweisungsvorlage für das LLM.",
      "description": "Kurze Beschreibung für das Cody-Befehlsmenü.",
      "mode": "ask",
      "context": {
        "codebase": false,
        "selection": true,
        "currentDir": false,
        "openTabs": false
      }
    }
  }
}

Die vier Kernattribute im Detail:

Ausführungsmodi: Gezielte Ausgabe im Editor

Die Eigenschaft mode definiert die Interaktion zwischen der Modellausgabe und der aktiven Arbeitsdatei:

1. ask (Interaktiver Dialog und Code-Review):

   • Schreibt die Antwort in das Cody-Chat-Seitenpanel.
   • Ideal für Sicherheitsüberprüfungen, Architekturanalysen, komplexe Algorithmus-Erklärungen oder PR-Zusammenfassungen, bei denen Entwickler das Ergebnis vor der Übernahme prüfen müssen.

2. edit (Direkte In-Place-Ersetzung):

   • Ersetzt die aktuell markierte Code-Auswahl direkt im aktiven Editorfenster.
   • Optimal für deterministische Refactorings: Schärfen von TypeScript-Typen, Beseitigen geschachtelter Ternär-Operatoren oder Umstellung auf unveränderliche Datenstrukturen.

3. insert (Gezielte Code-Einfügung):

   • Fügt den generierten Code direkt an der aktuellen Cursor-Position oder oberhalb der Auswahl ein.
   • Eignet sich hervorragend für standardisierte Dokumentationsblöcke (TSDoc/JSDoc) oder das Generieren eines neuen Testgerüsts in einer Datei.

Kontext-Scoping: Qualität vs. Latenz ausbalancieren

Fehlt einem KI-Modell der Kontext, drohen Halluzinationen; wird es mit zu vielen irrelevanten Dateien überflutet, steigen Token-Kosten und Antwortzeiten drastisch. Das context-Objekt in .vscode/cody.json ermöglicht eine präzise Steuerung:

• selection (boolean): Übergibt die aktuell im Editor markierten Zeilen. Bei fokussierten Refactorings oder Funktionsdokumentationen stellt true sicher, dass das Modell sich exakt auf den Zielcode konzentriert.
• codebase (boolean): Aktiviert die semantische Suche von Sourcegraph über das gesamte Repository. Dies erlaubt Cody, projektweite Test-Fixtures, Domänenmodelle und Hilfsfunktionen zu finden. Für rein lokale Transformationen sollte dies deaktiviert bleiben, um Abfragezeiten zu minimieren.
• currentDir (boolean): Bezieht Dateien im selben Verzeichnis wie die aktive Datei ein. Sehr nützlich in modularen Projektstrukturen, in denen Komponenten, Typdefinitionen und Mocks im selben Ordner liegen.
• openTabs (boolean): Liest den Inhalt anderer geöffneter Editor-Tabs ein. Hilfreich bei featureübergreifender Arbeit, birgt jedoch das Risiko, unnötige Hintergrundinformationen einzuschleusen.

Praxiserprobte Rezepte für Engineering-Teams

Hier ist eine produktionsreife Konfiguration für TypeScript- und React-Projekte mit vier standardisierten Befehlen:

{
  "commands": {
    "unit-test": {
      "description": "Erzeugt Vitest-Unit-Tests gemäß Teamstandards inklusive Mocks und Grenzwertabdeckung",
      "mode": "ask",
      "context": {
        "selection": true,
        "codebase": true,
        "currentDir": true,
        "openTabs": false
      },
      "prompt": "Du bist ein erfahrener Test-Automation-Engineer. Erstelle eine umfassende Test-Suite für den ausgewählten Code unter Verwendung von Vitest und @testing-library/react.\n\nVerbindliche Regeln:\n1. Strukturiere alle Tests strikt nach dem Arrange-Act-Assert (AAA)-Muster.\n2. Verwende bestehende Test-Fixtures und Mock-Konventionen aus der Codebasis wieder.\n3. Decke Standardfälle, Grenzwerte, Null-/Undefined-Werte und asynchrone Fehlerfälle (Rejections) ab.\n4. Importiere keine externen Mock-Bibliotheken; nutze vitest-interne Funktionen vi.fn() und vi.spyOn().\n5. Liefere vollständigen, ausführbaren Code ohne Platzhalter-Kommentare wie '// hier implementieren'."
    },
    "refactor-clean": {
      "description": "Refaktoriert den gewählten Code gemäß Clean-Code- und strikten TypeScript-Prinzipien",
      "mode": "edit",
      "context": {
        "selection": true,
        "codebase": false,
        "currentDir": false,
        "openTabs": false
      },
      "prompt": "Refaktoriere den ausgewählten Codeblock nach Clean-Code- und strikten TypeScript-Standards:\n1. Behalte bestehende API-Signaturen, Parameterverträge und das Laufzeitverhalten exakt bei.\n2. Ersetze unspezifische 'any'-Typen durch präzise Discriminated Unions oder Generics.\n3. Ersetze veränderbare Zustandskonstrukte durch reine Funktionen und unveränderliche Datenstrukturen.\n4. Löse tief verschachtelte Bedingungen durch klare Early-Return-Anweisungen (Guard Clauses) auf.\n5. Gib AUSSCHLIESSLICH den modifizierten Code ohne umgebendes Markdown oder Erläuterungen aus."
    },
    "security-audit": {
      "description": "Prüft die Auswahl auf OWASP Top 10 Sicherheitslücken und Datenabfluss",
      "mode": "ask",
      "context": {
        "selection": true,
        "codebase": true,
        "currentDir": false,
        "openTabs": false
      },
      "prompt": "Führe ein detailliertes Sicherheits-Code-Review für den ausgewählten Codeabschnitt durch.\n\nUntersuche folgende Risikofaktoren:\n1. Injection-Schwachstellen (SQL, NoSQL, OS-Befehle, Template-Injection, XSS).\n2. Autorisierungsfehler, fehlende Rollenprüfungen und Privilege Escalation.\n3. Unsichere direkte Objektreferenzen (IDOR) und unvalidierte Benutzereingaben.\n4. Offenlegung von Geheimnissen, API-Schlüsseln oder personenbezogenen Daten (PII) im Code oder Log.\n5. Unzureichende Fehlerbehandlung, die interne Stack-Traces nach außen lecken könnte.\n\nAusgabeformat: [Schweregrad: Hoch/Mittel/Niedrig] | [Schwachstelle] | [Zeile] | [Behebungsvorschlag und Diff]."
    },
    "doc-api": {
      "description": "Erzeugt normierte TSDoc/JSDoc-Dokumentation für Funktionen oder Schnittstellen",
      "mode": "insert",
      "context": {
        "selection": true,
        "codebase": false,
        "currentDir": false,
        "openTabs": false
      },
      "prompt": "Erstelle einen professionellen TSDoc-Dokumentationsblock für die ausgewählte Funktion oder Schnittstelle:\n1. Formuliere eine prägnante einzeilige Zusammenfassung, gefolgt von Details zum Funktionsverhalten.\n2. Dokumentiere alle @param-Tags mit exakten Typen und semantischer Erklärung.\n3. Dokumentiere @returns mit Rückgabetypen und Bedingungen.\n4. Dokumentiere @throws für alle möglichen Ausnahmen und Fehlerfälle.\n5. Füge ein praxisnahes @example-Codebeispiel hinzu.\n6. Formatiere die Ausgabe als sofort einsatzbereiten JSDoc/TSDoc-Block direkt oberhalb des Codes."
    }
  }
}

Best Practices für Team-Governance und Weiterentwicklung

Um den maximalen Nutzen aus .vscode/cody.json zu ziehen, sollten Entwicklungsteams klare Workflows etablieren:

1. Prompts wie Produktivcode verwalten (Prompts as Code)

Die Befehle in .vscode/cody.json sind Teil der gemeinsamen Codebasis. Änderungen an Prompts sollten denselben Pull-Request- und Review-Prozessen unterliegen wie regulärer Programmcode. Eine Validierung des JSON-Schemas in CI-Pipelines stellt sicher, dass Syntaxfehler die VS-Code-Erweiterung nicht beschädigen.

2. Disziplinierter Umgang mit dem Codebase-Kontext

Ein typischer Fehltritt besteht darin, "codebase": true pauschal für jeden Befehl zu aktivieren. Bei lokalen Refactorings verlängert eine repositoryweite Suche lediglich die Antwortzeit. Beschränken Sie diesen Schalter auf Befehle, die zwingend dateiübergreifende Abhängigkeiten auflösen müssen.

3. Sukzessiver Übergang zur Sourcegraph Prompt Library

Wenn eine Organisation Dutzende Microservices verwaltet, kann die Pflege separater .vscode/cody.json-Dateien zu Versionsdrift führen. Sourcegraph bietet mit der Prompt Library (ab Cody v1.30 und in Sourcegraph Enterprise) eine zentrale webbasierte Prompt-Verwaltung.

Teams können Vorlagen in .vscode/cody.json auf Repository-Ebene erproben und ausgereifte Prompts anschließend in die organisationsweite Prompt Library überführen. Dort profitieren Entwickler von Tag-Verwaltung, offiziell empfohlenen Prompts (Promoted Prompts) und dynamischen @-Erwähnungen (@selection, @file, @repo) über VS Code und JetBrains hinweg.

Referenzen

• Cody for VS Code v1.16: More powerful custom commands plus Claude 3 models as the new default
• Cody for VS Code v1.30: Introducing prompts and the Prompt Library
• Top 5 tips for using Cody with React
• Prompts - Sourcegraph docs