harvest-all

コードベース全体を棚卸しし、ドキュメント化されていない暗黙知を洗い出して docs/ / .claude/rules/ / .claude/knowledge/ に直接反映する。 初期導入時や定期棚卸し用のオンデマンドスキル。 「/harvest-all」「棚卸し」「全量棚卸し」と言った時に使用。

SKILL.md

GitHub

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