Erweiterbarkeit und Anpassung

Was Sie lernen werden

Wie Sie Verdent for VS Code mit drei leistungsstarken Erweiterbarkeitsmethoden anpassen und erweitern: benutzerdefinierte Subagenten, Regelsysteme und MCP-Integration.

Überblick über die Erweiterbarkeit

Verdent for VS Code bietet drei primäre Methoden, um die Fähigkeiten zu erweitern und das Verhalten anzupassen:

1. Benutzerdefinierte Subagenten – Erstellen Sie spezialisierte KI-Agenten für domänenspezifische Aufgaben
2. Regelsystem – Steuern Sie das Verhalten über VERDENT.md, AGENTS.md und plan_rules.md
3. MCP-Integration – Verbinden Sie externe Werkzeuge und Dienste über das Model Context Protocol

Jede Methode dient unterschiedlichen Anpassungsbedürfnissen und kann für eine umfassende Workflow-Optimierung kombiniert werden.

Methode 1: Benutzerdefinierte Subagenten

Überblick

Benutzerdefinierte Subagenten sind spezialisierte KI-Agenten mit eigenen System-Prompts, Aufrufrichtlinien und aufgabenspezifischem Fachwissen. Sie erweitern die integrierten Subagenten von Verdent (@Verifier, @Explorer, @Code-reviewer) um projektspezifische Fähigkeiten.

Speicherort: ~/.verdent/subagents/

Erstellen benutzerdefinierter Subagenten

Dateistruktur:

---
name: subagent-name
description: One-line purpose description
---
# System Prompt

[Behavior definition, personality, task interpretation approach]

Invocation policy (strict|flexible): Policy description

When to use:
- Scenario 1
- Scenario 2

When NOT to use:
- Avoid scenario 1
- Avoid scenario 2

Erstellungsmethoden:

Methode 1: Einstellungsmenü

1. Einstellungen → Subagenten
2. „Neuen Subagenten erstellen“
3. Name, Beschreibung und System-Prompt definieren
4. Aufrufrichtlinie konfigurieren
5. In ~/.verdent/subagents/ speichern

Methode 2: Direkte Dateierstellung

1. Navigieren Sie zu ~/.verdent/subagents/
2. Markdown-Datei erstellen (z. B. security-reviewer.md)
3. YAML-Frontmatter hinzufügen
4. System-Prompt und Nutzungsrichtlinien schreiben

Anwendungsfälle für benutzerdefinierte Subagenten

Domänenspezifisches Fachwissen:

• Finanzberechnungen: Steuerkonformität, Finanzvorschriften
• HIPAA-Konformität im Gesundheitswesen: Standards für den Umgang mit Patientendaten
• Kryptografie: Best Practices für die Sicherheitsimplementierung

Teamspezifische Workflows:

• Durchsetzung des Code-Stils: Team-Coding-Standards, die über Linter-Regeln hinausgehen
• Konsistenz der Dokumentation: Sicherstellen, dass Dokumentation den Team-Vorlagen folgt
• Abhängigkeitsprüfer: Überwachung von Drittanbieter-Paketen anhand genehmigter Listen

Spezialisten für den Technologie-Stack:

• React-Performance-Optimierer: Erkennen unnötiger Re-Renders
• SQL-Abfrageoptimierer: Analyse und Verbesserung der Datenbankleistung
• Docker-Konfigurationsprüfer: Validierung von Containerisierungspraktiken

Qualitätssicherung:

• Testabdeckungsanalysen: Identifizierung ungetesteter Codepfade
• Fehlerbehandlungsprüfer: Sicherstellen einer umfassenden Ausnahmebehandlung
• Durchsetzung von Logging-Standards: Überprüfung der Logging-Praktiken

Beispiel: API-Dokumentationsgenerator

---
name: api-documenter
description: Generates comprehensive API documentation from code
---
# System Prompt

You are an API documentation specialist.

Documentation approach:
- Extract endpoints, parameters, and responses from code
- Generate OpenAPI/Swagger specifications
- Include usage examples and error codes
- Document authentication requirements

Output format:
- Markdown tables for endpoints
- Code examples in multiple languages
- Authentication flow diagrams

Invocation policy (strict): Only run when explicitly requested.

