Keeping project context across Claude Code and Codex

I keep the project brief, settled decisions and next steps in files that both tools can read. Each tool gets a short starting instruction pointing to those files. A handover records where the work stopped.

I use Claude Code and Codex in my own design and build work. Switching between them brings a practical problem: a useful decision can stay buried in the conversation where it happened. The next session then needs the explanation again, or works from an older version.

Here’s a small example of how I organise the work. It follows the structure I use, with demonstration files in place of private project material.

Give the project a clear starting point

The brief says what we're making, who it's for and what the current task covers. I keep it separate from the instructions for operating a particular tool. That makes it useful to a human colleague as well.

website-example/
  AGENTS.md
  CLAUDE.md
  project/
    brief.md
    decisions.md
    handover.md
  site/

For this example, both entry files contain the same short pointer:

Before working on the site, read:
- project/brief.md
- project/decisions.md
- project/handover.md

State the current task and the files you expect to change.
If a named source is missing, report it before relying on it.
Prepare changes for review; publication needs owner approval.

These are instructions for the demonstration. They don't configure permissions or make either tool read every file automatically. Claude Code and Codex have their own rules for finding project instructions. Check those rules in the tool and directory where the work will actually run. Claude Code's memory documentation and Codex's AGENTS.md guide explain their respective behaviour.

Keep each fact in one place

A shared folder helps only if its contents agree. I give each file a specific job. The brief describes the work; the decisions file records choices that should survive a new conversation; the handover describes the current state.

Here is a complete brief for the demonstration:

# Website brief
Reader: a business owner comparing a website redesign.
Purpose: explain the offer and make an email enquiry easy.
Current task: add a way to copy the prepared enquiry.
Keep: the approved identity, layout and email-draft option.
Content source: the approved page copy in site/.
Done when: the copy works with keyboard input and the visitor
can recover the message when clipboard access is unavailable.

The decisions file could record that the form opens an email draft and does not send a message. That distinction affects both the interface and the analytics. If the next session calls an email-draft click a submitted lead, the implementation may work while the reporting becomes misleading.

Write the next person's starting point

A useful handover names the change, its evidence and the remaining work. “Almost done” leaves the next person to reconstruct all three.

# Handover example
Task: add the enquiry-copy fallback.
Changed: site/index.html and the enquiry script.
Checked: required fields and copied message contents.
Still to check: clipboard refusal and keyboard focus.
Publication: not approved.
Next action: test the fallback, then review the page.
Evidence: record the actual check result beside each item.

This handover is illustrative, not a test report. In live work I include the actual paths, commands and results. The next session should inspect the files and current Git state before taking the note as current.

Test whether the instructions are being found

One failure in my own setup was easy to miss: starting Codex inside a nested repository did not bring in the wider workspace instructions I expected. The instructions existed, but that session hadn't received them.

I added an explicit starting pointer and checked the project instructions from the directory where the session began. The lesson for a shared setup is practical: open a fresh session, ask it to name the brief and the current task, and compare its answer with the files. Repeat that check from the project directory as well as the workspace root.

If it names the wrong source, fix discovery before expanding the system. Adding more instructions to a file the tool isn't reading won't help.

Keep review attached to the work

Context files can still be stale, contradictory or misunderstood. They don't replace checking the result. For a website change I review the diff, run the relevant checks and look at the page in both desktop and mobile layouts. Publication remains a separate decision.

I'd start a team pilot with one repeatable workflow, such as taking an approved page brief through to a reviewed build. Agree the input, the person who owns each source and the evidence needed to finish. Then try a handover with somebody who didn't watch the original conversation.

A useful first result is that the next person can continue the work and explain why a decision was made. Broader claims about speed or quality need evidence from the pilot.

For the design and build side of this approach, see my portfolio. If your team is repeatedly re-briefing the same work, describe one example when you get in touch.

Discuss a workspace workflow