1natsu-document-harness-audit

name: 1natsu-document-harness-audit description: セッションをまたいで存在する既存ハーネスドキュメント（CLAUDE.md, .claude/rules/, docs/, feature README）を検査し、コードとの陳腐化、モデル進化に伴う表現の見直し、実装の偶有を仕様に書いた箇所（蒸留不足・機構名やコードの転記）、ドキュメント間の重複・不整合・参照切れ・欠落・粒度逸脱・参照不足を検出して改善提案を行う。「ドキュメントを監査して」「ハーネスの整合性チェックして」「古いドキュメントがないか確認して」「CLAUDE.mdがおかしい」「rulesが効いてない気がする」「今のモデルに合わせて見直したい」「ドキュメントが実装に寄りすぎている」等と言われた時に使用する。現セッションで自分が実装した変更に対するドキュメント生成・更新は 1natsu-document-harness を使い、このスキルではない。 license: MIT metadata: author: 1natsu version: "1.5.0"

ハーネスドキュメント監査

既存のハーネスドキュメントを検査対象として、問題を検出し改善提案を行うワークフロー。生成・更新スキルではなく検査スキルであり、対象は「過去セッション・他者・時間経過によって既に存在しているドキュメント」。

3層モデルの定義、配置先ルール、配置判断フローは 1natsu-document-harness-model スキルを参照。

このスキルを使うべきか判定

判定の軸: 「今セッションで自分が触った変更を反映する話」なら harness、「既に存在しているドキュメント全般の検査・見直し」なら audit。現セッション内のドリフト追従は audit の責務ではなく、harness の sync モードで扱う。

いつ使うか

audit が対象とするのは「セッションをまたいで存在する既存ドキュメント」であり、典型的なシーンは以下:

• 既存ドキュメントの陳腐化検査: 過去に書かれたドキュメントとコードの実態が乖離していないかを確認したい時（例: 「最近触っていないモジュールの docs/ が古そう」「rules/ の指示が今のコードと合っていない気がする」）
• AIツール・モデル能力進化に伴う見直し: 過去のモデル前提で書かれた冗長な前置き・過剰な MUST 表現・必要以上の防御的指示を、今のモデルに最適化された書き方に更新したい時
• ドキュメント間の整合性検査: CLAUDE.md / rules/ / docs/ の間で重複・矛盾・参照切れがないかを横断的に確認したい時
• 「ドキュメントを監査して」「整合性チェックして」「古いドキュメントがないか確認して」と言われた時
• 定期的なドキュメントメンテナンスの一環として

使わない場面:

• 現セッションで自分が実装した変更を反映したい場合 → 1natsu-document-harness (sync モード) を使う
• 単一の特定ドキュメントを「今書きたい」場合 → 該当する harness モードを使う

ワークフロー

スキャン → 検出 → 提案一覧 → ユーザー確認 → 実行 → 結果報告

このスキルは提案→確認→実行のフローを取り、検出した問題を自動修正しない。ドキュメントの統合・削除・再配置はプロジェクトの意図を理解した人間の判断が必要であり、機械的に処理すると情報が失われたり、意図しない配置になるリスクがあるため。

ステップ1: スキャン対象の収集

プロジェクト内のハーネスドキュメントを網羅的に収集する:

• CLAUDE.md（ルート + 各パッケージ）
• .claude/rules/**/*.md
• docs/**/*.md（ルート）
• packages/*/docs/**/*.md（各パッケージ）
• feature ディレクトリの README.md

monorepo の場合はルートとパッケージの両方を探索する。

audit の対象範囲の前提: audit は「セッションをまたいで存在している既存ドキュメント」を対象とする。現セッションで自分が直前に生成・更新したドキュメントは原則対象外（その差分追従は harness の sync モードの責務）。実行時、現セッションで自分が書いたドキュメントが対象に含まれそうな場合は、ユーザーに「これは harness sync で扱う領域では？」と確認を取る。

ステップ2: 9カテゴリの検査

収集したドキュメントに対して以下の9カテゴリで問題を検出する。各問題には重要度（高/中/低）を付与する。

カテゴリ一覧

デフォルト重要度は目安。セキュリティや認証に関わる問題は常に「高」に引き上げる。

重要度の判断基準

• 高: エージェントが間違った行動を取るリスクがある（矛盾する指示に従う、存在しないファイルを参照する等）
• 中: ドキュメントの信頼性やメンテナンス性に影響するが、即座の実害は小さい
• 低: 品質改善の余地があるが、放置しても問題は起きにくい

検査の着眼点

重複: 各ドキュメントのトピック（見出し単位）を比較し、同一テーマが複数箇所にないか確認する。発見したら 1natsu-document-harness-model の配置判断に基づき統合先を提案する。

不整合: rules/ の指示と docs/ の説明で異なることを言っていないか、CLAUDE.md の記述と実際のファイル内容が乖離していないかを重点的に確認する。

例: rules/api.md が「レスポンスは snake_case」と指示しているが、docs/api-design.md では「camelCase を採用した」と書かれている。

陳腐化: 2種類の陳腐化を検査する。

1. コード乖離: ドキュメントに記載されたファイル名、関数名、設定値、ディレクトリ構成がコード内に実在するかを検証する。

   例: docs/architecture.md に src/services/AuthService.ts と書かれているが、リファクタリングで src/auth/service.ts に移動済み。

