Access granted · practical field guide

OpenAI Codex field guide

Codex becomes useful when it can see the right context, operate inside explicit boundaries, and prove what changed. This field guide takes you from one safe task to a repeatable team workflow.

You will finish with

one outcome contract
one repository or workspace context file
one reusable skill
one verified change
one handoff note another person can continue

Question, brainstorm or quick draft

Chat

An answer or first draft

Connected business knowledge and files

ChatGPT Work

A reviewed artifact

Code, tests and repository files

Codex

A diff with evidence

0/13 complete

Step 01

Choose the right surface

Chat, Work and Codex are not interchangeable. Begin with the place where the source of truth lives and the evidence the finished task must produce.

If the source of truth is…	Start with…	Finish with…
code, tests and repository files	Codex	a diff, tests and review evidence
connected business knowledge and files	ChatGPT Work	a document, spreadsheet, presentation or report
a question, brainstorm or quick draft	Chat	an answer or first draft

Do this now

1.Name the source of truth for one live task.
2.Name the final artifact and the permission boundary.
3.Pick the smallest surface that can finish it.

Realistic example

The broken resource renderer

The source of truth is this React/TypeScript repository; success requires a rendered access page, a diff and build evidence. That makes it a Codex task, not a Work task.

Expected output: A read-only inspection plan before edits.

Copyable prompt

I need to complete: [task]. The source of truth is: [repo/files/connected knowledge/web]. The final artifact must be: [artifact]. The permission boundary is: [read-only/read-write/approval required]. Recommend Chat, ChatGPT Work or Codex. Explain why, what the first safe step is, and what evidence should prove completion.

Verification or handoff

Write down why this surface is correct. If the next step needs a git diff, shell command, test run or repository edit, move it to Codex.

OpenAI: how it uses Codex OpenAI: running Codex safely OpenAI: Codex best practices OpenAI: AGENTS.md guidance

Mark complete

Step 02

Write the outcome contract

Do not start with “make it better.” Give Codex the messy version of your intent, then ask it to turn that into a finish line, non-goals and proof.

Do this now

1.Capture the raw request in your own words before polishing it.
2.Fill outcome, scope, non-goals and source of truth.
3.Name constraints, verification commands and human approval points.

Realistic example

This access-page rebuild

Raw brief: the tutorial needs the advanced workflow guidance from a transcript, without publishing unverified product claims. The contract turns that into scoped content files, reviewable copy and type/test/build checks.

Expected output: No literal \n, copyable prompts, current links and all checks pass.

Copyable prompt

Here is the messy version of what I need: [notes, voice transcript or bullets]. Turn it into an outcome contract. Separate outcome, scope, non-goals, source of truth, constraints, definition of done, verification and approval points. Do not change files yet. Flag every assumption that needs confirmation.

Verification or handoff

A reviewer should be able to reject an edit that is outside the written scope without debating taste.

Mark complete

Step 03

Make the first run safe

Let Codex inspect before it edits. Start with the smallest permission boundary that can answer the question, especially in an unfamiliar repository.

pwd
git status --short
rg --files | head -80
find .. -name AGENTS.md -o -name AGENTS.override.md
git log -5 --oneline

Do this now

1.Read repository instructions and current git status.
2.Map the relevant files and available checks.
3.Request a plan, then explicitly approve the first edit.

Realistic example

Preserve unrelated work

A dirty checkout is not a reason to overwrite it. Create an isolated worktree from current main and keep the original work untouched.

Expected output: A clean branch with a narrow file list.

Copyable prompt

Do not edit files yet. Read the repository instructions and inspect the files relevant to [task]. Return: 1. the current implementation path, 2. the smallest safe change, 3. risks and unknowns, 4. tests or checks that will prove completion, 5. the exact files you expect to touch. Stop and wait for approval. Do not bypass a missing permission or tool restriction through another surface.

Verification or handoff

Confirm the proposed files do not overlap unrelated user changes, that all planned writes are reversible or reviewable, and that no alternate tool path bypasses an approval boundary.

Mark complete

Step 04

Create durable repository context

Put recurring truth where every future session can find it. Durable instructions should be short, factual and scoped to the directory they govern; keep one named project thread for the decisions that are still active.

global rules → repository AGENTS.md → directory rules → named project thread → task-specific plan → source files/tests

Do this now

1.Find the highest applicable AGENTS.md.
2.Name and pin one project thread; state its current objective and next verification step.
3.Separate repo-wide rules from task notes, then record only a lesson that will prevent a repeat failure.

Realistic example

This repository

Its AGENTS.md requires an isolated session, architecture reading, preservation of unrelated work and type/unit/build verification after code changes. The project thread carries the current plan and evidence; AGENTS.md carries only durable rules.

