hirokimry/harvest-all

ultrathink

全量棚卸しスキル

コードベース全体を走査し、ドキュメント化されていない暗黙知を洗い出して docs/ / .claude/rules/ / .claude/knowledge/ に直接反映する。

使用方法

/harvest-all
/harvest-all --scope <path>
/harvest-all --dry-run
/harvest-all --scope src/ --dry-run
/harvest-all --worktree <path>

• --scope <path>: 走査対象ディレクトリを限定する。省略時はプロジェクトルート全体を走査する
• --dry-run: 反映せず、発見項目のレポートのみ出力する
• --worktree <path>: 指定パス内で全操作を実行する

worktree モード

--worktree <path> が指定された場合、全操作を指定パス内で実行する。

• Bash: 全コマンドを cd <path> && command で実行する
• Read/Write/Edit: <path>/ を基準とした絶対パスを使用する
• 未指定時は従来通り CWD で実行する（後方互換）

前提条件

• standard 以上のプリセットで利用可能

/session-harvest との使い分け

• /session-harvest: セッション中の暗黙知をマージ前に吸い上げる日常ツール。session-harvest-gate と連携し、PR マージ前のゲートとして機能する
• /harvest-all: コードベース全体を走査して暗黙知を洗い出すオンデマンドツール。初期導入時や定期棚卸し用に使用する

ワークフロー

1. 走査対象の確定

--scope が指定されている場合、そのディレクトリのみを走査対象にする。未指定時はプロジェクトルート全体を対象とする。

走査対象ディレクトリの存在を確認する:

ls -d <scope_path>

2. 既存ドキュメントの読み込み

棚卸し結果との重複を検出するため、現在のドキュメント群を読み込む。

読み込み対象:

• docs/ 配下の全 .md ファイル
• .claude/rules/ 配下の全 .md ファイル
• .claude/knowledge/ 配下の全 .md ファイル

各ファイルの内容を読み込み、既にドキュメント化されている知見の一覧を把握する。

3. コードベースの走査・分析

走査対象のコードベースを以下の3観点で分析する。

3a. docs/ 向け: 設計判断・アーキテクチャの暗黙知

以下のパターンを探索する:

• コード内の長いコメントブロックに埋もれた設計判断の理由
• 複雑な条件分岐の背景（なぜその分岐が必要か）
• 外部サービスとの連携仕様（API の使い方、制約、リトライ戦略等）
• データフロー・状態遷移の暗黙の前提
• アーキテクチャ上の重要な決定（ディレクトリ構成の意図、モジュール分割の理由等）

3b. rules/ 向け: コーディング規約・パターン

以下のパターンを探索する:

• コードベース全体で一貫して守られているが明文化されていないパターン
• 命名規則（変数名、ファイル名、関数名の慣習）
• エラーハンドリングの共通パターン
• import / require の順序規則
• コメント記法の慣習

3c. knowledge/ 向け: 仕様上の注意点・トラップ

以下のパターンを探索する:

• TODO, FIXME, HACK, XXX, WORKAROUND コメント
• 既知のバグや制限事項を示すコメント
• 外部依存の制約・互換性に関する注意書き
• エッジケースの処理に関する暗黙の前提

4. 重複検出・除外

ステップ 2 で読み込んだ既存ドキュメントと、ステップ 3 で発見した項目を比較する。

• 既にドキュメント化されている知見は除外する
• 部分的にドキュメント化されている場合は「追記が必要」として残す

5. 優先度・カテゴリ別の整理

発見項目を以下の基準で整理する。

カテゴリ:

| カテゴリ | 反映先 | |---------|--------| | 設計判断・アーキテクチャ | docs/ | | コーディング規約 | .claude/rules/ | | 仕様上の注意点 | .claude/knowledge/ |

優先度:

| 優先度 | 基準 | |-------|------| | 高 | 新規メンバーが躓く可能性が高い、セキュリティ・データ整合性に関わる | | 中 | 開発効率に影響する、繰り返し質問されそう | | 低 | 知っておくと便利、コードの理解が深まる |

