English translation
Getting Started with Codex Zero: Reading the Codebase, Making Minor Changes, and Running Checks
When introducing Codex to your project for the first time, the most important thing is not to rush.
You’re not testing whether Codex can “generate code out of thin air.” Instead, you’re establishing a collaborative rhythm: read → ask → modify → verify → review the diff. Once this rhythm becomes habitual, using Codex for bug fixes, test writing, refactoring, or documentation becomes significantly more reliable.
I care far more about whether Codex can successfully complete one small, end-to-end change: clearly articulate what it read, precisely identify where to make the change, execute relevant checks, and meaningfully interpret the results. A standalone code snippet—without context, justification, or verification—is not evidence that Codex has truly entered your repository.
Here, readers are invited to run a low-risk task—e.g., updating a button label or adding a missing empty-state message. Success isn’t defined by “it looks changed,” but by three concrete outcomes:
✅ A clean, focused git diff
✅ A passing build
✅ A functional page in the browser
Step 1: Read Only — No Modifications
Navigate to your project’s root directory:
Before making any changes, confirm the repository’s structure, target files, expected modifications, and available validation commands. Every step should be traceable—so results remain auditable and reproducible.
codex
Your first prompt can be:
Do not modify any files yet. Please analyze the current project and tell me:
1. What technology stack is used?
2. Where is the main entry point file?
3. What are the local commands for starting, testing, and building?
4. Which directories or files carry the highest modification risk?
5. Based on this, what small, safe task would you recommend for my first change?
This step builds Codex’s mental map of your project—and simultaneously lets you assess whether Codex has correctly understood its structure.
Step 2: Pinpoint Specific Files
If you want to adjust the login page, avoid vague requests like “optimize login.” Instead, be precise:
The guide “Codex’s First Repository Entry: Read Structure, Make a Tiny Change, Run Checks” is best approached through four lenses: scenario, concept, action, and outcome. Align these four elements first—then return to details like parameters, code snippets, or workflows.
I want to update the error message text on the login page. Please locate the related component, API call, and styling files.
Still do not modify any files—only explain how you identified each file (e.g., via search, import analysis, or call-graph tracing).
Codex will use code search, dependency tracing, and structural analysis to find relevant files. Don’t judge the elegance of its answer—judge whether the files it identifies are actually correct and relevant.
Step 3: Modify Just One Small Thing
Once the entry points are confirmed, assign an extremely narrow scope:
Change *only* the error message shown when login fails. Do not modify APIs, state management logic, or add new dependencies.
After editing, run the smallest relevant validation command available in the project.
If Codex proposes changes across many files, pause and ask why. The smaller the first task, the faster trust is built.
Step 4: Require Verification
Official best practices emphasize that Codex performs best when it can verify its own work. Explicitly instruct it:
Please run the most relevant validation command and report:
1. The exact command executed
2. Whether it passed or failed
3. If it failed: Is the failure causally linked to this change?
Common frontend checks include npm run build, pnpm lint, or npm run type-check. In Python projects, it might be pytest. Avoid asking Codex to introduce new testing frameworks—leverage existing project tooling.
Step 5: Review the Diff Yourself
After Codex finishes, don’t just accept “Done.” Run:
git diff
Or ask Codex directly:
Please list all modified files and highlight:
- Any potentially unrelated changes
- Areas of elevated risk
- Any unverified aspects of this change
What you’re really building is a closed loop: clear objective → tightly scoped action → objectively verifiable outcome. Codex doesn’t replace engineering judgment—it helps you reach the point where judgment is needed, faster and more reliably.
Three Most Common First-Time Mistakes
Mistake #1: Overly broad tasks Phrases like “optimize the project” lack boundaries. Codex may scan dozens of files and propose sweeping changes—making review harder, not easier.
When revisiting “Codex’s First Repository Entry: Read Structure, Make a Tiny Change, Run Checks,” skip large-scale projects. Start with one simple, self-contained example to validate whether the core workflow is clear.
If the guide hasn’t fully clicked yet, walk through these four actions again—using this card as your checklist.
Mistake #2: Omitting reproduction steps When fixing bugs, how to reproduce matters more than guessing root causes. Tell Codex: → How to start the app → Exact user actions (e.g., “click ‘Login,’ enter invalid credentials”) → Observed behavior (e.g., “blank screen appears”) → Expected behavior (e.g., “error toast should display ‘Invalid email’”) This grounds Codex’s analysis in real, observable behavior.
Mistake #3: Skipping verification Never settle for “I’ve fixed it.” Always require Codex to run the minimal relevant check—and explicitly interpret the result. Even if tests fail, you’ll know whether the failure relates to your change—and where to investigate next.
The goal of Codex’s first repository entry isn’t to ship a major feature. It’s to confirm Codex can consistently complete one small, closed-loop task. Once that loop runs smoothly, gradually expand scope—confidently.
References:
Continue