> For the complete documentation index, see [llms.txt](https://livlog-llc.gitbook.io/engineering-handbook/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://livlog-llc.gitbook.io/engineering-handbook/codexwoshitana/20-repository-investigation.md).

# 20. 既存リポジトリの調査

## 目的

Codexに実装を依頼する前に、リポジトリの実際の構成、規約、実行方法、変更対象を把握します。READMEは重要な入口ですが、古い場合や詳細を省略している場合があるため、READMEだけで判断しません。

## 調査するファイル

リポジトリに存在するものを対象に、次を確認します。

| 分類   | 主な確認対象                                           |
| ---- | ------------------------------------------------ |
| 開発指示 | `AGENTS.md`、README、CONTRIBUTING、規約文書             |
| 依存関係 | `package.json`、`pom.xml`、`build.gradle`、lockファイル |
| 実行環境 | Dockerfile、Compose設定、環境変数のサンプル                   |
| 自動化  | CI設定、ビルドスクリプト、lint、format、テスト設定                  |
| DB   | マイグレーション、DDL、seed、Entity、Repository              |
| 実装   | `src`配下、設定、Controller、Service、View               |
| テスト  | 単体、結合、E2E、fixture、テスト用設定                         |

存在しないファイルを前提にせず、実在を確認してから報告します。環境変数ファイルを確認する場合も、値を出力させません。

## アプリケーション構造を確認する

JavaやWebアプリでは、次の役割がどこに置かれているかを調べます。

* ControllerまたはHandler
* ServiceまたはUseCase
* RepositoryまたはDAO
* EntityまたはDomain Model
* DTO、Request、Response
* View、Template、Component
* Validation、例外、エラーレスポンス
* Unit Test、Integration Test、E2E Test

名称はプロジェクトにより異なります。一般的なレイヤー構造を押し付けず、既存コードが採用している責務分担を確認します。

## 実装パターンを確認する

関連する既存機能を1つ以上探し、次を比較します。

* パッケージ、ディレクトリ、クラス、メソッド、変数の命名
* DTOとEntityの変換方法
* Validationの置き場所
* 例外の種類とHTTPステータスへの変換
* ログレベル、メッセージ、機密情報の扱い
* トランザクション境界
* DBアクセスとN+1などの性能上の注意
* テストの構成、命名、fixture、mockの使い方
* フロントエンドの状態管理、CSS、アクセシビリティの慣例

Codexには「推奨される一般論」ではなく、「このリポジトリで確認できた事実」と「提案」を分けて報告させます。

## 変更対象を特定する

調査結果から、次を明確にします。

1. 追加するファイル
2. 変更するファイル
3. 参照するが変更しないファイル
4. 変更してはいけない範囲
5. 実行すべきテストとコマンド
6. 互換性、DB、運用上のリスク
7. 調査だけでは確定できない事項

## 調査結果を記録する

小規模な変更では、`docs/design.md`の冒頭へ調査結果を含めます。中規模以上または未知のリポジトリでは、次のファイルを追加しても構いません。

```
docs/repository-investigation.md
```

推奨する構成は次のとおりです。

```markdown
# リポジトリ調査

## 技術構成

## ビルド・実行方法

## ディレクトリ構成

## 関連する既存機能

## 命名・実装パターン

## テスト方針

## 変更対象候補

## リスク

## 未確認事項
```

## 調査手順

1. リポジトリ内の開発指示を確認する
2. ビルド、依存関係、実行、CIの定義を確認する
3. 要件に近い既存機能を検索する
4. 入口からDBまたは画面まで処理経路を追う
5. 対応するテストを確認する
6. 変更候補と変更しない範囲を整理する
7. 根拠となるファイルパス付きで報告する
8. 人間が調査結果を確認してから設計へ進む

## Codexに依頼すること

* この段階ではファイルを変更せず、調査だけを行う
* 使用技術、主要構成、関連処理の経路を報告する
* 各判断の根拠となる実在ファイルを示す
* 実行可能なテストコマンドを設定ファイルから特定する
* 事実、推測、提案、未確認事項を分ける

## 人間が確認すること

* 調査範囲が要件に対して十分か
* 関連する既存機能の選択が適切か
* 古いREADMEだけを根拠にしていないか
* Codexが一般論を既存仕様として扱っていないか
* 秘密情報や個人情報を調査結果へ転記していないか


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://livlog-llc.gitbook.io/engineering-handbook/codexwoshitana/20-repository-investigation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.