読ませる
既存プロジェクトの構造、重要ファイル、処理の流れを説明してもらう。初見のコードベースに強い入口です。
Codexは、コードを書く・読む・直す・レビューする作業を手伝ってくれるOpenAIのコーディングエージェントです。 この資料では、Hiroの目線で「どの入口から始めるか」「最初に何を頼むか」「怖い変更を避けるにはどうするか」までを一気に整理します。
ChatGPTが相談相手だとしたら、Codexは作業フォルダに入って、ファイルを読み、必要なら編集し、コマンドやテストまで回す相棒です。 OpenAI公式では、コード作成、既存コードの理解、レビュー、デバッグ、反復作業の自動化に使えると説明されています。
既存プロジェクトの構造、重要ファイル、処理の流れを説明してもらう。初見のコードベースに強い入口です。
HTML資料、LP、スクリプト、UI、テストなどを、既存ルールに合わせて生成・編集してもらう。
エラーの原因調査、バグ修正、表示崩れ対応、レビュー指摘の反映を小さな差分で進める。
Codexで詰まる原因は、AIの性能というより「入口の選び方」「Git」「権限」「検証条件」にあります。 ここを先に押さえると、最初の体験がかなりラクになります。
Codexは返答だけでなく、リポジトリを読み、ファイルを書き換え、コマンドを実行し、テストまで回せる作業者です。
App、IDE拡張、CLI、Cloudで向き不向きが違います。最初はAppかIDE拡張から始めると、環境トラブルを切り分けやすいです。
Codexは安全のため、作業範囲や外部アクセスが制限されます。止まったときは「能力不足」ではなく「承認待ち」や「ネットワーク制限」も疑います。
「いい感じに直して」ではなく、目的、対象、制約、完了条件、検証方法まで渡すと、Codexが推測で暴れにくくなります。
Codexが変更したあとに戻せないと怖さが残ります。作業前後のgit statusとgit diffは最初に覚える操作です。
プロジェクトのルールはAGENTS.mdに保存できます。起動方法、禁止事項、完了条件を入れておくと再現性が上がります。
最初は用語で止まりがちです。ここでは「それが何か」より先に、「Codexへ頼むときにどう効くか」で整理します。
プロジェクト一式の置き場です。コード、資料、画像、設定、履歴をまとめて管理します。Codexに頼むときは「どのレポジトリーで作業するか」を明確にします。
ファイルやフォルダの住所です。例: output/Hiro/exports/...。Codexには「このパスを編集して」「このパスは触らないで」と伝えると安全です。
Codexが判断に使う材料です。関連ファイル、エラー文、スクショ、仕様、Design.md、AGENTS.mdなどを渡すほど、推測が減ります。
大きい作業を分担させるための専門担当です。調査、実装、レビューなどを並行・分業できます。ただし同じファイルを同時に触らせると衝突しやすいです。
AGENTS.mdCodexへのプロジェクト内ルールです。ユーザーが書いた「Agent.md」は、Codex文脈では基本的にAGENTS.mdとして扱うと理解すればOKです。
DESIGN.mdデザインのルールブックです。SUNAOではペルソナごとにあり、HiroならHiro/DESIGN.mdを読ませてから資料やLPを作ります。
使ってよい色のセットです。Hiro資料ではBrand Blue #2563EB、Emerald #10B981、Ice Blue #F0F4FAを軸にします。
トーン&マナーの略です。Hiroでは「テック感 × 親しみやすさ」「先生ではなく仲間目線」「ステップで再現性を出す」が基準です。
特定作業の手順書です。画像生成、資料作成、ブラウザ確認など、毎回同じ品質で進めたい作業を型にできます。
image gen画像生成・編集のスキルです。アイキャッチ、図解、サムネイル、モック画像が必要なときに使います。HiroではDESIGN.mdの色とトンマナを先に渡します。
ローカルページやWebアプリを実際に開いて、表示崩れ、クリック、入力、スクショを確認する作業です。Web制作では「作ったあとに見る」までがセットです。
ブラウザやデスクトップアプリを視覚的に操作する機能です。影響範囲が広いので、ログイン、送信、削除、購入などは人間の確認を挟みます。
Codex向けに特別な魔法の構成があるわけではありません。大事なのは、人間にもCodexにも入口が分かること。 ルートを見れば起動・テスト・ルールが分かり、アプリ本体、ドキュメント、テスト、スクリプト、生成物が分かれている構成が強いです。
AGENTS.md、README.md、package.json、.env.exampleを置き、起動方法とルールがすぐ分かる状態にします。
src/、tests/、docs/、scripts/、public/、.github/のように棚を分けます。
構成だけ整えても、意図がなければ迷います。フォルダーの役割はAGENTS.mdとREADME.mdに短く書きます。
codex-starter/
├─ AGENTS.md
├─ README.md
├─ package.json
├─ tsconfig.json
├─ .gitignore
├─ .env.example
├─ docs/
│ ├─ setup.md
│ ├─ architecture.md
│ └─ coding-rules.md
├─ src/
│ ├─ app/
│ ├─ components/
│ │ ├─ ui/
│ │ └─ layout/
│ ├─ features/
│ ├─ lib/
│ ├─ hooks/
│ ├─ types/
│ └─ styles/
├─ tests/
│ ├─ unit/
│ └─ e2e/
├─ scripts/
├─ public/
└─ .github/
├─ workflows/
└─ pull_request_template.md
src/に集める
Next.jsでも、アプリ本体をsrc/appやsrc/pagesへ置く構成が案内されています。
public/、package.json、設定ファイル、.env.*はルートに残すのが基本です。
features/で探索範囲を狭める
機能が増えたらsrc/features/auth/、src/features/articles/のように分けます。
Codexに「記事機能だけ見て」と頼みやすくなり、誤修正が減ります。
src/app、components、lib、tests、docsで十分。
機能が3つ以上になったらfeatures/を追加し、設計判断はdocs/decisions/へ。
.github/、PRテンプレ、CODEOWNERS、機密情報ルールを整える。
content/、briefs/、research/、templates/、prompts/、assets/、exports/に分けると、下書き・リサーチ・出力を管理しやすくなります。
curriculum/、lessons/、handouts/、quizzes/、assignments/、rubrics/に分けると、問題・解答・採点基準を個別に頼めます。
apps/web、apps/admin、apps/api、packages/uiのように分け、必要なら下位ディレクトリにもAGENTS.mdを置きます。
final.tsx、final_new.tsx、memo2.md、old/、new/のように役割が読めない名前が増えること。Codexは賢いですが、ラベル付きの棚のほうが圧倒的に探しやすいです。
このリポジトリのフォルダー構成を分析して。
以下を出して。
1. 現在の主要フォルダーと役割
2. Codexが作業するときに迷いやすい点
3. 初心者が理解しにくい点
4. 変更せずに改善できるドキュメント案
5. 実際にフォルダー移動するなら、安全な段階的リファクタ案
まだファイルは変更しないで。
Codexが作業しやすく、初心者にも分かりやすいフォルダー構成に改善したい。
制約:
- まだファイル移動はしない
- 既存のimport pathが壊れないようにする
- 変更案は段階的に出す
- まず現状分析、次に理想構成、最後に移行手順を出す
出力:
1. 現状の問題点
2. おすすめ構成
3. 移行ステップ
4. リスク
5. 移行後に実行すべきテスト
Codexはアプリ、IDE拡張、CLI、Cloudから使えます。最初から全部を覚える必要はありません。 迷ったら「Codex app」、普段エディタで作業する人は「IDE拡張」、ターミナルに慣れている人は「CLI」が始めやすいです。
macOS / Windowsで使えるデスクトップアプリ。プロジェクトを選んで、ローカルでCodexに作業してもらう入口です。
向いている人: まず視覚的に使いたい人、ファイル変更を見ながら進めたい人。
VS Code、Cursor、Windsurfなどのエディタ内でCodexを使う入口。開いているファイルや選択範囲を文脈にできます。
向いている人: ふだんエディタで実装している人。
ターミナルでcodexを起動して使う入口。ローカルのディレクトリで読み取り、編集、コマンド実行ができます。
向いている人: Gitやターミナル操作に慣れている人。
ブラウザからクラウド上の環境にタスクを任せる入口。GitHubリポジトリ接続後、差分をレビューしてPR作成まで進められます。
向いている人: 外出先でも依頼したい人、複数タスクを並行させたい人。
最初はCodex appで感覚を掴み、慣れてきたらIDEまたはCLIへ。GitHubで管理する案件はCloudも使う、が現実的です。
CodexはChatGPT各プランに含まれますが、利用上限はプランやタスクの重さで変わります。正式な条件は常に公式ページで確認します。
初回で大事なのは、いきなり大きな改修を頼まないこと。まずは説明と小さな確認から始めると、Codexの動き方を理解しやすくなります。
macOSまたはWindowsなら、公式Quickstartからアプリをダウンロードします。インストール後、ChatGPTアカウントまたはOpenAI APIキーでサインインします。
Codexに触ってほしいプロジェクトフォルダを選びます。HTML資料なら資料フォルダ、Webサイトならそのリポジトリを選びます。
最初の依頼は「作って」ではなく「読んで説明して」。Codexがどこまで見えているかを確認してから、次の依頼に進みます。
このプロジェクトの目的、主要フォルダ、起動方法、編集時に注意するルールを初心者向けに説明して。
見出し修正、テキスト追加、1コンポーネント変更など、差分がレビューしやすい依頼から始めます。
トップページのCTA文言だけを改善して。
既存デザインに合わせ、変更ファイルと理由を最後にまとめて。
Codexは結果を作るだけでなく、テストや表示確認まで任せると価値が出ます。依頼文に検証条件を入れます。
実装後にビルドまたは表示確認をして。
失敗した場合は原因と未完了事項を教えて。
Codexは、ChatGPTアカウントでサインインする方法と、OpenAI APIキーで使う方法があります。 初心者はまずChatGPTログインで始め、CI/CDや自動化など明確な理由が出てきたらAPIキー運用を検討するのが安全です。
Codex app、IDE拡張、CLIで使いやすい入口です。Codex Cloudを使う場合もChatGPTログインとGitHub接続が前提になります。
OpenAI Platform側の従量課金として扱います。自動化やCI/CDでは便利ですが、キー管理とコスト管理を自分で行います。
Codexは認証情報をローカルにキャッシュします。~/.codex/auth.jsonはアクセストークンを含む可能性があるため、共有・添付・コミットは禁止です。
codex login --device-auth のようなdevice code認証が役立つ場合があります。
ターミナルに慣れている人はCLIも便利です。公式Quickstartでは、macOS / Linuxはスタンドアロンインストーラ、npm、Homebrewが案内されています。
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex
npm install -g @openai/codex
# または
brew install --cask codex
初回起動時にChatGPTアカウントまたはAPIキーでサインインします。Windowsは公式QuickstartにPowerShell用コマンドが掲載されています。
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
Node、Python、Docker、bash前提の教材やOSSを扱うなら、WSL2 + VS Code Remote WSLも候補です。
cd ~/code/my-project
codex
ホームディレクトリなど広すぎる場所で起動すると、Codexが見る範囲が曖昧になります。
codex login status、PATH、WindowsならPowerShell/WSL2/企業PCポリシーを順に確認します。
Codexはファイルを編集できるので、GitとGitHubをセットで知っておくと一気に使いやすくなります。 Gitは手元の変更履歴、GitHubはその履歴をオンラインで共有・レビューする場所、と捉えるとわかりやすいです。
どのファイルを変えたか、いつ保存点を作ったかを管理する仕組みです。 Codexに作業を頼む前後で状態を確認しておくと、失敗しても差分を見て戻せます。
Gitの履歴をオンラインに置き、別PC・チーム・Codex Cloudから扱えるようにします。 Pull Requestを使うと、変更内容を確認してから本番側に取り込めます。
Codex app / CLI / IDEでファイルを編集する。
git statusとgit diffで何が変わったか見る。
必要ならGitHubへpushし、Pull Requestでレビューする。
作業前に、すでに変更中のファイルがないか確認します。ここで出てくる変更は、自分や他のAIが先に触った可能性があります。
git status
Codexが編集したあと、どこが変わったかを確認します。見慣れない変更があれば、その場でCodexに理由を聞きます。
git diff
内容に納得できたら、コミットとして保存します。コミットメッセージは「何をしたか」が後でわかる言葉にします。
git add output/Hiro/exports/codex-getting-started-guide-20260531.html
git commit -m "Add Hiro Codex getting started guide"
チームで見たい、別PCで作業したい、Codex Cloudを使いたい場合はGitHubにpushします。Codex CloudはGitHubリポジトリ接続が前提です。
git push origin ブランチ名
repository: プロジェクト置き場。
commit: 変更の保存点。
branch: 本線から分けた作業場所。
Pull Request: 変更をレビューして取り込む依頼。
「今の差分を初心者向けに説明して」「コミットメッセージ案を3つ出して」「PR本文を作って」と頼むと、Git操作の学習にもなります。
意味がわからないままgit reset --hardや強制pushをしないこと。戻せない・他人の変更を消す可能性がある操作は必ず確認します。
AGENTS.mdは、Codexにプロジェクト固有のルールを渡すための説明書です。
起動方法、テスト方法、禁止事項、完了条件を書いておくと、毎回プロンプトに同じ注意を書かなくて済みます。
ファイル名はAgent.mdではなく、基本は複数形・大文字のAGENTS.mdです。
プロジェクト概要、主要ディレクトリ、開発サーバー起動コマンド、テスト・lint・型チェック、触ってはいけないファイル、PR前の確認事項。
特にsrc/、docs/、tests/、scripts/、output/の役割を書くとCodexが迷いにくくなります。
長く曖昧なルールより、短く正確なルールが効きます。最初は1画面で読める量から始め、運用しながら更新します。
# AGENTS.md
## Project overview
このリポジトリはHiro向けの制作物を管理するプロジェクトです。
## Commands
- 開発サーバー: npm run dev
- テスト: npm test
- lint: npm run lint
## Rules
- 新しい依存パッケージを追加する前に確認する。
- .env、秘密鍵、顧客情報を読まない・変更しない。
- UI変更は既存デザインに合わせる。
- 大きな変更は先に計画を出す。
## Done when
- 関連チェックが通る。
- 変更内容と確認結果を最後に要約する。
このリポジトリ用のAGENTS.mdを作りたい。
まず現在のプロジェクト構成、package.jsonのscripts、テスト・lint・型チェック方法を調べて、
初心者にも保守しやすい短いAGENTS.md案を作って。
まだファイルは作成せず、内容案だけ提示して。
HTML資料、LP、図解、サムネイルを作るときは、先にDESIGN.mdを読ませます。
「青っぽく」ではなく、色・余白・文字サイズ・トンマナを明文化しておくことで、出力が安定します。
ペルソナ、カラーパレット、タイポグラフィ、Do/Don'tを確認する。
Hiroならクリーン、実践的、ステップ型、仲間目線に寄せる。
モバイル幅、文字のはみ出し、色の一貫性、リンクを確認する。
Hiro/DESIGN.mdを読んでから、HTML資料を作成して。
カラーパレット、タイポグラフィ、トンマナ、Do/Don'tを守って。
特にBrand Blue、Emerald、Ice Blueを使い、ステップ型で読みやすくして。
実装後はブラウザでモバイル幅も確認して。
Codexは「何を作るか」だけでなく、「どう確認するか」まで渡すと精度が上がります。Hiro資料づくりではこの流れが使いやすいです。
目的、既存ルール、関連ファイルを説明してもらう。
1ページ、1機能、1修正に絞って実装してもらう。
ビルド、テスト、ブラウザ確認、差分要約まで頼む。
Codexが止まる理由の多くは、サンドボックス、承認、ネットワーク制限、Cloud環境の差です。 初心者は最初から権限を広げず、必要なときだけ理由を確認して許可するのが基本です。
read-only読むだけの感覚で使うモード。初回のプロジェクト理解や調査に向いています。
workspace-writeワークスペース内の編集と通常コマンドを許す、ローカル作業の基本モードです。
danger-full-access境界を大きく外すモード。初心者は原則使わず、必要性が明確なときだけ慎重に検討します。
npm install、外部API、GitHub issue取得などはネットワーク制限で止まることがあります。 開ける前に「本当に必要か」「必要なドメインはどこか」「秘密情報を読ませていないか」を確認します。
ローカルでは動いても、Cloudには依存関係、環境変数、ランタイム、setup scriptが足りない場合があります。 APIキーなどのsecretsは扱いに注意し、diffとログを必ず見ます。
.env、秘密鍵、顧客情報、個人情報、~/.codex/auth.jsonは共有・添付・コミットしません。
Codexの価値は、作るだけでなく確認までつなげられることです。画像が必要ならimage gen、Webページならブラウザ操作を組み合わせます。
毎回同じ品質で進めたい作業に使います。例: HTML資料、X投稿、図解、画像生成、PDF化、ブラウザ検証。
image genを使う場面アイキャッチ、資料の背景画像、サムネイル、説明用モック画像を作るとき。先に用途、サイズ、色、トンマナを指定します。
ローカルHTMLやWebアプリの表示確認、クリック、フォーム入力、スクショ確認。制作物では最終確認としてほぼ必須です。
Hiro向けのHTML資料を作成して。
必要ならimage genでアイキャッチ案も作って。
Hiro/DESIGN.mdのカラーパレットとトンマナを守って。
完成後、ブラウザ操作でPC幅とスマホ幅を確認し、
文字のはみ出し、リンク、画像読み込み、表示崩れを報告して。
ポイントは「目的」「対象ファイル」「制約」「検証」を入れることです。曖昧なまま投げるより、Codexが判断しやすくなります。
Goal:
[何を変えたいか]
Context:
[関係するファイル、画面、エラー、背景]
Constraints:
- 新しい依存関係は追加しない
- 既存の設計に合わせる
- 変更範囲を最小にする
Done when:
- 関連テストが通る
- lintまたは型チェックが通る
- 変更内容と確認結果を最後に要約する
このプロジェクトを初めて触る人向けに説明して。
目的、主要ディレクトリ、起動方法、編集時に守るルール、まず読むべきファイルをまとめて。
次の不具合を調査して。
まだ修正せず、原因候補と確認手順を先に出して。
症状:
[ここに症状]
再現手順:
[ここに手順]
期待する動作:
[ここに期待動作]
実際の動作:
[ここに実際の動作]
Hiro向けのHTML資料を作成して。
対象読者はAI活用を始めたい初心者。
デザインはHiro/DESIGN.mdに合わせ、ステップ形式で読みやすく。
成果物は output/Hiro/exports/ に保存して。
以下の問題を最小差分で修正して。
関連ファイルを読んでから実装し、不要なリファクタはしないで。
最後に変更点、確認コマンド、残ったリスクをまとめて。
今の差分をコードレビューして。
バグ、表示崩れ、セキュリティ、テスト不足を優先して指摘して。
問題がなければ、残るリスクだけ短く教えて。
Codexは便利ですが、ファイルを編集できるからこそ「戻せる状態」を作ってから使うのが大事です。
git statusで未保存・未整理の変更がないか確認します。人の変更を巻き戻さないのが基本です。この順番で進めると、Codexの感覚をつかみながら、怖さを小さくできます。
Codex appまたはCLIを起動し、ChatGPTアカウントでサインイン。練習用フォルダを開く。
「このプロジェクトを説明して」と頼む。返答の中で不明点を追加質問する。
見出し、文言、CSSの余白など、すぐ確認できる変更を1つだけ頼む。
ビルド、表示確認、差分要約を依頼。何を確認したかまで記録してもらう。
うまくいった依頼文を保存。次回からテンプレとして使う。
HTML資料、LP、ブログ下書き、社内マニュアルなど、Hiroの制作物に転用する。
1日で全部覚えようとしないこと。小さく触って、Gitで戻せる状態を作り、検証付きの依頼へ広げていきます。
Codex appまたはIDE拡張を入れ、サンプルリポジトリで「このプロジェクトを説明して」と聞く。まだ編集しない。
READMEや文言など安全なファイルを少しだけ変更。git diffで差分を見る。
軽微な修正を頼み、テスト・lint・型チェックを実行させる。結果を読んでcommitする。
起動方法、テスト方法、禁止事項、完了条件を短くまとめる。次回の作業が安定するか確認する。
少し大きいタスクで、いきなり実装せず計画を先に出させる。人間がレビューしてから進める。
未コミット変更のレビュー、GitHub連携、Cloud環境、setup script、PR作成の流れを試す。
料金、対象プラン、利用上限、インストール方法は更新される可能性があります。公開前に公式ページで最終確認してください。