codebase-research

コードベースの調査

概要

既存のプロジェクトに新しいコードを書く前に、そのプロジェクトにすでに何があるのかを理解してください。コードベースそのものが、どのように構築すべきかを示す最も信頼できる情報源です。どのプロジェクトにも慣習、パターン、暗黙の基準が蓄積されており、新しいコードはそれらを尊重する必要があります。

基本原則： コーディングする前に、現在のコードベースを検索してください。類似するファイル、関数、パターンを見つけて、既存の慣習に正確に合わせてください。すでに方法が確立されているなら、別の方法を持ち込んではいけません。

例外なし。回避策なし。近道なし。

最優先の指針

NO NEW CODE WITHOUT UNDERSTANDING THE EXISTING CODE FIRST

同じパターンの既存実装を現在のコードベースで検索していないなら、一貫性を損なうおそれがあります。類似するものが見つからなかった場合は、何を検索したのかを記録してください。そのうえで、意図的に慣習を確立しながら実装してください。

言い訳は通用しません：

• 「とりあえずコーディングして、後で慣習を確認する」ことはしないでください
• 自分が好むパターンがプロジェクトのパターンだと思い込まないでください
• プロジェクトですでに同等のライブラリを使用しているなら、新しいライブラリを導入しないでください
• 既存の構成と矛盾する新しいファイル構成を作らないでください
• 「これが最善の方法だと思う」は、プロジェクトですでに別の方法が一貫して採用されているなら関係ありません

使用するタイミング

必須の場合：

• 既存のコードベースに新機能を追加するとき
• 新しいファイル、コンポーネント、モジュール、サービスを作成するとき
• プロジェクト内の別の場所にもありそうなパターンを実装するとき
• 既存の機能に対するテストを書くとき
• エラー処理、ログ記録、検証ロジックを追加するとき

特に有効な場合：

• プロジェクトに確立されたアーキテクチャパターン（MVC、ヘキサゴナルなど）がある
• 作成するものに類似した既存ファイルがある
• コードベースに独自のユーティリティ、ヘルパー、共有モジュールがある
• プロジェクトで特定の命名規則やコード構成のルールを使用している
• 期待されるテスト方法を示す既存のテストがある

開始時の手順

digraph codebase_research_gate {
    rankdir=TB;
    start [label="Task: Write new code\nin existing project", shape=doublecircle];
    search [label="SEARCH\ncurrent codebase for\nsimilar implementations", shape=box];
    found [label="Similar patterns found?", shape=diamond];
    analyze [label="ANALYZE\nConventions, structure,\nnaming, error handling", shape=box];
    template [label="Use as template?\n(follow the pattern)", shape=diamond];
    follow [label="FOLLOW\nMatch the existing pattern\nexactly", shape=box style=filled fillcolor=lightgreen];
    adapt [label="ADAPT\nUse the convention\nwith modifications", shape=box style=filled fillcolor=lightyellow];
    establish [label="ESTABLISH\nNo precedent exists;\ncreate a deliberate\nnew convention", shape=box];
    document [label="Document search results\nand decision rationale", shape=box];

    start -> search;
    search -> found;
    found -> analyze [label="yes"];
    found -> document [label="no"];
    document -> establish;
    analyze -> template;
    template -> follow [label="yes - close match"];
    template -> adapt [label="partially - same idea\ndifferent details"];
}

既存のプロジェクトに新しいコードを書く前に：

1. 検索 -- 類似するファイル、関数、パターン、慣習をコードベースから探します
2. 分析 -- 既存のコードが同じ課題をどのように扱っているかを調べます
3. 適合 -- 新しいコードを確立された慣習に合わせます
4. その後で初めて -- コードを書き始めます

検索方法

検索対象

新しいものを作成する前に、コードベースで次の項目をそれぞれ検索してください。

検索対象	理由	方法
類似するファイル	参考にするひな形を見つける	類似した名前のファイルや、類似したディレクトリにあるファイルを Glob で検索します
類似する関数	関数シグネチャやパターンを合わせる	類似した処理を行う関数を Grep で検索します
インポートと依存関係	プロジェクトですでに使われているものを利用する	import 文を Grep で検索し、確立されたライブラリを見つけます
エラー処理	プロジェクトのエラーパターンに合わせる	try/catch、Result 型、エラークラスを Grep で検索します
命名規則	同じ表記方法と用語を使用する	隣接するファイルを読み、camelCase、snake_case、kebab-case のどれが使われているか確認します
ファイル構成	新しいファイルを適切な場所に配置する	ディレクトリ構成を一覧表示し、類似するコードの配置場所を確認します
テストパターン	プロジェクトと同じ方法でテストを書く	類似するモジュールのテストファイルを見つけ、構成を合わせます
設定パターン	設定方法を合わせる	.env の使用方法、設定ファイル、定数を検索します