2. 表現の陳腐化（AIツール・モデル能力進化）: 過去のモデル前提で書かれた「過剰な MUST / NEVER の連発」「冗長な前置き」「自明なことの過剰説明」「同じ指示の繰り返し」など、今のモデルなら短く・理由ベースで書けば伝わる箇所を検出する。原則として「指示を緩める」のではなく「同じ意図をより短く・より理由が伝わる形に書き直す」方向での提案を行う。

   例: ある rules/ ファイルに「YOU MUST ALWAYS validate input. NEVER skip validation. ALWAYS handle errors. NEVER ignore errors.」と冗長に書かれている → 「入力検証とエラーハンドリングを行う（理由: ...）」のように理由付きで簡潔化する提案。

参照切れ: CLAUDE.md の @ 参照先、rules/ の paths パターンにマッチするファイル、markdown 内の相対リンクがすべて有効か確認する。

欠落: monorepo の各パッケージに CLAUDE.md があるか、docs/ 内のファイルが CLAUDE.md からポインタで参照されているか（背景知識はプレーンポインタ）、新しいディレクトリに対応するドキュメントがあるかを確認する。

monorepo では docs/ のスコープ配置も検査する（双方向チェック）:

• パッケージの関心がルート docs/ に漏出していないか: 特定パッケージに閉じた知識がルート docs/ に配置されている場合、パッケージ内 docs/ への移動を提案する
• 全体共通の知識がパッケージ docs/ に閉じていないか: 複数パッケージやリポジトリ全体に関わる知識が特定パッケージの docs/ にのみ存在する場合、ルート docs/ への昇格を提案する

粒度・構成の逸脱: 同階層のドキュメント間で詳細度に大きな差がないか、文体が統一されているか、1つのファイルに複数の層（指示と知識等）が混在していないかを確認する。

参照不足: rules/ ファイルの内容が言及しているモジュールやパスパターンを抽出し、paths frontmatter に含まれていないが対象にすべきパスがないか提案する。

コンテキスト経済: eager/lazy の既定（lazy）から外れた記述を検出する。①背景知識の docs を @-import で繋いでいる（起動時フルロードで節約にならない → プレーンポインタ化を提案）、②paths なし rule（常時ロード）に eager 意図のマーカーがない、③パッケージ内 rule の paths glob が rule のあるディレクトリ基準とずれてミススコープ。判断基準は 1natsu-document-harness-model「コンテキスト経済」を参照。

実装結合（蒸留不足）: 記述が「今は正しい」が実装の偶有を仕様として書いているために、コードが変わった瞬間に陳腐化する箇所を、陳腐化が起きる前に検出する。各記述に swap test を当てる（「実装を別の妥当な方法に書き換えたら嘘になるか？」嘘になるなら偶有）。典型:

• ルール（指示層）に機構名・ライブラリ名が書かれている（「Redis を使う」等）。それが今後の義務でなく単なる現状報告なら、ポリシー記述へ蒸留し、機構の経緯は docs/ の rationale へ移す提案を出す
• docs にコードのシグネチャ・内部変数名・処理手順がそのまま転記されている → コードから読めるものは削り、「設計判断と理由」へ蒸留する提案を出す

ただし外部契約面の名前（利用者が設定する環境変数名・公開 API ルート・設定キー・公開型）は名前そのものが契約なので、偶有として扱わない。判断基準・3分類は 1natsu-document-harness-model「実装の偶有を仕様に蒸留する」を参照。

ステップ3: 提案一覧の提示

検出結果を重要度の高い順にテーブル形式で提示する:

## 検査結果: N件の問題を検出

| # | 重要度 | カテゴリ | 対象ファイル | 問題の概要 | 提案するアクション |
|---|--------|---------|------------|-----------|-----------------|
| 1 | 高     | 不整合   | rules/api.md, docs/api-design.md | レスポンス形式の指定が矛盾 | rules/ の記述に統一 |
| 2 | 高     | 参照切れ | CLAUDE.md:15 | @docs/removed.md が存在しない | 参照を削除または移転先に更新 |
| 3 | 中     | 参照不足 | rules/api.md | paths に src/api/** がない | paths に追加 |

問題が検出されなかった場合は、その旨を報告して終了する。

ステップ4: ユーザー確認

提案一覧を提示した後、ユーザーに選択肢を提示する:

• 全件実行: 「全部やって」で全アクションを実行
• 番号で選択: 「1, 3, 5 をやって」で指定項目のみ実行
• スキップ: 「今回はいい」で修正せず終了

ユーザーの応答を待ち、選択された項目のみ実行する。

ステップ5: 修正実行

承認された項目について修正を実行する。

• ファイルの新規作成・統合・削除を伴う場合は、1natsu-document-harness-model の配置判断に従う
• 重複の統合では、情報の欠落がないよう内容をマージしてから元ファイルを削除する
• 参照の修正では、関連する全ファイル（CLAUDE.md の @ 参照、rules/ の paths、markdown リンク）を連動して更新する
• コード乖離の修正では、置換後の値（正しいパス・名前・定数）を必ずコードで裏取りしてから書く。推測で埋めない。挙動依存で静的に確定できない事実は、実測するか「要検証」として残す
• 実装結合の是正では、記述を消すだけでなく再蒸留する（契約はルールへ、機構名は docs/ の rationale へ。検出側の着眼点・判断基準は本スキルのステップ2 ＋ 1natsu-document-harness-model「実装の偶有を仕様に蒸留する」）

ステップ6: 結果報告

実行した修正の一覧と各ファイルの変更概要を報告する:

• 変更したファイルのリスト
• 各変更の概要（追加 / 更新 / 削除 / 統合）
• スキップした項目がある場合はその旨も記載する