Exploring a repo safely

Codex is open. The project folder is attached. You can feel the pull of the ticket: “just fix onboarding.” The agent will happily invent a helper that does not exist, touch six packages, and leave you with a diff you cannot defend in review. The fix is not a secret prompt template. The fix is a four-beat conversation: ask, map, bound, then small change. Same order you would use with a sharp junior engineer on their first day in the monorepo.

This is Part 2 of the ChatGPT Codex tutorial. Part 1 covered what Codex is, where it sits next to Chat and Work, plan-shaped limits, and the first-run ritual (open project, orient, tiny change, review). If product doors still blur, keep the ChatGPT product map open. Account and first-week safety stay in Learn ChatGPT from scratch. Human-led Chat skills without agent blast radius live in the ChatGPT everyday tutorial. Office multi-step jobs stay in the ChatGPT Work tutorial. Here we stay in Codex and go deep on exploring a repo safely before you invite real edits.

UI labels and permission prompts still move. Treat workflows below as a July 2026 field guide. Re-check developers.openai.com/codex, Using Codex with your ChatGPT plan, and ChatGPT Work and Codex when you codify team habits.

What you’ll learn

Why explore-before-edit beats “fix everything in one breath”
A four-beat loop: ask, map, bound, then small change
First questions that force paths, commands, and boundaries (not brochure language)
How to use tests, siblings, and blast-radius questions as a map
Branching, secrets hygiene, and why Codex is not for silent production deploys
A worked explore loop on a toy notes API you can copy this week
Smells that mean you should stop editing and go back to questions

The four beats: ask, map, bound, change

Explore a repo safely in four steps: ask what is this, map entry points, bound what not to touch, then small change

Think of Codex as a teammate who can read the tree faster than you and write faster than you. Speed is only useful if the shared map is right. The four beats keep the map honest.

Beat	Your job	Agent’s job	Done when
Ask	State role, goal, and constraints in plain language	Answer with structure and file paths	You can open the cited files and they match the story
Map	Drill into one area; demand examples and tests	Search, read, summarize, maybe run read-only commands	You know where a change should live and what might break
Bound	Name folders, systems, and actions that are off limits	Stay inside the fence; surface risks instead of “helpfully” expanding	The agent can restate the fence without you prompting twice
Change	Name the smallest useful patch; review every diff	Edit under your approvals; run checks if asked	You can explain the patch in one sentence and a check holds

People collapse the beats because tickets are written as outcomes (“dark mode”) not as investigations (“where is theme state owned today?”). Codex will happily collapse with you. Your job is to refuse the collapse until the map is good enough.

Before you type: branch and fence the workspace

Exploration is safer on a clean branch with a clean mental fence.

cd ~/src/notes-sandbox
git status
git checkout -b explore/onboarding-map

Branch: so weird experiments do not land on main.
Project root only: grant Codex the repo folder, not your entire home directory, unless you have a rare reason and a real policy for it.
No secrets in chat: do not paste .env, private keys, customer dumps, or session cookies “for context.” Describe shapes. Use placeholders.
No silent production deploys: explore and patch in the tree; ship through your normal release path with humans on the critical steps.

If the working tree is already dirty with your half-finished work, stop. Commit or stash first. Mixed human and agent edits in one unreadable soup make review impossible.

Beat 1: ask questions that force a map

Good first questions for Codex: what does this project do, where is the main entry, how do I run tests, what would br…

Starters should be intentionally boring. On a cold repo, try:

What does this project do?

Where is the main entry point? List file paths.

What technologies does this project use? Cite config files.

Explain the top-level folder structure. One sentence per top-level path.

Then move from brochure language to operational language:

How do I run tests and start the app locally? Quote the exact commands from the repo. Do not invent scripts.

Where is user authentication enforced for HTTP requests? List file paths.

Which package owns billing, and which packages only consume it?

Are there .env.example files or secret patterns I should never commit? Do not print secret values.

