Codexに小さなUI変更を任せる前に決めること

3行まとめ

Copy

文言。

Space

余白。

State

状態。

Props

部品値。

小さなUI変更は、最初に種類と範囲を分けます。

• 小さなUI変更は、copy、spacing、state、component propsに分けると膨らみにくくなります。
• Codexには、before、after、target files、対象外、確認条件をセットで渡します。
• PRには、差分、画像、確認結果、未決事項を残し、戻し方も短く書きます。

小さなUI変更は、AIに任せやすい作業です。button文言を変える、余白を少し直す、empty stateを整える、badgeの出し分けを変える。OpenAI公式のCodex Use Casesにも、既存appでfast, focused UI iterationを行う「Make granular UI changes」が紹介されています。

ただし、小さい依頼ほど油断しやすいです。「ちょっと直して」と投げると、周辺componentの整理、copyの全面変更、別stateの追加、styleの共通化まで広がることがあります。見た目の変更は小さくても、PRが大きくなればreviewは重くなります。

この記事では、2026年6月1日時点のOpenAI公式Codex docsをもとに、既存appの小さなUI変更をCodexへ任せる前の範囲管理を整理します。Figma designをcodeへ変換する話ではなく、すでに動いている画面の差分を小さく作る話です。

この記事でわかること

Scope

対象。

Before

現状。

Check

確認。

PR

証跡。

beforeとafterがあると、UI差分の判断が揃います。

• 小さなUI差分を分類する方法
• scopeを1画面、1componentへ絞る考え方
• Codexへ渡すbefore/afterとtarget filesの作り方
• 変えるもの、変えないものを確認条件へ入れる方法
• PRを小さく保つための証跡
• rollbackやfollow-upを残す理由

Figma designをcodeへ変える場合は、公開済み記事のCodexでFigmaデザインをコードにする前に見る差分が近いです。この記事では、design sourceが大きくある前提ではなく、既存画面の小さな修正に絞ります。

前提知識

項目	内容	見方
Granular UI		小変更。
Front-end		UI作成。
Features		作業入口。
Worktrees		差分分離。
AGENTS.md		repo手順。

既存appの小さな変更は、design作成ではなく差分管理として扱います。

OpenAI公式のCodex Use Casesでは、Make granular UI changesがfront-end design用途として紹介されています。既存appでfast, focused UI iterationを行う用途です。同じfront-end系には、Figma designをcodeへ変える用途、screenshotsやvisual referencesからresponsive front-end designを作る用途もあります。

小さなUI変更は、設計や新規UI生成よりも、差分管理の色が強い作業です。すでにある画面を壊さず、限定された箇所だけ変え、reviewで確認できる証跡を残すことが大事です。

Codex Use Casesで見る位置づけ

用途	この記事での扱い
Make granular UI changes	既存appの小さなUI差分を作る
Turn Figma designs into code	designを実装へ変換する
Build responsive front-end designs	visual referenceからUIを作る
QA your app with Computer Use	実際の画面操作で確認する
Review GitHub pull requests	human review前に差分を見る

design-to-codeとの違い

design-to-codeは、Figmaやvisual referenceから実装へ変換する作業です。対象のdesign sourceがあり、componentやtokenとの対応を見ます。

granular UI changeは、既存appの小さな差分です。button文言、余白、empty state、tooltip、badge、component propなど、限定された変更を小さなPRで完了させます。

小さなUI差分を4種類に分ける

項目	内容	見方
Copy		button文言。
Spacing		余白。
State		emptyやerror。
Props		component値。

種類を分けると、必要なreviewerと確認方法が見えます。

小さなUI差分は、copy、spacing、state、component propsに分けます。これだけで、必要なreviewerと確認方法が見えやすくなります。

copyは文言の変更です。spacingは余白や配置の調整です。stateはempty、error、loading、disabled、selectedなどです。component propsは、既存componentへ渡す値やvariantの変更です。

copy

copy変更は簡単に見えますが、product ownerやsupport ownerの確認が必要なことがあります。button文言、error message、empty state、tooltip、CTAは、ユーザーの理解や問い合わせに影響します。

Codexには、変更前と変更後の文言、変更理由、確認者を渡します。似た文言が他画面にある場合も、今回は対象外か、同時に直すかを決めます。

spacing

spacing変更では、既存tokenやutility classを優先します。Figmaの数値や目視の感覚でhard-coded valueを増やすと、後で揃わなくなります。

