wastech-mdlint
Deterministisches Linting für das Markdown, das Ihre Agenten lesen.
wastech-mdlint ist eine CLI und Bibliothek in TypeScript, die den Markdown-Kontext in Ihrem Repository prüft, von AGENTS.md und CLAUDE.md bis zum Dokumentationsbaum. Jede Prüfung läuft lokal, ohne Netzwerkzugriffe und ohne ein Modell dazwischen, sodass dieselben Dateien immer dasselbe Ergebnis liefern.
Warum es hier ist
Gute Arbeit von Agenten hängt auch davon ab, dass die Dateien, die sie lesen, in Ordnung sind, und dafür habe ich dieses Tool geschrieben. Es läuft lokal und in der CI, und ich nutze es in meinen eigenen Produkten, darunter Wastime und diese Website. Eine funktionierende Konfiguration liegt im öffentlichen Repository von wastech-orchestrator.
Problem
Die Dateien, die Ihre Agenten lesen, ändern sich mit dem Code, und wenn nichts sie prüft, laufen Links ins Leere, sobald eine Datei verschoben wird, und Kontextdateien wachsen über die Größe hinaus, die ein Modell gut liest. Dabei schlägt kein Test fehl, also ist das erste Anzeichen vielleicht ein Agent, der schlechter arbeitet, und das schiebt man leicht auf das Modell.
Lösung
wastech-mdlint behandelt Markdown für Agenten wie Quellcode. Es bringt 22 eingebaute Regeln mit, von Link-Zielen bis zu Pflichtspalten in Tabellen, dazu Budgetregeln, die der Kontextgröße eine Obergrenze setzen. Eigene Regeln werden als Konfiguration aus einem geschlossenen Satz von Prüfungen geschrieben, sodass in Ihrer CI kein beliebiger Code läuft.
- Sobald eine Konfiguration die Regeln einschaltet, lassen defekte interne Links und verrutschte Tabellen eine Prüfung in der CI oder bei einem lokalen Lauf fehlschlagen.
- Ein Token-Budget für den Kontext wird zu einer Grenze, die die CI prüfen kann.
- Eigene Regeln sind reine Daten, sodass ihr Lauf in der CI eines anderen keinen Code ausführt.
Wichtige Funktionen
- 22 eingebaute RegelnKategorien für Tabellen, Abschnitte und Struktur, Verweise, Qualität der Inhalte und die Integrität des Graphen.
- Kontext-Hygiene für LLMsBudgets für Bytes, Zeilen und Tokens, dazu ein Budget für Eager-Importe in Kontextdateien.
- Deklarative eigene RegelnEin geschlossenes Vokabular von Prüfungen, in der Konfiguration zusammengesetzt, ohne Neubau und ohne Ausführung von Code in Ihrer CI.
Beispielläufe
wastech-mdlint lint .broken.md 3:11 error Link target "missing.md" does not resolve to a file. REF-001✖ 1 problem (1 error, 0 warnings)wastech-mdlint graph .nodes: 8edges: 7cycles: 1entry points (3): design.md index.md orphan.mdtop hubs: (none: no document has 3 or more incoming references)cycles: cycle-a.md -> cycle-b.md -> cycle-a.mdclusters: cluster 1 (5 files): design.md glossary.md guide.md index.md requirements.md cluster 2 (2 files): cycle-a.md cycle-b.md cluster 3 (1 files): orphan.mdreading order (6): design.md index.md glossary.md guide.md orphan.md requirements.mdall 2 documents below sit in a cycle.excluded from reading order (2): cycle-a.md cycle-b.mdcoverage: nodes: 8 edges: 7 files outside corpus (1): appendix.mdFür wen
- Teams, die viel Dokumentation und Kontext für Agenten pflegen.
- Alle, die CLAUDE.md / AGENTS.md / SKILL.md in einem Repository haben.
Stack
- Sprache
- TypeScript
- Laufzeit
- Node.js 24 LTS
- Struktur
- Monorepo mit npm workspaces
- TypeScript project references
- KI-Integration
- Model Context Protocol (stdio)
Installation
npm install --save-dev @wastech-mdlint/clinpx wastech-mdlint initnpx wastech-mdlint lint .Grenzen
- Externe HTTP-Links werden nicht geprüft, so bleibt jeder Lauf lokal und deterministisch.
- Eigene Regeln sind nur Daten, ohne Konfigurationen in TypeScript oder JavaScript und ohne Plugins mit eigenem Code.
- Der Kontextgraph wird bei jedem Lauf neu aufgebaut, einen inkrementellen Cache gibt es noch nicht.