Codebase guide

🎯 目的

指定されたディレクトリについて、 レビュー者がコードベースを素早く理解できる資料を作成する。

このレポートは以下の目的を持つ。

• 新規開発者が構造を理解できる
• 重要ファイルの読む順番が分かる
• 代表的な処理の流れが理解できる
• 設計思想を推定できる
• 改善余地と強みを把握できる

⚠️ このレビューは「品質評価」ではなく
コードベース理解支援を主目的とする。

---

📥 入力

対象ディレクトリについて以下を取得する

• ディレクトリ構造
• ファイル構造
• import依存
• class / interface / function
• export構造
• エントリーポイント

---

⚙️ 準備

リポジトリ情報の確認

以下のコマンドは、スキルディレクトリ .agents/skills/codebase-guide/ からの相対パスである。

スキル実行時は、スキルディレクトリをカレントディレクトリにして以下を実行し、 リポジトリ情報を自動検出すること。

node scripts/init-repo-info.js

これにより assets/repo-context.md が生成され、以下の情報が取得される：

• OWNER: GitHub リポジトリのオーナー
• REPO_NAME: リポジトリ名
• BRANCH: 現在のブランチ名

これらの情報は、GitHub URL を構築する際に使用される。

⚠️ このステップは最初に実行すること

---

🧠 分析手順

以下の順序で分析すること。

---

① ディレクトリ構造理解

ディレクトリツリーを取得し、
各ディレクトリの役割を推定する。

以下を特定する

• 構造タイプ

  • Layer型
  • Feature型
  • Utility型
  • 混合型

• エントリーポイント

• 外部依存ポイント

⚠️ ツリー形式で視覚的に構造を表現する
⚠️ この例外は ① ディレクトリ構造理解 セクションのみ。ここではファイルリンクは不要で、ディレクトリリンクのみを記載する
⚠️ ファイルは列挙せず、ディレクトリ単位の役割整理に限定する
⚠️ ②以降のセクションでは、対象ファイルや関数への GitHub リンクを必ず記載する

---

② レビュー対象ファイル候補

理解に重要なファイルを抽出し、優先的に読むべきファイルを提示する。

選定基準

• エントリーポイント
• 多数からimportされている
• 抽象定義
• コアロジック
• 外部接続点

提示形式

各ファイルについて以下を明示する（テーブル形式または番号リスト）

• GitHubファイルリンク
• 役割
• 種別（抽象 / 実装）
• 依存特徴
• 選定理由（アーキテクチャ理解 / ビジネスロジック理解 / システム特徴理解のどれに対応するか）
• 読む優先度（1～10の相対優先度）

⚠️ 最大10個まで提示する

---

③ 依存構造解析

import関係から依存方向を分析する。

確認すること

• 依存方向
• 循環依存
• 横断依存
• 抽象依存 / 具体依存

依存構造は文章で説明する。

---

④ 代表的な処理フロー

コードベースの特徴が理解できる
代表的な処理フローを2つ抽出する。

例

• API処理フロー
• UI → Domain処理
• データ取得
• 状態更新

各フローについて

0. 何のフローか
1. 開始地点
2. 呼び出しチェーン
3. コアロジック
4. 最終結果

を具体的なファイル名や関数名を挙げて説明する。

⚠️ ④で参照する関数 / メソッド / クラスは、必ずコードスニペットリンク（#Lstart-Lend）で記載すること

---

⑤ 設計思想推定

以下を推定する

• レイヤード設計
• クリーンアーキテクチャ
• Feature中心設計
• モジュール設計
• スピード優先設計
• 技術負債許容設計

推定には

• 確度（高 / 中 / 低）
• 根拠

を必ず付ける。

---

⑥ 良い設計ポイント

このコードベースの

• 設計の良い点
• 保守しやすい点
• 拡張しやすい点
• 開発効率を高めている点

を構造的根拠付きで説明する。

⚠️ ⑥の各ポイントには、根拠となる関数 / メソッド / クラスのコードスニペットリンクを最低1つ含めること

---

⑦ 改善ポイント

以下の視点で改善案を提示する

• 開発効率向上
• 理解コスト削減
• 依存整理
• 責務分離

⚠️ 保守性だけでなく
開発スピード向上の観点で提案する。

⚠️ ⑦の各改善案には、対象となる関数 / メソッド / クラスのコードスニペットリンクを最低1つ含めること

---

⑧ 参考スコア

SOLID違反スコアリング

各原則を5段階評価。

1. S（単一責務）
2. O（拡張に開いているか）
3. L（置換可能性）
4. I（インターフェース分離）
5. D（依存逆転）

理解容易性（Comprehensibility）

以下を0〜5で評価し、100点換算する。

1. 責務の明確さ
2. 依存の追跡しやすさ
3. 抽象のわかりやすさ
4. 命名の意味性
5. 変更理由の想像しやすさ

---

📤 出力要件

出力ファイル名

以下の形式

review-codebase-{directory名}.md

例

review-codebase-domain.md
review-codebase-components.md

---

出力フォーマット

リンク形式

すべてのリンクは GitHub URL を使用すること。

フォーマット:

[{相対パス}](https://github.com/{OWNER}/{REPO_NAME}/blob/{BRANCH}/{相対パス})

関数 / メソッド / クラスへのリンク（コードスニペット）:

[{シンボル名}](https://github.com/{OWNER}/{REPO_NAME}/blob/{BRANCH}/{相対パス}#L{start}-L{end})

例:

• updateState 関数: https://github.com/1-10/public-skills/blob/develop/apps/app-nextjs/src/app/sugoroku/game/page.tsx#L42-L78

⚠️ 関数参照は必ず行範囲付き（#Lstart-Lend）のコードスニペットリンクを使用すること

テンプレート変数:

• {OWNER}: assets/repo-context.md の OWNER 値
• {REPO_NAME}: assets/repo-context.md の REPO_NAME 値
• {BRANCH}: assets/repo-context.md の BRANCH 値

例 (リポジトリが 1-10/public-skills の場合)

• ディレクトリ：https://github.com/1-10/public-skills/tree/develop/apps/app-nextjs
• ファイル：https://github.com/1-10/public-skills/blob/develop/apps/app-nextjs/src/app/sugoroku/game/page.tsx
• 関数スニペット：https://github.com/1-10/public-skills/blob/develop/apps/app-nextjs/src/app/sugoroku/game/page.tsx#L42-L78

⚠️ ローカルパスや workspace-local 相対パスは使用しない

---

出力テンプレート

詳細は assets/template.md を参照

---

⚠️ 制約

• 感覚的な批評は禁止
• 必ず構造的根拠を書く
• 推定には確度を付ける
• 出力はMarkdownファイルとして保存する