AIにコードを調べてもらうとき、「どのコードを見ているか」は最初に確認したいことです。リポジトリ、ブランチ、ファイルが曖昧だと、別の機能や開発中の版を見て、現在の仕様だと思ってしまうことがあります。CRUD表を更新する例で、それぞれの意味を整理します。
この記事のポイント
対象のプロジェクトはリポジトリ、調べた版はブランチとコミット、根拠の場所はファイルパスで示します。これらを残しておくと、AIが調べたのと同じ情報を開いて確認し直せます。
リポジトリはファイルと変更履歴を管理する場所
リポジトリでは、プロジェクトに関係するファイルと、その変更履歴を管理します。画面やAPIのコードのほか、自動テスト、設定、仕様書、CSVなどが入っていることもあります。Gitは状態をコミットとして記録するので、後から過去の内容を確認できます。
コミットには作成者やメッセージなども残ります。ただ、なぜ変えたかを後から知るには、人がその理由をメッセージやレビュー記録に書いておく必要があります。Gitが業務上の意図まで自動で判断してくれるわけではありません。
product-repository/
├─ frontend/ 画面に関するコード
├─ backend/ APIやデータ処理
├─ tests/ 自動テスト
├─ docs/ 仕様や説明資料
├─ crud/ CRUD表のCSV
└─ README.md プロジェクトの説明リモートとローカルを区別する
手元のPCにあるのがローカルリポジトリです。共同作業のために接続する、別の場所のリポジトリをリモートリポジトリと呼びます。GitHubはリモートを置く場所の一例で、Gitそのものとは別です。
cloneは、すでにあるリポジトリを新しい場所に複製する操作です。手元で調べるときは、複製した作業フォルダを開きます。リモートに新しい変更があっても、いつも自動で手元に反映されるわけではありません。調査を始める前に、どの版を使うかを確認します。
ファイルパスで根拠の保存場所を示す
ファイルは個々のデータで、パスはその保存場所を表します。たとえばbackend/users/controller.tsは、backendフォルダの中のusersフォルダにある、controller.tsというファイルを指しています。
調査結果に『削除処理がある』とだけ書かれていると、読み手はどこを見ればよいか分かりません。ファイルパスに関数名や該当箇所を添えると、同じ処理を探しやすくなります。CSVには調査したコミットも残しておきます。後でコードが変わっても、確認した版を特定できます。
ブランチを使って作業を分ける
ブランチは、あるコミットを指す名前です。その後の作業を分けて進めるために使います。たとえばmainをもとに、feature/user-deleteやupdate/crud-csvという作業用のブランチを作ります。名前の付け方やそれぞれの役割は、チームごとに確認が必要です。
mainという名前でも、本番に公開済みの版や、新しい機能が全部入った版とは限りません。また、ブランチを分けても、作業フォルダそのものが別の場所に隔離されるわけではありません。ブランチを切り替える前にも、まだコミットしていない変更があるかを確認します。
| 仮の参照先 | ユーザー削除機能の状態 |
|---|---|
| main | 削除機能をまだ取り込んでいない |
| feature/user-delete | 削除処理を開発中 |
| 本番環境 | 開発中の削除処理は未公開 |
コードがあっても公開済みとは限らない
この例では、調べるブランチによって見つかるコードが変わります。開発中のブランチで削除処理を見つけても、今のユーザーがDeleteを使えるとは限りません。どの版かに加えて、公開状況、権限、機能が有効になる条件も確認します。
CRUD表を更新する前に、『どのブランチの、どの時点の情報を載せるか』『実装済みと利用可能を分けて記録するか』を決めます。ブランチの内容は後から変わるので、名前と一緒にコミットIDも残すと、調べた時点を特定できます。
よく使うGitの操作とその意味
pullを実行すると、作業中のブランチに変更を取り込みます。最新情報を表示するだけの操作ではないので、実行前に今の状態を確認します。また、通常のgit diffだけでは、ステージ済みの差分や未追跡ファイルをすべて確認できません。statusも一緒に使って確認します。
| 用語 | 確認したい意味 |
|---|---|
| clone | 既存リポジトリを新しい場所へ複製する |
| pull | リモートの変更を取得し、現在のブランチへ統合する |
| status | 作業ツリー、ステージ、未追跡ファイルなどの状態を見る |
| diff | 指定した二つの状態の違いを見る |
| commit | ステージした内容を、履歴の一単位として記録する |
| push | ローカルのコミットや参照をリモートへ送る |
| merge | 別の履歴を現在のブランチへ取り込む |
CSVを更新するときの確認手順
最初に、対象のリポジトリ、参照するブランチとコミット、すでに変更されているファイル、CSVのパスを確認します。チームの手順に沿って必要な更新を取り込み、作業ブランチを用意したら、一つの機能から調べてみます。
調査結果をレビューし、確認済みの情報をCSVに反映します。その後、変更内容と、対象外のファイルが変わっていないかを確認します。変更をコミットして共有し、GitHubなどを使っている場合はPull Requestでレビューを依頼します。内容を確認してから、チームで決めたブランチに取り込みます。
ファイルを変更せず、調査を始める前の状態を確認してください。
- 対象リポジトリ
- 現在のブランチと最新コミット
- すでに変更されているファイル
- 調査対象と更新対象CSVのパス
対象の版が不明な場合は、実装の判定へ進まず不明点を示してください。