1natsu document harness audit

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

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

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

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

状況	使うスキル
現セッションで実装した変更を初めてドキュメント化する	1natsu-document-harness (init)
同一セッション内で既に harness を実行済み、追加修正・実装乗り換えが入った	1natsu-document-harness (sync)
過去セッションで書かれた既存ドキュメントの陳腐化・不整合を検査したい	audit
AIツール・モデル能力進化に伴うドキュメント表現の見直し	audit
エージェントのメモリに溜まった知識の整理・リポジトリへの蒸留	audit

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

いつ使うか

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

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

使わない場面:

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

ワークフロー

スキャン → 検出（ドキュメント10カテゴリ ＋ コード内コメント ＋ メモリ監査） → 提案一覧 → ユーザー確認 → 実行 → 結果報告

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

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

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

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

monorepo の場合はルートとパッケージの両方を探索する。docs/ は .md 以外（.mdx / .txt / .rst / .adoc）も収集対象に含める。

コード内のコメントもハーネスドキュメントだが、ここでは収集しない。 ソースに散在して走査の費用が桁で違い、是正がソースファイルの変更になるため、ステップ2.5 で独立して扱う（定義と分離の理由は 1natsu-document-harness-model「ハーネスドキュメントの定義」）。

あわせて、実行環境のエージェントが永続メモリ機構を持つ場合はメモリストアも収集対象にする（検出方法とルーティングはステップ3を参照）。

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

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

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

カテゴリ一覧

#	カテゴリ	何を探すか	デフォルト重要度
1	重複	同一/類似トピックが複数ファイルに散在	中
2	不整合	ドキュメント間で矛盾する記述	高
3	陳腐化	コードの現状と合わなくなった記述 / AIツール・モデル能力進化に伴い古くなった表現	高
4	参照切れ	存在しないファイルへの @ 参照やリンク	高
5	欠落	ドキュメントがあるべき箇所に不在	中
6	粒度・構成の逸脱	周囲と明らかに粒度やトーンが異なるファイル	低
7	参照不足	rules/ の paths に含めるべきパスが漏れている	中
8	コンテキスト経済	eager/lazy の誤用（背景 docs の @ eager ロード / paths なし rule の意図マーカー欠如 / glob ミススコープ）	中
9	実装結合（蒸留不足）	実装の偶有（機構名・内部変数名・コード転記）を仕様として記述。今は正しいがコード変更で嘘になるドリフト予備軍	中
10	用語・文体の規約違反	比喩由来のジャーゴン・造語、同一概念の用語ゆれ、規範に混ざった作業記録、ナラティブ、日本語ドキュメントのダッシュ使用・不自然な訳語	中

コード内コメントへのカテゴリ10 の適用はステップ2.5 で扱う。

デフォルト重要度は目安。セキュリティや認証に関わる問題は常に「高」に引き上げる。カテゴリ10 は、比喩・造語が指示層（.claude/rules/）にあってエージェントの行動を誤らせうる場合は「高」、表記だけの違反（ダッシュ等）は「低」に調整する。

重要度の判断基準

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

検査の着眼点

重複: 各ドキュメントのトピック（見出し単位）を比較し、同一テーマが複数箇所にないか確認する。発見したら 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「実装の偶有を仕様に蒸留する」を参照。

用語・文体の規約違反: 1natsu-document-harness-model「用語と文体」の基準を当てる。他カテゴリで指摘した箇所に限定しない。表記の違反は1箇所でも残ると、後続の書き手がそれを既存の文体とみなして複製するため、対象を絞ると再発する。

対象はステップ1 で収集したハーネスドキュメント全件（コード内コメントはステップ2.5）。費用は走査時間ではなく読む量で決まる。 検索自体は数ミリ秒だが、ヒット行はすべてコンテキストに載る。絞り込みは検索を速くするためではなく、読む行を減らすために行う。

