research-codebase

name	research-codebase
description	コードベースを深く調査し、research MDをObsidian Vault（my-vault）に生成する。 「コードベースリサーチ」「codebase research」「深く調査して」「research MD作成」 「コードを調査してresearchにまとめて」「リサーチして」などのリクエストで使用。 既存コードの理解、実装前の調査、アーキテクチャの把握が必要な場面で使用する。

コードベースリサーチ

コードベースを深く調査し、調査結果をObsidian Vault（my-vault）の 065_dev/ にresearch MDとして保存する。Boris Tane式ワークフロー（リサーチ → 計画 → 注釈サイクル → 実装）のリサーチフェーズを担う。

定数

定数	値
my-vaultパス	~/ghq/github.com/shifumin/my-vault
出力先	{my-vault}/065_dev/

処理フロー

1. 入力の確認

以下を確認（不足時はAskUserQuestionで質問）:

項目	必須	例
調査対象	必須	フォルダ、ファイル、機能名、概念
プロジェクト名	必須（cwdから推定可）	hanica, my-vault
調査の目的・背景	任意	「通知システムをリファクタしたい」

プロジェクト名はcwdの最後のディレクトリ名から推定する（例: /Users/shifumin/ghq/github.com/kufu/hanica → hanica）。

2. コードベースの深い調査

使用可能ツール制限: このスキルの実行で使用できるツールは Read・Bash（読み取り専用コマンド限定）・Write（ステップ3のresearch MD 1ファイルのみ）・Agent（ステップ2cの並列調査のみ）の4種のみ。 Editツールはこのスキルの実行中に絶対に使用しない。調査中に改善点・問題・バグを発見しても修正せず、発見事項をresearch MDに記録するにとどめる。

Bashで許可されるコマンドの例: date, git log, ls, find, grep, cat（いずれも読み取り専用）。ファイルを変更するBashコマンド（sed -i, tee, >>, >等）は使用禁止。

表面的に読むだけでは不十分で、動作の詳細と特異性をすべて理解する深さが必要（理由: 浅い理解で計画を立てると、既存パターンとの矛盾や見落としが発生し手戻りになるため）。

2a. 事前コンテキスト収集

Agentを立てる前に、プロジェクトのドキュメントを直接読む。ドキュメントにはコードからは読み取れない設計意図・制約・規約が凝縮されており、これを先に把握することで調査の方向性が定まり、Agent への指示の質が大きく変わる。

必ず読むドキュメント:

読むべきファイル	理由
プロジェクトルートの CLAUDE.md / README.md	全体のアーキテクチャ、規約、技術スタック
対象ディレクトリの AGENTS.md / README.md	ディレクトリ固有のガイドライン、設計判断
package.yml（packwerkプロジェクトの場合）	依存関係、privacy設定、パッケージの境界

調査対象に関連するドキュメントを探索:

上記に加え、Glob で関連ドキュメントを探す。これらは設計の「なぜ」を記録しており、コードの「何」だけでは分からない背景を補完する。

# ADR（Architecture Decision Records）
**/adr/**/*.md, **/decisions/**/*.md

# 設計ドキュメント・ワークフロー定義
**/docs/**/*.md, **/.ai/**/*.md

# 対象ディレクトリ配下の全ドキュメント
<対象ディレクトリ>/**/*.md

見つかったドキュメントのうち、調査対象に関連するものを読む（全部読む必要はない。ファイル名やディレクトリ構造から関連性を判断する）。

git history の確認:

# 対象領域の最近の変更履歴（設計意図や進化の方向が分かる）
git log --oneline -20 -- <対象ディレクトリ>

2b. 調査戦略の決定

対象の規模に応じてAgentの構成を変える（多すぎると各Agentが浅く広く読んでしまい、少なすぎると時間がかかる）。

対象規模	例	Agent数	分割の考え方
最小（単一ファイル）	単一クラス、単一スキルファイル	0（直接読む）	メインエージェントが直接Read/Grep
小（数ファイル〜1ディレクトリ）	ユーティリティクラス、Concern	1-2	実装の読解 + テスト・使用箇所の調査
中（1パッケージ・1モジュール）	packs/hatsurei/	2-3	構造・パターン / 依存関係・データフロー / テスト
大（複数パッケージ・システム全体）	Package API基盤全体	3-4	パッケージごと、またはレイヤーごとに分割

