contextlint-fix Skill

contextlint-fix は contextlint が検出した違反を 修正する ための Skill です。AI が「lint 直して」「壊れたリンク直して」のような依頼を受け取ったときに自動で起動します。

なぜこの Skill があるか

ドキュメントの整合性は、リファクタリング、ファイル名変更、AI による一括編集などをきっかけに静かに崩れます。CI で違反が出ても、人間が手で 1 件ずつ修正するのは負担が大きく、後回しにしがちです。

contextlint-fix はこの摩擦を取り除きますが、意味のある変更を勝手に書き込まない という設計を厳守しています。修正は次の 2 つに分類され、扱いが変わります。

機械的修正（タイポ、見出し追加、空セルの埋め草など） — 自動で適用
意味的判断（参照削除、値の捏造、チェックリストの完了印、グラフの切断など） — 必ずユーザーに確認

「AI が黙って意味を変えた」という事態を起こさないことが、この Skill の最も重要な制約です。

起動条件

ユーザーが次のような依頼をしたときに起動します。Skill 名を明示する必要はありません。

「lint 直して」「lint エラーを修正して」「contextlint がエラー出してるから直して」
「壊れたリンク直して」「ドキュメント整理して」「コミット前に docs クリーンアップ」

contextlint という名前を出さずに「ドキュメントの整合性を直して」のような依頼でも起動します。

挙動の流れ

1. セットアップの確認

contextlint.config.json と @contextlint/cli が利用可能かを最初に確認します。未セットアップの場合は contextlint-init Skill の利用を案内し、その時点で停止します。

2. lint 実行

npx contextlint --format json

--format json で機械可読な出力を得て、後続のステップで違反を 1 件ずつ処理します。MCP サーバーが利用可能な環境では、lint ツールを直接呼んで JSON パースを省略します。

3. ルールカテゴリ別の修正戦略

ルール接頭辞	自動修正	人間に確認
REF-*	タイポと判定できるリンク先 ID を訂正	参照対象が本当に存在しないケース（削除されたのか改名なのか）
SEC-*	不足セクションを `<!-- TODO -->` 付きで追加	—
TBL-*	空セルに `TODO` を挿入	許可値違反（値の捏造はしない）
STR-*	不足ファイルを placeholder 付きで作成	—
CHK-*	—	チェックボックスを勝手に埋めない
CTX-*	—	placeholder の解消は人間の判断が必要
GRP-*	—	循環参照や orphan の解消はファイル間波及があるため確認必須

骨格作りは Skill の責務、内容を埋めるのは人間の責務、という線引きをしています。たとえばセクション不足は見出しを追加した上で本文に  を残すので、形式は満たすが「未完了」のシグナルは残ります。

4. 再 lint で確認

修正後に npx contextlint を再実行し、残った違反を 0 にできたかを確認します。0 に到達できない場合、残っているのは人間判断が必要な項目だけのはずです。

5. サマリの提示

Skill は最後に「自動で直したもの」と「人間に確認が必要なもの」を分けて提示します。

Done:
  - typo'd cross-refs in design.md を 3 件修正
  - adr/0005.md に Consequences セクションを追加（TODO placeholder）

Needs your attention:
  ? FR-101 が design.md から参照されているが定義が見つからない — 参照を消すか、要件を定義するか
  ? architecture.md と overview.md の循環参照 — どちらを source of truth にするか

決定は人間に残し、Skill は判断材料を整える役割に徹します。

大量違反時の挙動

50 件を超える違反が検出された場合は、すべてを一括処理せず、カテゴリ別のサマリを提示してから「全部の自動修正を進めるか / 一部に絞るか」をユーザーに尋ねます。AI が大量にファイルを書き換えると人間が変更レビューに困るため、適用の粒度を選べるようにしています。

エッジケース

@contextlint/cli 未インストール — contextlint-init の利用を案内するか、npm install -D @contextlint/cli の実行を提案します。
cross-file ルールの結果が空 — include パターンが cross-ref 先のファイルを覆っているかを確認します。include が狭いと REF-002 や TBL-006 が暗黙のうちにスキップされます。
MCP サーバー利用可能 — CLI の JSON パースより MCP の lint ツールを優先します。