表記の違反は検索を1段目に使う。検索は判定ではなく、目視する範囲を削るための絞り込みで、可否は2段目（ヒット行を読んで文脈を見る）で決める。この立て付けなので、1段目は取りこぼさないよう広く当てる。

rg -n --hidden -g '!.git' '[—–―─]' .
# rg がなければ
grep -rn --exclude-dir=.git -e '—' -e '–' -e '―' -e '─' .

末尾のパス . を省かない。 rg はパス引数がないと標準入力を読みに行き、エージェントの実行環境では閉じないパイプを待って停止する（実測で確認）。

拡張子も言語も指定しない。 rg は型を指定しなければ全テキストファイルを走査するので、.md 以外のドキュメントも、Rust・Go・Python・Ruby いずれのソースコメントもこれだけで入る。表記の違反は文字が一致するかどうかだけで判定でき、絞り込む理由がない。走査から外すべき生成物（node_modules / target / __pycache__ 等）は .gitignore が既に列挙しており、rg はそれを既定で尊重する。言語ごとの除外パターンを skill 側に持たないのはこのためで、リポジトリの .gitignore に任せるほうが正確かつ言語非依存になる。ただし .gitignore が効くのは生成物だけで、コミットされている第三者の文章（Go の vendor/ 等）と fixture は1段目に残る。これらは2段目で落とす。

この検索はソースコメントのダッシュも拾う。拾った結果はステップ2.5 の節で報告する（是正がソースファイルの変更になるため）。検索を2回に分けないのは、同じ文字を探すのに走査を重ねる意味がないから。

以下は ripgrep 15.2.0 で実測して確定した挙動:

• --hidden は省略できない。既定ではドット始まりのディレクトリを飛ばすため、.claude/rules/ 配下が丸ごと漏れる
• -g '!.git' は --hidden とセットで必須。--hidden を付けると .git/ の中身まで走査対象になる（公式ドキュメントも「ドット始まりのファイル・ディレクトリの扱いは --hidden 側が決める」と明記している）
• ハーネスドキュメント自体が .gitignore 配下にあるリポジトリでは、--hidden を足しても拾えない。その場合だけ --no-ignore-vcs を追加する。ただし生成物も一緒に戻ってくるので、対象パスを指定して範囲を限る

grep -r は既定でドットディレクトリも辿るため追加のオプションは要らないが、.gitignore を見ないので生成物まで拾う。

2段目で次を落とす:

• 表の空セル、数値範囲（18–21）: 規約上の対象外
• 英語の文中のダッシュ: 規約は日本語の文章に対するもの
• 文章でないもの: コードの文字列リテラル、URL、テストの期待値、ASCII 図の罫線
• ハーネスドキュメントでないもの: 取り込んだ第三者の文章（vendor/、ライセンス、引用）と、fixture・テストの入力データ。1natsu-document-harness-model「ハーネスドキュメントの定義」が対象外と定めている。どちらもコミットされていて .gitignore に載らないので1段目では落ちない。fixture の文字列は検証の素材なので、書き換えるとテストが壊れる

残ったものが違反で、接続詞と読点・:・文の分割への書き換えを提案する。ハイフン - と長音符 ー は別の文字なので1段目にも含めない。ソースのコメントで見つかったものは、ステップ4 の「コード内コメント」の節へ回す。

ヒットが多すぎて読み切れないときは、先に rg -c でファイル別の件数だけ取り、多い順に処理する。件数の一覧は数百バイトで済むので、全ヒット行を読む前に分布を掴める。

判断を要する違反（比喩由来のジャーゴン・造語、用語ゆれ、規範に混ざった作業記録、ナラティブ）はファイルを読んで個別に挙げる。判定の目安:

