Sharing Claude Code and Codex Rules in shared/
What you’ll learn
- Why common policy for Claude Code and Codex belongs in
shared/ - A folder 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/
shared/ is a custom folder where this project keeps common rules and work procedures. The original document used as the reference is the “source of truth”; an “adapter” is a connecting file through which each AI tool refers to it. Content and connections are kept separate.
Claude Code reads from CLAUDE.md and Codex from AGENTS.md, the instruction files used when work begins, to reach the shared source. Think of a common company manual referenced by department-specific guides: the arrangement separates duplicated content from the places that need updates. This is a design with explicitly configured references, not an automatic feature shared by both products.
Problems When Instructions for AI Accumulate
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, publishing procedures, review standards—keeping all of this in one file buried important rules. 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 collected the shared files this project needs AI to reference in the custom shared/ folder 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 language policy, prohibited screen changes, and constraints on publishing. 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 writing blog articles and reviewing them. 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.
Placement Criteria for Shared Files
The most important thing when designing the shared/ folder 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/ - “Multi-step process from start to finish” →
workflow/
When in doubt, I start by placing something in rules/ and reorganize later if needed.
Checking Synchronization Between Shared Rules and Runtime Files
A single source does not eliminate differences between policy, the files a tool actually reads, and implementation. This article calls that difference “harness drift.” It is not an industry-standard term; it applies the idea of configuration drift to the rules and procedures given to AI.
For example, a Skill may still tell the AI to add a field that the article format no longer uses. A moved file may still be referenced at its old location. Check where a change must propagate as well as where its source lives.
In this project, changing shared rules, regenerating runtime adapters, and checking synchronization form one operation. Regeneration carries the source changes into runtime files; synchronization checks whether references and settings agree.
This order helps expose cases where the source is updated but a connection remains outdated. Building validation scripts with AI explains how to decide which conditions a check should treat as violations.
Automated checks cover relationships explicitly defined as check targets. A person must also verify support for new runtime environments and whether an existing rule still matches the implementation in meaning.
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. Organizing the files also makes it easier to identify which document needs an update.
This separation is useful to consider when multiple AI tools share rules that will keep changing. If a project uses only one tool or has a few stable rules, this folder split may add more maintenance than it removes.