Expected output: A concise rule and a legible active workstream that a future agent can continue.

Copyable prompt

Inspect this repository and its active work context. Draft a concise AGENTS.md improvement only for durable facts, then propose a named project-thread summary with objective, decisions, links to source-of-truth files, current state and next verification step. Do not invent policies or edit until approved.

Verification or handoff

Check that the rule names a concrete command or boundary, and that the thread summary contains current work rather than copying permanent repo instructions.

Mark complete

Step 05

Plan and isolate the work

A plan turns a vague request into a reviewable change. Isolation protects unrelated work and makes the final diff coherent.

request → inspection → plan → isolated change → checks → diff review → handoff

Do this now

1.Identify the issue and current baseline.
2.Start a session branch or worktree.
3.Record in-scope files and stop if scope expands materially.

Realistic example

The resource-page contract

A page is not complete when only its React component exists. The landing, access route, capture config, manifest, sitemap, OG surface, IndexNow and tests have to move together.

Expected output: A dependency-aware implementation checklist.

Copyable prompt

Create an implementation plan for issue [number]. Group the work by dependency. For every step include files, expected behavior, verification, rollback concern and whether human approval is required. Do not implement until the plan is approved.

Verification or handoff

Compare the finished diff with the file list. Explain every intentional omission before handoff.

Mark complete

Step 06

Turn repeated behavior into a skill

If you explain the same workflow twice, turn it into a reusable instruction. Grow it deliberately: one successful manual run, a small personal skill, repeat validation, then a team-owned workflow with review.

Do this now

1.Find the existing workflow owner.
2.Read its required files and verification gates.
3.Propose a small addition only after the manual run works.

Realistic example

One-off to system

Instead of “create another resource page,” use the resource-page skill to clone the reference, update every required surface and report the evidence. It becomes a team workflow only after examples, an owner and review gates exist.

Expected output: A repeatable workflow with one source of truth.

Copyable prompt

Find the smallest existing skill or instruction that already governs this work. Read it completely. Follow its required file list and verification gates. If the workflow is recurring but not codified, propose the exact skill change after completing the current task. State its maturity: manual run, personal skill, validated repeatable skill or team-owned workflow. Do not create a duplicate skill.

Verification or handoff

Blind-test the instruction on a related task. Before sharing it with a team, name the owner, permissions, example task and change-review rule.

Mark complete

Step 07

Connect MCP deliberately

Every integration increases capability and the permission surface. Start read-only, allowlist the tools needed, and name failure behavior before use.

Connection	Useful for	Default posture
Supabase	inspect approved application data	read-only first
GitHub	issues, PRs and source	scoped repository access
SEO tools	research evidence	research only until verified
custom MCP	domain actions	allowlist tools and approvals

Do this now

1.List the exact tools needed.
2.Identify data access and side effects.
3.Define approval and revocation points.

Realistic example

Wrong database, wrong answer

This repository explicitly requires the Supabase connector for application data and warns against using an unrelated database connector.

Expected output: A scoped read-only query or a clear stop.

Copyable prompt

Before using this MCP connection, list the tools you need, the data each tool can access, the side effects each tool can cause, and the approval required. Use the minimum tool set. Prefer read-only inspection. Stop before any write or destructive action.

Verification or handoff

Record the tool used and source returned. Treat a tool error as a blocker, never as permission to guess.

Mark complete

Step 08

Use subagents with control

Parallel work helps only when the slices are independent and the evidence can be reviewed by the lead agent.

lead agent → researcher / implementer / verifier → lead synthesis

Do this now

1.Split only independent work.
2.Give each role a narrow output and no-overlap boundary.
3.Synthesize findings before changing shared files.

Realistic example

A useful verifier brief

Ask a read-only verifier to find duplication, escaped newlines and the browser checks that would prove a resource-page fix.

Expected output: Findings with file paths and evidence, not edits.

Copyable prompt

Role: verifier. Scope: inspect only [files]. Questions: [questions]. Output: findings with file paths and evidence. Restrictions: no edits, no external writes. Stop when evidence is incomplete.

Verification or handoff

Do not delegate ambiguous product decisions, destructive work or overlapping file ownership.

Community report: keeping AGENTS.md focused Community report: reviewing agent-created changes

Mark complete

Step 09

Run durable work with goals and monitors

Long-running work needs a named goal, a verifier and a stop condition—not an agent running forever. Keep the project thread current, report only material changes and escalate when a human decision is needed.

goal → plan → smallest safe action → verifier → material update or stop → handoff

Do this now

1.Write one measurable goal and the command, test or review that verifies it.
2.Choose a cadence and define what counts as a material update.
3.Set an owner, stop condition and approval point before any monitoring starts.

