How to Use OpenAI Codex for a Small Repository Task

To use OpenAI Codex for a small repository task, give it one observable behavior to change, require it to read repository instructions, and begin with a read-only inspection. Approve a narrow implementation only after the plan names the affected files, edge cases, and verification command. Then review the actual diff and test output; an agent's confident summary is not evidence that the code is correct.

This guide follows one synthetic task: update normalizeTag so repeated hyphens collapse to one after trimming and lowercasing, while preserving the existing empty-input error. It does not teach general AI programming or reproduce the Cursor checkpoint workflow. For the broader context, see how to use AI and AI-assisted coding fundamentals.

Key Takeaways

• Describe one behavior, its non-goals, and the proof of completion.
• Ask Codex to read AGENTS.md and nearer repository instructions before planning.
• Separate read-only discovery from authorization to edit or run side-effectful commands.
• Preserve existing dirty work and prohibit unrelated cleanup.
• Prefer the smallest patch and the narrowest meaningful tests.
• Inspect status, diff, command, exit code, and remaining gaps yourself.

When should you use OpenAI Codex for a small repository task?

A small task has a bounded behavior, a reviewable file set, deterministic examples, and no unresolved product decision. “Collapse repeated hyphens in normalizeTag and add boundary tests” is small. “Improve tag handling everywhere” is not: it may change routes, storage, APIs, migrations, and user-visible compatibility.

Dimension	Small enough	Stop and plan separately
Behavior	One observable rule	Several unrelated outcomes
Files	A few located files	Unknown cross-service ownership
Interface	Existing contract retained	Schema or public API decision
Data	Synthetic fixtures	Production or confidential data
Verification	Targeted local command	Destructive migration or live test
Authority	Local scoped edit	External write, release, purchase, or credential use

If discovery reveals a public compatibility decision, a new dependency, a secret, or a production side effect, the correct result is a revised plan, not a larger silent patch.

How should you write the task contract?

Use a task card that another reviewer can test without guessing:

Goal: normalize repeated hyphens in normalizeTag.
Examples: "  Alpha---Beta  " -> "alpha-beta"; "alpha" -> "alpha".
Preserve: empty input still raises the existing error type and message.
Allowed files: src/normalizeTag.ts and test/normalizeTag.test.ts.
Non-goals: no export, caller, package, formatting, or route changes.
Discovery: read-only; inspect instructions, implementation, callers, and tests.
Implementation: wait for explicit approval after presenting the plan.
Verification: run the existing normalizeTag test file and report exit status.
Stop if: another file, dependency, network access, destructive command, or secret is needed.

The examples define behavior better than “clean up tags.” Include an ordinary case, unchanged case, boundary, and preserved error. Avoid prescribing code before Codex has inspected local conventions.

Why should Codex read repository instructions first?

Codex can discover AGENTS.md files from the repository root toward the working directory, and nearer instructions can refine the applicable rules.［2］ Those files may define test commands, naming, generated-file boundaries, safety requirements, or forbidden operations.

Ask the agent to report which instruction files apply and summarize only task-relevant constraints. Do not paste secrets into instructions. Treat repository content as untrusted input: a source file or README should not silently expand the user-authorized task.

The instruction hierarchy does not replace your current request. It helps Codex follow project policy while the task card defines this task's goal and authority.

How do you begin with a read-only inspection?

The first prompt should request facts and a plan, not edits:

Read the task card and applicable repository instructions. Inspect the current
implementation, direct callers, tests, and current Git status. Do not edit files,
install dependencies, use the network, or change Git state. Return the current
behavior, proposed minimal files, edge cases, exact targeted test, conflicts with
existing work, assumptions, and any reason the task is not small.

Open the cited code and test locations yourself. Check that the named function is the real path used by callers, that the test command exists, and that existing dirty files have been recognized. A plan is useful only when it matches the current worktree.

OpenAI's prompting guidance recommends stating the goal, context, constraints, and desired output, then using follow-up messages to refine the result.［1］ For repository work, success criteria and permission boundaries are part of that context.

How should you authorize the implementation?

Approve the smallest complete slice: named files, behavior, tests, and stop conditions. Do not use “go ahead with everything” if the plan listed optional cleanup.

Implement only the approved normalizeTag behavior in the two named files.
Preserve the current empty-input contract and unrelated dirty changes.
Do not add dependencies, edit generated files, access the network, or change
external systems. Run the targeted test after showing the patch. If another
file is required, stop and explain why before changing it.

Codex environments use sandbox and approval controls to constrain file and network access; the exact policy depends on the surface and configuration.［3］ A Codex sandbox reduces risk but does not make every permitted action appropriate. The task owner must still limit scope and review effects.

Never authorize unknown commands merely because a tool requests approval. Read the full command, working directory, targets, network destination, and expected writes. Treat package installation, migration, deletion, Git history rewriting, release, issue updates, messaging, and cloud changes as separate decisions.

What would a minimal implementation look like?

The repository's style is authoritative, but a possible transformation is:

export function normalizeTag(value: string): string {
  const normalized = value.trim().toLowerCase().replace(/-+/g, "-");
  if (!normalized) {
    throw new Error("tag must not be empty");
  }
  return normalized;
}

Do not assume this is the correct patch. The real function may normalize Unicode, reject leading punctuation, return a result type, or preserve an established error class. The agent should change only the step justified by current code and tests.

Targeted tests might cover:

