Maintenance Docs

ドキュメントの棚卸し

ドキュメントの現在の姿を10個の検査にかけ、出た指摘を仕分けて直す。変更差分ではなく現状を 見るので、git diff を起点にする code-review スキルとは対象が重ならない。

置き場と索引と「## タスク運用」節は、スキルが読み書きする契約であって好みで動かせる飾りでは ない。docs/history/progress.md が別名になっていればアーカイブは節を見つけられず、 - 検証コマンド: の行頭が変わっていれば /next-task は受け入れ判定のコマンドを読めない。 静かに壊れて、壊れたことに誰も気づかない種類のズレなので、定期的に見る価値がある。

対象

docs/**/*.md（docs/history/ を除く）と、リポジトリのルートの README.md・CLAUDE.md。

• docs/history/ 配下は対象外。 当時の記述をそのまま残すアーカイブで、今の姿と違って いるのが正しい。/plan-tasks と archive.py が機械的に積むので、索引にも載せない。 このスキルの報告もここへ書く（下の「報告を残す」）——点検の記録が点検対象になると、 自分が書いた実在しないパスの引用や見出しを次回に拾い、回すたびにノイズが増える
• 検査9（索引の無い大きなドキュメント）だけは README.md・CLAUDE.md を見ない。 この2つは通読される前提の入口なので、目次が無くてよい

出すもの / 出さないもの

出す: 検査の指摘を仕分けた一覧（端末へ）、確定群の修正、承認された候補群の修正、 そして同じ内容を docs/history/maintenance/<YYYY-MM-DD>.md に残した報告。

出さない:

• 新しいドキュメント。 提案書は architecture-proposal、用語集と ADR は domain-modeling、 調査メモは research が書く。このスキルは既にあるものの位置・索引・参照を直すだけ
• 中身の良し悪し（説明が下手、情報が足りない）。コードとの突き合わせが要る別の仕事
• タスクの登録とコミット（下の手順7）

判断は1問で決める

指摘を2群に分ける。確定群は直せば必ず正しくなるもの、候補群は次の1問で正否が決まるもの。

その記述は、今の姿の説明として書かれているか、それとも**昔の話（経緯の記録）**か。

昔の話なら正当で、直すと経緯が失われる。今の姿の説明なら実物とのズレ。この1問は機械化 しない——ドキュメントが何を語ろうとしているかは文脈でしか決まらないので、検査は候補を 挙げるところまでで止める。

判断の根拠になる置き場の正典は、スキルの側にある（このスキルに写し取ると、片方だけ直したときに 気づけなくなる。検査の == 参考 canon == 節が実行時の地図になる）:

判定がスキルの文面の細部にかかるときは、表を信じずその節を読む。

検査項目

検査6〜10が候補群なのは、そのままで正しい場合があるから:

• 検査6 — 「以前は src/old.ts にあった」という経緯の記録なら正当。今の姿の説明として 書かれているならズレ。ちょうど上の1問が効くところ
• 検査7 — 種類はファイル名ではなく中身で決まる。notes.md が実質 ADR のことも、 adr-ideas.md がただのメモのこともある。検査は手がかりを出すだけなので、見出しを見て 迷ったら開く
• 検査8 — 片方が参照でもう片方が本文なら正当。両方が本文なら正典の二重化。 同じ見出しが3ファイル以上にあるもの、および ADR や調査メモが共有する書式の見出し （「状況と決定」「一次情報」など）は、規約とみなして指摘に出ない（誤検知になるため）
• 検査9 — 通読させる気で書いた長文なら目次は要らない。索引を足すか、分けるかの判断が要る
• 検査10 — プロジェクト側で意図して同名にしていることがある。ただしユーザー単位スキルは プロジェクト単位の同名スキルより優先されるので、SHADOWED はほぼ意図と違う

検査を走らせる

リポジトリのルートで実行する（別の場所を見るならルートを引数で渡す）:

python3 ${CLAUDE_SKILL_DIR}/scripts/check_docs.py

出力の読み方:

docs/ を全文読まない。 指摘に出たファイルだけを、指摘された箇所を確かめるために開く。 棚卸しでコンテキストを使い切ると、直すところまで届かない。

「無い」ことは指摘にならない

docs/ 系は遅延作成で、書くべき内容ができたスキルがそのとき作る。次はすべて正常であり、 検査も報告も出さない:

• docs/ そのものが無い（まだ何も書いていないプロジェクト）
• docs/README.md が無く、索引に載せるべきファイルも無い
• docs/adr/ や docs/research/ が無い、docs/history/ が無い
• 正典が「ここに置く」と言っているだけで、まだ書かれていないパス（検査6が差し引く）

逆に、中身の無い索引が先回りして置かれているのは指摘（検査3）。次に書く人に「ここに 載せる運用がある」と誤解させるだけで、遅延作成の意図に反する。

develop/ の3ファイルは遅延作成ではない。3つとも無いのはタスク運用を使っていないだけ だが、節があるのに一部だけ欠けているのはズレ（検査5）。

手順

1. 前回の報告を読んでから、検査を走らせる。 docs/history/maintenance/ があれば いちばん新しい1件だけ開く（無ければ初回）。前回の「承認待ち」がそのまま残っている なら、今回も同じ指摘が出るはずで、同じ質問を繰り返さずに「前回から未回答」と 添えられる。読んだら上のコマンドをそのまま実行する。

2. 仕分ける。 検査番号・ファイル・件数の一覧を出す。確定群と候補群を混ぜない—— 全件が同じ重さに見えると、ユーザーは結局すべてを自分で確かめ直すことになる。 候補群は1件ずつ、上の1問にどう答えたか（今の姿か昔の話か）を1行で添える。

3. 全件を片付けに行く。聞くのは、答えが決まらないものだけ。 出た指摘は最後まで 面倒を見る。残すのは既定ではなく例外で、例外に回すたび、それが未対応だと ひと目で分かる形にする責任が生まれる。

   分かれ目は指摘の確かさではなく、直し方が一意に決まるか。確定群かどうかは 「ズレているか」の話で、そのまま直せるかは「答えが1つか」の話なので、重ならない。

   • 答えが1つのものは、そのまま直す。 索引に足す、索引のリンクを実在する 後継ファイルへ向け直す、欠けた行を なし で補う——正典が答えを持っている。 「洗い出して」と頼まれた場合でも直す（頼んだ人が欲しいのは、直っている状態と 何を直したかが分かる報告であって、宿題ではない）
   • 答えが割れるものは、その場で聞いてから直す。 典型は検査4のリンク切れで、 指す先がどこにも無いとき 消す／別のファイルへ向ける／実体を書く の3択になる。 候補群の1問（今の姿の説明か、昔の話か）も同じ。最後まで抱えて「承認待ち」として 差し出さない——答えをもらってから直すところまでが1回の棚卸し
   • 聞くのは1回にまとめる。 検査と仕分けを終えた時点で、聞くべきものを全部並べて 一度に出す。1件ずつ止めると往復が増えるうえ、読む側も全体を見てからのほうが 答えやすい
   • 判断した結果「直さないのが正しい」も、片付いたうち。 候補群を読んで 「昔の話として正当」と決めたなら、それは未対応ではなく対応済み。 報告でも保留と混ぜない
   • 例外は明示の指示。 「見るだけにして」「まだ触らないで」と言われたらそれに従う。 原則は既定であって、はっきり言われたことを上書きしない

   聞けないとき（/loop や委譲で動いているとき）は、答えが要るものだけが残る。 このときは**「棚卸し完了」と書かない。** 報告の冒頭を「未対応 N 件」で始めて、 残件と、それぞれ何を聞きたいのかを先に出す（下の「完了報告のフォーマット」）。 直したぶんはその後ろ。全部片付いたように読める報告が、いちばん害がある。

4. 直す。 答えをもらったものは、その答えのとおりに直す。

   • 指摘の解消に必要な最小限の編集にとどめる。ついでの整形、言い回しの改善、節の 並べ替えをしない。棚卸しで文面が勝手に変わると、次から点検を任せてもらえなくなる
   • ユーザーが書いた散文を書き換えない。 行頭・置き場・索引の形を直すだけ
   • 検査8で「本文が二重にある」と決まったものは、正典側を残して他方を参照に置き換える （両方を消さない・両方を残さない）
   • ファイルを移したら、索引の行と、そのファイルを指している記述も一緒に直す （片方だけ直すと新しいズレを作る）
   • develop/ の3ファイルと「## タスク運用」節の骨組みは手で書かず /setup-tasks （節名がズレるとアーカイブが節を見つけられない）

5. 検査をもう一度走らせる。 直した指摘が消え、新しい指摘が増えていないことを確認する。

