Sharing Claude Code and Codex Rules in shared/
What you’ll learn
- Why common policy for Claude Code and Codex belongs in
shared/ - A directory design that separates rules, skills, and workflows by role
- How to separate the source of truth from tool-specific adapters and reduce missed updates
Keep Shared Claude Code and Codex Rules in shared/
Giving Claude Code and Codex the same policy requires separating the shared source of truth from the adapters each tool loads. This repository centralizes policy in shared/ and organizes rules, skills, and workflows by role. Reducing duplicate copies still requires explicit reference paths and synchronization checks.
By the end of this article, you will have practical criteria for answering “How should the source of truth for common rules be separated from tool-specific loading files?” in your own context.
Use shared/ as the Source for Tool-Specific Adapters
As harness (the set of rules, procedures, and validation that guides AI work in a project) engineering progresses, the number of files AI references grows. What started as a single file becomes unwieldy as content is added, and it becomes difficult to know where specific information lives.
The problem I ran into while building this site was that CLAUDE.md was getting too long. Prohibition rules, content writing guidelines, deployment procedures, review standards—keeping all of this in one file meant AI was processing a large amount of text at the start of every session, and important rules were getting buried. When I wanted AI to read only the rules relevant to a specific task, everything was mixed together in one place.
The shared/ Directory Structure
To address this, I moved all files AI references into a directory called shared/ and organized them by role.
To use an analogy of onboarding a new team member:
shared/rules/→ “Company policies and prohibitions”shared/skills/→ “Step-by-step guides for each type of work”shared/workflow/→ “Multi-step process flows”
These three categories are the foundation of the structure.
Store Shared Rules in rules/
This is a collection of files covering prohibitions and project policies—what AI must not do and what approach this project takes. Examples include content-i18n.md (language policy for content), no-ui-regression.md (the scope of prohibited UI changes), and build-and-deploy.md (deployment constraints). Rules are written as direct policies rather than conditional guidance so that AI can apply them without ambiguity.
Store Reusable Task Procedures in skills/
These are step-by-step guides for specific types of tasks. They are the equivalent of procedural manuals a new team member would look up when unsure how to do something. Examples include blog-writing/SKILL.md (how to write blog articles) and editorial-review/SKILL.md (the review procedure). When AI begins a task, it refers to the relevant skill file and works through the steps described there.
Store Ordered Workflows in workflow/
These files describe multi-step process flows that span more than one type of work. While a rule or skill covers a single policy or procedure, a workflow describes the sequence of a larger operation from start to finish. An example would be: write the article, translate it, conduct a review, and publish.
Centralizing shared/ Reduces Rule Drift Between Claude Code and Codex
Organizing files by role makes it clearer to AI where to find the information relevant to a current task.
CLAUDE.md can reference specific files rather than containing everything: “For content language requirements, see shared/rules/content-i18n.md.” This keeps CLAUDE.md concise while all the detail remains organized under shared/.
When a rule needs to be updated, it is also clear which file to change. When everything is in one large file, a single change can unintentionally affect other content in ways that are hard to trace.
Update Canonical Shared Rules Separately from Tool-Specific Adapters
The most important thing when designing the shared/ directory is deciding the placement criteria upfront. Without clear criteria, the classification becomes ambiguous as files accumulate.
The criteria I use:
- “Must not do” or “project policy” →
rules/ - “Steps for this type of task” →
skills/(placed as SKILL.md in a subdirectory) - “Multi-step process from start to finish” →
workflow/
When in doubt, I start by placing something in rules/ and reorganize later if needed.
Summary: Centralize Common Policy in shared/ and Keep Only Adapters Tool-Specific
When the files AI references grow in number, organizing them by role is effective. Using three categories—shared/rules/ for prohibitions and policies, shared/skills/ for task procedures, and shared/workflow/ for multi-step process flows—makes it easier for AI to find the relevant information and keeps CLAUDE.md concise. When files are organized, AI behavior becomes more consistent and maintaining and updating rules becomes more manageable.
Start with one rule duplicated across Claude Code and Codex, then separate it into a shared source and tool-specific references. If a project uses only one tool or has a few stable rules, this directory split may add more maintenance than it removes.