shared/ディレクトリの設計：AIが参照するルール・スキル・ワークフローの整理方法
ルールファイルが増えてきたときの問題
ハーネスエンジニアリングを進めていくと、AIに渡すルールファイルが増えていきます。最初は1ファイルで管理できていたものが、内容の追加とともに肥大化し、「どこに何が書いてあるか」がわかりにくくなります。
私がこのサイトを構築する中で直面したのは、CLAUDE.mdが長くなりすぎるという問題でした。禁止ルール、コンテンツの書き方、デプロイ手順、レビュー基準——これらをすべて1ファイルに書き続けると、AIが最初に参照するファイルが大きくなりすぎて、重要なルールが埋もれます。また、特定の作業に関係するルールだけをAIに読ませたいときでも、すべてのルールが1ファイルに混在していると、不要な情報も一緒に渡すことになります。
shared/ディレクトリの構造
この問題の対処として、AIが参照するすべてのファイルを shared/ というディレクトリに集め、その中を役割で分類する設計にしました。
新入社員に渡すマニュアルで例えると：
shared/rules/→ 「会社の規則と禁止事項」shared/skills/→ 「各業務の手順書」shared/workflow/→ 「複数ステップの作業フロー」
この3つの分類を使います。
rules（ルール）
禁止事項と方針を記録するファイル群です。「何をしてはいけないか」「このプロジェクトではどのような方針を取るか」を記述します。
たとえば content-i18n.md（コンテンツの言語方針）、no-ui-regression.md（UI変更の禁止範囲）、build-and-deploy.md（デプロイの制約）などです。ルールは条件ではなく方針として書き、AIが判断に迷わないよう明確にします。
skills（スキル）
特定のタスクを実行するための手順書です。新入社員が「この作業はどうやるんだっけ」と参照するマニュアルに相当します。
blog-writing/SKILL.md（ブログ記事の書き方）、editorial-review/SKILL.md（編集レビューの手順）などが該当します。AIはタスクを開始するときに関連するスキルファイルを参照し、手順に沿って作業を進めます。
workflow（ワークフロー）
複数のステップをまたいで進める作業フローを記述するファイル群です。ルールやスキルが単一のルール・手順であるのに対し、ワークフローは「最初から最後までの作業の流れ」を示します。
たとえば「記事を書いてから翻訳し、レビューして公開する」という一連の流れを記述するファイルです。
分類することで何が変わるか
ファイルを役割で分類することで、AIが「今の作業に必要な情報はどこにあるか」を把握しやすくなります。
CLAUDE.mdには「詳細はshared/rules/content-i18n.mdを参照」という形で参照先だけを書き、詳細を別ファイルに移動できます。CLAUDE.mdをコンパクトに保ちながら、必要な情報はすべてshared/配下に整理されている状態です。
また、ファイルが役割ごとに分かれていると、ルールを更新したいときに「どのファイルを変更すればよいか」が明確です。すべてが1ファイルにある状態では、1つの変更が他の記述に意図せず影響する場合があります。
運用のポイント
shared/ディレクトリを設計するときに重要なのは、「どこに何を置くか」の基準を最初に決めることです。基準がないと、ファイルが増えるにつれて分類が曖昧になります。
私が使っている判断基準は次のとおりです。
- 「やってはいけないこと」や「このプロジェクトの方針」→
rules/ - 「この作業の手順」→
skills/（サブディレクトリにSKILL.mdとして置く） - 「複数ステップにわたる作業フロー」→
workflow/
判断に迷う内容は、まず rules/ に入れて、後で必要であれば分類を変えます。
まとめ
AIに渡すルールファイルが増えてきたときは、役割による分類が有効です。shared/rules/（禁止事項・方針）、shared/skills/（作業手順）、shared/workflow/（複数ステップの流れ）という3分類を使うことで、AIが必要な情報を参照しやすくなり、CLAUDE.mdをコンパクトに保つことができます。ファイルが整理されると、AIの動作が一貫し、ルールの更新・管理もしやすくなります。