Claude Code configuration

Claude Code configuration has to answer two questions: who should see this fact, and how it should take effect. Habits that hold across repositories belong at the user layer. Facts the team shares belong in the repo. Rules that only bind frontend or backend sit next to that directory. This change stays in the prompt. A repeatable judgment workflow becomes a skill. A mechanical action that must run is a hook, a permission, or existing CI.

The split does not require a separate config repository or a new directory template. It starts from the repo already in use and moves facts out of chat logs, global files, and duplicated project rules until each fact has one source of truth. Claude Code and Codex can share that source. Each client still owns its file format, discovery order, and events.

Here, configuration means instructions and settings that change agent context, workflow, or tool boundaries. API keys, model choice, and proxy URLs are runtime access, not this collaboration chain. Before moving files, keep a working repository, one coding agent, and permission to read project config. Organization-managed policy is not something a project member should override from a laptop.

Claude Code configuration is decided by scope and mechanism

Learning CLAUDE.md, AGENTS.md, skills, and hooks one file at a time produces several places that can hold a rule, and no owner when they conflict. Scope and mechanism choose the file.

Scope answers who needs the fact: every project, one repository, one directory, one machine, or this task. Mechanism answers how it takes effect: as standing context, loaded only when relevant, run on a fixed event, or attached as an external capability. The file name comes after those two axes.

A named source of truth stops the same fact from having two originals. If package.json, a Makefile, or CI already owns the test command, project rules should point at that entry instead of copying a script that will rot. If an API field is owned by a contract file, rules should state the change boundary and who verifies it, not paste the field table into markdown.

Scope decides who sees a rule

The wider a rule applies, the more stable, short, and project-agnostic it should be. “Reply in English” can be a personal preference. “Ship database migrations with the model change” belongs only to the repo or backend directory that uses that migration path. Put the second rule in a global file and unrelated repositories inherit a false constraint.

Claude Code global files and project files form a load chain. A project file does not disable the user file. Codex also merges user and project instructions, but the two clients do not search or merge in the same order.

Codex first reads AGENTS.override.md in ~/.codex/, then AGENTS.md if the override is missing. It then walks from the project root to the current working directory. Each directory contributes at most one matching file, and files closer to the working directory appear later. Extra fallback names can be added in config. OpenAI’s AGENTS.md guide(opens in a new tab) also sets a combined size cap; Codex stops adding files after project_doc_max_bytes (32 KiB by default).

Claude Code separates managed, user, project, local, and directory memory files. ~/.claude/CLAUDE.md applies to every project. ./CLAUDE.md or ./.claude/CLAUDE.md is shared with the repo. ./CLAUDE.local.md is the uncommitted local file. Nested files enter context when Claude reads files in that directory, not at session start. Locations and load behavior follow Claude Code’s CLAUDE.md documentation(opens in a new tab).

The working directory is therefore an input. Starting at the repo root and starting in frontend/ can load different directory rules. When the same prompt behaves differently in two terminals, compare launch directory and loaded sources before rewriting the prompt.

Mechanism decides how a requirement takes effect

The same scope still does not pick the same mechanism. A project may require “after a public contract change, verify producers and consumers together.” The long-lived boundary belongs in project rules. Which field changed belongs in the prompt. The contract-upgrade workflow that keeps repeating can become a skill. A cheap, unambiguous syntax check after save can become a hook. Access to the test environment is owned by permissions and credentials.

Anthropic’s feature overview(opens in a new tab) treats CLAUDE.md, skills, hooks, subagents, and MCP as different jobs: persistent context, on-demand knowledge, event automation, isolated work, and external connections. OpenAI’s skills documentation(opens in a new tab) uses progressive disclosure: hosts first see name and description, then read the full SKILL.md plus references, scripts, or assets after the skill is selected. A complex workflow in a skill is paid for only on matching tasks.

Rules, prompts, and skills are interpreted by the model. They change what the model chooses. They do not turn natural language into an unbypassable boundary. “Do not touch production” in a project rule is weaker than omitting production credentials, restricting network, tightening permissions, or rejecting the command on a known event. Claude Code’s configuration debug guide(opens in a new tab) separates project guidance from the enforcement job of permissions and hooks.

A hook is also not a full sandbox. It can only handle events, matchers, and payloads the client actually provides. If the config did not load, the event is uncovered, or the script is wrong, the protection is absent. Stronger limits belong next to the resource: OS permissions, cloud IAM, branch protection, and CI. Hook events, payloads, and exit codes have to be wired and verified per client. Copying one file does not make the two clients behave the same.

How a full-stack repo splits project rules

An existing project may contain an API, an admin UI, a user UI, async jobs, deploy config, and a shared contract. Directory names do not matter. Each local rule only needs to sit next to the module that owns it. These names mark common responsibilities; the repo does not have to be renamed:

repo/
├── backend/       # API, database, server tests
├── admin/         # operator UI and admin permissions
├── frontend/      # user pages and browser checks
├── worker/        # async jobs, retries, schedules
├── deployments/   # environment and delivery config
└── contracts/     # contracts consumed by more than one side

Root rules keep facts every directory needs: the canonical build entry, module boundaries, where the shared contract lives, and which changes must verify direct consumers. They do not need a frontend component naming scheme, and they should not copy every backend migration flag.

Directory rules fill in the local remainder. backend/ can point at the project’s migration and service-test entry. frontend/ can state routing, component boundaries, and browser checks. worker/ can state idempotency and retry constraints. deployments/ can state which environment actions need extra authorization. If contracts/ output is consumed by backend and frontend, “changing the contract must check producers and consumers” is a root boundary. Generate commands and file formats stay in contracts/.

When the API already returns a status name the user page does not use, the prompt does not need to restate the whole repo, and it should not guess a file list:

Fix the order-status name mismatch between the API response and the user page.

Read the project rules that apply in this directory, then follow the shared contract to the actual producer and the direct consumer.
Change only this status name and the adapters it requires. Do not change admin flows or deploy config. Run the repo’s existing contract check, then confirm on the local page that the API value and the visible status match.
If current code encodes two conflicting meanings for the same status, stop and list the conflict evidence a product owner has to resolve.

That request is valid only when “API and page status names disagree” can be checked. Project rules point at the boundary. Build files provide project commands. Source and registration prove actual ownership. Unknown paths should be searched. Unknown commands should be read from the build file. Unconfirmed business rules cannot be guessed by making the prompt longer.

When contract upgrades keep repeating the same compatibility judgment, generation, producer tests, consumer tests, and change notes, they can become a skill. A cheap, unambiguous JSON syntax check after save can become a hook. Neither should swallow the root rule or the current task: a skill does not own the project source of truth, and a hook does not know why this status changed.

What belongs in the repository, and what stays on one machine

Commit decisions follow “does the team need this as a reviewable fact,” not “does the file work on my laptop.” Rules, project skills, and project hooks affect other contributors and automation, so they should be reviewed like code. Personal model defaults, absolute machine paths, and throwaway experiments should not force the whole team to adopt them.

Machine differences should not be disguised as project facts. “The browser is at /Applications/...” is true on one laptop. Shared rules should describe the browser result that has to be checked; the executable path belongs in local config or tool discovery. If the whole team must use the repo-locked Hugo, Node, or Go version, the version file and build script are the original. Agent rules only cite them.

Share project facts between Claude Code and Codex

Copying a full rule set for Claude Code and Codex creates drift. Forcing both clients into one file layout erases real capability differences. Keep one project fact. Adapt the client entry.

If the repo already stores cross-tool rules in AGENTS.md, Claude Code’s project entry can import it with the official syntax, then add a short Claude-only note in the same file:

@AGENTS.md

Claude-specific notes can continue after the import line. They should not repeat what AGENTS.md already says. After clone, Codex finds AGENTS.md directly. Claude Code reads the same content through the import. Claude Code’s memory docs(opens in a new tab) state the pairing explicitly: Claude Code reads CLAUDE.md, not AGENTS.md. A symlink CLAUDE.md -> AGENTS.md also works; on Windows, creating that symlink needs Administrator rights or Developer Mode, so the import is the safer default.

If the only project rule file today is CLAUDE.md, and the team is not ready to add AGENTS.md, register a fallback name in Codex ~/.codex/config.toml:

project_doc_fallback_filenames = ["CLAUDE.md"]

In a new session, Codex checks AGENTS.override.md, then AGENTS.md, then fallback names. Each directory still contributes at most one project instruction file, so an existing AGENTS.md in that directory keeps CLAUDE.md from merging as a fallback. If every teammate’s Codex cannot be guaranteed to set that field, make AGENTS.md the shared original and let Claude Code import it.

A fallback name only changes discovery. It does not convert Claude Code hooks, settings, or skill metadata into Codex format. Which file is the original should follow the repo’s current source of truth. A third copy created “for consistency” is another original waiting to drift.

Client-specific short entries can be versioned with the project. A separate config repo, symlink farm, or generator is only justified after several repos, clients, and machines have already drifted. Those tools distribute files. They are not a prerequisite for global and project configuration to work together.

When a client changes instruction discovery, skill metadata, hook events, or permission schema, update that short entry. When repo directories, canonical commands, or module owners change, update the project source of truth first, then the root and directory rules that cite it. Mixing those two changes into one “sync config” pass lets a client upgrade rewrite project facts.

When Claude Code configuration does not apply, inspect the loaded files

Before moving anything, confirm the current client, working directory, and files that actually loaded. Otherwise the edit lands in a file that never loads, or a higher-priority override is ignored.