• ジャーゴン・造語: その語をリポジトリ内で定義せずに使っているか。定義がなく、指す対象がコードや他ドキュメントから確定できないなら違反。提案は「削る」ではなく「指している実体で書き直す」形にする。実体を確定できない場合は、憶測で埋めずユーザーへの確認項目として出す（確定できたかどうかの判定手順は 1natsu-document-harness-model「実体を名指しする」）
• 規範に混ざった作業記録: その行を削っても規範の妥当性を判断できるか。判断できる（日付・依頼者・修正回数）なら作業記録として削除を提案。判断できない（捨てた選択肢の棄却理由、一般解と違う選択をした理由）なら根拠なので残す。rationale を作業記録と誤判定して消す提案を出さない
• ナラティブ: 節を単独で読んで意味が通るか。ただしインシデントレポート・調査報告は例外として扱い、docs/ にある限り違反にしない
• 用語ゆれ: 同じ概念が複数の語で書かれていないか。ファイル単位では気づけないので、横断で語を突き合わせる。統一先は既に定着している側を選び、外部契約面の識別子（ヘッダ名・env var 名等）は本文の統一に巻き込まない

報告の行の粒度はステップ4の「1行 = 1つの是正アクション」に従う。表記の違反は書き換え方が一様なので複数ファイルを1行にまとめてよく、その場合は対象ファイルと該当件数を列に書く。ファイルごとに採否を分けたいなら行を分ける。件数が多くても提示を省略せず、重要度で並べ替えて他カテゴリの高重要度の問題が埋もれないようにする。

ステップ2.5: コード内コメントの検査

コメントもハーネスドキュメントだが、ソースに散在するため走査の費用が他と桁で違い、是正がソースファイルの変更になる。独立したステップにするのはこの2点が理由で、対象として格下だからではない。

絞り込み

表記（ダッシュ等）はステップ2 の検索で既に拾えている。ここで絞り込むのは、読んで判断するしかない違反（ジャーゴン・造語・用語ゆれ・作業記録・ナラティブ）の対象を作るため。

ソースの全行を読まない。 行頭または行末のコメント記号と日本語の文字を同時に満たす行だけを取る。

rg -n --hidden -g '!.git' -g '!*.md' -g '!*.mdx' -g '!*.rst' -g '!*.adoc' -g '!*.txt' \
  '(^\s*(//|/\*|\*|#|--|;|%|<!--|!|\(\*|\{-|=begin)|\s(//|/\*|#|--|;|%|<!--))(?-u:.)*[\p{Hiragana}\p{Katakana}\p{Han}]' \
  .

除外する拡張子はステップ1 の収集対象と揃える。 .md .mdx .rst .adoc .txt はステップ1 が docs/ 配下で既に収集しており、ここで拾うと同じファイルを2回報告する。加えてこの節の報告規約（是正はコメント本文に限る）はドキュメントファイルには当てはまらない。

記号の集合はリポジトリで実際に使われている言語に合わせる。 使っていない言語の記号を残すと誤ヒットが増え、使っている言語の記号が無いとそのファイル群が丸ごと落ちる。既定から外してあるもの、足し方の判断は references/comment-extraction.md を参照。

この絞り込みは完全ではない。 取りこぼす範囲と誤って拾う範囲を把握したうえで使い、絞り込みが完全でない旨を報告に添える。何が漏れて何を誤検出するかは同じリファレンスにある。

検査項目

得られた行に**カテゴリ10（用語・文体）**を当てる。基準はドキュメントと同じ（1natsu-document-harness-model「用語と文体」）。

読む過程でコードと明らかに食い違うコメントに気づいたら陳腐化として挙げる。ただしコメント全件の裏取りはしないので、網羅は保証しない。

他のカテゴリは当てない。重複・配置・コンテキスト経済はファイル単位の観点であり、実装結合（蒸留不足）はコメントには当たらない（コメントは実装の近傍にあり、機構名や変数名を書いてよい場所のため）。

報告

提案一覧では他のカテゴリと節を分ける。 是正がソースファイルの変更になるので、ドキュメントの監査を依頼した人にとっては想定外になりうる。変更がコメント本文に限ること（コードには触れないこと）も明記する。

ステップ3: メモリ監査（正本性の検査）

