Use one shared instruction file with tool-specific exceptions

If you keep giving an AI coding tool the same correction, that correction probably belongs in the repository.

For Codex, persistent project guidance normally starts in AGENTS.md. Claude Code reads CLAUDE.md, but that file can import AGENTS.md. This makes it possible to maintain one shared project contract and keep only genuine tool differences in a small adapter.

The distinction matters. Package commands, architecture boundaries, content rules, and public-route requirements do not change because a different coding agent opens the repository. Image tools, permission models, validation environments, and tool-specific commands may change.

Start with a shared project contract

The shared file should contain facts and working agreements that apply regardless of which coding tool is active.

Useful instructions include:

• Project structure and ownership boundaries
• Package manager and common commands
• Test, lint, type-check, and build expectations
• Framework and content conventions
• Accessibility, security, performance, and SEO requirements
• Public behavior that must remain stable
• Areas that need approval before changes
• How to report checks that ran and checks that could not run

For a business website, that may mean preserving contact links, keeping language versions aligned, not changing published URLs without redirects, and testing forms, booking flows, or payment callbacks after relevant edits.

This is project knowledge, not model-specific prompting. Put it in the shared source rather than maintaining the same rule in several vendor files.

Write operational rules

An instruction should change a decision the coding agent makes. Vague quality statements rarely do that.

Weak instruction:

Write clean, scalable, high-quality code.

Operational instruction:

Use existing components before creating new ones. Do not add dependencies
without approval. Run pnpm check-types after TypeScript changes. Preserve
public routes unless a redirect is added.

The second version names actions and boundaries that can be checked in the final diff. The same principle applies to content work: “write good copy” is vague, while “preserve the page’s search intent, use first person singular, and update the translated counterpart” can guide a real edit.

Avoid turning the file into a repository inventory. The agent can inspect package.json, folders, and configuration files. Use the instruction file for decisions it cannot safely derive: why a route must not change, which command is authoritative, where business logic belongs, or which generated files should never be edited by hand.

How Codex discovers AGENTS.md

Codex builds an instruction chain before it starts work. According to the official OpenAI documentation for AGENTS.md, it reads global guidance and then walks from the project root towards the current working directory. Instructions closer to the working directory are added later and can override broader guidance.

This supports a practical hierarchy:

• A global AGENTS.md for personal working preferences across repositories
• A root AGENTS.md for rules that apply to the whole project
• A nested AGENTS.md when one application or package genuinely needs local guidance
• AGENTS.override.md when a scope needs to replace the normal file at that level

Do not split a small project prematurely. One root file is easier to review. Add nested guidance when commands, ownership, or risk really differs—for example when a monorepo has separate frontend and worker runtimes with incompatible validation commands.

Let CLAUDE.md import the shared rules

Claude Code reads CLAUDE.md, not AGENTS.md directly. Its official project-memory documentation recommends importing an existing AGENTS.md and adding Claude-specific instructions below it.

A minimal file can be this small:

@AGENTS.md

## Claude-specific exceptions

- Add only rules that differ because Claude uses different tools or runs in
  a different environment.

The import is better than copying the shared content. If a build command, route rule, or content convention changes, it is updated once. CLAUDE.md then explains only where Claude Code must behave differently.

Claude Code also supports CLAUDE.local.md for private project preferences and .claude/rules/ for modular or path-scoped guidance. Those files are useful, but they should not become another copy of the shared project contract.

Document differences that affect real work

Tool-specific instructions earn their place when the difference changes what the agent can complete, what it may access, or how it should verify the result.

Capability ownership

One coding environment may have an approved tool that another does not. Make the handoff explicit instead of encouraging a substitute that violates the project standard.

For example, an article repository may require raster hero images from an approved image-generation workflow available in Codex. Its CLAUDE.md can say:

@AGENTS.md

## Claude-specific exceptions

### Article images

- The approved article-image workflow in this repository is available only
  in Codex.
- Do not replace it with an SVG, screenshot, placeholder, or reused image.
- Complete the non-image work and report the missing asset clearly.
- Images supplied by the user may still be wired into the article normally.

That is more useful than a broad claim that Claude can never work with images. Capabilities can change through plugins or external tools; the durable fact is which workflow this repository currently approves.

Execution environment and validation

Codex and Claude Code may run with different sandbox, network, or process permissions. A shared rule can define which validation the change requires. The tool-specific file can explain how the current environment affects that work.

For example, one environment may need approval before downloading dependencies, while another can run the build directly. Neither agent should claim that a check passed, or that sandboxing blocked it, without observing that result.

Tool-specific commands

Do not put Claude slash commands, Codex configuration keys, or vendor-specific tool names into the shared file unless every agent can use them. Keep commands such as Claude’s /context in CLAUDE.md guidance and Codex-specific configuration in the Codex setup.

The shared instruction should describe the outcome: verify which instructions loaded, inspect the working tree, or run the project’s type check. The adapter can describe the tool-specific way to do it.

Guidance is not enforcement

An instruction file influences the agent’s decisions. It is not a technical security boundary.

“Ask before deploying” belongs in project guidance because it explains the working agreement. If deployment must be impossible without approval, enforce that through permissions, credentials, hooks, CI, or the execution environment. The same applies to secrets, production databases, destructive commands, and access to external systems.

Claude’s documentation distinguishes CLAUDE.md guidance from permissions and hooks. Codex likewise has separate sandbox and approval controls. Use the instruction file to explain how the project should be handled; use the environment to restrict what must not happen.

Verify what the tools loaded

Do not assume that an instruction file is active merely because it exists.

For Codex, start a new session in the intended directory and ask it to summarize the active instructions or list their sources. This also reveals whether a nested override or global file is affecting the task.

For Claude Code, run /context and check the memory-file section. /memory is useful for opening and maintaining the files, but /context shows what actually entered the current session.

Then test the instructions with a small, observable task. If the agent keeps making the same mistake, check for vague wording, contradictory rules, an incorrect scope, or a file that has grown too large to remain useful.

Maintain instruction files like code

Project instructions need review because repositories and tools change.

Update them when:

• A command, package manager, or deployment process changes
• A code review exposes a repeated misunderstanding
• A new application or runtime introduces different constraints
• A tool gains or loses a capability used by the workflow
• A temporary exception becomes permanent or is no longer needed

Remove stale rules instead of appending corrections forever. A short file with current decisions is more useful than a long history of how the project used to work.

The final structure should be simple: one shared contract, small tool-specific adapters, and technical enforcement where a reminder is not enough. Combined with a controlled workflow for using Claude Code and Codex in an existing codebase and a separate AI code review, that gives coding agents useful context without pretending that instructions remove the need for verification.