Codex Appを技術作業台にする──画面、ファイル、thread、reviewの使い方 第7回

Codex App は、単なる「チャットでコードを書かせる画面」ではありません。

うまく使うと、技術作業の作業台になります。

リポジトリをつなぐ。
thread を分ける。
ファイルを読ませる。
画面を見せる。
エラーを説明させる。
修正案を作らせる。
レビューさせる。
次回に残すものを整理させる。

CLI は、手元で速く作業するには強いです。

でも、Codex App には別の強さがあります。

画面で作業を見られる。
thread と project で文脈を分けられる。
複数の作業を並べて管理しやすい。
スクリーンショットやアプリ画面を渡しやすい。
技術者ではない人も、作業の入口に入りやすい。

第6回では、既存リポジトリ調査と障害調査で agent を使う方法を書きました。

今回は Codex App です。

特に、非エンジニアや周辺職種の人にも分かるように、作業の型として書きます。

Codex Appは「会話」ではなく「作業場」

ChatGPT の延長で見ると、Codex App は会話画面に見えます。

でも、開発で使うなら会話ではなく作業場として見る方がいいです。

会話なら、1つの thread に何でも投げたくなります。

このエラー見て。
ついでにUIも直して。
あとREADMEも更新して。

これをやると、文脈が混ざります。

作業場として見るなら、thread を分けます。

Thread A: 商品検索の障害調査
Thread B: 商品検索UIの修正
Thread C: PR review
Thread D: AGENTS.md 更新

1 thread 1目的。

これだけで、かなり使いやすくなります。

projectは作業範囲

Codex App では、project を作ってフォルダやリポジトリに接続します。

project は、単なる保存場所ではありません。

agent に見せる作業範囲です。

だから、最初から巨大なホームディレクトリを選ばない方がいいです。

良い project の作り方です。

Project:
- 対象リポジトリ単位
- または、作業用に切った小さなフォルダ

含める：
- source code
- tests
- docs
- AGENTS.md
- INDEX.md

含めない：
- secrets
- unrelated projects
- private notes
- production credential

非エンジニアが使う場合も同じです。

たとえば、営業資料を整理するなら、プロジェクト用フォルダを作ります。

customer-brief/
  source-notes/
  slides/
  meeting-memo.md
  output/

そこだけを Codex App に見せる。

全部のデスクトップを見せない。

これはセキュリティだけではありません。

agent が迷わないためでもあります。

threadは作業単位

thread は、タスクの単位です。

1つの thread で1つの目的にします。

悪い使い方です。

このプロジェクト全体を良くして。

良い使い方です。

この thread では商品検索の障害調査だけをします。
まだ修正しないでください。

出力：
- 関連ファイル
- 現在の処理の流れ
- 再現条件
- 原因候補
- 修正前に確認すべきこと

thread の最初に、目的と禁止事項を書く。

これだけで作業が締まります。

最初のthreadでやること

新しい project を作ったら、いきなり実装しません。

最初の thread は、project 調査にします。

この project を read-only で調査してください。
まだファイルは変更しないでください。

出力：
- 主要ディレクトリ
- アプリの入口
- テストコマンド
- docs / AGENTS.md / INDEX.md の有無
- 触ってはいけない領域
- 最初に整備した方がよい文脈

この thread は、以後の作業の地図になります。

出力が良ければ、INDEX.md や AGENTS.md に戻します。

この調査結果から、次回のagentが最初に読むための INDEX.md 案を作ってください。

こうすると、Codex App の最初の会話が、次回の作業を楽にします。

Appshots / 画面共有は説明を減らす

画面を見せられる環境では、Appshots やスクリーンショットがかなり効きます。

特に、言葉で説明しにくいものです。

• UIが崩れている
• ボタンが見切れている
• 表の列幅がおかしい
• エラー画面が出ている
• 管理画面の操作が分からない
• PPTや資料のレイアウトが変
• ブラウザ上のフォームが意図通り動かない

こういうとき、長く説明するより画面を渡した方が早いです。

ただし、画面を渡すときも境界を書きます。

この画面を見て、UI崩れの原因候補を出してください。
まだファイルは変更しないでください。

見てほしいこと：
- どの要素が崩れているか
- 画面サイズとの関係
- 既存CSSで疑うべき場所
- 修正するなら最小変更範囲

見なくてよいこと：
- デザイン全体の作り直し
- 色やブランド変更
- unrelated refactor

画面を渡すと、agent は強くなります。

だからこそ、何を見るかも書きます。

画面は「証拠」として使う

画面共有の価値は、説明を楽にすることだけではありません。

証拠として使えることです。

たとえば、ユーザーから「検索画面が壊れている」と言われたとします。

人間が言葉で説明すると、曖昧になります。

検索欄のあたりが変です。

画面を渡すと、具体化できます。

この画面から、UI上の問題を事実と推測に分けてください。

Facts:
- 画面上で見えていること

Hypotheses:
- CSS / state / data の原因候補

Next:
- どのファイルを見るべきか

agent に「画面から事実と推測を分ける」ように頼むと、調査に入りやすくなります。

Codex Appは非エンジニアにも効く

Codex App の大きな意味は、コードを書ける人だけのものではないことです。

非エンジニアが、いきなりコードを修正する必要はありません。

でも、次の作業には使えます。