In Claude Code, /context lists current context sources by category, so CLAUDE.md, rules, and skill descriptions can be checked first. /memory, /skills, /hooks, /mcp, and /permissions show the matching sources and state. A subdirectory CLAUDE.md missing at startup is not automatically a bug: official docs load it when Claude reads a file in that directory. /doctor continues into install health and invalid config.

Codex documents two smoke commands. From the repo root:

codex --ask-for-approval never "Summarize the current instructions."

Then compare loaded sources from the real subdirectory:

codex --cd frontend --ask-for-approval never "List the instruction sources you loaded."

Replace frontend with the directory actually in use. If root and subdirectory report the same files while a non-empty nested rule file exists, check project-root detection, filenames, override precedence, and the merge size cap. Repeating the prompt will not repair a discovery miss.

Searching for a distinctive sentence, such as “a public contract change must verify direct consumers,” also finds duplicate originals. If that sentence appears in user-global, repo-root, directory, skill, and hook files with different ranges, decide who owns the fact, then delete the other copies. “Nearest file wins” only resolves load order. It does not tell the team which file to edit.

Move scattered configuration back to one source of truth

Move one layer, then check load and behavior. Rewriting every file at once makes it impossible to see which change altered the agent.

1. Draw the load chain that exists. Record the actual user, repo-root, current-directory, local-override, skill, hook, permission, and MCP sources. Do not reverse-engineer an ideal tree.
2. Give each duplicate one source of truth. Commands return to build files, fields to contracts, architecture decisions to engineering docs. Agent rules keep only the boundary needed to use those facts.
3. Move static rules. Cross-repo personal habits go up to the user layer. Shared project facts stay at the root. Local commands and constraints sink to the nearest directory. One-off goals leave rules and return to the prompt.
4. Split mechanisms. Branching workflows that are only needed sometimes become skills. Mechanical actions on fixed events become hooks or the existing toolchain. Secrets and grants move into the permission system.
5. Adapt both clients. Confirm the shared text first, then fill Claude Code and Codex discovery, metadata, and event differences. Re-check after each layer.

Substitute the directories above into that order. If the root rule currently contains frontend format commands, backend migration steps, a full release workflow, and “do not touch deploy this time,” the migrated root keeps only cross-module boundaries. Frontend and backend commands return to their directories and cite project scripts. The release workflow becomes an on-demand skill. “Do not touch deploy” is this task’s range. The permission that can actually block deploy stays in the environment. After the move, a task only loads standing rules for the current scope. Other workflows enter when they are relevant.

Longer configuration is not more reliable. Configuration Smells in AGENTS.md Files(opens in a new tab) reported lint-rule leakage, context bloat, skill-content leakage, and conflicting instructions across 100 public repos. Do Context Files Help Coding Agents?(opens in a new tab) did not observe a measurable accuracy gain from context files in its controlled tasks. That second result does not prove project rules are useless. It does prove that rule line count, file count, or one successful run cannot stand in for effect. Effect is fewer wrong files and commands on representative tasks, plus a correct software result.

Prove Claude Code configuration actually loaded

“The file saved” and “the agent said it saw the file” are incomplete. A configuration change needs loaded sources, the agent’s choice, and a software result.

After diagnostics confirm loaded sources, ask a no-edit question at the repo root and in the target subdirectory, for example “which smallest verify entry should run after a code change in this directory, and where does that instruction come from.” The answers should cite different layers of project commands. A paraphrase of a vague principle means the directory rule is still too thin, or the client did not load it.

Then run one representative task. A public contract change is not done when the agent says “frontend and backend are updated.” Run the repo’s existing contract check, read the API producer, and have the actual frontend consumer parse or render the result. Hooks need event, matcher, exit code, stdout, and side effects. Skills need a matching request to trigger, a non-matching request to stay unloaded, and a stop when required input is missing. MCP needs connection state, tool schema, permission denials, and failure returns, not only “the server is configured.”

If the file loaded and behavior is still unstable, check for conflicting copies of the same fact, rules that say “mind the quality” or “follow best practices,” and standing context stuffed with workflows that should load on demand. If a hook is listed and never runs, check whether the event covers the current action, whether the matcher hits, and whether the script received the expected payload. Pasting the same command into the prompt is not a fix.

After configuration loads, still run tests, open the page, or call the API. Rules, skills, and hooks only change what the agent chooses. They cannot make an unchecked consumer correct. Without observing the direct consumer, the only proven fact is that a file was read.

Start with one durable project fact

Pick one long-lived fact the repo already repeats. Find its source of truth in code or engineering docs, then decide whether it holds for the whole repository or one directory. Put it in the root rule or the nearest directory rule. Check loaded sources from the repo root and from the target directory, and run the project command that rule points at. When Claude Code and Codex both read the same fact and pick the right command in the target directory, move the next fact.

Root rules and directory rules, and how AGENTS.md and CLAUDE.md share a fact without covering each other, are the next job. After those long-lived rules stabilize, the current task only adds a prompt. Repeatable workflows then become skills. Deterministic actions become hooks.