6. 整形コマンドを通してから、検証コマンドを通す。 どちらも CLAUDE.md の 「## タスク運用」節にある（なし なら飛ばす）。順番が要る——整形を先に通さないと、 検証が整形の差分で落ちる。

   ドキュメントだけの変更でも省略しない。 リンク切れや索引の整合を検証に組み込んで いるリポジトリがあるうえ、Markdown の表は整形の対象で、セルの文字数が変われば桁が ずれる。実測した例では、表の中のリンクの表示文字列が数文字短くなっただけで format:check が落ちた。棚卸しは表の行を足したり書き換えたりする作業なので、 これはむしろ起こりやすいほう。

7. 報告を残す。 端末に出した内容を docs/history/maintenance/<YYYY-MM-DD>.md にも 書く（上の「報告を残す」）。

8. コミットしない。 何をどう直したかを報告して終わる。タスクの一部として呼ばれたなら コミットは呼び出し元（/next-task）の手順に属し、単独で呼ばれたならコミットの単位を 決めるのはユーザー。push も明示的に頼まれたときだけ。

どちらに寄せるか

ズレは「どちらかが間違っている」ではなく「どちらに寄せるか」の問題。既定はこう:

迷ったら聞く。 ドキュメントは人が読むためのもので、勝手に寄せて意図を壊すより、1行聞く ほうが安い。

報告を残す

端末に出すのと同じ内容を docs/history/maintenance/<YYYY-MM-DD>.md に書く （日付は date +%F）。ディレクトリが無ければそのとき作る。

• docs/README.md の索引には載せない。 docs/history/ 配下は索引の対象外
• 同じ日に2回走らせたら上書きする。 その日の最新の姿が1件あればよく、 同じ日の途中経過を積む価値は無い
• 端末の報告が主で、ファイルは控え。ファイルに書いたから端末では省く、をしない ——頼んだ人はその場で読みたい

残す理由は未対応の引き継ぎ。聞けば片付くものは1回で片付くが、聞けない状況で 走った回は答え待ちが残る。どこまで聞いて何が未回答かが記録されていないと、次に 走らせた人が同じものを同じ言葉でもう一度差し出すことになる。

完了報告のフォーマット

端末と docs/history/maintenance/<YYYY-MM-DD>.md の両方に、この順で示す。

1行目は状態。 すべて対応済み（N件） か 未対応 N 件 / 対応済み M 件 のどちらか。 読む人が最初に知りたいのは「閉じてよいか」で、それ以外の情報は全部その後でいい。

未対応があるなら、それを先に出す。 1件ずつ、何を聞きたいのかと選択肢を添える。 直した話を先に読ませると、そこで満足して残りを読まずに閉じる——この報告で いちばん避けたい壊れ方がそれ。

そのあとに:

• 検査番号ごとの指摘件数（実行前 → 実行後）。 0件だった検査も0と書く（見たことの証拠になる）
• 対応済みの内訳。 直したものと、判断した結果そのままが正しかったものを分けて書く （後者も対応済みで、未対応ではない）
• 正典を寄せ替えたなら、どちらを正典にしてどちらを参照にしたか
• 整形コマンドと検証コマンドの結果（走らせなかったなら、その理由）

「完了」「片付いた」と書けるのは、未対応が0件のときだけ。

やりがちな失敗

• docs/ を全部読んでから考え始める。 検査が指したファイルの、指された箇所だけを開く
• 「無い」ものを並べる。 遅延作成の原則があるので、欠けていること自体はズレではない。 ADR が無いプロジェクトに「ADR がありません」と報告しても、誰も得をしない
• 確定群を報告だけして返す。 直し方が一意に決まるものは直すのが原則（手順3）。 「洗い出して」と言われたことを、直さない理由にしない
• 逆に、答えが割れるものまで黙って直す。 指すべき先が無いリンクを勝手に消すと、 「書く予定だった」のか「消し忘れ」なのかの区別が失われる。選択肢を並べて聞く
• 聞けるのに聞かず、「承認待ち」として持ち帰る。 聞けば1回で終わるものを 次のセッションへ送ると、同じ棚卸しを2回やることになる（手順3）
• 未対応があるのに「完了」と書く。 読んだ人は片付いたと思って閉じる。 1行目を状態にして、残件を先に出す
• 候補群を確定群として直す。 経緯の記録を「実物と違う」と言って消すと、なぜ今の形に なったかが失われる。1問に答えてから触る
• 点検のついでに書き足す。 足りない説明を見つけても、それは別の仕事。見つけたことだけ 1行添えて、このスキルでは書かない
• 直して終わりにする。 手順5をやらないと、直した拍子に作ったリンク切れに気づけない