検索手法

体系的な検索手順 -- 十分に網羅するため、次の順序に従ってください。

1. DIRECTORY SCAN: List files in the relevant directories
   -> Understand the project's file organization

2. SIMILAR FILE SEARCH: Glob for files with similar names or purposes
   -> Find the closest existing template for what you need to build

3. PATTERN GREP: Search for specific patterns you plan to use
   -> Confirm the project's approach to that pattern

4. IMPORT ANALYSIS: Check what libraries and utilities are already imported
   -> Use existing dependencies rather than introducing new ones

5. TEST FILE REVIEW: Find tests for similar functionality
   -> Match the testing approach, assertion style, and setup patterns

新しいコードを書く前の最低基準： コードベース内の類似するファイルを少なくとも2つ確認してください。

慣習との一致

一貫性の原則

コードベースがある方法で処理しているなら、同じ方法で処理します。個人の好みは関係ありません。個人の意見より、プロジェクトの一貫性を優先します。

観点	完全に合わせる項目
命名	変数名、関数名、ファイル名、クラス名
構造	ファイル構成、ディレクトリ構成、モジュールの境界
パターン	プロジェクトでの状態、エラー、非同期処理、バリデーションの扱い方
スタイル	フォーマット、コメントのスタイル、ドキュメントの方針
依存関係	代替ライブラリではなく、プロジェクトで既に使用しているライブラリを使う
テスト	テストフレームワーク、アサーションライブラリ、セットアップ／ティアダウンの方法
エラー処理	スローするか返すか、エラーの種類、エラーメッセージ

一般的な慣習の手掛かり

LOOK FOR these indicators of established conventions:

- Linter/formatter config (.eslintrc, .prettierrc, rustfmt.toml, etc.)
  -> These are explicit rules. Follow them exactly.

- Shared utility files (utils/, helpers/, lib/, common/)
  -> These are the project's building blocks. Use them.

- Base classes or interfaces (BaseController, AbstractService)
  -> These define the inheritance/composition pattern. Extend them.

- Barrel files (index.ts, __init__.py, mod.rs)
  -> These define the export pattern. Add to them.

- Test helpers (test/helpers/, fixtures/, factories/)
  -> These are the testing infrastructure. Build on them.

分析チェックリスト

コードベース内で類似のコードを見つけたら、次の質問への答えを抽出します。

1. FILE PLACEMENT: Where does this type of file live?
   -> Same directory? Nested by feature? Grouped by type?

2. FILE NAMING: What naming pattern does the file follow?
   -> ComponentName.tsx? component-name.ts? component_name.py?

3. EXPORTS: How are things exported?
   -> Default export? Named exports? Re-exported from barrel?

4. FUNCTION SIGNATURES: What do similar function signatures look like?
   -> Parameter ordering, return types, async vs sync

5. ERROR HANDLING: How does this part of the codebase handle errors?
   -> Try/catch? Result types? Error callbacks? Thrown exceptions?

6. LOGGING: Does the project have a logging pattern?
   -> Logger instance? Console methods? Structured logging?

7. VALIDATION: How does the project validate input?
   -> Zod? Joi? Manual checks? Type guards?

8. STATE MANAGEMENT: How is state handled?
   -> Redux? Zustand? Context? Signals? Local state?

9. TESTING APPROACH: What do tests for similar code look like?
   -> Unit tests? Integration? What assertion library?

10. DOCUMENTATION: Are there JSDoc comments, docstrings, or inline docs?
    -> Match the existing documentation density and style.

前例がない場合

コードベースでこれまで一度も行われていないことを、実際に構築する場合もあります。その場合は、次の手順に従います。