• エラー画面を説明させる
• 管理画面の操作手順を整理させる
• CSVの前処理案を作る
• 仕様書の不明点を洗い出す
• 開発者に渡すバグ報告を作る
• PRの説明を読みやすくしてもらう
• テスト観点を作る
• FAQや手順書の初稿を作る

ここで重要なのは、Codex App に「開発を全部やらせる」ことではありません。

技術者に渡す材料を整えることです。

非エンジニアの依頼例です。

このエラー画面と操作メモから、開発者に渡すバグ報告を作ってください。

含めるもの：
- 何をしようとしたか
- 何が起きたか
- 期待した結果
- 実際の結果
- 再現手順
- 画面から読み取れるエラー
- 追加で必要そうな情報

推測は推測として分けてください。

これはかなり実用的です。

開発者は「何が起きたか」を聞き返す時間を減らせます。

非エンジニアも、技術的な報告を作りやすくなります。

CLIとAppを使い分ける

Codex CLI と Codex App は、どちらが上という話ではありません。

向いている場面が違います。

CLI が向いているもの：

• 手元で素早くファイルを読ませる
• 小さな修正を進める
• テストを回しながら直す
• terminal の流れに乗せる
• 自分だけで集中して作業する

App が向いているもの：

• project / thread を分けて管理する
• 複数作業を並べる
• 画面やスクリーンショットを渡す
• 非エンジニアと作業を共有する
• 長めの調査やレビューを残す
• 進行中の作業を見返す

使い分けは単純です。

手元で速く直すなら CLI。
作業を見せる、残す、分けるなら App。

browser / frontend workでの使い方

frontend の作業では、画面が重要です。

コードだけ見ても分からないことがあります。

• hover 時に崩れる
• mobile だけ重なる
• 文言がボタンからはみ出る
• empty state が見にくい
• loading 中に layout shift する
• table の列が狭すぎる

Codex App では、画面を渡しながらこう頼みます。

この画面を見て、frontend review をしてください。

見るもの：
- text overflow
- mobile layout
- loading / empty / error state
- keyboard 操作
- 既存デザインとの違い

出力：
- 問題点
- 影響範囲
- 疑うべきファイル
- 最小修正案

ここでも、いきなり修正しない方がいいです。

まず review。
次に最小修正。
最後に再チェック。

この順番が安定します。

threadを分ける実例

商品検索のUI崩れを直す場合、thread をこう分けます。

Thread 1: 画面確認
- Appshot / screenshot を見せる
- 事実と原因候補を分ける
- 関連ファイルを出す

Thread 2: 実装修正
- 対象ファイルを限定する
- 最小修正だけ行う
- 関連テストを実行する

Thread 3: Review
- diff を見る
- UI状態を確認する
- mobile / empty / error state を見る

Thread 4: Compound
- 今回の見落としを AGENTS.md / checklist に戻す

1つの thread に全部詰め込まない。

これが大事です。

thread を分けると、人間も見返しやすいです。

「どこで判断したか」が残ります。

Appで使う依頼テンプレート

最初の project 調査：

この project を read-only で調査してください。
まだ変更しないでください。

出力：
- 主要ディレクトリ
- アプリの入口
- テストコマンド
- 既存docs
- AGENTS.md / INDEX.md の有無
- 最初に整備すべき文脈

画面確認：

この画面を見て、問題を事実と推測に分けてください。
まだ修正しないでください。

出力：
- 画面上の事実
- 原因候補
- 関連しそうなファイル
- 最小修正案
- 修正前に確認すべきこと

非エンジニア向けバグ報告：

この画面とメモから、開発者に渡すバグ報告を作ってください。

含めるもの：
- 操作手順
- 期待結果
- 実際の結果
- 再現条件
- 画面から読み取れるエラー
- 推測と事実の分離

PR review：

この差分を review してください。

見るもの：
- 仕様から外れていないか
- 変更範囲が広すぎないか
- 既存パターンに沿っているか
- テストが足りているか
- UI状態の見落としがないか

Compound：

今回の作業から、次回に戻すべきものを整理してください。

分けるもの：
- AGENTS.md に入れるルール
- checklist に入れる確認項目
- INDEX.md に入れる入口情報
- 今回だけのメモ

Appでやらない方がいいこと

Codex App が便利でも、何でも入れない方がいいです。

避けたい使い方です。

• 1つの thread に何でも詰める
• project に関係ないフォルダまで見せる
• secret や個人メモを含むフォルダを選ぶ
• 画面を渡して「全部直して」と頼む
• 変更範囲を書かない
• 画面上の情報をそのまま事実扱いする
• review なしで外部サービスへ反映する

App は作業台です。

作業台には、必要なものだけ置きます。

まとめ

Codex App は、チャット画面ではなく作業台として使うと強いです。

project は作業範囲。
thread は作業単位。
Appshots やスクリーンショットは説明を減らす材料。
画面は証拠として扱う。
CLI は手元で速い作業。
App は見せる、残す、分ける作業。

非エンジニアにとっても、Codex App は「コードを書く道具」だけではありません。

エラーを説明する。
バグ報告を整える。
仕様の不明点を出す。
開発者に渡す材料を作る。

ここが大きいです。

次回は、ここまでの流れをそのまま貼って使えるテンプレート集にします。