1natsu-vacation ハーネスドキュメント生成・更新
現セッションで実装した変更を、プロジェクト全体で一貫した粒度・配置でハーネスドキュメントに反映するワークフロー。
3層モデルの定義、配置先ルール、配置判断フローは 1natsu-document-harness-model スキルを参照。
このスキルを使うべきか判定
| 状況 | 使うスキル |
|---|---|
| 現セッションで実装した変更を初めてドキュメント化する | harness (init モード) |
| 同一セッション内で既に harness を実行済み、追加修正・実装乗り換え・バグ修正が入った | harness (sync モード) |
| 過去セッションで書かれた既存ドキュメントの陳腐化・不整合を検査したい | 1natsu-document-harness-audit |
| AIツール・モデル能力進化に伴うドキュメント表現の見直し | 1natsu-document-harness-audit |
迷ったら判定の軸は「今セッションで自分が触った変更を反映したいか」。Yes なら harness、それ以外（既存ドキュメントの検査）なら audit。
いつ使うか
- プランの実装が完了した後
- 新機能を追加・大幅変更した後
- アーキテクチャや設計方針を変更した後
- 同一セッション中に追加バグ修正や実装乗り換え（A → B）が発生し、既に出力したドキュメントを追従させたい時
- 「ドキュメント化して」「ハーネス更新して」と言われた時
ワークフロー
ステップ0: モードと作業範囲を判定する
まず init / sync を判定する。判定材料:
- 会話履歴: 同一セッション内で既に harness を実行した形跡があるか（生成したファイル一覧の報告、「ドキュメント化しました」等の応答）
- プランファイル / TodoList: ドキュメント化タスクが既に completed 状態か
- git の状態: 直近のコミットや uncommitted な差分にハーネスドキュメント（CLAUDE.md, .claude/rules/, docs/, feature README）への変更が含まれているか
判定:
- 上記いずれもなく、対象変更に対するドキュメント化が初めて → init モード
- 同セッションで既にドキュメントを書いたが、その後に実装が変わった / 追加された → sync モード
sync モードの場合は「前回出力した自分のドキュメントは、今の実装の最新状態と一致しているか」を最初に確認する観点を持つ。
ステップ1: 変更のスコープを把握する
「リポジトリ全体」ではなく「現セッションで触れた変更だけ」にスコープを絞る。無関係なファイルや既存ドキュメントを勝手に編集しない。
スコープは2軸の併用で確定する:
軸A: git による実装事実
git statusで uncommitted な変更ファイルを把握git diff <base-branch>...HEADでブランチ起点からの差分ファイル一覧を取得- これにより「実装として何が変わったか」のコード面が確定する
軸B: セッション作業成果物による意図・設計判断
- プランファイル（
~/.claude/plans/*.md等） - TodoList の履歴（completed タスクの内容）
- 会話文脈（直前の実装議論、A→B 乗り換えの経緯、「やっぱり〜にした」等の発言）
- これにより「なぜそう実装したか」「捨てた選択肢」「設計判断の根拠」が拾える
両軸の交集を主スコープ（=ドキュメント化対象）とし、片方にしかない情報は次のように扱う:
- 軸Aのみ（git に出るが会話に残っていない）: 機械的な refactor 等。既存ドキュメントの軽微な事実更新が必要な場合のみ反映
- 軸Bのみ（会話には出るが git に未反映）: 未実装の方針・棄却された案。ドキュメントには書かない
スコープ確定後、判断する:
- どのパッケージ / ディレクトリが影響を受けたか
- 新しいパッケージやディレクトリが追加されたか
- アーキテクチャレベルの変更か、機能レベルの変更か
ステップ1.5: 仕様へ蒸留する
配置の前に、各情報を仕様へ蒸留する。プラン・コード・差分をそのまま転記しない。捉えるのは「実装が変わっても保たれる契約・判断・理由」であって「今たまたまそうなっている事実」ではない。
変更のひとつひとつに swap test を当て（実装を別の妥当な方法に変えたら嘘になる記述＝偶有）、偶有は omit（コードから読める）/ rationale 化（判断・理由として docs/ へ）/ name（外部契約面の名前だけ名指し） に振り分ける。
特にルール（指示層）には機構名を持ち込まない。「Redis でレート制限する」ではなく「クライアント単位でレート制限する」とポリシーで書く（機構の使用そのものが今後の義務である場合だけ例外）。判定基準・3分類・例は 1natsu-document-harness-model「実装の偶有を仕様に蒸留する」を参照。
ステップ2: 既存ドキュメントの現状を調査する
変更に関連する既存ドキュメント（CLAUDE.md, .claude/rules/, docs/, feature README）をすべて読む。
確認ポイント:
- 既存ドキュメントの粒度・トーン・構成を把握する
- 今回の変更で古くなったドキュメントがないか特定する
- 重複しそうな記述がないか確認する
sync モードでの追加観点:
- 同セッションで自分が前に書いたドキュメントを再読し、「書いた当時の前提」と「今の実装」の差分を洗い出す
- A 実装の前提で書かれた説明が B 実装に変わったため不正になっていないか
- 追加修正で記述が不足していないか / 過剰になっていないか
- 削除すべき記述（捨てた A 案の痕跡）が残っていないか
ステップ3: 配置判断
変更内容を1つずつ分類する。各変更について:
- どの層に属するか特定する（指示 / インデックス / 知識）。契約・ポリシー（実装が変わっても守るべき不変条件）は指示層であり
.claude/rules/に rule 化する（例「クライアント単位でレート制限する」「レスポンスは snake_case」「トークンは15分で失効」）。現状の振る舞いの説明に見えても、今後の実装が守るべき約束なら docs だけで済ませず指示層に落とす（docs には理由・背景を rationale として置く）。- 判定: 「将来この記述に反する変更が入ったらバグ／リグレッションになるか？」Yes なら指示層の契約 = rule 化する。「行動を縛る指示が無い」と早合点しない（不変条件はそれ自体が全ての将来実装を縛る指示）
- ただしコード・型・テストから自明に読める契約はステップ1.5 の omit が先。rule 化するのはドキュメントでしか伝わらない契約に限る
- 対象ファイルを決定する（既存ファイルへの追記 or 新規ファイル）
- monorepo の場合、知識のスコープがパッケージに閉じるかリポジトリ全体かを判定し、
docs/の配置先を決める - 既存ファイルへの追記が可能な場合は新規作成より優先する
- ロード戦略を選ぶ: 既定は lazy（
pathsスコープ rule / プレーンポインタ / skill）。eager（CLAUDE.md 本体 /pathsなし rule /@-import）にする場合は、その場に意図マーカーを残す
判断基準・フローチャート・eager/lazy の選び方・意図マーカーの記法は 1natsu-document-harness-model スキル（「コンテキスト経済」セクション）を参照。
ステップ4: 一貫性チェックと用語・文体の規約
ドキュメントを書く前に、既存ドキュメントに合わせる項目と、既存に関係なく守る項目を分けて確認する。
既存に合わせる項目:
- 粒度: 既存の同レベルドキュメントと同じ詳細度か
- 構成: 既存のセクション構成・見出しレベルに揃えているか
- トーン: 既存の文体（体言止め / 文末表現 / 言語）に合わせているか
- 参照: docs/ 等へのポインタを更新したか（背景知識はプレーンポインタ＝必要時 Read、
@は全セッション必読時のみ） - 重複: 他のドキュメントと内容が被っていないか
既存に関係なく守る項目（1natsu-document-harness-model「用語と文体」）:
- 実体の名指し: 比喩由来のジャーゴンや造語で埋めず、指している対象を名指しする。名指しできない箇所は書かずに確認を取る。既に使われている語があるならそれに合わせ、同じ概念に別の語を持ち込まない
- 規範に作業記録を混ぜない: 日付・依頼者・修正回数など、削っても規範の妥当性を判断できる情報は書かない。捨てた選択肢の棄却理由のように、削ると判断できなくなる根拠は残す
- ナラティブにしない: 時系列で語らず、その節だけ読んで意味が通る形で書く
- 日本語で書く場合: 技術用語は原語のまま（pull request、dry run 等）、ダッシュ（
—–―─）を使わない
コード内のコメントもハーネスドキュメントの一部なので、今回の実装で自分が書いた日本語コメントにも同じ基準を当てる（1natsu-document-harness-model「3層モデル」）。ただし触れるのはコメント本文だけで、コードには手を入れない。「ドキュメントに反映して」という依頼で実装が変わるのは想定外なので、コメントを直したら報告に明記する。
これらは既存ドキュメントが違反していても合わせない。合わせると違反が複製され、次の書き手には「このリポジトリの文体」に見える。ただし直すのは今回自分が書く記述と、そのために触る既存記述まで。リポジトリ全体の一斉是正は 1natsu-document-harness-audit の責務で、ここでスコープを広げない。
ステップ5: ドキュメントの生成・更新
以下の優先順位で作業する:
- 既存ドキュメントの更新（古くなった記述の修正、新情報の追記）
- CLAUDE.md からのポインタ追加（新しい docs/ ファイルへのリンク。背景知識はプレーンポインタ＝必要時 Read。
@インポートは起動時フルロードで節約にならないため、全セッション必読の共有ファイルに限る） - 新規ドキュメントの作成（必要な場合のみ）
既存ドキュメントの更新を最優先にする理由: 新規ファイルを作るとメンテナンス対象が増え、将来の陳腐化リスクが高まる。既存ファイルに追記できるなら、情報の散逸も防げる。
sync モード時の追加挙動:
- 同セッションで前に自分が書いた記述のうち、「実装が変わって不正になった部分」は能動的に書き換え・削除する。古い記述を残さない
- A → B の乗り換え時は、A 案前提の説明・例・図解を消し、B 案ベースに置き換える
- 機構の乗り換え（Redis → LRU 等）は単純な名前置換で済ませない。swap test を当て直し、そもそもルールに機構名が載っていたなら、この機会にポリシー記述へ蒸留し直す。機構変更の経緯は docs の rationale に寄せる（ルールは機構非依存のポリシーに戻す）
- 追加修正で振る舞いが変わった部分は、既存記述に重ねるのではなく正しい記述に上書きする。置換後の値（パス・定数・名前）はコードで裏取りしてから書く（推測しない）
- 削除や大幅書き換えを行った時は、ステップ6 の最終報告で「削除した内容の概要」も伝える
配置先ごとの詳細なルールは 1natsu-document-harness-model スキルを参照。
ステップ6: 最終確認
すべてのドキュメント更新が完了したら、以下を確認する:
- CLAUDE.md が 200 行以下に収まっているか
- 新しい docs/ ファイルが CLAUDE.md からポインタで参照されているか（背景知識はプレーンポインタ。
@は全セッション必読時のみ） - eager にした記述（
pathsなし rule /@-import）に意図マーカーを付けたか -
.claude/rules/のpathsが正しいパターンか（パッケージ内 rule は rule の dir 基準＝パッケージ相対） - 既存ドキュメントとの重複がないか
- コードから読み取れることを冗長に書いていないか
- 各記述が swap test を通るか（実装を別の妥当な方法に変えても嘘にならないか）。偶有はルールに残さず docs の rationale か code に委ねたか
- 契約・ポリシー（不変条件）を docs だけに落とさず、指示層（
.claude/rules/）に rule として書いたか（「行動を縛る指示が無い」と見送っていないか） - ルールに機構名（ライブラリ・ミドルウェア名）を書いた場合、それは「今後もそれを使え」という義務か（単なる現状報告でないか）
- 用語と文体の規約を通るか（比喩・造語でなく実体を名指し、規範に作業記録を混ぜていない、ナラティブでない）。既存の違反表現をそのまま踏襲していないか
- 日本語で書いた場合: 技術用語を原語のまま使い、ダッシュ（
—–―─）を使っていないか（表の空セル・数値範囲は対象外） - 変更で古くなった既存ドキュメントを更新したか
- スコープ外（現セッションで触っていない領域）のドキュメントを誤って編集していないか
- ステップ5 でソースファイルに入れた変更は、コメント本文だけか（実装のコードに手を入れていないか）。入れたなら報告に書いたか。実装時のコード変更はここの対象ではない
- sync モードの場合: 前回出力に残っていた古い前提の記述を消去・修正できているか
確認結果をユーザーに報告し、生成・更新したファイルの一覧と各ファイルの概要を提示する。sync モードで削除を行った場合は、削除した内容の概要も併記する。