1. 存在しないことを確認する -- 前例がないと確信できるまで、少なくとも3つの異なる方法で検索します
2. 隣接するプロジェクトを確認する -- モノレポの場合は、兄弟パッケージを確認します
3. 外部情報源を参照する -- godmode:github-search を使って、公開リポジトリのパターンを探します
4. 意図を持って確立する -- 新しい慣習を作る際は、既存のコードベースの理念と一貫性を持たせます
5. 判断を文書化する -- 新しいパターンを導入した理由を記録します

他のスキルとの連携

意図の発見中

godmode:intent-discovery がプロジェクトの全体像を調査する際は、次の手順に従います。

1. 提案された機能に関連する既存の実装をコードベース内で検索します
2. 新機能が従うべき慣習を報告します
3. 再利用可能なコードを特定します -- 問題の一部を既に解決しているユーティリティ、コンポーネント、サービスを探します

実装中

設計の承認後にコードを書く際は、次の手順に従います。

1. テンプレートファイルを見つける -- 作成するファイルに最も近い既存のファイルを探します
2. 構造をコピーする -- テンプレートの構成に完全に合わせます
3. 固有の部分を置き換える -- パターンは保ちながら、ドメイン固有の詳細を置き換えます
4. 一貫性を確認する -- 新しいファイルをテンプレートと比較し、逸脱がないか確認します

思考の落とし穴

正当化	実態
「プロジェクトで使われている方法より、自分の方法のほうがすっきりしている」	プロジェクト全体の一貫性は、局所的な完璧さより価値があります。十分なパターンが2つあるより、1つあるほうが優れています。
「既存のコードをリファクタリングして、自分のスタイルに合わせよう」	リファクタリングは別の作業です。今は既存のスタイルに合わせます。必要であれば、後でリファクタリングを提案します。
「このプロジェクトには、これに使えるパターンがない」	十分に検索しましたか？ 類似ファイルを3つ以上確認してください。本当に前例がなければ、意図を持ってパターンを確立します。
「確認する必要はない。これは新しいモジュールだから」	新しいモジュールも既存のプロジェクトの一部です。その慣習を尊重する必要があります。
「既存のパターンは時代遅れだ」	時代遅れでも一貫性があるほうが、最新でも一貫性がないより優れています。分岐を作らず、移行を提案します。
「慣習の確認に時間がかかる」	レビューで却下されたり、一貫性を損なったりするコードを書くほうが、さらに時間がかかります。
「ただの小さなユーティリティ関数だ」	小さなユーティリティは、最も再利用されるコードです。パターンを誤ると、それに依存するすべてのものに影響します。

ガードレール

禁止事項：

• 類似する実装をコードベース内で検索せずに、新しいコードを記述すること
• プロジェクトですでに同等のライブラリを使用しているのに、新しいライブラリを導入すること
• 既存の構成に反するファイル構成を作成すること
• プロジェクトで確立されている規則と異なる命名規則を使用すること
• テストのパターンを調査せずに独自の方法でテストを書くこと

必須事項：

• 新しいコードを記述する前に、類似するファイルをコードベース内で少なくとも 2 つ検索すること
• 周囲のコードの命名規則に厳密に従うこと
• 重複を作成するのではなく、既存の共有ユーティリティやヘルパーを使用すること
• プロジェクトで確立されているテストパターンに従うこと
• コードベースに前例がない場合は、調査結果を記録すること

クイックリファレンス

SEARCH -> ANALYZE -> MATCH -> BUILD

Search: Find 2+ similar files, grep for patterns, check imports
Analyze: Extract conventions for naming, structure, error handling, testing
Match: Align your new code with every convention you found
Build: Write code that looks like it belongs in the project

統合

次の場面で呼び出されます：

• godmode:intent-discovery — 「プロジェクトの全体像を調査する」フェーズでコードベースを検索します
• godmode:reference-engine — コードの内部パターン調査のためにルーティングされます
• godmode:task-planning — 実装タスクごとに、規則に従っていることを確認します
• godmode:quality-enforcement — コードベースのパターンとの整合性を確認します

連携するスキル：

• godmode:github-search — 調査または採用するオープンソースの実装、ライブラリ、パターンを探すため、外部リポジトリ、GitHub、パッケージレジストリを検索します
• godmode:pattern-matching — コードベース内のパターンをさらに詳しく分析します
• godmode:specification-first — コードベースの規則を正式な仕様に反映します
• godmode:project-bootstrap — 新しいプロジェクトを開始するとき（調査対象となる既存のコードベースがない場合）に使用します