When to use:
- User requests API documentation generation
- Need to document REST/GraphQL endpoints
- Creating developer guides

When NOT to use:
- Inline code comments
- User-facing documentation

Verwendung:

@api-documenter document the /api/users endpoints

Beispiel: Prüfer für Datenbankmigrationen

---
name: migration-reviewer
description: Reviews database migrations for safety and correctness
---
# System Prompt

You are a database migration safety specialist.

Review checklist:
- Check for destructive operations (DROP, DELETE without WHERE)
- Verify reversible migrations (up/down compatibility)
- Identify potential data loss scenarios
- Validate index creation strategies
- Check for blocking operations on large tables

Risk assessment:
- Categorize migrations: low/medium/high risk
- Recommend staging environment testing for high-risk changes
- Suggest rollback procedures

Invocation policy (strict): Only run when explicitly requested.

When to use:
- User creates or modifies migration files
- Pre-deployment migration review
- Investigating migration failures

When NOT to use:
- Schema design from scratch
- Query optimization

Aufrufrichtlinien

Strikte Richtlinie:

• Der Subagent wird nur ausgeführt, wenn er über eine @-Erwähnung explizit angefordert wird
• Die Nutzerin oder der Nutzer behält die volle Kontrolle über den Aufruf
• Am besten geeignet für spezialisierte, gelegentlich genutzte Subagenten

Flexible Richtlinie:

• Ermöglicht den automatischen Aufruf basierend auf der Erkennung von Aufgabenmustern
• Der Hauptagent leitet passende Aufgaben automatisch weiter
• Am besten geeignet für häufig genutzte, klar definierte Subagenten

Methode 2: Regelsystem

Überblick

Regeldateien sind Markdown-Dokumente, die das Verhalten, die Ausgabeformatierung und die Entscheidungsfindung von Verdent ohne Codeänderungen steuern. Drei Regeltypen bieten umfassende Anpassungsmöglichkeiten:

Regelpriorität

Bei Konflikten gilt:

1. AGENTS.md (höchste) – Projektregeln überschreiben Nutzerpräferenzen
2. VERDENT.md (mittel) – Wird angewendet, wenn kein Projektkonflikt besteht
3. Standardverhalten (niedrigste) – Die integrierten Standardeinstellungen von Verdent

Beispiel für einen Konflikt:

VERDENT.md: "Use 2-space indentation"
AGENTS.md: "Use 4-space indentation for this project"
→ Result: 4-space indentation (project rules win)

VERDENT.md (globale Präferenzen)

Zweck: Persönlicher Coding-Stil und Präferenzen über alle Projekte hinweg

Beispiel:

# User Rules

## TypeScript Preferences
- Use strict mode in tsconfig.json
- Prefer interfaces over type aliases
- Include return types on all functions

## Code Organization
- One component per file
- Named exports instead of default exports
- Organize imports: external, internal, types

## Documentation
- TSDoc comments for public APIs
- Include @param and @returns tags

## Communication
- Provide explanations before showing code
- Highlight breaking changes explicitly

Zugriff: Einstellungen → Regeln → Benutzerregeln

AGENTS.md (Projektregeln)

Zweck: Teamweite Coding-Standards und projektspezifische Konventionen

Beispiel:

# AGENTS.md

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to navigate
- Run `pnpm install --filter <project_name>` for dependencies
- Check package.json name field for correct package name

## Testing instructions
- Run `pnpm turbo run test --filter <project_name>`
- From package root: `pnpm test`
- Focus on one test: `pnpm vitest run -t "<test name>"`
- Fix all errors before merge

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

Zugriff: Stammverzeichnis des Projekts (versionskontrolliert)

plan_rules.md (Plan-Anpassung)

Zweck: Steuerung von Ausgabeformat und Detailgrad von Plan Mode

Beispiel:

# Plan Rules

## Plan Structure
- Start with brief summary (2-3 sentences)
- Include estimated time for each major step
- List prerequisites before implementation steps
- Identify potential risks

## Level of Detail
- Break tasks into subtasks of 15-30 minutes
- Include specific file paths for modifications
- List functions/components to create/modify

## Format
- Use numbered lists for sequential steps
- Use bullet points for options
- Include code snippets for complex changes