2c. 並列調査の実行

Agentツールで以下の観点を並列に調査する。各Agentへの指示には以下を含めること（理由: Agentはメインの会話コンテキストを持たないため、明示的に渡さないと規約を無視した調査になる）:

• 2aで得たコンテキスト（プロジェクトの規約、関連ADRの要点、git historyの傾向）
• 探索先ディレクトリで AGENTS.md を見つけたら最初に読むこと（各ディレクトリのAGENTS.mdにはそのレイヤー固有の規約やパターンが書かれている）

調査観点	具体的に見ること
アーキテクチャ	ディレクトリ構成、レイヤー分離、主要な抽象化
既存パターン・規約	命名規則、エラー処理パターン、ORM/フレームワークの使い方
依存関係・データフロー	関連するモジュール、呼び出し関係、データの流れ
エッジケース・制約	既知のワークアラウンド、パフォーマンス考慮、既知の問題
テスト	テストの書き方、カバレッジ、テストヘルパー

3. research MDの生成

重要: 調査結果をユーザーに回答する前に、必ずこのステップを完了すること。 調査が完了したら、まずMDを書き出す。ユーザーへの報告はステップ4で行う。

現在日時を date "+%Y-%m-%dT%H:%M" で取得し、Writeツールで以下のフォーマットで生成する。

ファイルパス: {my-vault}/065_dev/research_{プロジェクト名}_{調査内容}_{YYYY-MM-DD}.md

{調査内容} の命名ガイド:

タイトルだけで「何を調査したか」が伝わる説明的な名前にする。ファイル一覧での視認性が最優先なので、長くなっても問題ない。日本語を積極的に使い、技術用語（クラス名、API名等）はそのまま英語で残すと読みやすい。

悪い例（何の調査か不明）	良い例（一目でわかる）
package_api_result	PackageAPI-Resultの実装パターンと依存関係
claude-md-improvement	CLAUDE.mdのプロジェクト別設定の改善方針
asking-ais-parallel-sessions	asking-aisスキルの並列セッション管理の仕組み

フォーマット:

---
created_at: {YYYY-MM-DDTHH:MM}
updated_at: {YYYY-MM-DDTHH:MM}
tags: dev/research
project: {プロジェクト名}
target: {機能名}
status: done
---
## 要約

{調査結果の全体像を3-5文で。計画作成時にはこのセクションを優先参照する}

## 詳細

{調査対象に応じたセクションを構成する（下記ガイド参照）}

セクション構成のガイド:

固定テンプレートではなく、調査対象の性質に合わせてセクションを選ぶ（理由: 認証フローの調査に「キャッシュ戦略」セクションは不要だし、パフォーマンス調査に「命名規則」セクションは薄い。対象に合ったセクションにすることで、後続の計画作成で本当に必要な情報に集中できる）。

セクション	いつ含めるか
アーキテクチャ	ほぼ常に。ディレクトリ構成、レイヤー分離、主要な抽象化
既存パターン・規約	実装を伴う調査。命名規則、エラー処理、フレームワークの使い方
依存関係・データフロー	モジュール間連携がある場合。呼び出し関係、データの流れ
エッジケース・制約	ワークアラウンドや既知の問題がある場合
テスト	実装を伴う調査。テストの書き方、ヘルパー
セキュリティ	認証・認可・機密データを扱う場合
パフォーマンス	クエリ最適化・キャッシュ・N+1 が論点の場合
設計経緯・ADR	設計判断の背景理解が重要な場合。なぜこの設計になったか

全セクションを必ず含める必要はない。調査で実質的な発見がないセクションは省略し、重要な発見があるセクションを厚く書く。

すべてのセクションで具体的なファイルパスとコード例を含めること（理由: 後続の計画作成で実際のコードに基づいた判断ができるようにするため）。

4. 完了報告

生成したresearch MDのパスを報告し、次のステップ（plan MD作成）を案内する。