KI-Assistenten generieren Code, der plausibel aussieht, aber eure Konventionen nicht zuverlässig kennt. Sie haben kein Gedächtnis für Architektur-Entscheidungen über die Session hinaus, ignorieren lange Convention-Dokumente, sobald das Context-Window enger wird, und kennen eure Architektur-Grenzen nicht. Das führt dazu, dass der Domain-Layer problemlos den Web-Layer referenziert. CodeCharter erkennt genau solche Verstöße in dem Moment, in dem sie entstehen.
CodeCharter hängt sich an drei Stellen in den KI-Workflow ein und zwingt
die KI in eure Regeln: als CLI-Kommando in der Build-Fix-Loop, als
ausführbare .ccr-Regeldateien in eurem Repo und als MCP-Server, der
direkt im Coding-Tool registriert ist.
Die Build-Fix-Loop
Agentische KI-Tools haben heute einen eingebauten Zyklus aus Code-Generierung, Testlauf und Selbst-Korrektur. CodeCharter wird darin zum Konventions-Wächter:
AI generiert Code
-> codecharter analyze <YourSolution.sln> --fail-on error
-> Finding: "Controller calls EF directly. Use repository pattern."
-> AI liest @recommendation
-> AI fixt es selbst
-> grüner Build
Der @recommendation-Header in jeder Regel wird zum Fix-Prompt für die
KI. Eure Devs schreiben einmal "Inject TimeProvider via constructor",
und ab da fixt die KI das selbst, jedes Mal, solange ihr CodeCharter
einsetzt.
Eure DSL-Regeln als ausführbare Team-Spezifikation
Was bisher in der README oder im Tribal Knowledge stand, wird zur
ausführbaren Datei im Repo. Die KI sieht beim nächsten Compose-Schritt
nicht nur den existierenden Code, sondern auch die .ccr-Files, die
die Regeln formulieren. Das ist deutlich verlässlicher als ein langes
Convention-Dokument, das im Context-Window ausläuft.
Beispiel: Eure Team-Konvention "Wir nutzen IClock statt TimeProvider,
weil wir noch nicht auf .NET 8 sind" muss die KI sonst aus existierendem
Code ableiten. Mit CodeCharter schreibt ihr eine Regel:
@name "Use IClock instead of TimeProvider"
@severity error
@category "Team-Conventions"
@recommendation "Inject IClock via constructor and call _clock.UtcNow instead of TimeProvider.System.GetUtcNow()"
from m in Methods
where m.CalledMethods.Any(c => c.FullName.Contains("TimeProvider"))
select m
Die KI bekommt beim nächsten Versuch eine klare Anweisung in der Recommendation und kann den Fix in einem Schritt erzeugen.
Recommendation-Texte für KI-Loops schreiben
Eine @recommendation ist nicht nur ein Hinweis für eure Devs, sondern
auch der Fix-Prompt für die KI. Drei Faustregeln für gute Recommendations.
Konkret statt vage
@recommendation "Fix this"
Das hilft weder Mensch noch KI. Besser:
@recommendation "Add 'CancellationToken cancellationToken = default' as the last parameter"
Code-Snippets sind willkommen
@recommendation "Inject TimeProvider via constructor and call _time.GetUtcNow() instead of DateTime.UtcNow"
Die KI baut die Recommendation als wörtlichen Hinweis in den Fix ein und generiert exakt das, was ihr beschrieben habt.
Hinweise auf etablierte Pattern
@recommendation "Move EF access into a repository class under Acme.Infrastructure.Repositories and inject it via the constructor"
Konkrete Namespace-Vorgaben helfen der KI, den Code an der richtigen Stelle abzulegen.
Setup für die gängigen Tools
codecharter mcp install registriert den CodeCharter-MCP-Server für
Claude Code, Claude Desktop, Cursor, Windsurf und
Gemini CLI (.gemini/settings.json). Der Default-Scope ist project;
Claude Desktop und Windsurf haben nur eine User-Konfiguration,
für diese beiden müsst ihr also --scope user mitgeben. Beachtet,
dass der MCP-Server eine gültige Lizenz voraussetzt: ohne Lizenz beendet
sich codecharter mcp mit einem Lizenzfehler, bevor der Server startet.
Für GitHub Copilot und Aider muss der MCP-Server manuell
konfiguriert werden, siehe jeweils die Tool-Dokumentation zur
MCP-Server-Einrichtung; verweist dabei auf codecharter mcp.
Cursor
Aktuelles Cursor (1.0+) nutzt Rule-Dateien unter .cursor/rules/. Legt
eine Datei wie .cursor/rules/codecharter.md an:
After every change, run: codecharter analyze <YourSolution.sln> --fail-on error
Fix any findings before considering the change complete. Read the
@recommendation field of each finding for guidance.
Ersetzt <YourSolution.sln> durch den Pfad zur Solution, z.B. src/Acme.sln.
Claude Code
In CLAUDE.md:
## Lint-Loop
After making changes, always run `codecharter analyze <YourSolution.sln> --fail-on error`
and fix any errors before reporting completion. The @recommendation field
of each finding tells you how to fix it.
Windsurf
codecharter mcp install --client windsurf --scope user registriert den
MCP-Server (Windsurf unterstützt nur den User-Scope). Die Registrierung
macht die MCP-Tools (scaffold_rule, save_rule, analyze_diff) für
Windsurf verfügbar. Für die Build-Fix-Loop weist ihr Windsurf zusätzlich
an, etwa per Rule-Datei oder Prompt, nach jeder Änderung analyze_diff
auszuführen und die Findings zu beheben.
GitHub Copilot mit Agent-Mode
Für GitHub Copilot tragt ihr den MCP-Server manuell in dessen MCP-Konfiguration ein. Nach der Einrichtung fügt ihr dem Agent-System-Prompt hinzu:
Run `codecharter analyze <YourSolution.sln> --fail-on error` after each
change. Findings under 'error' severity block completion. Read the
@recommendation field for fix guidance.
Aider
Bindet CodeCharter über Aiders --lint-cmd-Flag ein:
aider --lint-cmd "codecharter analyze <YourSolution.sln> --fail-on error"
Aider gibt den Lint-Output als Feedback an die KI für den nächsten Schritt zurück.
Performance in KI-Loops
Eine Analyse mit CodeCharter dauert je nach Solution-Größe wenige Sekunden bis eine Minute. In einer KI-Loop, in der die KI ohnehin nach jeder Code-Änderung den Build laufen lässt, fällt das nicht ins Gewicht.
Für noch schnellere Loops analysiert ihr nur die geänderten Zeilen:
codecharter analyze <YourSolution.sln> --git-ref main..HEAD --fail-on error
beschränkt die Findings auf Zeilen, die seit main geändert wurden
(alternativ nimmt --diff eine Unified-Diff-Datei entgegen). Über MCP
erfüllen die Tools analyze_diff, analyze_file und analyze_solution
denselben Zweck direkt im Coding-Tool; nach dem ersten Aufruf antworten
sie aus einem warmen Workspace-Cache, was wiederholte Checks in einer
Loop deutlich beschleunigt.
Orientierung vor der Änderung, nicht nur Prüfung danach
Alles oben Beschriebene fängt einen Verstoß erst ab, nachdem die KI den Code
bereits geschrieben hat. Die MCP-Tools graph_overview, graph_neighborhood
und graph_impact lassen einen Agenten sich vorher orientieren: womit ist
dieser Typ verbunden, und was wäre von einer Änderung an ihm sonst noch
betroffen. Ein Agent, der vor einer Änderung graph_impact auf den
betroffenen Typ ausführt, erkennt einen breiten Auswirkungsradius, bevor er
auch nur eine Zeile schreibt, statt ihn erst drei Fix-Loop-Durchläufe später
zu entdecken. Das vollständige Bild samt CLI-Gegenstück steht unter
codecharter graph.
Eine Änderung an ihrer Existenzgrundlage verankern
Orientierung ist nicht nur strukturell. Wer Requirements als .req.md-Dateien
pflegt (siehe Requirements), kann sie über
die MCP-Tools req_context, req_search und req_justify lesen lassen, ohne
die Dateien je direkt anzufassen: req_context liefert vor einer Änderung
alles Relevante zu einem Symbol oder einer Datei, req_search findet ein
Requirement nach Id oder Freitext, und req_justify beantwortet "warum
existiert das", indem es von einem Symbol zu den verankernden
Requirement-Wurzeln zurückläuft. Alle drei sind rein lesend – ein Agent kann
eine Änderung verankern oder ungerechtfertigten Code markieren, aber das
Annehmen eines Requirements bleibt ein menschlicher Akt auf der Kommandozeile.
Der vollständige Vertrag steht unter
Requirements über MCP.
Weiterführend
- Hello-World-DSL: die erste eigene Regel schreiben
- Best Practices: was gute von schlechten Regeln unterscheidet
- Quick Start: erste Analyse in fünf Minuten