hirokimry/harvest-all

ultrathink

🧹 全量棚卸しスキル

[!IMPORTANT] このスキルは コードベース全体を走査 し、ドキュメント化されていない暗黙知を docs/ / .claude/rules/ / .claude/knowledge/ に直接反映する。 初期導入時や定期棚卸し用のオンデマンドスキル。 ユーザーが個別承認した項目のみを反映する（暗黙的に大量のファイルを書き換えない）。 harvest-all-active スタンプを設置して protect-knowledge-direct-writes.sh を通過させる。スタンプは fail-secure 設計（decisions/ / audit-*.md は常に deny）。

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

📖 使用方法

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

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

🌳 worktree モード

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

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

⚙️ 前提条件

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

🤝 /vibecorp:session-harvest との使い分け

| スキル | 使い所 | |---|---| | /vibecorp:session-harvest | セッション中の暗黙知をマージ前に吸い上げる日常ツール。session-harvest-gate と連携し、PR マージ前のゲートとして機能する | | /vibecorp: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 の場合はこのレポートを出力して終了する。

6.5. ガードレール一時通過スタンプの設置（必須）

/vibecorp:harvest-all は .claude/knowledge/ への作業ブランチ直書きを行うが、protect-knowledge-direct-writes.sh フックがこの直書きを deny する設計である。本スキルはユーザーが個別承認した項目のみを反映するオンデマンドツールであり、docs/specification.md の「作業ブランチ直接書込フロー」例外として明示されているため、ステップ 7 の反映前に harvest-all-active スタンプを設置してフックを通過させる。

ただしスタンプは fail-secure 設計: .claude/knowledge/{role}/decisions/ および .claude/knowledge/accounting/audit-*.md / .claude/knowledge/security/audit-*.md への直書きはスタンプの有無にかかわらず常に deny される（C*O 判断記録 / 監査の責務領域は本スキルのスコープ外）。

# 反映前: ガードレール一時通過スタンプの設置
. "$CLAUDE_PROJECT_DIR/.claude/lib/common.sh"
stamp_dir="$(vibecorp_state_mkdir)"
touch "${stamp_dir}/harvest-all-active"
trap 'rm -f "${stamp_dir}/harvest-all-active"' EXIT

ステップ 8（結果報告）の後にスタンプを削除する（trap で異常終了時も削除されるが、正常終了時の明示削除も行う）。

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

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

反映ルール:

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

反映時の制約:

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

8. 結果報告

## /vibecorp:harvest-all 完了

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

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

9. スタンプ削除（必須）

ステップ 6.5 で設置した harvest-all-active スタンプを削除する。trap で異常終了時も削除されるが、正常終了時の明示削除も行う。

rm -f "${stamp_dir}/harvest-all-active"

🛡️ buffer worktree 経由ではない理由

本スキルはユーザーが個別承認した項目のみを反映するオンデマンドツール。承認済み項目は session-harvest 等の自動収集と異なり、ユーザー判断で main へ直接 PR 化する想定。docs/specification.md の「作業ブランチ直接書込フロー」例外として明示されている。

Phase 4 のガードレール hook（protect-knowledge-direct-writes.sh）を通過させるため、ステップ 6.5 で harvest-all-active スタンプを設置する。スタンプは fail-secure 設計で、decisions/ および audit-*.md パターンには適用されない（C*O 判断記録 / 監査は本スキルのスコープ外）。

🛟 介入ポイント

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

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

🚧 制約

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

🔗 関連ルール

• 動作主語ルール: .claude/rules/communication.md
• プロンプト作成基準: .claude/rules/prompt-writing.md
• マークダウン規約: .claude/rules/markdown.md
• シェル規約: .claude/rules/shell.md
• 兄弟スキル（セッション知見吸い上げ）: /vibecorp:session-harvest
• 兄弟スキル（PR レビュー指摘収集）: /vibecorp:review-harvest