Codexには、既存のspacing scale、component props、style utilityを確認させます。新しい値が必要な場合は、勝手に追加せずopen questionへ残します。

state

state変更は、normalだけで判断しないことが大事です。empty、loading、error、permission denied、disabled、long text、small data、large dataを見ます。

小さな変更でもstateを触ると影響が広がります。たとえばempty stateを直すだけのつもりが、API errorやpermission表示にも関係することがあります。

component props

component propsの変更は、既存componentの使い方を変える作業です。variant、size、tone、icon、disabled、loading、label、descriptionなどです。

Codexには、componentの利用箇所を見させます。今回の画面だけ変えるのか、component defaultを変えるのかで影響範囲が大きく違います。

scopeを1画面に絞る

1. 1Route

   画面。

2. 2Component

   部品。

3. 3Files

   対象file。

4. 4Out

   対象外。

1つのPRでは、routeとcomponentを絞るほどreviewしやすくなります。

小さなUI変更は、scopeを1画面に絞ります。route、component、target files、out of scopeを明示します。

「似た箇所も全部直す」は魅力的ですが、PRが膨らみます。まず1画面で確認し、必要ならfollow-upへ分けます。

route

routeは、対象画面です。URL、app内の画面名、feature flag、roleを含めます。

Codexには、対象routeだけを確認させます。関連routeへ波及する場合は、今回のPRで見るか、別PRにするかを決めます。

component

componentは、変更対象の部品です。page componentなのか、shared componentなのか、local componentなのかを分けます。

shared componentを触ると、他画面へ影響します。小さなUI変更では、まずlocal usageやprops調整で済むかを見ます。

out of scope

out of scopeは、今回やらないことです。copyだけ変えるならlayout変更はしない。spacingだけ直すならcomponent APIは変えない。empty stateだけならerror stateは触らない。こうして範囲を守ります。

out of scopeを明示すると、Codexの提案が広がっても止めやすくなります。

Codexに渡す入力

Before

現状。

After

期待。

Files

対象。

Rules

制約。

入力は、現状と期待の差分が分かる形へまとめます。

Codexに渡す入力は、before、after、target files、constraintsです。曖昧な依頼ではなく、差分が分かる依頼にします。

beforeは現状です。afterは期待です。target filesは触ってよい場所です。constraintsは守る条件です。

before

beforeには、現在の画面、現在の文言、現在のstate、問題点を書きます。screenshotやURLがあれば添えます。

Codexには、beforeを見て「どこを変えるべきか」を推測させるのではなく、「ここをこう変える」と指定する方が安定します。

after

afterには、期待する見た目や文言を書きます。完全なdesignがなくても、beforeとの差分を書ければ十分な場合があります。

たとえば、「empty stateのtitleを短くする」「secondary buttonをlink styleにする」「warning badgeを既存のtoneへ合わせる」のようにします。

target files

target filesは、変更候補のfileです。Codexに探索させる場合でも、対象directoryやrouteを絞ります。

fileを指定できない場合は、まず調査だけを依頼します。いきなり編集まで進めるより、対象componentを特定してから修正する方がreviewしやすいです。

確認条件を先に決める

項目	内容	見方
Visual		見た目。
Behavior		操作。
A11y		利用性。
No change		非変更。

変えるものだけでなく、変えないものも確認条件に入れます。

確認条件は、visual、behavior、accessibility、変えないものに分けます。小さなUI変更でも、確認なしでは不安が残ります。

Codexには、実装後に何を確認したかを報告させます。できれば、実行command、URL、screenshot、未確認項目を残します。

visual

visualでは、変更した箇所が期待通りかを見ます。文言、余白、badge、alignment、icon、stateの表示を確認します。

before/after screenshotがあると、reviewerが判断しやすくなります。小さな変更ほど、何が変わったのかが見えにくいからです。

behavior

behaviorでは、click、focus、hover、disabled、loading、navigation、submitなどを見ます。

見た目だけの変更でも、buttonやlinkの構造を変えると操作に影響する場合があります。component props変更では特に注意します。

accessibility

accessibilityでは、label、focus、keyboard、contrast、screen reader向けの名前を見ます。

copy変更でも、buttonの意味が曖昧になることがあります。iconだけのbuttonにした場合は、accessible nameが必要です。

変えないものを確認する

小さなUI変更では、変えないものも確認します。API、routing、permission、data取得、他state、他画面を変えないことです。

