docs-lint

name	docs-lint
description	markshelf の docs/ が4階層ドキュメント規約（要求定義→要件定義→仕様＋用語集、リンクは上位レイヤへ一方向）を守っているか検査する。ドキュメントの追加・編集後、リンク切れ・下向きリンク・親リンク欠落・命名違反を確認したいときに使う。

docs-lint — ドキュメント規約チェック

markshelf のドキュメントは厳格な4階層構造を持つ（docs/要求定義/README.md などを参照）:

レイヤ	フォルダ	役割	リンク方向
要求定義	R{n}-…	ユーザーが望む状態	上位なし（最上位）
要件定義	REQ{n}-…	システムが何をすべきか	要求定義へ上向き
仕様	SPEC{n}-…	どう実装するか	要件定義へ上向き
用語集	用語集/	横断的な用語	どこからでも参照可

中核ルール: ドキュメント間リンクは常に「下位 → 上位」の一方向のみ。 下向きに張るとリンクグラフが双方向に濁って読めなくなる。

手順

1. リポジトリルートで検査スクリプトを実行する:

   node .claude/skills/docs-lint/lint-docs.mjs
   

   • 特定ディレクトリを指定する場合は第1引数にパスを渡す（既定は ./docs）。
   • 機械可読な出力が欲しい場合は --json を付ける。
   • 違反(error)が1件以上あれば終了コード 1。

2. 検出される違反の種類と対処:

   • broken-link — 相対リンクの解決先ファイルが存在しない。リンク先パスを修正する。フォルダ宛（../../用語集/ 等）は README.md が無いと解決できないので、具体的なファイルを指すか README を用意する。
   • escapes-root — ../ が多すぎて docs ルートより上を指している。ビューアは root 起点で .. を吸収するため画面上は動くが、IDE・GitHub・実ファイルシステムではリンク切れになる。../ を1つ減らす（例: SPEC 個別ファイル docs/仕様/SPEC*-…/SPEC*.md から要件定義へは ../../../要件定義/ ではなく ../../要件定義/）。
   • downward-link — 上位レイヤから下位レイヤへリンクしている。リンクを削除し、参照は下位レイヤ側から上向きに張り直す。
   • missing-parent-link — 要件定義/仕様 配下のファイルに、親レイヤ（要求定義/要件定義）への上向きリンクが本文に無い。冒頭（最初の段落）に対応する上位ドキュメントへのリンクを追加する。対応する上位がまだ無い場合は、まず上位ドキュメントの新設を検討する（docs-new スキルが使える）。
   • naming（warn） — R{n} / REQ{n} / SPEC{n} の命名プレフィックスに合致しないファイル名。リネームを検討する。

3. 検出結果をユーザーに報告する。修正を依頼されたら、上記の対処方針に沿って直し、再度スクリプトを実行して error 0件を確認する。

注意

• リンク解決ロジックは src/lib/links.ts の resolveLink に揃えてある（アンカー #…・クエリ ?… 除去、/ 始まりは docs ルート相対、拡張子省略時の .md / README.md 補完）。アプリ本体のグラフ生成と同じ判定なので、ここで解決できないリンクはビューア上でもエッジにならない。
• カテゴリ直下 README（docs/要求定義/README.md など）は規約の説明用メタページなので、下向きリンク・親リンク・命名の検査対象から除外している。
• コードフェンス（``` / ~~~）とインラインコード内のリンクは無視される（本体と同じ）。