1natsu document harness

ハーネスドキュメント生成・更新

現セッションで実装した変更を、プロジェクト全体で一貫した粒度・配置でハーネスドキュメントに反映するワークフロー。

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つずつ分類する。各変更について:

1. どの層に属するか特定する（指示 / インデックス / 知識）。契約・ポリシー（実装が変わっても守るべき不変条件）は指示層であり .claude/rules/ に rule 化する（例「クライアント単位でレート制限する」「レスポンスは snake_case」「トークンは15分で失効」）。現状の振る舞いの説明に見えても、今後の実装が守るべき約束なら docs だけで済ませず指示層に落とす（docs には理由・背景を rationale として置く）。
   • 判定: 「将来この記述に反する変更が入ったらバグ／リグレッションになるか？」Yes なら指示層の契約 = rule 化する。「行動を縛る指示が無い」と早合点しない（不変条件はそれ自体が全ての将来実装を縛る指示）
   • ただしコード・型・テストから自明に読める契約はステップ1.5 の omit が先。rule 化するのはドキュメントでしか伝わらない契約に限る
2. 対象ファイルを決定する（既存ファイルへの追記 or 新規ファイル）
3. monorepo の場合、知識のスコープがパッケージに閉じるかリポジトリ全体かを判定し、docs/ の配置先を決める
4. 既存ファイルへの追記が可能な場合は新規作成より優先する
5. ロード戦略を選ぶ: 既定は lazy（paths スコープ rule / プレーンポインタ / skill）。eager（CLAUDE.md 本体 / paths なし rule / @-import）にする場合は、その場に意図マーカーを残す

判断基準・フローチャート・eager/lazy の選び方・意図マーカーの記法は 1natsu-document-harness-model スキル（「コンテキスト経済」セクション）を参照。

ステップ4: 一貫性チェック

ドキュメントを書く前に、既存ドキュメントとの一貫性を確認する。

• 粒度: 既存の同レベルドキュメントと同じ詳細度か
• 構成: 既存のセクション構成・見出しレベルに揃えているか
• トーン: 既存の文体（体言止め / 文末表現 / 言語）に合わせているか
• 参照: docs/ 等へのポインタを更新したか（背景知識はプレーンポインタ＝必要時 Read、@ は全セッション必読時のみ）
• 重複: 他のドキュメントと内容が被っていないか

ステップ5: ドキュメントの生成・更新

以下の優先順位で作業する:

1. 既存ドキュメントの更新（古くなった記述の修正、新情報の追記）
2. CLAUDE.md からのポインタ追加（新しい docs/ ファイルへのリンク。背景知識はプレーンポインタ＝必要時 Read。@ インポートは起動時フルロードで節約にならないため、全セッション必読の共有ファイルに限る）
3. 新規ドキュメントの作成（必要な場合のみ）

既存ドキュメントの更新を最優先にする理由: 新規ファイルを作るとメンテナンス対象が増え、将来の陳腐化リスクが高まる。既存ファイルに追記できるなら、情報の散逸も防げる。

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 として書いたか（「行動を縛る指示が無い」と見送っていないか）
• ルールに機構名（ライブラリ・ミドルウェア名）を書いた場合、それは「今後もそれを使え」という義務か（単なる現状報告でないか）
• 変更で古くなった既存ドキュメントを更新したか
• スコープ外（現セッションで触っていない領域）のドキュメントを誤って編集していないか
• sync モードの場合: 前回出力に残っていた古い前提の記述を消去・修正できているか

確認結果をユーザーに報告し、生成・更新したファイルの一覧と各ファイルの概要を提示する。sync モードで削除を行った場合は、削除した内容の概要も併記する。