PR本文に「変更していないもの」を短く書くと、reviewerが安心して見られます。

PRを小さく保つ

項目	内容	見方
Diff		少量。
Test		範囲対応。
Shot		画像。
Owner		確認者。

小さなUI変更は、小さなPRとして完了させます。

PRは小さく保ちます。UI差分、test、screenshot、ownerを分けて、reviewできる単位にします。

小さなUI変更のPRで、ついcomponent整理やstyle cleanupまで入れると、reviewが重くなります。cleanupは別PRに分けた方がよいことが多いです。

diff

diffでは、変更file数、変更行数、shared componentの有無を見ます。

shared componentを触った場合は、影響画面を列挙します。local componentだけなら、その画面の確認に集中できます。

test

testは変更範囲に合わせます。typecheck、lint、unit test、component test、Storybook、Playwright、manual screenshotなどです。

すべてを毎回走らせる必要はありませんが、何を確認し、何を確認していないかは残します。

owner

ownerは、design owner、product owner、front-end ownerを分けます。

copyはproductやsupport、spacingやcomponentはdesignやfront-end、stateはproductとengineeringが見ることがあります。誰が最終判断するかを決めます。

rollbackしやすくする

1. 1Flag

   切替。

2. 2Revert

   戻す。

3. 3Follow

   次PR。

4. 4Note

   記録。

小さな差分でも、戻し方を短く残します。

小さなUI変更でも、戻し方を短く残します。feature flag、revert、follow-up、記録の4つです。

特に、copyやUI stateはユーザー反応を見て戻すことがあります。小さい差分として残っていれば、戻しやすくなります。

feature flag

feature flagがあるなら、切り替え可能にする選択肢があります。ただし、小さな文言変更までflag化すると運用が重くなります。

flagが必要なのは、影響が広い、A/B testをする、段階公開する、戻す可能性が高い場合です。

revert

revertしやすいPRにするには、差分を混ぜないことです。copy変更、component整理、test cleanupを同じPRに入れると戻しにくくなります。

PR本文には、戻す場合の対象commitや影響範囲を短く書きます。

follow-up

follow-upは、今回やらない関連作業です。似た画面の横展開、component共通化、token整理、追加state、A/B testなどです。

follow-upへ逃がすことで、今回のPRを小さく保てます。

よくある失敗

Too wide

広がる。

No before

現状なし。

No state

状態なし。

No owner

確認者なし。

小さい依頼ほど、前提が抜けやすくなります。

よくある失敗は、依頼が広すぎる、beforeがない、afterが曖昧、stateを見ない、shared componentの影響を見ない、ownerがいないことです。

もう1つは、「小さいから確認不要」と扱うことです。小さな文言や余白でも、重要なflowではconversionや問い合わせに影響します。

Codexに任せるなら、作業そのものより、scopeとreviewの型を固定することが大事です。小さい変更を小さいまま終わらせる仕組みを作ります。

FAQ

項目	内容	見方
Copy?		owner確認。
Spacing?		token優先。
State?		既存pattern。
Large?		分割。

迷ったら、今回のPRで何を変えるのかへ戻します。

copyだけならreviewはいりませんか？

文言の種類によります。内部toolの小さなlabelなら軽く済むこともありますが、CTA、error、empty state、料金、権限、公開画面のcopyはowner確認を入れます。

spacingだけならscreenshotで十分ですか？

screenshotは有効ですが、状態や画面幅も関係します。必要に応じて、対象stateや主要viewportを確認します。

shared componentを直してもよいですか？

直せます。ただし、影響範囲が広がります。小さなUI変更では、まず対象画面でprops調整できるかを見て、共通化は別PRへ分ける判断もあります。

変更が大きくなったらどうしますか？

一度止めて、調査PR、component整理PR、UI差分PRに分けます。大きくなったままreviewへ出すと、意図も確認も見えにくくなります。

参照した主な情報源

• https://developers.openai.com/codex/explore/
• https://developers.openai.com/codex/use-cases
• https://developers.openai.com/codex/app/features
• https://developers.openai.com/codex/app/worktrees
• https://developers.openai.com/codex/guides/agents-md

次に読むなら

更新履歴

1. 2026.06.01

   初版。

Codexのfront-end use casesは、導入時に公式docsで見直します。

• 2026年6月1日: OpenAI公式Codex docsを確認して初版を作成しました。