One Universal Prompt That Makes Codex Understand Your Project First

Use project discovery, requirement restatement, clarification, an implementation plan, and acceptance criteria to make Codex confirm the scope before changing code, reducing accidental edits, over-refactoring, and unverifiable implementations.

Many people's first instruction to Codex is:

Add a login feature for me.

Codex immediately starts creating files, installing dependencies, rearranging directories, and changing configuration. A few minutes later, it has certainly written a lot of code.

But there is a problem:

It may not truly understand your project. It does not know how the existing code is organized. It does not know the project's development conventions. It does not know which features must not change. It does not know how far you want the change to go. It may not even know how to verify the result.

The faster Codex works, the more disorder it may create.

The solution is simple:

Do not let Codex start changing things as soon as it receives a task.

First, make it do four things:

Read the project; Restate the requirements; Ask questions; Create a plan.

Every new Codex user should save the following prompt.

Universal Prompt: Understand the Project Before Making Changes

Copy this directly:

First, fully understand the current project and this task. Do not modify any files yet.

Step 1: Understand the project

Read the directories, code, configuration, and project documentation relevant to this task, then tell me:

1. What is the project's main purpose?
2. Which major technologies does it use?
3. Which core files relate to this task?
4. How is the current feature implemented?
5. Does the project contain AGENTS.md, README.md, or other development guidance?
6. How should the project be started, tested, and verified?

Step 2: Understand the requirements

Restate my request in your own words and clarify:

1. What problem should this task solve?
2. What should the user see when it is complete?
3. Which functionality needs to change?
4. What is outside the scope of this task?
5. What criteria do you think determine completion?

Step 3: Identify open questions

If the request is ambiguous, contradictory, or incomplete, ask me questions first.

Do not invent important business rules, page flows, data structures, or technical approaches.

If several implementations are possible, explain:

1. The advantages and disadvantages of each;
2. Their impact on the existing project;
3. Which one you recommend;
4. Why you recommend it.

Step 4: Create a plan

Provide a step-by-step implementation plan and explain:

1. Which files you intend to modify;
2. What will change in each file;
3. Whether new files are needed;
4. Whether new dependencies are needed;
5. Whether existing behavior may be affected;
6. What risks may exist;
7. How the completed change will be tested and accepted.

Until I approve the plan:

- Do not modify files;
- Do not create files;
- Do not delete code;
- Do not install or upgrade dependencies;
- Do not run database migrations;
- Do not change environment variables;
- Do not run destructive commands.

First provide:

1. Project understanding;
2. Requirement restatement;
3. Open questions;
4. Implementation plan;
5. Risks and acceptance method.

Wait for my confirmation before executing.

The prompt looks long, but it really does only one thing:

Prove that you understand before you are allowed to act.

Why Must Codex Read the Project First?

The same feature can be implemented very differently in different projects.

Suppose you ask Codex to add login.

The project may already use:

• A managed authentication service
• A custom account system
• Third-party login
• Local mock accounts
• No backend at all

If Codex does not read the project first, it may install an entirely new authentication framework.

Now the old system still exists and a second system has been added. Code is duplicated, logic conflicts, and maintenance becomes progressively harder.

Before changing anything, Codex should at least answer:

What does the project already have?

It should not jump directly to:

What should I add?

You cannot make a sensible change without understanding the current state.

Why Make It Restate the Requirements?

Many people believe their request is already clear, but what “done” means to you may differ completely from what it means to Codex.

You say:

Add customer search.

You may mean:

• Search by name
• Search by phone number
• Filter as the user types
• Show a message when nothing matches
• Restore all customers when the search is cleared

Codex may understand only:

• Add a search field
• Filter the current page after clicking a button

Both results can be called “search,” but only one matches your actual need.

Before execution, ask it to restate:

What are you going to do? What are you not going to do? What state counts as complete?

If its restatement is wrong, you only need to correct a few sentences. If you discover the misunderstanding after it finishes, dozens of files may need to be redone.

Correcting understanding first is always cheaper than correcting code later.

Why Make It Ask Questions?

One common beginner mistake is assuming Codex knows everything. In reality, it can only infer from the existing files and your description.

For example:

Add order refunds.

Many questions remain:

• Are refunds full or partial?
• What is the order status after a refund?
• Must the reason be recorded?
• Should it really call the payment provider?
• Who may initiate a refund?
• What happens when a refund fails?
• Should a notification be sent?

Without answers, Codex has to choose. Letting AI decide business logic on its own is usually dangerous.

The prompt should therefore say:

If information is ambiguous or missing, ask first. Do not assume.

A good Codex should not merely execute commands. It should also recognize when it must not continue.

Why Review the Plan First?

A plan is not there to look professional. It lets you catch a wrong direction before code changes.

A good plan should tell you:

• Which files will change
• Why each change is needed
• Whether dependencies will be added
• Whether existing functionality may be affected
• How the work will be tested
• How to recover from a failure

