Using Both on One Project

You don't have to pick a side. Plenty of people run Claude Code and Codex on the same project. One builds and the other double-checks, or one gets stuck and the other takes a fresh look.

It works great, as long as you set things up so both tools follow the same rules and don't trip over each other's work. That's what this lesson is all about.

The Problem With Two Instruction Files#

Claude Code reads CLAUDE.md. Codex reads AGENTS.md. Keep two separate files and sooner or later they drift apart. You add "always run the tests" to one and forget the other, and now your two helpers follow different rules while you sit there wondering why one keeps skipping the tests.

The fix is simple. Keep your shared rules in one file, and let the other tool read that same file.

Option 1. AGENTS.md as the One File (Recommended)#

Put all your shared project rules in AGENTS.md. Codex reads it automatically. Then make a tiny CLAUDE.md right next to it that imports the AGENTS.md file. In Claude Code, a line that starts with @ followed by a file path pulls that file in.

@AGENTS.md
 
## Claude Code
- Use plan mode before changing anything in the billing folder.

Claude Code reads AGENTS.md first through the import, then any Claude-only notes you put below it. Codex just reads AGENTS.md. Now both tools follow the same rules, and you only ever edit ONE file.

Option 2. Only AGENTS.md#

Recent versions of Claude Code read AGENTS.md on their own when the project has no CLAUDE.md at all. So the very simplest setup is just one AGENTS.md file and nothing else.

The catch? If anybody ever adds a CLAUDE.md to the project later, Claude Code switches to reading that one instead. Older versions of Claude Code also don't read AGENTS.md directly. Option 1 dodges both of those surprises, which is why we recommend it.

Option 3. A Symlink (Mac and Linux Only)#

A symlink is a shortcut file that points at another file. You can make CLAUDE.md a shortcut to AGENTS.md.

ln -s AGENTS.md CLAUDE.md

This works, but Anthropic warns it causes trouble on Windows, where symlinks need special settings and can turn into a plain one-line text file. If anyone on your project uses Windows, stick with Option 1.

What Goes in the Shared File#

Same stuff you learned for CLAUDE.md. Keep it short and practical.

# AGENTS.md
 
## About this project
A small website for a local bakery. Plain HTML, CSS, and a little JavaScript.
 
## Commands
- Start the site with `npm run dev`
- Run the tests with `npm test`
 
## Rules
- Run the tests after every change.
- Ask before adding new packages.
- Never edit files in the `vendor` folder.

Handing Work Between Tools With Git#

Here's the most important habit in this whole lesson. Use Git commits as the handoff point. A commit is a saved snapshot of your project. When one tool finishes a chunk of work, you commit it, and the other tool starts from that clean, saved snapshot.

You'll learn Git properly in the GitHub module. For now, here's the general shape of it.

Step 1. Start a branch for the task#

A branch is a separate line of work, so your main code stays safe.

git switch -c add-contact-form

Step 2. Let the first tool do the work#

Open Claude Code (or Codex) in the project and give it the task. When it's done, read the changes yourself.

Step 3. Commit the result#

git add .
git commit -m "Add contact form (built with Claude Code)"

Writing which tool did the work in the message is a nice lil habit. Later, when you look back, you'll know who built what.

Step 4. Hand off to the second tool#

Open the other tool in the same folder and point it at the last commit.

Look at the last commit on this branch. It adds a contact form.
Add validation so the email field can't be empty, then run the tests.

When it's done, read the changes and commit again. That way each tool always starts from a saved, known-good spot.

Asking One Tool to Review the Other#

This is where running both REALLY shines. Have one tool build something, then ask the other to check it. A second opinion catches stuff the first one missed.

Codex Reviewing Claude Code's Work#

Codex has a built-in /review command. Type it inside Codex and it reviews the changes in your working folder, then reports the problems it finds without changing your files. Want it to compare against a base branch like main instead? Run codex review from your regular terminal, which can review uncommitted changes, a base branch diff or a single commit.

Claude Code Reviewing Codex's Work#

In Claude Code, just ask in plain words.

Review the changes on this branch compared to main. Look for bugs,
missing error handling, and anything that doesn't match the rules
in AGENTS.md. Don't change any files yet, just list what you find.

Then decide which suggestions you agree with, and ask either tool to fix those.

Safety Habits for Two Tools#

Twice the helpers means twice the reason to be careful. These habits keep you safe no matter which tool is driving.

1. Commit before you let either tool loose. If something goes wrong, you can always go back to your last commit. OpenAI's own advice for Codex says the same thing.
2. Read every diff. A diff shows exactly what changed. Use git diff in your terminal, or type /diff inside Codex. Never keep a change you haven't looked at.
3. One tool at a time in one folder. Finish, commit, then switch.
4. Keep risky modes off while you learn. Leave Codex in Auto or Read Only and stay far away from its --yolo flag. In Claude Code, switch to Manual mode with Shift+Tab whenever you want to approve each step.
5. Keep one set of rules. Shared rules in AGENTS.md, imported by CLAUDE.md, so both tools play by the same rules.

TL;DR#

• Keep shared rules in AGENTS.md and import it from CLAUDE.md with @AGENTS.md, so both tools follow one set of rules
• Use Git branches and commits as the handoff point between tools
• Have one tool build and the other review, with Codex's /review or a plain review request in Claude Code
• Run one tool at a time in a folder, commit often and read every diff

What's Next?#

You've finished the AI Coding Tools module! You know how to work with Claude Code and Codex, and how to use them together. Next up is the GitHub module, where you'll pick up the Git and GitHub skills that make all this handoff stuff feel easy...