Codex は、渡された情報しか使わない
「Codexに良いコードを書かせたい」と考えたとき、
多くの人はプロンプトを工夫します。
長い指示、詳細な要件、参考 URL の列挙。
間違いではない。ただ、それ以前に見るべきものがある。
Codex が参照するのは、あなたが渡したファイル、コメント、関数名、フォルダ構造です。その情報が散らかっていれば、
どれだけ丁寧に指示しても、出力は曖昧になる。
逆に、情報が整っていれば、指示は「この関数を拡張して」の一行で済む。
私たちが実際に見てきた現場では、Codex を導入してすぐ「使えない」と判断したチームと、初日から工数を削減できたチームがいました。違いは、環境の整え方にあった。
整えたのは、この3つ
最初に手を入れたのは、ディレクトリ構成です。
機能ごとにフォルダを分け、命名を統一し、役割が一目で分かる階層にする。Codex は、ファイル名とパスから「このコードが何をするか」を推測します。
`utils/old/backup_20231105.ts` のような名前では、推測が働かない。
次に、命名規則を揃えました。
関数名、変数名、型定義。チーム内で表記ルールを決め、既存コードをリファクタリングする。
Codex は、一貫性のある名前から文脈を読み取る。`fetchUserData` と `getUserInfo` が混在していると、どちらを参考にすべきか判断できず、新しいコードで第三のパターンを生成してしまう。
そして、既存コードの密度を上げる。
コメントではなく、型とテストで意図を伝える。TypeScript の型定義を丁寧に書き、Jest のテストケースを増やす。Codex は、型とテストから仕様を理解します。ドキュメントを書く時間があるなら、型を書いたほうが効く。
この3つを整えた後、プロンプトの文字数は平均で40%減りました。指示が短くなっても、出力の精度は上がった。
実際の変化は、修正工数に出る
ある受託案件で、管理画面の Codex 機能を Codex に生成させたとき、環境を整える前と後で比較しました。
整える前は、生成されたコードをそのまま使えることは稀で、手作業で変数名を直し、型エラーを潰し、既存の API 呼び出しパターンに合わせる必要がありました。
生成に3分、修正に20分。
整えた後は、生成されたコードがそのままマージできるか、軽微な調整で済むようになった。
生成に3分、修正に5分。1ファイルあたり15分の差です。10ファイル書けば、150分。丸1営業日が浮く計算になります。
工数が減ると、単価交渉の余地が生まれる。
「納期を半分にできます」ではなく、「同じ納期で、仕様の詰めに時間を使えます」と提案できるようになる。
クライアントが求めているのは速さではなく、期待を超える精度です。
環境整備は、営業ツールになる
フリーランスとして案件を取るとき、「Codexを使っています」と言っても差別化にはなりません。
誰でも使えるからです。
一方で、「Codexが最大限活きるリポジトリ構成を最初に設計します」と伝えると、話が変わる。クライアントは、納品後の保守性を気にしています。コードが整っていれば、引き継ぎが楽になる。追加開発のコストが下がる。
私たちが見てきた中で、リピート受注率が高いエンジニアは、コードそのものよりも、リポジトリの可読性と拡張性に時間を使っていました。Codex は、その設計思想を加速する道具として機能します。
環境を整えることは、自分の工数を減らすだけでなく、クライアントへの提案力を上げる投資になる。