原則: リポジトリに存在するドキュメント類が正本（source of truth）であり管理ファイルである。 エージェントの永続メモリはユーザー固有・リポジトリ管理外で、クラウド共有もされない一時的なメモにすぎない。恒久的なプロジェクト知識がメモリ側にあるのは「置き場所の誤り」で、チームに共有されずメンバー間の知識差異を生む。メモリ監査の目的は、メモリに溜まった恒久知識をリポジトリ側へ蒸留し、メモリを本来の役割（個人的・一時的なメモ）に戻すこと。

メモリストアの検出とルーティング

メモリの格納場所・ファイル構造・インデックスの仕組みはエージェントごとに異なる。実行環境のエージェントに対応するリファレンスを読み、具体的な扱い方を把握してから監査する:

エージェント	リファレンス
Claude Code（auto-memory）	references/memory-claude-code.md

対応リファレンスがないエージェントの場合は、ユーザーにメモリの格納先を確認し、本節の汎用原則だけで監査する。メモリストアが存在しない・空の場合は本ステップをスキップし、その旨を結果に添える。

蒸留対象の判定（恒久性 × 関心の所在）

各メモリを2軸で分類し、アクションを決める:

	チームの関心（プロジェクト知識）	個人の関心（好み・役割・個人向け作業指示）
恒久（1ヶ月後も真であるべき事実・制約・判断）	蒸留対象 → リポジトリのドキュメントへ移し、メモリから削除	メモリに残す（リポジトリへ蒸留しない）
一時（進行中の作業状態・短期のメモ）	メモリに残す。ただし完了・失効していれば削除を提案	同左

判定のリトマス試験: 「このメモを、別のユーザー（新メンバー）のエージェントが知らないと困るか？」困るならチーム知識であり、リポジトリ側に存在しないのは欠落。メモリの type/分類フィールド（あれば）は目安に使うが、判定は内容で行う（個人向け分類でもプロジェクト規約が書かれていることがある）。

検査項目

ドキュメント10カテゴリと同様に、各問題へ重要度（高/中/低）を付与する:

#	検査項目	何を探すか	デフォルト重要度
M1	メモリ限定知識	恒久的なチーム知識がメモリにしかなく、対応するドキュメントが存在しない	中
M2	メモリとドキュメントの不整合	同一トピックについてメモリとドキュメントで内容が食い違う	高
M3	ドキュメントの劣後	同一トピックだがメモリ側が詳しく・新しく、ドキュメントが追いついていない	中
M4	メモリの陳腐化	現状と合わないメモリ（完了済み作業の残骸、変わってしまった事実、参照先の消滅）。個人系メモリもこの検査は対象	中
M5	メモリとドキュメントの重複	同一トピックでメモリとドキュメントの内容が一致している（矛盾なし）	低

同一トピックがメモリとドキュメントの両方にある場合、その関係は3状態のいずれかで、対応が異なる: 一致 = M5（正本は docs 側なのでメモリが冗長。docs は変更せず、メモリ削除のみ。蒸留は不要）／食い違い = M2（コード裏取りで真偽を確定してから統一）／メモリ優位 = M3（差分を docs へマージしてからメモリ削除）。M5 は今は無害だが、放置すると2つのコピーが別々に育って M2（高）に化けるドリフト予備軍なので、見つけ次第の削除を提案する。

検査の注意点:

• M2 の真偽判定はコードで裏取りする。メモリが新しいとは限らず、どちらも古いこともある。裏取りの結果を提案に含める
• M1/M3 の蒸留は転記ではない。メモリの記述には実装の偶有（機構名・その時の手順）が混ざりやすい。蒸留先は 1natsu-document-harness-model の3層モデル・配置判断に従い、swap test を通してから書く（指示は rules へ、背景・理由は docs へ、反復手順は skill へ）
• 蒸留した記述は「用語と文体」の規約も通す。メモリは走り書きなので、比喩・その場限りの造語・書いた時の経緯が残りやすい。リポジトリ側へ移す時点で実体の名指しへ直し、作業記録は落とす。メモリ本体の文体は監査対象にしない（個人のメモであってハーネスドキュメントではない）
• M1 とドキュメント側カテゴリ5（欠落）は表裏。メモリの存在が「本来ドキュメント化されるべきだった知識」の証拠になる
• メモリ削除を伴う提案には、必ずインデックスファイル該当行の連動削除と、削除対象を指すインバウンド参照リンクの削除／張り替え（Claude Code は MEMORY.md の該当行と、他メモリ本文中の [[name]] リンク）を提案そのものに含める。参照元を洗い出し、dangling になるリンクを残さないことを完了条件とする。実体だけ消してインデックス行や被参照リンクを残すと次セッションの参照切れになる。これは蒸留（M1/M3）に限らず、純粋な削除（M4 陳腐化・M5 重複）でも同じ。連動先の具体構造はエージェント別リファレンス（Claude Code は memory-claude-code.md「削除・書き換え時の連動」）を参照

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

出力は2段構成にする。一覧表が全体の見取り図で、書き直し案が承認の判断材料になる。

表だけで終わらせない。承認する側が知りたいのは「何が問題か」ではなく「直した結果どうなるか」で、表の 提案するアクション 列はそれを1行に圧縮してしまう。表を読んだだけでは、提案が自分の意図と合っているか判断できない。

書き直し案を本文に置く対象と置き方:

• 記述の書き換えを伴う項目: 現状と書き直し後を並べる。引用で現状、コードブロックで書き直し後を示し、どこが変わるかを目で追えるようにする
• 実体を確定できない項目: 書き直し案の代わりに、何が確定できないかと確認したい内容を書く。ここで案を捏造しない
• 削除だけ・パス修正だけの項目: 表の1行で足りる。全件に節を作ると、判断が要る項目が埋もれる

検出結果は重要度の高い順にテーブル形式で提示する。表は検出元ごとに分ける。 ステップ2（ドキュメント）・ステップ2.5（コード内コメント）・ステップ3（メモリ）は承認の判断材料が違う。コメントの是正はソースファイルの変更になるのでコードに触れていないことの確認が要り、メモリの削除は git で戻せないのでバックアップの確認が要る。1つの表に混ぜると、承認する側が行ごとにどの判断をすればよいか読み分けることになる。

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

### ドキュメント

