Using CLAUDE.md and AGENTS.md in the Same Project

Shared project rules for Claude Code and Codex, a small import when needed, and a separate record of unfinished work.

Cover: AI-generated illustration.

When I moved work from Codex to Claude Code, I sometimes spent the beginning of a session explaining things the project already knew. The previous conversation had the background. The new one had the code, but finding the same working assumptions took effort.

That experience helped shape the instruction-sharing workflow in AigoPilot, which I build and use. I am its founder. The underlying arrangement is also useful without the studio: keep durable project guidance in a shared file, make sure each tool loads it, and record unfinished work separately.

Check what your version already supports

Codex reads AGENTS.md for project instructions. Current Claude Code documentation describes direct support from v2.1.277, with version and configuration exceptions. Under its default selection, a project or local CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in or above the working directory takes precedence over direct AGENTS.md loading.

That leaves two arrangements I would consider:

• Shared file only: use AGENTS.md when both installed tools actually load it.
• Shared file with a wrapper: keep AGENTS.md and a small CLAUDE.md importing it when that fits the environment or Claude-specific additions are needed.

Before adding a bridge, inspect the existing files and the instructions loaded by your session. Preserve useful rules already in the repository. There is no reason to replace a working setup just to match a diagram in an article.

Give the shared file a limited job

The first temptation is to put everything the project has ever discussed in AGENTS.md. That produces a document nobody can maintain confidently.

I would start with what a new contributor needs to avoid a predictable mistake: the project's purpose, where its important parts live, the relevant validation commands, and constraints that remain true across tasks.

Here is an illustrative starter. Replace the descriptions and commands with your repository's real ones before using it:

# Project instructions

## Purpose
This repository contains a desktop application and its supporting services.

## Working boundaries
- Preserve unrelated changes already present in the workspace.
- Read the existing implementation before proposing a replacement.
- Keep platform-specific behavior inside the existing platform layer.
- Explain a missing dependency or failed check instead of reporting success.

## Before making changes
- Identify the UI, platform integration, and test directories.
- Read the build and test configuration before choosing commands.
- State which files the task is likely to affect.

## Validation
- Run checks appropriate to the change.
- Report the commands run and their actual results.
- If a check cannot run, explain what is missing.

## Project-specific facts
Replace this section with the repository's verified paths,
build commands, and architectural constraints.

This is a proposed structure, not a description of my private repository. Its useful feature is that each instruction has a reason to be available across sessions. Temporary debugging notes belong elsewhere.

Add a thin Claude-specific wrapper when needed

For a setup that needs the import arrangement, the CLAUDE.md beside AGENTS.md can contain just this:

@AGENTS.md

This is Claude's documented import syntax. A prose reminder to open another file relies on the model deciding to do it. Put any necessary Claude-specific additions below the import.

Keep the dependency one way. Do not make AGENTS.md point back to CLAUDE.md. That makes the arrangement harder to reason about and can create an import loop.

I would choose this small text file over introducing a filesystem link into a Windows team's setup. If direct loading already gives you what you need, there may be no wrapper to add.

The import keeps one maintained source of rules. It does not make those rules free of context cost, or carry over a previous conversation's history.

Keep task state out of the permanent rules

A persistent instruction file answers questions such as which platform layer owns a feature. A handoff answers which change is unfinished today.

Mixing those two jobs makes old instructions look current. A note saying a test is failing can remain in a shared file long after the test has been repaired.

I prefer this separation as a starting design:

• Durable repository expectations: AGENTS.md.
• Necessary tool-specific additions: CLAUDE.md or supported tool configuration.
• Current task, changed files, next action: a dated handoff note.
• Long background explanation: a relevant document referenced from the instructions.

Use your own filenames for the handoff and background documents. The separation matters more than inventing another file convention.

Verify by asking a question, not by editing production code

Open a fresh session at the intended project location. I would begin with this read-only check:

Before making any changes, identify the instruction files that
apply to this working directory. Distinguish instructions loaded
at startup from files you opened during this check.

Summarize two project constraints and the validation commands
the repository actually defines. If no command is documented,
say so. Name any conflicting instructions you found.

Do not edit files or run build or test commands for this check.

This is a verification prompt, not a guarantee that a model's account of its own context is complete. Compare its answer with the files and the tool's inspection features.

In Claude Code, use /context to inspect memory files. Codex's instruction-discovery guide describes how its working directory and overriding files affect the result. For example, Codex recognizes AGENTS.override.md; Claude's direct AGENTS.md loader does not. Matching filenames do not mean identical discovery rules.

I would also check one nested part of the project where the rules differ. For example, UI work and a native integration layer may need different validation. Do not assume the two tools resolve every override convention identically.

For the first real task after switching tools, choose a small change that you can review easily. Check whether the session uses the right paths, preserves unrelated edits, and reports its actual validation. A convincing summary followed by work in the wrong directory is still a failed handoff.

The aim is a new session that can explain the project's working constraints before touching code. Its conversation history may be empty; the repository guidance should still be available.

I described the wider experience of managing projects, sessions and desktop tests in my Claude Code and Codex workflow. This shared-file arrangement addresses one small part of that experience: the project briefing I want available when another session begins.

References

Documentation checked November 1, 2026:

• OpenAI: custom instructions with AGENTS.md
• Anthropic: how Claude remembers your project