Notice the pattern. You are asking for paths, commands, and boundaries, not vibes. “This is a modern scalable platform” is useless. “Entry is apps/web/src/main.tsx, API is services/api, auth middleware is services/api/src/middleware/auth.ts” is gold, but only after you open those files.

Frame role and risk up front

Codex does not know whether you are a new hire, a contractor, or the original author unless you say so. A short framing block saves thrash:

I am new to this repo. I can run basic git and tests.
I am not allowed to change production deploy config today.
Goal: understand how notes are created, then fix a small validation bug.
Prefer small diffs and existing patterns over new frameworks.
Do not edit until I say so.

That is not ceremony. It cuts off “helpful” refactors into a new state library when you asked about required fields on a form.

What good answers look like

They name files you can open in under ten seconds.
They distinguish “I read this” from “I am guessing.” If the agent never shows uncertainty on a messy repo, be suspicious.
They match what package.json, pyproject.toml, go.mod, or the README already say about scripts.
They stop when you say “enough map, next question,” instead of pitching a rewrite.

If answers stay abstract after two tries, change tactics: “Show the contents of the top-level directory and tell me what each top-level folder is for.” Agents get better when the question attaches to something concrete on disk.

Beat 2: map like you mean it

Map is still mostly reading. You may allow shell commands that list files, search, or run tests. You should still hesitate before write tools. Explicit language helps: “Do not edit files yet.” “List options with tradeoffs; recommend one; wait for my pick.” If the product offers a plan-only or read-first style control on your build, use it while you explore. Exact control names move; the intent does not: research before mutation.

Follow the path, not the slogan

When Codex says auth lives in middleware, open the middleware. Skim imports. Ask the next question from what you see:

In services/api/src/middleware/auth.ts, where do tokens get verified?
Is there a test that covers an expired token?
Do not edit yet.

This is the human part people skip. If you only read the chat pane, you are doing code review of a book report.

Find the sibling feature

Almost every “new” feature has a cousin. Want a new webhook? Find the last webhook. Want a new admin filter? Find the last admin filter. Point Codex at it:

Find an existing admin list filter and explain the pattern end to end:
route, query params, UI control, tests.
I want to add a filter for createdAfter using the same pattern.
Do not edit yet. List the files I would touch.

Agents imitate visible structure. When the sibling is clear, the first change is boring in the best way. When no sibling exists, say that out loud: “This may be a new pattern. Stay minimal.”

Use tests as a map

If the repo has tests, ask where behavior is specified before you invent behavior:

Which tests cover note creation?
What is the smallest command that runs only those tests if possible?
Run that command after you identify it.
Do not change code yet.

Read permission prompts for test commands. Running tests is usually lower risk than rewriting packages, but “run tests” should not silently become “upgrade the entire toolchain.” Deny command shapes you do not recognize.

Blast radius before renames

Before you rename a symbol or move a module, force a dependency map:

What would break if I rename createNote to createUserNote?
List importers and tests that reference the current name.
Do not edit yet.

If the answer is “everything, probably,” you either need a careful multi-step plan or you need a smaller goal. Explore is where you discover that truth, not after half the tree is rewritten.

Beat 3: bound what you will not touch

Maps without fences invite helpful disasters. After orientation, write the fence in the chat so it is part of the shared context:

Bounds for this session:
- Do not edit deploy/, infra/, or *.tf files
- Do not change database schema or migrations
- Do not add new dependencies without asking
- Do not print or request production secrets
- Do not open PRs or push without my explicit ask
- Prefer edits under src/routes/ and test/

Ask the agent to restate the bounds in its own words. If it “forgets” mid-session and proposes a migration, stop the change and restate the fence. Bounds are leadership, not paranoia.

Secrets and env files

Good explore question:

Point me at .env.example or config templates.
List which env var names the app expects.
Do not open real .env files if present.
Do not print any secret values.

If a real .env is in the tree and not gitignored, that is a finding for humans, not content for the model. Fix the ignore rules in a separate careful change. Do not paste the file into chat to “confirm.”

Production is out of bounds for silent agents

