なぜ contextlint が存在するか
contextlint は、特定のワークフローや方法論に紐づくものではなく、Markdown でドキュメントを管理する全てのプロジェクト が共通して抱える整合性問題を対象にしています。このページでは、その背景にある問題と、contextlint がそれをどう位置づけるかを解説します。
問題: ドキュメントが「壊れる」のに気づけない
Section titled “問題: ドキュメントが「壊れる」のに気づけない”複数の Markdown ファイルが互いに参照し合うリポジトリでは、いつのまにか整合性が崩れていく現象が日常的に発生します。
- ファイル名のリネームによってリンクが壊れているが、ビルドも markdownlint も通る
- 同じテンプレートで書いているはずの設計ドキュメントから必須セクションが欠けているが、レビューでも見落とされる
- 要件 ID をリネームしたが、参照側のファイルは古い ID のまま残っている
- AI に新しいドキュメントを生成させたら既存ファイルへの参照が壊れているが、生成時には誰も気づかない
これらは Markdown としては構文的に正しい 状態です。markdownlint は通り、ビルドも通り、CI も green です。それでも ドキュメントとしての整合性は崩れている — このギャップを埋めるツールが contextlint です。
なぜ AI 時代に顕在化したか
Section titled “なぜ AI 時代に顕在化したか”ドキュメントの整合性問題自体は新しいものではありません。ただし、AI 主導のソフトウェア開発が広まったことで影響が拡大した のは事実です。
| 変化 | ドキュメントへの影響 |
|---|---|
| 仕様駆動開発 (SDD) の普及 | 要件・仕様・設計を Markdown で書き、AI がそこからコードを生成する。ドキュメントが壊れていれば生成されるコードも壊れる |
| ADR / RFC の運用拡大 | 設計判断を Markdown で残すチームが増え、ファイル間の相互参照が複雑化 |
| AI による doc 生成 / 編集 | 人間が逐一確認する量を超えるスピードで Markdown が変更される |
| ドキュメント数の増加 | 数十〜数百のファイルが互いに参照し合う規模では、目視や grep では追いきれない |
ドキュメントは単独のファイルではなく、ID 参照、リンク、安定度の伝播などを通じて 依存関係のグラフを形成 しています。このグラフが崩れたとき、影響は表面化しにくく、サイレントに広がっていきます。
なぜコードのリンターと同じ仕組みが必要なのか
Section titled “なぜコードのリンターと同じ仕組みが必要なのか”コードには ESLint や型検査があり、構文上正しいだけでなく 意味的に整合しているか を検証する仕組みが整っています。一方、Markdown ドキュメントの世界では、構文・フォーマットのリンター（markdownlint）はあっても、コンテンツの意味的な整合性 を検証する標準ツールが存在しませんでした。
コードに対して eslint や tsc が果たしている役割を、ドキュメントに対して果たすツールが必要 — これが contextlint の出発点です。
contextlint が引き受ける範囲
Section titled “contextlint が引き受ける範囲”contextlint は、構造化された Markdown ドキュメントの 意味的な整合性 に特化したリンターです。
- Markdown テーブルの内容（必須カラム、空セル、許可値、パターン、一意性、カラム間制約）
- 必須セクションの存在と順序
- ファイル間の参照整合性（リンク、ID トレーサビリティ、アンカー、画像）
- ドキュメント依存グラフの健全性（トレーサビリティチェーン、循環参照、孤立ドキュメント）
- コンテンツ品質（プレースホルダーの残存、用語の一貫性）
逆に 引き受けないこと も明確です。Markdown の構文・フォーマット・スタイル（見出しレベルの一貫性、リスト記法、テーブル構文）は対象外です。これは markdownlint の領域です。両者を併用することを推奨します。詳しくは 意味的リンターと構文リンター を参照してください。
想定する利用者
Section titled “想定する利用者”contextlint は、Markdown 中心のワークフローを採用しているチーム・個人に向いています。具体的には次のようなケースです。
- 仕様駆動開発 (SDD) — 要件・仕様・設計を Markdown で書き、それを基に AI がコードを生成するアプローチ
- ADR (Architecture Decision Records) — 設計判断を Markdown で残しているチーム
- ドキュメント駆動開発 — 設計を先に文章化してから実装に入るスタイル
- 大規模リポジトリのドキュメント整備 — 数十〜数百の Markdown ファイルが互いに参照し合う規模
次のステップ
Section titled “次のステップ”- 意味的リンターと構文リンター — markdownlint との関係と棲み分け
- 3 層フィードバックの設計 — LSP / MCP / CI に分けた理由
- Context Graph — ドキュメント依存グラフを基盤に据えた理由