はじめに
たとえば、こういうことが起きていませんか？
- 別ファイルへのリンクを張っていたが、リンク先のファイル名がいつのまにかリネームされていた。リンクは壊れているが、ビルドも markdownlint も通る
- 同じテンプレートで書いているはずの設計ドキュメントで、いつの間にか必須セクションが 1 つ欠けていた。レビューでも見落とされた
- AI に新しいドキュメントを生成させたら、既存ファイルへの参照がいくつか壊れていた。生成時に人間は気づかない
これらは 構文としては正しい Markdown です。markdownlint も通る、ビルドも通る、CI も green。それでも ドキュメントとしての整合性は崩れている — これが contextlint が解決しようとする問題です。
contextlint は、構造化された Markdown ドキュメントの 意味的な整合性 を検証するルールベースのリンターです。リンク切れ、必須セクションの欠落、テーブルの空セル、ID の重複、ドキュメント間の依存関係の崩れといった問題を、決定論的に、数秒で検出します。
想定する利用者
Section titled “想定する利用者”contextlint は、Markdown 中心のワークフローを採用しているチーム・個人に向いています。たとえば次のようなケースです。
- 仕様駆動開発（SDD） — 要件・仕様・設計を Markdown で書き、それを基に AI がコードを生成するアプローチ
- ADR（Architecture Decision Records） — 設計判断を Markdown で残しているチーム
- ドキュメント駆動開発 — 設計を先に文章化してから実装に入るスタイル
- 大規模リポジトリのドキュメント整備 — 数十〜数百の Markdown ファイルが互いに参照し合う規模
contextlint と markdownlint の関係
Section titled “contextlint と markdownlint の関係”contextlint は コンテンツの意味とファイル間の整合性 に特化しています。Markdown の構文・フォーマット・スタイル（見出しレベルの一貫性、リスト記法、テーブル構文など）は対象外です。これらは markdownlint の領域なので、両者を併用することを推奨します。
| 観点 | markdownlint | contextlint |
|---|---|---|
| Markdown の構文 | ✓ | — |
| フォーマット・スタイル | ✓ | — |
| テーブル内のデータ整合性 | — | ✓ |
| 必須セクションの存在 | — | ✓ |
| ファイル間の参照整合性 | — | ✓ |
| 依存グラフの検証 | — | ✓ |
なぜ静的解析なのか
Section titled “なぜ静的解析なのか”ドキュメントの整合性を LLM にチェックさせる選択肢もありますが、contextlint は 静的解析 にこだわっています。理由はいくつかあります。
- 再現性 — 同じ入力なら同じ結果。プロンプトや temperature に左右されません。CI で安定して動かせます。
- コスト — トークンを消費しません。100 ファイルを検証してもコストはゼロです。
- 速度 — サブ秒で完了します。エディタ統合（LSP）で「入力中にリアルタイム検出」が成り立つ速さです。
- 明確さ — エラーメッセージが固定なので、機械処理（自動修正、CI でのフィルタリング）に向いています。
LLM はドキュメントを 書く 役割で力を発揮し、できあがったドキュメントを 検証する のは静的解析が向いています。それぞれの得意な領域を分担させるのが contextlint の設計思想です。
三層のフィードバック
Section titled “三層のフィードバック”contextlint は、ドキュメントのライフサイクルの 3 つのタイミング に組み込めます。
| タイミング | プロトコル | 主なツール |
|---|---|---|
| 書いている間 | LSP | VS Code / Cursor / Neovim / Helix / JetBrains |
| AI が書いている間 | MCP | Claude Code / Cursor Agent / Cline / Codex / Windsurf |
| マージ前 | CLI | GitHub Actions / pre-commit / Husky / lint-staged |
書く瞬間からマージまで、ドキュメントの整合性を継続的に保てます。