Realistic example

A safe pull-request monitor

Check the PR twice daily for review feedback and failed checks. Summarize only changed status, draft fixes with evidence, and stop at merge, a blocker or a request for approval.

Expected output: A concise status update—not silent, open-ended autonomy.

Copyable prompt

Set up a durable work plan for [goal]. Define the project thread name, source of truth, plan, verification method, check cadence, material-update rule, stop condition, owner and approval points. Default to read-only monitoring and drafts. Do not send messages, merge, publish or bypass permissions without approval.

Verification or handoff

A monitor is safe only if another person can answer: what it checks, how it proves progress, when it stays quiet, when it stops and who can authorize the next action.

Mark complete

Step 10

Ship evidence, not confidence

“It looks right” is not a release check. Use a verification ladder that covers code, rendered behavior and asset substance.

npm run check:types
npm run test:unit
npm run build

Do this now

1.Inspect the source and diff.
2.Run type, unit and production-build checks.
3.Open the rendered page and verify links and assets substantively.

Realistic example

The SPA fallback trap

A missing image can return HTTP 200 because the SPA catch-all serves HTML. Check content type for image assets, not status alone.

Expected output: A browser-verified page and content-type evidence.

Copyable prompt

Review the implementation against the acceptance criteria. Inspect the diff, run the required checks, open the rendered page, and report failures with evidence. Do not claim success from HTTP 200 alone.

Verification or handoff

Check no literal \n appears, no prompt body is duplicated, copy buttons work, mobile is readable and every jump link resolves.

Mark complete

Step 11

Teams and enterprise governance

Enterprise Codex is a capability-and-authorization problem. A rollout is ready only when access, change authority and review accountability are explicit.

Role	Responsibility
member	works inside the approved boundary
technical owner	maintains repository and workflow context
security reviewer	approves data and tool exposure
workspace admin	controls groups, seats and settings

Do this now

1.Choose an approved repository and limited pilot group.
2.Set read-only first, then controlled write.
3.Define audit evidence, rollback and an owner.

Realistic example

Pilot worksheet

Capture approved users, repositories, apps/MCP tools, read-write boundary, approval points, data handling and rollback criteria before enabling a workflow.

Expected output: A pilot another admin can audit.

Copyable prompt

Pilot goal: [goal]
Approved users/groups: [groups]
Approved repositories: [repos]
Allowed apps and MCP tools: [tools]
Read/write boundary: [boundary]
Human approval points: [points]
Audit evidence: [evidence]
Data and secret handling: [policy]
Rollback/exit criteria: [criteria]
Owner: [owner]

Verification or handoff

The organization must answer: what Codex may access, what it may change, and who reviews the evidence.

OpenAI: how it uses Codex OpenAI: running Codex safely OpenAI: Codex best practices OpenAI: AGENTS.md guidance

Mark complete

Step 12

The non-developer route

You do not need to be a full-time developer to use Codex safely. You do need plain-language explanations, approval points and proof of what changed.

Do this now

1.Start with one bounded task.
2.Ask for a plain-language plan before edits.
3.Review changed files and remaining risks at the end.

Realistic example

Content-page update

A non-developer can own an issue-driven update to a resource page: inspect, approve the plan, review the preview and confirm the checks.

Expected output: A reviewed change, not a mystery automation.

Copyable prompt

I am not a developer. Explain the repository and proposed change in plain language first. Ask before editing. After implementation, show me the files changed, what could still be wrong, and how to verify the result.

Verification or handoff

Hand off to ChatGPT Work when the next output is a business artifact and no repository, shell or test evidence is required.

Mark complete

Step 13

Handoff and maintenance

Finish by improving the system that will handle the next task. A completed change should be legible to a teammate who did not see the conversation.

Do this now

1.Summarize changed files and behavior.
2.Attach verification evidence and known limits.
3.Create a follow-up or update a durable instruction when needed.

Realistic example

A useful closeout

The handoff says the generic text renderer was replaced, names the two access pages, lists checks run and points to the source model for future updates.

Expected output: A clear owner and next review date.

Copyable prompt

Prepare a handoff for another operator. Include changed files, behavior, verification evidence, unresolved risks, follow-up work and the durable instruction that should be updated so this failure does not recur.

Verification or handoff

If you cannot name the next owner, the evidence or the remaining risk, the handoff is not done.

Mark complete

Finish with a handoff

Make the next run easier.

Record what changed, why it changed, the checks or sources used, remaining limits, the next owner and the next review date. A useful workflow is one another person can continue without redoing the discovery.

Back to the tutorial overview ChatGPT Work tutorial Claude Code tutorial AI Work Cycle Context Engineering