Zugriff: Einstellungen → Regeln → Plan-Regeln

Best Practices zum Verfassen von Regeln

Seien Sie spezifisch und direktiv:

✓ Good: "Always use async/await for asynchronous operations"
✗ Vague: "Try to use modern JavaScript"

Logisch organisieren:

• Gruppieren Sie zusammengehörige Regeln unter Abschnittsüberschriften
• Trennen Sie Themenbereiche (Stil, Tests, Dokumentation, Sicherheit)
• Verwenden Sie eine einheitliche Struktur über alle Dateien hinweg

Kritische Regeln priorisieren:

• Platzieren Sie wichtige Regeln zuerst in jedem Abschnitt
• Verwenden Sie Betonung für nicht verhandelbare Standards: **NEVER** commit credentials
• Konzentrieren Sie sich auf Fehlervermeidung und Sicherheit

Wirksamkeit testen:

• Starten Sie eine neue Unterhaltung, um die Anwendung der Regel zu überprüfen
• Verfeinern Sie Regeln basierend auf dem tatsächlichen Agentenverhalten
• Aktualisieren Sie die Regeln, wenn sich das Projekt weiterentwickelt

Methode 3: MCP-Integration

Überblick

Das Model Context Protocol (MCP) erweitert Verdent, indem es externe Werkzeuge, Datenquellen und Dienste verbindet. MCP-Server fungieren als Brücke zwischen Verdent und externen Systemen.

Konfiguration: ~/.verdent/mcp.json über Einstellungen → MCP-Server

Fähigkeiten von MCP

Zugriff auf externe Systeme:

• Werkzeuge für Datenbankabfragen (PostgreSQL, MySQL, MongoDB)
• Cloud-Dienst-APIs (AWS, Azure, GCP)
• Projektmanagement (Jira, Linear, Asana)
• CI/CD-Pipelines (Jenkins, GitHub Actions)
• Monitoring-Dienste (Datadog, New Relic)

Entwicklung benutzerdefinierter Werkzeuge: Erstellen Sie MCP-Server für proprietäre Systeme:

• Interne API-Integrationen
• Brücken zu Legacy-Systemen
• Spezialisierte Datenquellen
• Werkzeuge zur Workflow-Automatisierung

MCP im Vergleich zu benutzerdefinierten Subagenten und Regeln

Beispiel: Kombination aller drei Methoden

Szenario: Full-Stack-Entwicklungsteam mit strengen Compliance-Anforderungen

Benutzerdefinierter Subagent:

---
name: compliance-auditor
description: Audits code for regulatory compliance (SOC2, HIPAA)
---
[System prompt for compliance checking]

AGENTS.md (Projektregeln):

## Security Standards
- All API endpoints must validate inputs
- Never log PII or credentials
- Encrypt sensitive data at rest and in transit

## Compliance
- Run @compliance-auditor before all PRs
- Document data retention policies in code comments
- Include audit trails for data access

MCP-Integration:

• Compliance-Datenbank-MCP-Server: Überprüft Vorgänge anhand der Compliance-Regeln
• Audit-Log-MCP-Server: Zeichnet jeden Zugriff auf sensible Daten auf

Workflow:

User: "Create endpoint for user profile updates"
Verdent: [Applies AGENTS.md rules]
         [Generates secure endpoint with validation]
         [Automatically invokes @compliance-auditor]
         [Uses MCP to log operation in audit system]
         Result: Compliant, secure, audited endpoint

Best Practices für Erweiterbarkeit

Einfach starten, schrittweise ausbauen

Schrittweise Einführung:

1. Phase 1: Beginnen Sie mit einfachen Regeln (VERDENT.md oder AGENTS.md)
2. Phase 2: Fügen Sie benutzerdefinierte Subagenten für wiederkehrende Spezialaufgaben hinzu
3. Phase 3: Integrieren Sie MCP für Verbindungen zu externen Systemen

Methoden strategisch kombinieren

Beispiele für Synergien:

Regeln + Subagenten:

• AGENTS.md legt fest, wann benutzerdefinierte Subagenten aufgerufen werden
• Regeln stellen sicher, dass Empfehlungen der Subagenten befolgt werden

Regeln + MCP:

• AGENTS.md definiert, welche MCP-Server für die Nutzung freigegeben sind
• Regeln legen fest, wann der Zugriff auf externe Daten erforderlich ist

Subagenten + MCP:

• Ein benutzerdefinierter Subagent nutzt MCP-Werkzeuge für den Zugriff auf externe Systeme
• Der Subagent interpretiert die Ergebnisse von MCP mit spezialisiertem Fachwissen

Anpassungen dokumentieren

Teamdokumentation: Für benutzerdefinierte Subagenten und Projektregeln (AGENTS.md):

• Dokumentieren Sie die Begründung für nicht offensichtliche Regeln oder Subagenten
• Stellen Sie Beispiele für die korrekte Anwendung bereit
• Fügen Sie Anleitungen zur Fehlerbehebung hinzu
• Versionskontrolle zusammen mit dem Code

Persönliche Dokumentation: Für VERDENT.md und persönliche Subagenten:

• Kommentieren Sie komplexe Regeln mit der jeweiligen Begründung
• Halten Sie die Regeln organisiert und aktuell
• Entfernen Sie veraltete Regeln umgehend

Gründlich testen

Validierungsprozess:

1. Anpassung erstellen (Subagent/Regel/MCP-Konfiguration)
2. Neue Unterhaltung zum Testen starten
3. Überprüfen, ob das Verhalten den Erwartungen entspricht
4. Basierend auf den Ergebnissen verfeinern
5. Erfolgreiche Muster dokumentieren

Häufige Testszenarien:

• Wird der Subagent wie erwartet automatisch aufgerufen?
• Überschreiben Projektregeln die Benutzerregeln korrekt?
• Verbindet sich der MCP-Server und führt Vorgänge aus?
• Interagieren die kombinierten Methoden ohne Konflikte?

Fehlerbehebung bei der Erweiterbarkeit

Probleme mit benutzerdefinierten Subagenten

Der Subagent wird nicht aufgerufen:

• Überprüfen Sie die Aufrufrichtlinie (bei „strikt“ ist eine explizite @-Erwähnung erforderlich)
• Stellen Sie sicher, dass die Richtlinien unter „Wann verwenden“ zu Ihrer Anfrage passen
• Stellen Sie sicher, dass sich die Datei im Verzeichnis ~/.verdent/subagents/ befindet
• Überprüfen Sie die YAML-Frontmatter-Syntax

Unerwartetes Verhalten des Subagenten:

• Überprüfen Sie den System-Prompt auf Klarheit
• Verfeinern Sie die Richtlinien unter „Wann verwenden“ und „Wann nicht verwenden“
• Testen Sie mit einer expliziten @-Erwähnung, um das Verhalten zu isolieren
• Passen Sie den System-Prompt basierend auf den Ergebnissen iterativ an

Regelkonflikte

Die Regel wird nicht angewendet:

• Überprüfen Sie die Regelpriorität (AGENTS.md > VERDENT.md)
• Stellen Sie sicher, dass sich die Datei am richtigen Ort befindet
• Starten Sie eine neue Unterhaltung, um die frische Anwendung zu testen
• Formulieren Sie die Regeln spezifischer und direktiver

Unerwartetes Verhalten:

• Achten Sie auf widersprüchliche Regeln in derselben Datei
• Prüfen Sie, ob die Regeln zu vage formuliert sind
• Stellen Sie sicher, dass die richtige Regeldatei bearbeitet wird
• Verwenden Sie eindeutige Formulierungen („Immer“, „Niemals“, „Bevorzugen Sie“)

Probleme mit der MCP-Integration

Verbindungsfehler:

• Überprüfen Sie die Syntax von mcp.json
• Überprüfen Sie die Authentifizierungsdaten
• Stellen Sie sicher, dass der MCP-Server läuft und erreichbar ist
• Validieren Sie die Netzwerkverbindung

Probleme beim Werkzeugaufruf:

• Bestätigen Sie, dass der MCP-Server die erwarteten Werkzeuge bereitstellt
• Überprüfen Sie die Formate der Werkzeugparameter
• Prüfen Sie die Protokolle des MCP-Servers auf Fehler
• Testen Sie den MCP-Server eigenständig

Siehe auch