Claude CodeとCodexの共通ルールをshared/で管理する
この記事で学べること
- Claude CodeとCodexの共通方針を
shared/へ集約する理由 - rules・skills・workflowを役割ごとに分けるフォルダー設計
- 正本とツール別アダプターを分け、更新漏れを減らす運用方法
Claude CodeとCodexの共通ルールのshared/への集約
shared/は、このプロジェクトで共通ルールや作業手順を一か所へまとめる独自のフォルダーです。判断の基準になる元の文書を「正本」、各AIツールがそこを参照するための接続ファイルを「アダプター」と呼び、内容と接続を分けます。
Claude CodeはCLAUDE.md、CodexはAGENTS.mdという作業開始時の指示ファイルから、共通の正本を読む構成です。会社の共通マニュアルを、部署別の案内から参照する形に近いと考えると、内容の重複と更新箇所を区別できます。これは各製品共通の自動機能ではなく、このプロジェクトで参照先を設定した設計です。
AIへ渡す指示が増えたときの課題
ハーネス（AIに渡すルール、作業手順、検証方法をまとめた仕組み）エンジニアリングを進めていくと、AIに渡すルールファイルが増えていきます。最初は1ファイルで管理できていたものが、内容の追加とともに肥大化し、「どこに何が書いてあるか」がわかりにくくなります。
このサイトでは、CLAUDE.mdが長くなりすぎる問題に直面しました。禁止ルール、コンテンツの書き方、公開手順、レビュー基準を1ファイルへ重ねると、重要なルールが埋もれます。
特定の作業に関係するルールだけをAIへ渡したくても、1ファイルに混在していれば不要な情報まで含まれます。
shared/フォルダーの構造
この問題の対処として、このプロジェクトでAIに参照させたい共有ファイルを shared/ という独自フォルダーに集め、その中を役割で分類する設計にしました。
新入社員に渡すマニュアルで例えると：
shared/rules/→ 「会社の規則と禁止事項」shared/skills/→ 「各業務の手順書」shared/workflow/→ 「複数ステップの作業フロー」
この3つの分類を使います。
rules/に置く共通ルール
禁止事項と方針を記録するファイル群です。「何をしてはいけないか」「このプロジェクトではどのような方針を取るか」を記述します。
たとえば コンテンツの言語方針、画面変更の禁止範囲、公開操作の制約などです。ルールは条件ではなく方針として書き、AIが判断に迷わないよう明確にします。
skills/に置く再利用可能な作業手順
特定のタスクを実行するための手順書です。新入社員が「この作業はどうやるんだっけ」と参照するマニュアルに相当します。
ブログ記事の書き方や編集レビューの手順などが該当します。AIはタスクを開始するときに関連するスキルファイルを参照し、手順に沿って作業を進めます。
workflow/に置く作業の順序
複数のステップをまたいで進める作業フローを記述するファイル群です。ルールやスキルが単一のルール・手順であるのに対し、ワークフローは「最初から最後までの作業の流れ」を示します。
たとえば「記事を書いてから翻訳し、レビューして公開する」という一連の流れを記述するファイルです。
共有ファイルの配置基準
shared/フォルダーを設計するときに重要なのは、「どこに何を置くか」の基準を最初に決めることです。基準がないと、ファイルが増えるにつれて分類が曖昧になります。
私が使っている判断基準は次のとおりです。
- 「やってはいけないこと」や「このプロジェクトの方針」→
rules/ - 「この作業の手順」→
skills/ - 「複数ステップにわたる作業フロー」→
workflow/
判断に迷う内容は、まず rules/ に入れて、後で必要であれば分類を変えます。
共有ルールと実行用ファイルの同期確認
正本を一か所へ集めても、ツールが実際に読むファイルやコードとのずれは残ります。本記事では、このずれを「ハーネスドリフト」と呼びます。業界標準の用語ではなく、AIに渡すルールや手順へ設定のずれを当てはめた呼び方です。
たとえば、記事の設定項目を廃止したのにSkillに追加手順が残ると、AIは不要な値を入れ続けます。ファイルを移して参照先を更新しなければ、古い場所を探します。正本の配置だけでなく、変更後にどこへ反映されるかも確認する必要があります。
このプロジェクトでは、共有ルールの変更、実行用アダプターの再生成、同期検査を一つの作業として扱います。再生成は正本の変更を実行用ファイルへ反映する処理、同期検査は参照先や設定が一致するかを確かめる処理です。
この順序により、正本だけ更新して接続先を古いままにする問題を見つけやすくなります。検査を作る際に何を違反とするかは、AIと作るバリデーションスクリプトで説明しています。
自動検査が確認できるのは、検査対象として定義した関係です。新しい実行環境への対応漏れや、存在するルールの意味が現在の実装と合うかは、人の確認も必要です。
まとめ：共通方針をshared/へ集約し、アダプターだけをツール別に保つ
ルールファイルが増えたら、役割で分類します。shared/rules/は禁止事項と方針、shared/skills/は作業手順、shared/workflow/は複数ステップの流れを保持します。
参照経路が明確になれば、AIは必要な情報を見つけやすくなり、CLAUDE.mdも短く保てます。更新対象も特定しやすくなります。
複数のAIツールが同じルールを使い、その内容を継続して更新する場合に、この分離を検討できます。利用するツールが1つだけ、またはルールが少数で変化しない場合は、このフォルダー分割が管理負荷を増やすことがあります。