# 1natsu Document Harness

> 現セッションで実装した変更（プラン実装後・機能追加後・追加バグ修正後・実装方針乗り換え後）に対して、プロジェクトのハーネスドキュメント（CLAUDE.md, .claude/rules/, docs/, feature README, コード内コメント）を一貫した粒度と適切な配置で生成・更新する。「ドキュメント化して」「ハーネス更新して」「実装をドキュメントに反映して」「CLAUDE.md更新して」「rulesファイル追加して」等と言われた時、またはプラン完了後・実装変更後にドキュメント反映が漏れていそうな時に使用する。同一セッション内で既に harness を実行済みの場合は sync モードで前回出力との差分を追従して更新・削除する。セッションをまたぐ既存ドキュメント全体の検査・陳腐化レビューは `1natsu-document-harness-audit` を使う。

- Skill: `1natsu-vacation/1natsu-document-harness` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add 1natsu-vacation/1natsu-document-harness`
- Raw SKILL.md: https://api.skillmd.com/api/skills/1natsu-vacation/1natsu-document-harness/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- License: MIT
- Author: 1natsu-vacation (https://skillmd.com/u/1natsu-vacation)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/1natsu-vacation/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、`@` は全セッション必読時のみ）
- **重複**: 他のドキュメントと内容が被っていないか

**既存に関係なく守る項目**（`1natsu-document-harness-model`「用語と文体」）:

- **実体の名指し**: 比喩由来のジャーゴンや造語で埋めず、指している対象を名指しする。名指しできない箇所は書かずに確認を取る。既に使われている語があるならそれに合わせ、同じ概念に別の語を持ち込まない
- **規範に作業記録を混ぜない**: 日付・依頼者・修正回数など、削っても規範の妥当性を判断できる情報は書かない。捨てた選択肢の棄却理由のように、削ると判断できなくなる根拠は残す
- **ナラティブにしない**: 時系列で語らず、その節だけ読んで意味が通る形で書く
- **日本語で書く場合**: 技術用語は原語のまま（pull request、dry run 等）、ダッシュ（`—` `–` `―` `─`）を使わない

**コード内のコメントもハーネスドキュメントの一部**なので、今回の実装で自分が書いた日本語コメントにも同じ基準を当てる（`1natsu-document-harness-model`「3層モデル」）。ただし触れるのは**コメント本文だけ**で、コードには手を入れない。「ドキュメントに反映して」という依頼で実装が変わるのは想定外なので、コメントを直したら報告に明記する。

これらは既存ドキュメントが違反していても合わせない。合わせると違反が複製され、次の書き手には「このリポジトリの文体」に見える。ただし直すのは今回自分が書く記述と、そのために触る既存記述まで。リポジトリ全体の一斉是正は `1natsu-document-harness-audit` の責務で、ここでスコープを広げない。

### ステップ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 として書いたか（「行動を縛る指示が無い」と見送っていないか）
- [ ] ルールに機構名（ライブラリ・ミドルウェア名）を書いた場合、それは「今後もそれを使え」という義務か（単なる現状報告でないか）
- [ ] 用語と文体の規約を通るか（比喩・造語でなく実体を名指し、規範に作業記録を混ぜていない、ナラティブでない）。既存の違反表現をそのまま踏襲していないか
- [ ] 日本語で書いた場合: 技術用語を原語のまま使い、ダッシュ（`—` `–` `―` `─`）を使っていないか（表の空セル・数値範囲は対象外）
- [ ] 変更で古くなった既存ドキュメントを更新したか
- [ ] スコープ外（現セッションで触っていない領域）のドキュメントを誤って編集していないか
- [ ] ステップ5 でソースファイルに入れた変更は、コメント本文だけか（実装のコードに手を入れていないか）。入れたなら報告に書いたか。**実装時のコード変更はここの対象ではない**
- [ ] sync モードの場合: 前回出力に残っていた古い前提の記述を消去・修正できているか

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