Codex can help you prepare a change. It does not own production. Treat suggestions to force-push, skip CI, disable auth “temporarily,” or deploy from the agent session as automatic stops. Your release process, not the chat transcript, is the source of truth for going live.

Beat 4: change small, then review

Only after the map is good enough do you invite writes. “Good enough” means you know the primary file(s), the pattern to copy, the fence, and a check you will run (test, script, or manual click path).

Write the change request like a careful ticket

Weak:

Fix validation

Stronger:

In the note creation API, reject empty titles with a 400 and a clear error body
matching existing error shape in this service.
Add or update a test next to the existing note creation tests.
Do not change database schema.
Do not refactor unrelated files.
Show the diff and wait for review before commit.

Specificity is kindness. It also makes bad diffs obvious: if the patch touches schema or renames half the module, something went wrong relative to the ask.

Review before commit (still non-negotiable)

After edits land:

git status
git diff

Ask Codex to explain the diff if you want a guided tour, then distrust the tour until the hunks match. Look for:

Files you did not mention
New dependencies you did not approve
Deleted tests or weakened assertions
Formatting-only churn that hides a real logic change
“Helpful” renames that break public API surface
Secrets, tokens, or .env contents that should never appear

Commit only when you can defend the patch. Later parts of this series go deeper on review, tests, and not trusting green checkmarks alone. The explore habit makes those reviews possible: small scope, known map, clear fence.

Worked example: empty title on a notes API

Setup from Part 1 style: you are in ~/src/notes-sandbox on branch explore/onboarding-map, desktop Codex attached to that folder, tests available via npm test.

Ask

What does this project do?
Where is the HTTP entry point?
How are notes created today?
Do not edit files yet.

Codex points at src/server.js, src/routes/notes.js, and src/db.js. You open notes.js. There is a POST /notes handler that inserts title and body with almost no checks.

Map

Do not edit yet.
How does this service format 400 errors for other routes?
Where are tests for POST /notes?
What command runs only those tests if possible?

You learn errors look like { "error": "message" } with status 400. Tests live in test/notes.test.js. Command is npm test -- test/notes.test.js. You allow the test run. Existing tests pass. None cover empty title.

Bound

Bounds:
- Touch only src/routes/notes.js and test/notes.test.js
- No schema changes
- No new dependencies
- No deploy config
Restate these bounds before you edit.

Change

Add validation so POST /notes returns 400 with { "error": "title is required" }
when title is missing or only whitespace.
Add a test in test/notes.test.js next to the other POST tests.
Do not change the database schema or other routes.

Codex proposes a small guard and a test. You approve both file edits after reading the paths. You ask it to run the notes tests again. Green. You run git diff. Two files. No surprise lockfile. You commit: “fix: reject empty note titles with 400.”

That loop took longer than a single “fix validation” prompt. It also produced something you can merge without praying.

Prompt patterns that transfer

Pattern	Example stub	When
Map first	“Explain X with file paths; no edits.”	New area of the tree
Sibling clone	“Match the pattern in FILE; list steps; wait.”	Feature similar to an existing one
Blast radius	“What else imports this symbol?”	Before renames or signature changes
Test seatbelt	“Find the smallest relevant test command; run it; no edits yet.”	Behavior bugs with a clear expected result
Scope lock	“Touch only these paths: …”	Any time the agent gets ambitious
Rollback line	“If tests fail, stop and summarize; do not keep hacking.”	Long agent loops
Secret fence	“Never print secrets; use .env.example only.”	Any config-adjacent work

Smells that mean stop editing

Unrelated files changed for a one-line ask
New framework or dependency you did not request
Deleted or weakened tests to make green appear
Deploy, infra, or secrets showing up in the plan
Huge rewrite for a tiny bug
Force-push or “skip CI” language
Paths that do not exist when you open them (map was wrong; go back to ask)

When you smell smoke, say “stop editing, summarize what you believe is true, list files you would open next.” Reset the map. Do not “just let it finish.”

Free/Go vs Plus/Pro while you explore

