Field guide / 12 min
Run the first repository session like an engineer
Working directory and definition of done shape the result more than prompt theatrics.
The first useful Codex session begins in the right repository with a bounded permission mode and a prompt that states goal, context, constraints, and done condition. Codex can explore, edit, run checks, and report evidence, but only when the task boundary is explicit.
Verified terminal sequence
- $
codex - $
codex -C path/to/repo - $
codex --sandbox workspace-write --ask-for-approval on-request
Working principles
Directory is context
Launch inside the intended repository or set it with -C. Repository guidance and project configuration are discovered from that root.
Prompt the contract
State the goal, relevant files or errors, boundaries, and observable completion criteria.
Ask for evidence
A confident summary is not verification. Require the checks run, their result, and any remaining uncertainty.
Field procedure
- 01
Choose a reversible task
Begin with a small documentation, test, or focused bug task whose expected result is easy to inspect.
- 02
Launch in the correct root
Use codex in the repository, or codex -C when your shell is elsewhere.
- 03
Write the task contract
Name goal, context, constraints, and done condition in plain language.
- 04
Let Codex inspect before editing
Ask it to locate the real execution path and state its intended validation before making changes.
- 05
Review the evidence
Inspect changed files, tests, and unresolved risks before accepting the result.
PASS / FAIL
Acceptance checklist
- The session workspace is the intended repository.
- The prompt states what must remain unchanged.
- Done means observable checks, not prose.
- You inspect the resulting diff.
WATCH / REJECT
Failure patterns
- Launching one directory above several unrelated repositories.
- Listing micro-steps while omitting the desired outcome.
- Accepting a completion claim without checks.