alterlab-link-health

リンクの健全性 — リポジトリ全体の Markdown リンク監査手法

リンクチェッカーでエラーが発生しているドキュメント中心のリポジトリを、エラーゼロにするための再利用可能な手法です。実際の監査で確立されたもので、AlterLab-IEU/AlterLab-Academic-Skills のリンクエラーを 1966 件中 1208 件 から、8 回のコミットで 1912 件中 0 件 にしました。自動検出された Tier 3 のリグレッションにより、ガードレールのルールも検証されました。

クイックスタート

完全監査（新しいリポジトリ、リンクチェッカーでエラーが発生している場合）：

Audit and repair the link health of <owner/repo>. Run the full four-tier pipeline.

→ playbooks/full-audit.md の 10 エージェントによる監査を実施し、その後、段階的な APPLY フェーズに進みます。

残存エラーの対象を絞った確認（最初の実施でエラーは減ったものの、一部が残っている場合）：

The link checker is down from 1208 to 67 errors. Close the residuals.

→ playbooks/followup-pass.md の 3 エージェントによるフォローアップを実施します。

マージ後のクリーンアップ（PR はエラーなしになったが、人間の判断が必要な項目を仕上げる場合）：

Finalize the post-merge cleanup: resolve pending human-decision items, file follow-up issues, document link debt.

→ playbooks/post-merge.md の 4 エージェントによるマージ後の確認を実施します。

---

このスキルを使う場面

• 毎週実行される Check Links（または同様の lychee／markdown-link-check）ワークフローが失敗している。
• ユーザーが大量（数百件以上）のエラーに言及し、その大部分が設定に起因する誤検出ではないかと考えている。
• ユーザーが、複数のスキルやドキュメントにわたるリポジトリ内の壊れたファイル参照を修正したい。
• ユーザーが、今後のリンク負債のメンテナンスに使える再利用可能なプロセスを求めている。

トリガーキーワード — 英語：link audit, dead links, link health, lychee, broken links, link checker, markdown link audit, link-health audit, 404 audit, check-links failing, CI link-check。繁體中文：連結健檢, 死鏈, 失效連結, 斷鏈檢查, 連結審計.

トリガーにならないケース

ケース	代わりに使用
引用文献が実在するかの確認（DOI／著者の照合、捏造または幻覚による参考文献、撤回の確認）	alterlab-citation-verifier — リンクの健全性確認ではハイパーリンクのみを修正します。引用文献の実在性は検証しません
1 つのファイル内にある 1 つの壊れたリンクの修正	直接編集 — パイプラインは不要です
リンク以外のリポジトリ構造の監査（スキーマ、frontmatter、メタデータ）	別途スキーマのドリフト監査を実施します（ここでは対象外です）

---

パイプラインの概要（4 つの Tier）

各 Tier は、個別にレビュー可能な 1 つのコミットです。順番に実行してください。各 Tier によってエラーの傾向がより明確になり、次の Tier に進めるようになります。

Tier	対象範囲	典型的な差分
1 — 設定	明示的な許容セットを含む .lychee.toml を導入します（lychee のデフォルト設定を置き換えるため、200..=299 を列挙します）。恒久的なノイズホスト用の .lycheeignore と、堅牢化した CI ワークフローも導入します。	最大の単独効果 — 多くの場合、エラーを 70%〜90% 削減します。「--accept 403 がデフォルトセットを置き換える」という落とし穴を回避できます。
2 — リポジトリ内参照	[ERROR] file:// の項目を修正します。単数形と複数形のディレクトリ名の誤り、パスプレフィックスの不足、YAML frontmatter の不具合などが対象です。教育目的のプレースホルダーパスはインラインコードで囲みます。	実際の破損の大部分を解消します。通常は 200〜400 件のエラーがゼロになります。
3 — URL の置換	検証済みで現在アクセス可能な代替先を使って、移転済みの外部 URL を置き換えます。DEAD_INFRA の URL は代替リソースに置き換えます。検証せずに置き換えてはいけません。	残存エラーを数十件程度まで減らします。
4 — 除外	これ以上修正できない項目をすべて対象にします。ボットを拒否するホスト、教育目的のプレースホルダー、期限切れの上流インフラ、慢性的に不安定な学術サイトなどです。	エラーをゼロにするか、安定した一桁台の残存エラーに抑えます。