Explore loops cost tokens and time. Free and Go can still learn the shape of Codex if the product exposes it on your account, but long multi-file investigations burn limited capacity. Plus and Pro are built for more usable coding sessions. Either way, explore questions are usually cheaper than failed rewrites: a path map prevents ten bad edit rounds. Scope the session: one area of the tree, one goal, one fence. Re-check live limits on chatgpt.com/pricing and help articles when you plan a team day of agent work.

Parallel habits, OpenAI names

If you have used other coding agents, the explore-before-edit idea is familiar. Keep the product names straight for OpenAI: Codex for software in a project, Chat for conversation, Work for office multi-step deliverables. Do not paste a monorepo into Work and expect a clean software patch. Do not ask Chat to “own” a multi-file refactor without project tooling. Shared vocabulary is how review culture survives tool churn.

Common mistakes

Skipping the map because the ticket is “small”

Small tickets still need a home in the tree. Wrong file, confident patch, long debug.

Never opening the cited paths

If you do not open files, you are trusting a summary of a summary. Open the entry point at least once.

No bounds

Without a fence, “helpful” agents wander into infra, lockfiles, and reformats of half the repo.

Secrets in the prompt

Explore does not require production credentials. If debugging needs real values, do it in a controlled local env without pasting secrets into chat.

Working on main

Branch first. Undo is a feature. Use it.

Treating green tests as permission to deploy

Tests help. They do not replace human review or release process. Part 4 in this series digs into review and green-checkmark traps. The rule starts here: explore and patch carefully; ship through your real path.

How this series fits the AMS ChatGPT path

Learn ChatGPT from scratch: orientation and safety foundations
ChatGPT product map: Chat vs Work vs Codex and related splits
ChatGPT everyday tutorial: human-led Chat skills
ChatGPT Work tutorial: multi-step office agent work
ChatGPT Codex tutorial: Part 1 open features and first project; Part 2 explore safely (you are here); then skills/tasks, review/tests, git habits

Wider curriculum paths also sit on Learn.

Practice for this week

Pick a sandbox repo. Create an explore branch.
Run five orientation questions with “do not edit yet.” Open every path the agent cites.
Write a bounds block (no deploy, no secrets, limited paths).
Find one sibling feature and document the pattern in three sentences yourself.
Only then request a small change with an explicit test or manual check.
Review git diff. Commit only if you can defend the patch in one sentence.

Quick recap

Explore before edit: ask, map, bound, then small change
Force paths, commands, and fences; open the files yourself
Use siblings and tests as maps; blast-radius questions before renames
Branch first; no secrets in chat; no silent production deploys
Stop when diffs sprawl, tests vanish, or paths do not exist
Next: skills, tasks, and scheduled help as the product offers them (Part 3)

What’s next

Part 3: Skills, tasks, and scheduled help (as product offers) covers power-ups after you can review a simple change: reusable workflows, one-off tasks, and scheduled jobs you watch carefully. After that, review and tests without trusting green checkmarks alone, then git-friendly habits for beginners.

Sources

Official product and help materials used for this article (re-check the week you set policy; UI and plan packaging move):

Codex in ChatGPT (product overview for agentic software engineering)
OpenAI Help: ChatGPT Work and Codex (Chat vs Work vs Codex; when to write, debug, run tests, review changes, work with a repository)
OpenAI Help: Using Codex with your ChatGPT plan (access and getting started; plan-shaped usage including Free and Go)
OpenAI Help: Moving to the new ChatGPT desktop app (Codex as software development with local files, repositories, terminals, developer tools)
OpenAI Help: Codex collection (security, rate card, related how-tos)
OpenAI Help: Codex Security (security-oriented guidance; re-check for current recommendations)
OpenAI Developers: Codex (technical docs for Codex surfaces and workflows)
OpenAI and OpenAI Help Center (live release notes and account-specific steps)
Analytics Made Simple: Learn ChatGPT from scratch
Analytics Made Simple: ChatGPT product map
Analytics Made Simple: ChatGPT everyday tutorial
Analytics Made Simple: ChatGPT Work tutorial
Analytics Made Simple: Learn