6. ユーザーへの確認

発見項目の一覧をユーザーに提示し、反映の承認を求める。

## 棚卸し結果

### 発見項目一覧

#### docs/ 向け（設計判断・アーキテクチャ）
| # | 優先度 | タイトル | 根拠 | 反映先ファイル |
|---|--------|---------|------|---------------|
| 1 | 高 | {タイトル} | {該当コード箇所・理由} | {ファイルパス} |
| 2 | 中 | {タイトル} | {該当コード箇所・理由} | {ファイルパス} |

#### rules/ 向け（コーディング規約）
| # | 優先度 | タイトル | 根拠 | 反映先ファイル |
|---|--------|---------|------|---------------|
| 1 | 中 | {タイトル} | {該当コード箇所・理由} | {ファイルパス} |

#### knowledge/ 向け（注意点・トラップ）
| # | 優先度 | タイトル | 根拠 | 反映先ファイル |
|---|--------|---------|------|---------------|
| 1 | 高 | {タイトル} | {該当コード箇所・理由} | {ファイルパス} |

### サマリ
- docs/ 向け: {n} 件
- rules/ 向け: {n} 件
- knowledge/ 向け: {n} 件
- 合計: {n} 件

反映しますか？
- 全て反映する場合: y
- 選択して反映する場合: 番号をカンマ区切りで指定（例: 1,3,5）
- 中止する場合: n

--dry-run の場合はこのレポートを出力して終了する。

7. ドキュメントへの直接反映

ユーザーが承認した項目について、該当ファイルに直接反映する。

反映ルール:

| カテゴリ | 反映方法 | |---------|---------| | docs/ 向け | 既存ファイルに追記、または新規セクション追加。既存の記述スタイルに合わせる | | rules/ 向け | 既存の rules ファイルに追記、または新規 .md ファイル作成。1ルール1ファイルの原則に従う | | knowledge/ 向け | 該当ロールの knowledge ディレクトリに追記、または新規ファイル作成 |

反映時の制約:

• 既存ファイルに追記する場合、既存の記述スタイル・フォーマットを維持する
• 新規ファイル作成時は、同ディレクトリの既存ファイルの命名規則に従う
• knowledge/ の記事は、既存の記事がある場合は追記する（新規ファイル乱立を防ぐ）

8. 結果報告

## /harvest-all 完了

### 反映内容
| # | カテゴリ | 優先度 | タイトル | 反映先 |
|---|---------|--------|---------|--------|
| 1 | docs/ | 高 | {タイトル} | {ファイルパス} |
| 2 | rules/ | 中 | {タイトル} | {ファイルパス} |

### サマリ
- 走査対象: {スコープ}
- 発見項目: {n} 件
- 重複除外: {n} 件
- 反映済み: {n} 件
- スキップ（ユーザー判断）: {n} 件

介入ポイント

以下の状況ではユーザーに報告して判断を委ねる:

| 状況 | タイミング | |------|-----------| | 走査対象ディレクトリが存在しない | ステップ 1 | | 発見項目が 0 件 | ステップ 5 | | ユーザーが反映を承認しない | ステップ 6 | | 反映先ファイルの編集で競合が発生する | ステップ 7 |

制約

• --force、--hard、--no-verify は使用しない
• ユーザーの明示的な指示なしに force push しない
• jq では string interpolation \(...) を使わない — Bash 上で \ がエスケープ文字、() がサブシェルとして解釈され、意図しない展開やパースエラーを引き起こすため。必ず + で結合する
• コマンドをそのまま実行する — 2>/dev/null、|| echo、; echo 等のリダイレクトやフォールバックを付加しない（根拠）
• 介入ポイントではユーザーの指示を待つ（自動でスキップしない）
• 反映前に必ずユーザーの承認を得る（暗黙的に大量のファイルを書き換えない）