learn/best-practices.md +223 −0 added
1# Best practices
2
3If you’re new to Codex or coding agents in general, this guide will help you get better results faster. It covers the core habits that make Codex more effective across the [CLI](https://developers.openai.com/codex/cli), [IDE extension](https://developers.openai.com/codex/ide), and the [Codex app](https://developers.openai.com/codex/app), from prompting and planning to validation, MCP, skills, and automations.
4
5Codex works best when you treat it less like a one-off assistant and more like a teammate you configure and improve over time.
6
7A useful way to think about this: start with the right task context, use `AGENTS.md` for durable guidance, configure Codex to match your workflow, connect external systems with MCP, turn repeated work into skills, and automate stable workflows.
8
9## Strong first use: Context and prompts
10
11Codex is already strong enough to be useful even when your prompt isn't perfect. You can often hand it a hard problem with minimal setup and still get a strong result. Clear [prompting](https://developers.openai.com/codex/prompting) isn't required to get value, but it does make results more reliable, especially in larger codebases or higher-stakes tasks.
12
13If you work in a large or complex repository, the biggest unlock is giving Codex the right task context and a clear structure for what you want done.
14
15A good default is to include four things in your prompt:
16
17- **Goal:** What are you trying to change or build?
18- **Context:** Which files, folders, docs, examples, or errors matter for this task? You can @ mention certain files as context.
19- **Constraints:** What standards, architecture, safety requirements, or conventions should Codex follow?
20- **Done when:** What should be true before the task is complete, such as tests passing, behavior changing, or a bug no longer reproducing?
21
22This helps Codex stay scoped, make fewer assumptions, and produce work that's easier to review.
23
24Choose a reasoning level based on how hard the task is and test what works best for your workflow. Different users and tasks work best with different settings.
25
26- Low for faster, well-scoped tasks
27- Medium or High for more complex changes or debugging
28- Extra High for long, agentic, reasoning-heavy tasks
29
30To provide context faster, try using speech dictation inside the Codex app to
31 dictate what you want Codex to do rather than typing it.
32
33## Plan first for difficult tasks
34
35If the task is complex, ambiguous, or hard to describe well, ask Codex to plan before it starts coding.
36
37A few approaches work well:
38
39**Use Plan mode:** For most users, this is the easiest and most effective option. Plan mode lets Codex gather context, ask clarifying questions, and build a stronger plan before implementation. Toggle with `/plan` or <kbd>Shift</kbd>+<kbd>Tab</kbd>.
40
41**Ask Codex to interview you:** If you have a rough idea of what you want but aren't sure how to describe it well, ask Codex to question you first. Tell it to challenge your assumptions and turn the fuzzy idea into something concrete before writing code.
42
43**Use a PLANS.md template:** For more advanced workflows, you can configure Codex to follow a `PLANS.md` or execution-plan template for longer-running or multi-step work. For more detail, see the [execution plans guide](https://developers.openai.com/cookbook/articles/codex_exec_plans).
44
45## Make guidance reusable with `AGENTS.md`
46
47Once a prompting pattern works, the next step is to stop repeating it manually. That's where [AGENTS.md](https://developers.openai.com/codex/guides/agents-md) comes in.
48
49Think of `AGENTS.md` as an open-format README for agents. It loads into context automatically and is the best place to encode how you and your team want Codex to work in a repository.
50
51A good `AGENTS.md` covers:
52
53- repo layout and important directories
54- How to run the project
55- Build, test, and lint commands
56- Engineering conventions and PR expectations
57- Constraints and do-not rules
58- What done means and how to verify work
59
60The `/init` slash command in the CLI is the quick-start command to scaffold a starter `AGENTS.md` in the current directory. It's a great starting point, but you should edit the result to match how your team actually builds, tests, reviews, and ships code.
61
62You can create `AGENTS.md` files at different levels: a global `AGENTS.md` for personal defaults that sits in `~/.codex`, a repo-level file for shared standards, and more specific files in subdirectories for local rules. If there’s a more specific file closer to your current directory, that guidance wins.
63
64Keep it practical. A short, accurate `AGENTS.md` is more useful than a long file full of vague rules. Start with the basics, then add new rules only after you notice repeated mistakes.
65
66If `AGENTS.md` starts getting too large, keep the main file concise and reference task-specific markdown files for things like planning, code review, or architecture.
67
68When Codex makes the same mistake twice, ask it for a retrospective and update
69 `AGENTS.md`. Guidance stays practical and based on real friction.
70
71## Configure Codex for consistency
72
73Configuration is one of the main ways to make Codex behave more consistently across sessions and surfaces. For example, you can set defaults for model choice, reasoning effort, sandbox mode, approval policy, profiles, and MCP setup.
74
75A good starting pattern is:
76
77- Keep personal defaults in `~/.codex/config.toml` (Settings → Configuration → Open config.toml from the Codex app)
78- Keep repo-specific behavior in `.codex/config.toml`
79- Use command-line overrides only for one-off situations (if you use the CLI)
80
81[`config.toml`](https://developers.openai.com/codex/config-basic) is where you define durable preferences such as MCP servers, profiles, multi-agent setup, and feature flags. You can edit it directly or ask Codex to update it for you.
82
83Codex ships with operating level sandboxing and has two key knobs that you can control. Approval mode determines when Codex asks for your permission to run a command and sandbox mode determines if Codex can read or write in the directory and what files the agent can access.
84
85If you're new to coding agents, start with the default permissions. Keep approval and sandboxing tight by default, then loosen permissions only for trusted repos or specific workflows once the need is clear.
86
87Note that the CLI, IDE, and Codex app all share the same configuration layers. Learn more on the [sample configuration](https://developers.openai.com/codex/config-sample) page.
88
89Configure Codex for your real environment early. Many quality issues are
90 really setup issues, like the wrong working directory, missing write access,
91 wrong model defaults, or missing tools and connectors.
92
93## Improve reliability with testing and review
94
95Don't stop at asking Codex to make a change. Ask it to create tests when needed, run the relevant checks, confirm the result, and review the work before you accept it.
96
97Codex can do this loop for you, but only if it knows what “good” looks like. That guidance can come from either the prompt or `AGENTS.md`.
98
99That can include:
100
101- Writing or updating tests for the change
102- Running the right test suites
103- Checking lint, formatting, or type checks
104- Confirming the final behavior matches the request
105- Reviewing the diff for bugs, regressions, or risky patterns
106
107Toggle the diff panel in the Codex app to directly [review
108 changes](https://developers.openai.com/codex/app/review) locally. Click on a specific row to provide
109 feedback that gets fed as context to the next Codex turn.
110
111A useful option here is the slash command `/review`, which gives you a few ways to review code:
112
113- Review against a base branch for PR-style review
114- Review uncommitted changes
115- Review a commit
116- Use custom review instructions
117
118If you and your team have a `code_review.md` file and reference it from `AGENTS.md`, Codex can follow that guidance during review as well. This is a strong pattern for teams that want review behavior to stay consistent across repositories and contributors.
119
120Codex shouldn't just generate code. With the right instructions, it can also help **test it, check it, and review it**.
121
122If you use GitHub Cloud, you can set up Codex to run [code reviews for your PRs](https://developers.openai.com/codex/integrations/github). At OpenAI, Codex reviews 100% of PRs. You can enable automatic reviews or have Codex reactively review when you @Codex.
123
124## Use MCPs for external context
125
126Use MCPs when the context Codex needs lives outside the repo. It lets Codex connect to the tools and systems you already use, so you don't have to keep copying and pasting live information into prompts.
127
128[Model Context Protocol](https://developers.openai.com/codex/mcp), or MCP, is an open standard for connecting Codex to external tools and systems.
129
130Use MCP when:
131
132- The needed context lives outside the repo
133- The data changes frequently
134- You want Codex to use a tool rather than rely on pasted instructions
135- You need a repeatable integration across users or projects
136
137Codex supports both STDIO and Streamable HTTP servers with OAuth.
138
139In the Codex App, head to Settings → MCP servers to see custom and recommended servers. Often, Codex can help you install the needed servers. All you need to do is ask. You can also use the `codex mcp add` command in the CLI to add your custom servers with a name, URL, and other details.
140
141Add tools only when they unlock a real workflow. Do not start by wiring in
142 every tool you use. Start with one or two tools that clearly remove a manual
143 loop you already do often, then expand from there.
144
145## Turn repeatable work into skills
146
147Once a workflow becomes repeatable, stop relying on long prompts or repeated back-and-forth. Use a [Skill](https://developers.openai.com/codex/skills) to package the instructions in a SKILL.md file, context, and supporting logic Codex should apply consistently. Skills work across the CLI, IDE extension, and Codex app.
148
149Keep each skill scoped to one job. Start with 2 to 3 concrete use cases, define clear inputs and outputs, and write the description so it says what the skill does and when to use it. Include the kinds of trigger phrases a user would actually say.
150
151Don't try to cover every edge case up front. Start with one representative task, get it working well, then turn that workflow into a skill and improve from there. Include scripts or extra assets only when they improve reliability.
152
153A good rule of thumb: if you keep reusing the same prompt or correcting the same workflow, it should probably become a skill.
154
155Skills are especially useful for recurring jobs like:
156
157- Log triage
158- Release note drafting
159- PR review against a checklist
160- Migration planning
161- Telemetry or incident summaries
162- Standard debugging flows
163
164The `$skill-creator` skill is the best place to start to scaffold the first version of a skill. Keep the first version local while you iterate. When it's ready to share broadly, package it as a [plugin](https://developers.openai.com/codex/plugins/build). One of the most important parts of a skill is the description. It should say what the skill does and when to use it.
165
166Personal skills are stored in `$HOME/.agents/skills`, and shared team skills
167 can be checked into `.agents/skills` inside a repository. This is especially
168 helpful for onboarding new teammates.
169
170## Use automations for repeated work
171
172Once a workflow is stable, you can schedule Codex to run it in the background for you. In the Codex app, [automations](https://developers.openai.com/codex/app/automations) let you choose the project, prompt, cadence, and execution environment for a recurring task.
173
174Once a task becomes repetitive for you, you can create an automation in the Automations tab on the Codex app. You can choose which project it runs in, the prompt it runs (you can invoke skills), and the cadence it will run. You can also choose whether the automation runs in a dedicated git worktree or in your local environment. Learn more about [git worktrees](https://developers.openai.com/codex/app/worktrees).
175
176Good candidates include:
177
178- Summarizing recent commits
179- Scanning for likely bugs
180- Drafting release notes
181- Checking CI failures
182- Producing standup summaries
183- Running repeatable analysis workflows on a schedule
184
185A useful rule is that skills define the method, automations define the schedule. If a workflow still needs a lot of steering, turn it into a skill first. Once it's predictable, automation becomes a force multiplier.
186
187Use automations for reflection and maintenance, not just execution. Review
188 recent sessions, summarize repeated friction, and improve prompts,
189 instructions, or workflow setup over time.
190
191## Organize long-running work with session controls
192
193Codex sessions aren't just chat history. They're working threads that accumulate context, decisions, and actions over time, so managing them well has a big impact on quality.
194
195The Codex app UI makes thread management easiest because you can pin threads and create worktrees. If you are using the CLI, these [slash commands](https://developers.openai.com/codex/cli/slash-commands) are especially useful:
196
197- `/experimental` to toggle experimental features and add to your `config.toml`
198- `/resume` to resume a saved conversation
199- `/fork` to create a new thread while preserving the original transcript
200- `/compact` when the thread is getting long and you want a summarized version of earlier context. Note that Codex does automatically compact conversations for you
201- `/agent` when you are running parallel agents and want to switch between the active agent thread
202- `/theme` to choose a syntax highlighting theme
203- `/apps` to use ChatGPT apps directly in Codex
204- `/status` to inspect the current session state
205
206Keep one thread per coherent unit of work. If the work is still part of the same problem, staying in the same thread is often better because it preserves the reasoning trail. Fork only when the work truly branches.
207
208Use Codex’s [subagent](https://developers.openai.com/codex/concepts/subagents) workflows to offload bounded
209 work from the main thread. Keep the main agent focused on the core problem,
210 and use subagents for tasks like exploration, tests, or triage.
211
212## Common mistakes
213
214A few common mistakes to avoid when first using Codex:
215
216- Overloading the prompt with durable rules instead of moving them into `AGENTS.md` or a skill
217- Not letting the agent see its work by not giving details on how to best run build and test commands
218- Skipping planning on multi-step and complex tasks
219- Giving Codex full permission to your computer before you understand the workflow
220- Running live threads on the same files without using git worktrees
221- Turning a recurring task into an automation before it's reliable manually
222- Treating Codex like something you have to watch step by step instead of using it in parallel with your own work
223- Using one thread per project instead of one thread per task. This leads to bloated context and worse results over time