Codexでプロジェクトを読む

引き継いだプロジェクトを開いても、ファイルが多く、どこから読めばよいか分からないことがあります。Codexには、いきなり修正を頼む前に、入口と役割を説明してもらえます。

この記事では、変更を始めるために必要な範囲を絞り、根拠のファイルと一緒に説明を受け取る方法を紹介します。すべてのコードを一度に理解することを目標にしなくても大丈夫です。

読む目的を一つ決める

最初に「何を変えたいから構成を知りたいか」を伝えます。「案内ページの見出しを変更したい」なら、ページの入口、本文の場所、表示を決めるファイルが分かると次へ進めます。

プロジェクトを開いたら、まず対象のフォルダーが合っているかを確認します。似た名前のバックアップや出力先を開いていると、正本ではないファイルを編集する原因になります。

このプロジェクトの案内ページの見出しを変更したいです。
まだ編集せず、次の点を初心者向けに説明してください。

1. プロジェクトの目的と、判断に使ったファイル。
2. 画面の入口、本文、見た目を担当するファイル。
3. 編集する正本と、自動生成される出力の違い。
4. 変更後の確認方法がどこに書かれているか。

存在を確認したパスを示し、推測は推測と明記してください。
依存パッケージや出力フォルダーを全件読む必要はありません。

小さな構成を例にする

次のような静的ページを例に考えます。この例にはビルド処理やサーバーへの送信処理はありません。

guide-sample/
  index.html   ページの文章と構造
  styles.css   色や余白などの見た目
  README.md    開き方と確認方法

HTMLの中に href="styles.css" というスタイルシートの指定があれば、index.html が styles.css を読み込む関係を確認できます。名前の印象だけで役割を決めるのではなく、実際の参照を見ます。

以下の図は調べる順番です。入口から参照先へたどり、最後に変更後の確認方法を把握します。

各段階で確認してから、次の操作へ進みます。

1. 1目的を決める変更したい画面や機能へ範囲を絞る
2. 2入口を探すREADMEと実際の入口ファイルを照合
3. 3参照をたどる本文・見た目・生成物の関係を確認
4. 4次の作業へ正本と確認方法を計画に渡す

具体的な依頼と、結果の確かめ方は本文にあります。

この三ファイル構成は説明用の例です。練習用ファイル一式をダウンロードして展開し、コピーで構成を確かめられます。Astroなどを使う実際のサイトでは、元のソースからHTMLが生成される場合があるため、同じファイル名でも役割を確かめます。

説明に根拠を付けてもらう

受け取った回答では、次の対応を確かめます。

「通常はここにあります」という一般論だけなら、「このプロジェクトで実際に確認したパスを教えてください」と続けます。READMEの内容と実装が食い違う場合は、どちらが現在の動作と一致するか追加確認が必要です。

package.jsonがある場合の起動方法の探し方

Node.jsを使うプロジェクトでは、package.json の scripts に実行用の名前と命令が書かれていることがあります。次は読み方を説明する例です。自分のファイルへ追加する設定ではありません。

{
  "scripts": {
    "dev": "node server.mjs",
    "check": "node check.mjs"
  }
}

この例なら dev は server.mjs、check は check.mjs を実行します。名前だけで「devは安全な確認」「checkは変更しない検査」と決めず、呼び出すファイルも読みます。対応する predev・postdev などがあれば前後の処理も確認します。

npmを使うことがREADMEと設定で分かり、すでに導入済みなら、対象パッケージのフォルダーで次を実行すると定義されたスクリプトを一覧できます。

npm run

一覧を見る命令と npm run dev のように処理を実行する命令は別です。Missing script: "dev" は、対象にその名前の定義がないという手掛かりです。別名の起動命令や別フォルダーの設定がないか確認し、エラーを消すためだけに dev を書き足しません。npm以外を使うプロジェクトでは、そのプロジェクトの手順を優先します。npm公式のrun-script説明

READMEとpackage.jsonのscriptsを照合してください。
起動・検査・公開の命令を分け、呼び出すファイルを根拠に説明してください。
前後に自動実行される処理も確認してください。
まだインストール、設定変更、起動、外部送信は行わないでください。
記載と実装が違う場合は、どちらが未確認かを残してください。

説明用の小さなパッケージで、一覧の表示と存在しないスクリプトのエラーを確認しました。あなたのプロジェクトの起動成功や、Codexによる実操作の検証とは別です。

大きなプロジェクトでは範囲を絞る

最初から全ファイルの説明を求めると、読む側にも負担がかかります。まず対象の画面や機能から関係するファイルへ絞り、必要なときに範囲を広げます。

今回は見出しの変更に関係する範囲だけを調べてください。
入口から本文の正本までを、三段階以内で説明してください。
別の機能や生成済みファイルの詳細は、必要になったときに調べてください。

node_modules や生成済みの dist などは、問題の原因を追う場合には必要でも、最初の構成理解で全件確認する対象とは限りません。フォルダーの意味はプロジェクトの設定で確認します。

分からないことを残したまま整理する

起動に認証が必要、資料が古い、テストの定義がない、といった事情で全部を確定できないこともあります。その場合は「存在確認済み」「実行して確認済み」「未確認」を分けてもらいます。

ファイルを読めたことは、アプリが正常に起動する証拠ではありません。動かす必要があるなら、依存関係の追加や外部接続の影響を把握してから別の確認として進めます。

理解した結果を次の作業へつなぐ

構成が分かったら、変更前の計画に対象ファイルと完成条件を渡せます。繰り返し使う開き方や確認方法はREADMEの作成へ残すと、次回の自分や引き継ぐ人も迷いにくくなります。

この記事では説明用の小さなファイル構成を用いています。あなたのプロジェクトを調査済みである、またはCodexの回答が常に正しいという意味ではありません。根拠のファイルを一つ開いて照合するところから始められます。

一つの文言や関数を直す場所に絞るなら、名前・本文・参照から変更箇所を探す方法を使えます。

独立した読み取り調査が複数ある場合は、サブエージェントへの分担で役割と報告範囲を決められます。

構成を読んだ後は、依存関係の準備と確認でインストール前後を点検できます。