| # | 重要度 | カテゴリ | 対象 | 問題の概要 | 提案するアクション |
|---|--------|---------|------|-----------|-----------------|
| 1 | 高     | 不整合   | rules/api.md, docs/api-design.md | レスポンス形式の指定が矛盾 | rules/ の記述に統一 |
| 2 | 中     | 参照不足 | rules/api.md | paths に src/api/** がない | paths に追加 |
| 3 | 中     | 用語・文体 | rules/deploy.md | 「デプロイのゲート」が何を指すか定義されていない | 実体（承認フローの通過条件）で書き直す |
| 4 | 低     | 用語・文体 | docs/queue-design.md:7,11 / rules/release.md:8 / docs/ops-runbook.txt:5 | 日本語本文のダッシュ 4箇所 | 接続詞と読点・`:`・文分割へ書き換え |

### コード内コメント（ステップ2.5）

是正はコメント本文に限り、コードには触れない。

| # | 重要度 | カテゴリ | 対象 | 問題の概要 | 提案するアクション |
|---|--------|---------|------|-----------|-----------------|
| 5 | 中     | 用語・文体 | src/api/dispatch.ts:3 | 「配信のゲート」が何を指すか定義されていない | 実体で書き直す |

### メモリ（ステップ3）

| # | 重要度 | カテゴリ | 対象 | 問題の概要 | 提案するアクション |
|---|--------|---------|------|-----------|-----------------|
| 6 | 高     | M2 メモリ不整合 | memory/api-format.md, docs/api-design.md | メモリは snake_case、docs は camelCase。コード裏取りでは camelCase が実態 | docs を正とし、メモリを削除（＋MEMORY.md 行・被参照 `[[name]]` の連動削除） |
| 7 | 中     | M1 メモリ限定知識 | memory/deploy-constraint.md | デプロイ制約がメモリにしかない | docs/deploy.md へ蒸留し、メモリを削除（＋MEMORY.md 行・被参照 `[[name]]` の連動削除） |

該当のない節は見出しごと省く。重要度の並びは節の中で保つ。番号は節をまたいで通しにする（ステップ5 の承認が番号で行われるため）。

カテゴリ列の書き方:

• 列は増やさない。下位区分を示すときは 陳腐化（コード乖離） のようにカテゴリ列へ括弧書きで入れる。7列目を作ると 対象・概要・アクション が潰れて読めなくなる
• 下位区分を書くのは、区分によって是正の性質が変わるときだけ。「コード乖離」（コードで裏取りしてから直す）と「表現の陳腐化」（意図を変えず書き直す）は作業が別物なので区別する意味がある。一方、概要 を読めば何の違反か分かる場合の括弧書きは重複でしかない。ただし同一カテゴリ内では書くか書かないかを揃える（片方だけ付くと、付いていない行が別種に見える）
• 1行 = 1つの是正アクション。 同じ箇所が複数カテゴリに当たるとき、1回の書き直しで両方解消するならカテゴリ列に併記して1行にまとめ、別々の是正が要るなら行を分ける。承認する側は是正の単位で選ぶので、行の粒度をそれに合わせる
• 対象列で「ほか N ファイル」と省略しない。 複数ファイルをまとめた行でも全ファイルを列挙し、行を指せるものは path:line で書く。省略すると、HTML レビューへ渡す findings.md が対象を持てず、委譲先が原文を取り直すことになる（references/html-review.md）。件数が多くて表に収まらない場合は、表に全ファイル名を出し、行番号は書き直し案の節に載せる

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

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

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

• 全件実行: 「全部やって」で全アクションを実行
• 番号で選択: 「1, 3, 5 をやって」で指定項目のみ実行
• スキップ: 「今回はいい」で修正せず終了
• HTML で詳細レビュー: 1件ずつ書き直し案を見ながら採否を決める

HTML レビューは求められたら作る。表で始めた後でもよい。作り方（使えるスキルへの委譲、生成の委譲）と満たすべき要件は references/html-review.md を参照する。

メモリ削除を含む提案がある場合は、実行時にメモリストア全体を一時ディレクトリへバックアップしてから削除すること（ステップ6）をこの時点で添える。メモリは git で復元できないため、戻す手段があると分かっていれば削除を承認する判断がしやすい。

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

ステップ6: 修正実行

承認された項目について修正を実行する。判断が HTML レビュー経由で返ってきた場合も扱いは同じで、次の4点を守る。

• 実行するのは承認された項目だけ。 却下・保留・未判断は実行しない。黙って落とさず、報告に番号と件数を残す

• 指示が一意に定まらない項目は実行の流れから外す。 コメントに条件が付いていて解釈が割れるなら、そのまま書き換えない。承認したものと違う結果が残る

• 確認事項への回答と、外した項目は対話へ戻す。 回答を踏まえて書き直し案を作り、承認を取り直してから実行する。回答を得た時点で実行に進むと、案を見せないまま書き換えることになる

• 再提示は会話の中で行う。 HTML は改めて求められたときだけ作る。1回目に求められたことを2回目の希望と見なさない（ページ1枚の生成は待ち時間を伴う）

• ファイルの新規作成・統合・削除を伴う場合は、1natsu-document-harness-model の配置判断に従う

• 重複の統合では、情報の欠落がないよう内容をマージしてから元ファイルを削除する

• 参照の修正では、関連する全ファイル（CLAUDE.md の @ 参照、rules/ の paths、markdown リンク）を連動して更新する

• コード乖離の修正では、置換後の値（正しいパス・名前・定数）を必ずコードで裏取りしてから書く。推測で埋めない。挙動依存で静的に確定できない事実は、実測するか「要検証」として残す

• 実装結合の是正では、記述を消すだけでなく再蒸留する（契約はルールへ、機構名は docs/ の rationale へ。検出側の着眼点・判断基準は本スキルのステップ2 ＋ 1natsu-document-harness-model「実装の偶有を仕様に蒸留する」）

• 用語・文体の是正は書き換えであって削除ではない。比喩・造語は指している実体に置き換え、ダッシュは接続詞と読点・:・文の分割へ書き直す。文意が変わらないことを確認する（実体が確定できない箇所は書き換えず、確認待ちとして残す）

• メモリ側に手を入れる前に、メモリストア全体を一時ディレクトリへバックアップする。メモリはリポジトリ管理外で git から復元できないため、削除・書き換えの取り消し手段はこのバックアップだけになる。実行日時入りのディレクトリを作り、メモリディレクトリを丸ごとコピーする。

BACKUP=$(mktemp -d "${TMPDIR:-/tmp}/memory-audit-backup.XXXXXX") &&
  cp -R <メモリディレクトリ>/. "$BACKUP/" &&
  echo "backup ok: $BACKUP"

backup ok: が出力されなければ削除へ進まない。 各段を && で繋ぐのは、途中で失敗した時に後続を止めるため。繋がないと、mktemp が失敗して $BACKUP が空のまま cp の宛先が / になり、あるいは cp が失敗したことに気づかないまま削除だけが実行される。バックアップの成否は削除の前提条件であって、独立した手順ではない。

mkdir と時刻でパスを組み立てない。同じ秒に走ると既存ディレクトリを黙って再利用し、権限も umask 次第（実測で drwxr-xr-x）になる。メモリには個人的な内容が入るので、mktemp -d が作る drwx------ を使う。テンプレートに ${TMPDIR:-/tmp} を明示するのは、素の $TMPDIR が未定義環境でルート直下を指し、バックアップを取れないまま削除へ進むため。削除対象ファイル単体でなくストア全体を取るのは、連動更新でインデックスや他メモリの [[name]] も書き換わるためで、部分バックアップでは変更前の状態に戻せない。このパスはステップ7で必ず報告する

• メモリの蒸留（M1/M3）では、リポジトリ側への書き込みとメモリ側の削除を1セットで行う。片方だけだと正本が二重化し、次の乖離の種になる
• メモリを削除する時は必ずインデックスファイル（Claude Code は MEMORY.md）の該当行も同時に削除し、削除対象を指すインバウンド参照リンク（[[name]]）も参照元を洗い出して削除／張り替える。蒸留（M1/M3）だけでなく純粋な削除（M4 陳腐化・M5 重複）でも同じ。実体だけ消してインデックス行や dangling リンクを残すと参照切れになる（連動先の具体構造はエージェント別リファレンスを参照）
• メモリの削除・書き換えは承認された項目に限り、承認範囲を超えて「ついでに」他のメモリへ手を入れない。バックアップがあることは承認範囲を広げる理由にならない

ステップ7: 結果報告

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

• 変更したファイルのリスト（リポジトリ側とメモリ側を分けて示す。メモリ側の変更は git に残らないため、何を削除・蒸留したかをここで明示する）
• 各変更の概要（追加 / 更新 / 削除 / 統合 / 蒸留）
• メモリ側に変更を加えた場合は、そのメモリ側の報告の中に注釈として、ステップ6で取ったバックアップの扱いを添える: バックアップのパス、そこからコピーで戻せば変更前の状態に復元できること、内容を確認して不要になった時の削除コマンド（例: rm -rf <バックアップパス>）。バックアップは独立した作業ではなくメモリ変更の安全策なので、報告でも独立セクションにせずメモリ側の変更に付随させる（読み手が「メモリに何をしたか」と「戻したい時どうするか」を1箇所で読めるように）。$TMPDIR 配下は OS の再起動や定期掃除で消えうる一時保管のため、長期に残したい場合は恒久的な場所へ移すことも添える
• スキップした項目がある場合はその旨も記載する