Suppose the plan says:

Refactor the entire user module.

But your request was only:

Change the login button's text.

You can stop it immediately:

Do not refactor the user module. This task changes only the button copy and related tests. Reduce the scope.

Planning is the least expensive stage at which to correct course. A few sentences can change the direction. Waiting until all the code is written may require starting over.

How Should You Start Execution After Approving the Plan?

Do not reply only with:

Okay, start.

Use a safer execution instruction:

The plan is approved. You may begin.

Follow the approved plan strictly and do not expand the scope.

During execution:

1. Complete one step at a time;
2. Do not modify files unrelated to the task;
3. Explain why before installing a new dependency;
4. Pause and ask me about problems outside the plan;
5. After each step, check whether existing behavior is affected;
6. Run the relevant tests after making changes;
7. Do not delete tests or lower verification standards merely to make tests pass.

When finished, tell me:

1. Which files changed;
2. Exactly what changed in each;
3. Which commands were run;
4. The test results;
5. Whether anything remains incomplete;
6. Whether any risks remain;
7. How I should verify it manually.

This prevents Codex from suddenly doing extra work “while it is here,” such as upgrading the framework, refactoring directories, replacing the database, or changing other pages.

Many projects are not broken by one obvious mistake. They become disorganized through countless incidental “improvements.”

Do Small Tasks Need Such a Long Prompt?

Not necessarily.

If you are fixing a typo, adjusting a button color, or adding a short explanation, you do not need the full template every time.

Use a compact version for simple tasks:

Inspect the code related to this task first. Do not modify it immediately.

First tell me:

1. How is the current feature implemented?
2. Which files do you intend to change?
3. How will you verify the result?
4. Could it affect other functionality?

Wait for my confirmation before executing.

Use the full version for complex tasks and the compact version for simple ones.

The criterion is not how much code you expect to write, but how much damage a mistake could cause.

The full version is recommended for:

• Login and permissions
• Database schemas
• Payments
• APIs
• Project architecture
• Large refactors
• Production environments
• Private user data
• Coordination across multiple modules

Add One More Rule: Prefer the Smallest Change

Codex sometimes initiates a large refactor to implement a small feature. Add this to your prompt:

Prefer the implementation with the smallest scope that is easiest to test and recover.

Unless the existing structure genuinely cannot satisfy the requirement, do not refactor unrelated modules, replace the current technology, or upgrade major dependencies.

This is extremely useful. In a real project, the best solution is not always the most advanced one. It is usually the one that solves the current problem at the lowest cost without breaking existing behavior.

Add Explicit Completion Criteria

Do not merely ask Codex to “finish the feature.” State what completion means.

For example:

This task is complete only when all of the following are true:

1. Users can search customers by name and phone number;
2. Results match the entered text;
3. A clear message appears when nothing matches;
4. Clearing the search restores the complete list;
5. Customer creation, editing, and deletion are unaffected;
6. All related tests pass;
7. The project restarts successfully.

Codex is most likely to stop at:

The code is written.

Your completion criterion should be:

The feature has been verified and works.

Written code does not mean a completed task.

A Realistic Example

Suppose you want to add search to a customer-management tool. Do not say only:

Add customer search.

Say this instead:

I want to add search to the current customer-management tool.

Goal:

Users can search customers by name or phone number.

Requirements:

1. Display matching customers after a keyword is entered;
2. Support partial name matching;
3. Support partial phone-number matching;
4. Show all customers when the search is empty;
5. Display “No customers found” when nothing matches;
6. Do not affect customer creation, editing, or deletion;
7. Do not replace the current technical approach.

Read the relevant project files first. Do not modify anything yet.

First tell me:

1. How is the current customer list implemented?
2. Where does customer data come from?
3. Which files need to change?
4. Do you recommend frontend filtering or backend search?
5. What are the differences between the two approaches?
6. How will you test the change?

If anything is uncertain, ask me first.

Do not modify files, install dependencies, or create modules until I approve the approach.

This prompt uses no complex technical terms, but it clearly states what to build, what must remain unaffected, how completion will be judged, and when execution may begin. It is far more reliable than “add search.”

Summary

Making Codex understand a project before acting consists of five steps:

First, read the project and learn its existing structure and implementation.

Second, restate the requirements and confirm that Codex's expected result matches yours.

Third, ask questions instead of guessing important rules.

Fourth, create a plan and review the scope, risks, and test approach in advance.

Fifth, wait for confirmation. Before approval, do not modify, install, or delete anything.

Codex's greatest advantage is execution speed. The faster it executes, however, the more expensive a wrong direction becomes.

Do not begin by asking:

Can you finish it immediately?

Ask first:

Do you truly understand this project and task?

Understand, then plan. Confirm, then execute.

That may be the simplest and most effective rule for using Codex.