wastech-mdlint
Linting determinístico do Markdown que seus agentes leem.
O wastech-mdlint é uma CLI e uma biblioteca em TypeScript que verificam o contexto em Markdown do seu repositório, do AGENTS.md e do CLAUDE.md até a árvore de documentação. Cada verificação roda localmente, sem chamadas de rede e sem nenhum modelo no meio, então os mesmos arquivos sempre dão o mesmo resultado.
Por que está aqui
Parte de conseguir um bom trabalho dos agentes é manter em ordem os arquivos que eles leem, e escrevi esta ferramenta para isso. Ela roda localmente e no CI, e eu a uso nos meus próprios produtos, entre eles o Wastime e este site. Uma configuração em uso está no repositório público do wastech-orchestrator.
Problema
Os arquivos que seus agentes leem mudam junto com o código e, se nada os verifica, os links deixam de funcionar quando um arquivo muda de lugar e os arquivos de contexto passam do tamanho que um modelo lê bem. Nenhum teste falha quando isso acontece, então o primeiro sinal pode ser um agente trabalhando pior, e é fácil atribuir isso ao modelo.
Solução
O wastech-mdlint trata o Markdown voltado para agentes como código-fonte. Ele traz 22 regras embutidas, dos destinos dos links até as colunas obrigatórias das tabelas, além de regras de orçamento que colocam um teto no tamanho do contexto. As regras próprias são escritas como configuração a partir de um conjunto fechado de asserções, então nada arbitrário roda no seu CI.
- Depois que uma configuração ativa as regras, links internos quebrados e tabelas desatualizadas fazem uma verificação falhar no CI ou numa execução local.
- Um orçamento de tokens para o contexto vira um limite que o CI consegue verificar.
- As regras próprias são apenas dados, então rodá-las no CI de outra pessoa não executa nenhum código.
Principais funcionalidades
- 22 regras embutidasCategorias para tabelas, seções e estrutura, referências, qualidade do conteúdo e integridade do grafo.
- Higiene do contexto para LLMOrçamentos em bytes, linhas e tokens, além de um orçamento de imports eager para os arquivos de contexto.
- Regras próprias declarativasUm vocabulário fechado de asserções combinadas na configuração — sem recompilar e sem executar código no seu CI.
Exemplos de execução
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.mdPara quem é
- Equipes que mantêm um grande volume de documentação e de contexto para agentes.
- Qualquer pessoa que mantenha CLAUDE.md / AGENTS.md / SKILL.md em um repositório.
Stack
- Linguagem
- TypeScript
- Runtime
- Node.js 24 LTS
- Estrutura
- Monorepo com npm workspaces
- TypeScript project references
- Integração com IA
- Model Context Protocol (stdio)
Instalação
npm install --save-dev @wastech-mdlint/clinpx wastech-mdlint initnpx wastech-mdlint lint .Limitações
- Links HTTP externos não são verificados, o que mantém cada execução local e determinística.
- As regras próprias são apenas dados, sem configurações em TypeScript ou JavaScript e sem plugins com código do usuário.
- O grafo de contexto é reconstruído a cada execução, ainda sem cache incremental.