各 Tier の判断ルールについては、references/tier1-config.md から references/tier4-exclusions.md を参照してください。

---

Tier 3 のガードレール

URL の置換処理を行った後は、リンクチェッカーを再実行し、ベースラインの成功セットと差分を比較してください。ベースラインで 200 OK を返し、置換後に 200 以外を返す URL はすべてリグレッションです。コミットする前に元に戻してください。

セルフチェック：

diff <(grep "^\[200\]" baseline.log | sort -u) \
     <(grep "^\[200\]" post.log | sort -u)

出力には追加のみが表示され、削除はないはずです。削除がある場合、置換によって以前は正常に機能していた URL がリグレッションを起こしています。

このルールがあるのは、ソース監査中に、広範な sed によるプレフィックス置換で、より具体的なパスに気付かないまま文字列が連結されたためです（例：/v3/ → /v3/docs により、すでに正しかった /v3/docs が /v3/docsdocs になりました）。ガードレールが検出したのは 2 回目の CI ディスパッチ時で、コミット時ではありません。Tier 3 の処理でリグレッションが発生することを前提にしてください。必ず検証してください。

詳細：references/tier3-substitution.md。

---

検証優先のルール

URL を置換する前に、必ずプローブで検証してください。検証していない置換は、実在しない URL が公開スキルに入り込む原因です。[old] → [new] の置換を行う前に、必ず次の手順を実施してください。

1. GitHub リポジトリの場合：gh api repos/owner/name を実行します。ステータスが 200 である必要があります（リポジトリが存在し、アーカイブされていないこと）。
2. HTTP URL の場合：curl -sSI -L --max-time 15 '<new>' を実行します。リダイレクト後の最終ステータスが 200 である必要があります。
3. PyPI／npm／crates のパッケージの場合：レジストリ API またはランディングページを直接確認します。

検証に失敗した場合は、置換先を推測するのではなく、.lycheeignore に理由をコメントとして記載し、無効なリンクを除外してください。無効なリンクを除外するのは誠実な対応ですが、間違ったリンクに置換するのは時限爆弾です。

詳細：references/tier3-substitution.md §「検証ルール」。

---

プレイブック

このスキルの各 Tier を正しい順序で実行する、すぐにディスパッチできる 3 つのプロンプトバンドルです。

プレイブック	使用する場面	エージェント
playbooks/full-audit.md	新規監査、CI の失敗、過去の作業がない場合。	10 個の並列サブエージェント＋統合
playbooks/followup-pass.md	エラーが大幅に減ったものの、残存するエラーがある場合。	対象を絞った 3 つのサブエージェント
playbooks/post-merge.md	PR が成功し、人間の判断が必要な保留項目に対応する場合。	4 個の並列サブエージェント

3 つすべてが同じ流れに従います：事前確認 → 並列ディスパッチ → 統合 → コミット／PR／マージ → 検証。

---

リファレンス

ファイル	内容
references/tier1-config.md	.lychee.toml のスキーマ、ワークフロー YAML、accept-code の注意点
references/tier2-intra-repo.md	リポジトリ内パスの監査、ディレクトリ名の単数形／複数形パターン、フロントマターの修正
references/tier3-substitution.md	URL 置換ルール、ガードレール、sed の安全な使用パターン
references/tier4-exclusions.md	除外と置換の使い分け、.lycheeignore のカテゴリ別基準
references/known-debt-template.md	メンテナー向け KNOWN_LINK_DEBT.md の 5 カテゴリ構成

---

例

• examples/pr-1-retrospective.md — このスキルの元となったソース監査。1208 件のエラーを 0 件に削減し、8 回のコミットを実施。コミット 5（9cbd801）で Tier 3 のリグレッションを自動検出し、93a72fe としてマージしました。

---

スコープの遵守

このスキルが修正するのはリンクの健全性です。次の作業は行いません。

• リポジトリ全体の SKILL.md スキーマを標準化すること。ファイルスキーマの不整合は別の課題として扱います。
• スキルの内容、例、説明文をリファクタリングすること。変更対象はリンク URL と CI 設定のみです。
• 実際の問題を隠すために .lychee.toml の accept リストを変更すること。断続的な上流の 5xx／タイムアウトは、一括で許容せず、理由を添えてホストごとに除外します。

スコープを守ることで、PR のレビューがしやすくなり、リンクチェックのシグナルの信頼性が保たれます。

AlterLab Academic Skills スイートの一部です。