wastech-mdlint
Детерминированный линтинг Markdown, который читают ваши агенты.
wastech-mdlint – это CLI и библиотека на TypeScript, которые проверяют Markdown-контекст в вашем репозитории, от AGENTS.md и CLAUDE.md до дерева документации. Каждая проверка выполняется локально, без сетевых запросов и без модели в цикле, поэтому одни и те же файлы всегда дают один и тот же результат.
Почему он здесь
Хорошая работа агентов отчасти зависит от порядка в файлах, которые они читают, и этот инструмент я написал как раз для этого. Он работает и локально, и в CI, и я использую его в своих продуктах, среди них Wastime и этот сайт. Рабочую конфигурацию можно открыть в публичном репозитории wastech-orchestrator.
Проблема
Файлы, которые читают ваши агенты, меняются вместе с кодом, и если их ничто не проверяет, ссылки перестают работать после переноса файла, а контекстные файлы разрастаются сверх того объёма, который модель хорошо читает. Ни один тест при этом не падает, поэтому первым признаком может стать то, что агент работает хуже, и это легко списать на модель.
Решение
wastech-mdlint относится к Markdown для агентов как к исходному коду. В нём 22 встроенных правила, от целей ссылок до обязательных колонок таблиц, и правила бюджета, которые ограничивают размер контекста. Собственные правила описываются конфигурацией из закрытого набора проверок, поэтому в вашем CI не выполняется произвольный код.
- Когда конфигурация включает правила, битые внутренние ссылки и разъехавшиеся таблицы роняют проверку в CI или при локальном запуске.
- Бюджет токенов на контекст становится ограничением, которое может проверить CI.
- Собственные правила – это просто данные, поэтому их запуск в чужом CI не выполняет никакого кода.
Ключевые возможности
- 22 встроенных правилаКатегории для таблиц, разделов и структуры, ссылок, качества содержимого и целостности графа.
- Гигиена контекста для LLMБюджеты в байтах, строках и токенах, а также бюджет eager-импортов для контекстных файлов.
- Декларативные собственные правилаЗакрытый словарь проверок, из которых правила собираются в конфигурации, без пересборки и без выполнения кода в вашем CI.
Примеры запуска
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.mdДля кого
- Команды, которые поддерживают большой объём документации и контекста для агентов.
- Все, кто хранит CLAUDE.md / AGENTS.md / SKILL.md в репозитории.
Стек
- Язык
- TypeScript
- Среда выполнения
- Node.js 24 LTS
- Структура
- Монорепозиторий на npm workspaces
- TypeScript project references
- Интеграция с ИИ
- Model Context Protocol (stdio)
Установка
npm install --save-dev @wastech-mdlint/clinpx wastech-mdlint initnpx wastech-mdlint lint .Ограничения
- Внешние HTTP-ссылки не проверяются, благодаря этому каждый запуск остаётся локальным и детерминированным.
- Собственные правила задаются только данными, без конфигураций на TypeScript или JavaScript и без плагинов с пользовательским кодом.
- Граф контекста строится заново при каждом запуске, инкрементального кэша пока нет.