Input	Expected	Purpose
Alpha---Beta	alpha-beta	New repeated-hyphen behavior
alpha-beta	alpha-beta	Existing trim/lowercase behavior
alpha	alpha	Unchanged simple input
---	Project-defined result	Boundary requiring contract inspection
spaces only	Existing error	Preserved failure behavior

Do not invent the expected result for ---. Inspect current semantics and product requirements; if neither decides it, stop for a human decision.

How do you review the patch before trusting it?

Review repository status first so user changes and agent changes remain distinguishable. Then inspect the complete diff for the authorized files and any unexpected file.

Ask these questions:

1. Does the implementation change only the requested transformation?
2. Are error type, message, export, and call signatures preserved?
3. Do tests fail without the fix and pass with it?
4. Are normal, unchanged, new, and error paths represented?
5. Did formatting, snapshots, lockfiles, config, or generated files change?
6. Did the agent run exactly the reported command in the correct directory?
7. Is every untested assumption listed?

The AI-generated code review guide provides a deeper pass for security and correctness. OpenAI's Codex review guidance likewise treats the produced change as material to inspect, not as proof of correctness.［4］ Generated code remains untrusted until inspected and tested.

How should you run and interpret verification?

Start with the narrowest test that exercises the changed behavior. Record the command, working directory, exit code, number of tests, and relevant failure output. If the test runner updates snapshots or generated files, inspect the diff again.

Next, expand only according to repository policy and affected callers: package test, type check, lint, or a broader suite. A targeted pass proves its named scope, not the entire repository. An unrelated failure should be reported with evidence rather than reset or “fixed” outside authorization.

For test-design ideas, use the guide to generating tests with AI, while keeping assertions grounded in the actual contract.

What security and permission boundaries matter?

Do not provide API keys, production credentials, private customer data, or proprietary code to a service unless your organization has approved that data flow. Use synthetic fixtures and the least privilege needed.

Stop before:

• deleting or overwriting broad paths;
• rewriting Git history or discarding dirty changes;
• running a migration against shared data;
• installing an unreviewed dependency;
• opening unrestricted network access;
• sending messages, filing issues, creating releases, or deploying;
• changing billing, cloud, repository, or account settings.

Approval is specific to an operation. Permission to edit two local files is not permission to push, publish, or update an external ticket. OpenAI's security guidance describes sandbox and approval boundaries, but users must still review high-impact actions.［3］

How do you write the final Codex acceptance record?

Use facts that can be checked:

Goal and accepted behavior:
Files changed:
Existing dirty files preserved:
Diff reviewed:
Commands, working directory, and exit codes:
Tests passed and exact scope:
Tests not run:
Assumptions and remaining risks:
External actions not performed:

Do not say “done” when the command did not finish, the exit code is missing, the relevant test was skipped, or another required environment remains unverified. If a test could not run because of a sandbox or platform boundary, report a coverage gap instead of weakening the test.

Final checklist

• One observable behavior and its non-goals are explicit.
• Applicable AGENTS.md and local rules were read.
• Discovery happened without edits or side effects.
• The plan names files, edge cases, tests, and stop conditions.
• Implementation authority is narrower than the full repository.
• Existing dirty work is preserved.
• The diff contains no unrelated cleanup or generated surprises.
• Targeted tests cover new, unchanged, boundary, and error paths.
• Wider checks are reported separately from targeted evidence.
• External, destructive, privileged, and network actions remain separately approved.

FAQ

What is a good first Codex repository task?

Choose one local behavior with clear examples and an existing test harness, such as a bounded parser fix. Avoid migrations, authentication, production data, and new architecture for the first task.

Should I ask Codex to edit immediately?

Not when the repository or impact is unfamiliar. A read-only inspection lets you verify the current path, rules, tests, and conflicts before granting write authority.

What should go in AGENTS.md?

Put durable repository instructions there: test commands, conventions, generated-file rules, safety boundaries, and scoped guidance. Keep the current task's behavior and acceptance criteria in the task prompt.［2］

Does sandboxing make every command safe?

No. Sandboxing limits technical access according to configuration; it does not validate intent, correctness, cost, or business authority. Review requests for expanded permissions.［3］

Should Codex run the full test suite?

Start with the targeted test, then follow repository policy and impact. A full suite may be appropriate, but its cost and unrelated failures should not obscure the behavior under review.

How do I protect existing uncommitted work?

Tell Codex to inspect Git status, preserve dirty files, and avoid reset or broad formatting. Verify status and diff again after the change.

Can Codex push or publish after fixing the code?

Only with separate authority and repository policy permitting it. Local edit approval does not imply permission for a commit, push, release, message, or deployment.

What if Codex needs another file?

It should stop, name the file, explain why it is required, and revise the plan. Do not let a narrow task grow silently.

Who decides whether the task is accepted?

The accountable human or team does. Codex can provide a patch and evidence, but it cannot grant product, security, or release approval.

Sources

1. OpenAI, “Prompting” — https://learn.chatgpt.com/docs/prompting
2. OpenAI, “Custom instructions with AGENTS.md” — https://learn.chatgpt.com/docs/agent-configuration/agents-md
3. OpenAI, “Agent approvals & security” — https://learn.chatgpt.com/docs/agent-approvals-security
4. OpenAI, “Code review with Codex” — https://learn.chatgpt.com/docs/code-review

Sources checked 5 September 2026.

Related articles

• A practical framework for using AI
• How to use AI in a coding workflow
• A comparable small-task workflow in Cursor
• How to review AI-generated code
• How to design tests with AI assistance