AI エージェント前提の開発基盤設計 ── ルールファイルの参照チェーンと分割戦略

dotD の松村です。

社内で、AI エージェントを前提にした開発テンプレートを作っています。
モノリポ構成のスターターキットに、ルール、設計書、テストまで含めて、プロダクト開発を進めるための土台の整備を進めています。

テンプレート整備のモチベーション

dotD は「次々と新しい価値を生み出す事業創造ファーム」として、同時に複数の新規事業に取り組み、連続的に新しい価値を世の中に生み出し続けることを掲げています。
生成 AI の普及により、エンジニアではないロールの人でも、提案用のプロトタイプを作ったり、自分でアプリ開発をするようになってきました。しかし、どうやって品質を確保していくかという点ではまだ課題があります。

テンプレート整備の目的は、プロダクト開発の品質基準を全社で揃えることにあります。
エンジニアだけでなく、非エンジニアが Vibe Coding でプロトタイプを作る場面でも、一定の品質を満たしたコードが生成される状態を作ることが目標です。
0 → 1 の開発で、プロトタイピングのスピードを落とさずに、本番開発へ進めるときの品質も担保するための土台として、このテンプレートを設計しています。

この記事で扱うこと

CLAUDE.md / AGENTS.md / DESIGN.md の役割分担と参照チェーン設計
ルールファイルをなぜ・どう分割するか
AI 自身がルールを生成・更新する前提の設計
共通 / Backend / Frontend / Infra のスコープに実際に置いているルールの事例

ルールファイルの参照チェーン設計

テンプレートのルール構成は以下のようになっています。

project-root/
├── CLAUDE.md              # Claude Code向けエントリーポイント
├── AGENTS.md              # エージェント共通ルール（CLAUDE.mdから参照）
├── DESIGN.md              # デザインルール
└── docs/
    └── rules/
        ├── coding-style.md
        ├── testing-strategy.md
        ├── api-design.md
        ├── error-handling.md
        ├── naming-conventions.md
        └── ...

ポイントは3層の参照チェーンです。

CLAUDE.md → AGENTS.md → docs/rules/*
            DESIGN.md → docs/rules/*

CLAUDE.md

は Claude Code 固有の設定に絞り、コーディングルールは

AGENTS.md

に委譲します。こうすることで、Claude Code 以外のエージェント（Codex など）を使う場合でも、

AGENTS.md

を参照先に指定すれば同じルールが適用されます。

AGENTS.md

と

DESIGN.md

は、それぞれ

docs/rules/

配下の個別ルールファイルへの参照リンクを持つインデックスです。エージェントはタスクに関連するルールだけを辿って読み込みます。

なぜルールを1ファイルにまとめないのか

CLAUDE.md に全ルールを書いていくのは、4 つの課題があります。

1. PJやチームごとにルールをカスタマイズしにくい

ルールは全社共通で固定できるものばかりではありません。プロダクトの技術スタック、チームのレビュー観点、運用フェーズによって「守るべきこと」は変わります。

1 つの巨大ファイルに全てを書いてしまうと、PJ 固有のルールを足したいだけなのに、共通ルールまで巻き込んで編集することになります。ファイルを分割しておけば、共通ルールはそのままに、PJ ごとのルールファイルだけを追加・差し替えできます。

2. ルールを更新しにくい

開発を進めていると「この書き方はやめよう」「このパターンで統一しよう」という判断が日々生まれます。

1 つの巨大ファイルに集約すると、AI による安全な追記は難しくなります。ファイルの末尾への追記では、構造崩れのリスクがあります。適切なセクションに挿入するには、既存の構造を正確に理解する必要があります。

ファイルが分割されていれば、新しいルールを 1 ファイル追加して、

AGENTS.md

のインデックスに 1 行足すだけで対応できます。AI と人間の双方にとって、安全に扱いやすい構造になります。

3. コンテキストウィンドウを圧迫する

フロントエンドの修正で、バックエンドの API 設計ルールまで参照する必要があるケースは多くありません。全ルールを 1 ファイルにまとめると、タスクに無関係なルールまでコンテキストウィンドウに入り、トークンを消費します。

参照チェーンで分割しておけば、エージェントは

AGENTS.md

のインデックスを読み、タスクに関連するルールファイルだけを選択的に読み込みます。

4. 変更履歴の粒度が粗くなる

ルールが 1 ファイルにまとまっていると、git の差分で「何が変わったか」を把握しにくくなります。ファイル単位で分割されていれば、コミットログからルールの変遷を追跡できます。設計書、変更経緯、意思決定ログなども全て.md にして git 上でバージョン管理することで、担当者が変わっても同じ判断基準で開発を進められます。

実際にどんなルールを置いているか

docs/rules

を以下の 5 つのレイヤーに分けました。

```
10_principles
```
（原則）
```
20_domain
```
（ドメイン定義）
```
30_architecture
```
（構造）
```
40_process
```
（手順）
```
50_decisions
```
（意思決定）

各レイヤーの下に

common

frontend

backend

infra

のスコープを切っています。
それぞれのスコープに置いている代表的なルールをいくつか紹介します。

共通: AIが実装するときの行動原則

10_principles

レイヤーで、AI エージェントが実装・修復・レビューをするときの共通行動原則を定義しています。
たとえば次のような項目を置いています。

経路分岐や再試行判定、状態コード処理など決定論的に書ける処理はコードで実装し、モデル推論には委ねない
既存実装と矛盾する 2 つのパターンを折衷して、第 3 のパターンを増やさない
変更前に対象ファイルの公開 API、直近の呼び出し元、共有ユーティリティを読み、既存の設計意図を把握する
業務ロジックが変わったときに失敗しないテストは「不十分」として扱う
命名・責務分割・エラーハンドリングは既存規約に揃え、異論があれば実装内で暗黙に分岐させず別タスクとして提案する

これらは特定の技術スタックに依存しない、AI に任せて動かすうえで普遍的に効くガードレールです。

Backend: 層境界とDDDの固定

Backend は TypeScript / Python / Go のいずれを採るにしても、DDD ベースの層構造を共通の前提にしています。

30_architecture/

レイヤーで定義しているのは次のような構造です。

```
domain/
```
: Entity, Value Object, Repository Port
```
usecase/
```
: ユースケースのオーケストレーション、認可、トランザクション境界
```
infrastructure/
```
: 永続化、外部サービス接続
```
interface/
```
: API 入出力、transport 仕様（REST / RPC）とのマッピング

依存方向は

interface -> usecase -> domain

のみ許可し、

domain

は外部ライブラリや transport 仕様に依存しないと明記しています。

これと対になる手順ルールが

40_process

レイヤーで、Backend 変更時のフローを次のように固定しています。

変更対象を
```
domain
```
/
```
usecase
```
/
```
infrastructure
```
/
```
interface
```
に分類
failing test を先に作成（Red）
最小実装で test を通す（Green）
test が通る状態を維持したまま改善（Refactor）
```
pnpm lint
```
と該当テストを実行
```
interface
```
変更時は
```
contracts
```
マッピング差分を確認

「TDD で進めること」と「層境界違反は設計を再分割する」までを手順として書ききっているので、AI が PR を出すときも人間がレビューするときも、判断軸が揃います。

Frontend: UI原則とアクセシビリティ

Frontend では視覚設計の原則を　

10_principles

レイヤーに定義しています。

近接・整列・反復・コントラストで情報の視覚的階層を明確にする
余白とグリッドは一貫したリズムで適用する
情報構造とレイアウト構造を対応させる
視覚的階層と情報優先度が逆転するレイアウトは禁止

ユーザビリティとアクセシビリティの原則も定義しています。

10_principles

レイヤーに、ニールセンのヒューリスティックスと WCAG 2.1 AA を実装判断に落としてルール化しています。
これらは弊社デザイナーがデザインレビューする上での観点に含まれているものです。

システム状態を常に可視化し、ユーザーが次の操作を予測できるようにする
テキストコントラスト比は 4.5:1 以上、フォントサイズは 12px 以上
情報伝達を色だけに依存させず、形状・文言・アイコンで補完する
エラー原因や復旧手順を提示しない失敗表示は禁止

日本語 UI 固有の組版ルールも

10_principles

レイヤーに定義しています。
このあたりは、Awesome Design MD 日本語版を参考にしました。

```
font-family
```
は単一フォント指定を禁止し、和文・欧文・generic family の順でフォールバックチェーンを定義
日本語本文の
```
line-height
```
は 1.5 以上（業務 UI は 1.5–1.6、長文 UI は 1.7–1.9）
```
word-break: break-all
```
は URL や識別子など例外領域に限定し、本文への全体適用は禁止

フロントエンドの構造は

30_archtecture

レイヤーで、Features + Colocation を採用しています。
「2 ルート以上で再利用される実装は

features

へ昇格する」など、抽出の判断基準まで言語化しています。

Infra: Terraformの安全運用と必須設計観点

Infra は事故の影響が大きいので、

10_principles

に強めの制約を原則ルールに置いています。

Agent 実行は
```
validate
```
/
```
plan
```
までを標準とし、
```
apply
```
は人間レビュー後に明示的承認で実施
破壊的変更を含む差分は decision とセットで管理
変更提案には耐障害性、可用性、パフォーマンス、バックアップ/リストア、セキュリティ、脆弱性対策、モニタリング、アラート設計を必ず含める
監視・アラート未設定のまま本番運用を開始することは禁止

手順側の

40_process

でも、上記の設計観点を設計レビューで明示的に確認します。

terraform validate

→

terraform plan

を経てから

apply

承認に進む流れを固定しています。

「AI に Terraform を任せるなら何を必ず守らせるか」を、原則と手順の両方で重複して定義しています。
そうすることで、エージェントがどちらを読んでも同じ結論へたどり着くようにしています。

まとめ

Context Engineering を実際のテンプレートに実装して得た学びをまとめます。

ルールファイルは分割する。1 ファイル 1 関心事。AI 自身がルールを安全に追加できる構造にする
参照チェーンを設計する。CLAUDE.md → AGENTS.md → docs/rules/* の 3 層構造で、タスクに必要なコンテキストだけを選択的に読み込む
共通 / Backend / Frontend / Infra のスコープで分けて書く。共通ルールは技術スタックに依存しない行動原則を、スコープごとのルールは層境界・UI 原則・IaC 安全運用といった性質の違うガードレールを置く

Design System を Context 資産としてテンプレートに取り込む設計は、今後組み込んでいく予定です。Token やコンポーネントカタログをどう参照させ、どう検証するかは別記事で改めて扱います。

AI エージェント前提の開発基盤設計 ── ルールファイルの参照チェーンと分割戦略

추출된 키워드

원문

AI エージェント前提の開発基盤設計 ── ルールファイルの参照チェーンと分割戦略

テンプレート整備のモチベーション

この記事で扱うこと

ルールファイルの参照チェーン設計

なぜルールを1ファイルにまとめないのか

1. PJやチームごとにルールをカスタマイズしにくい

2. ルールを更新しにくい

3. コンテキストウィンドウを圧迫する

4. 変更履歴の粒度が粗くなる

実際にどんなルールを置いているか

共通: AIが実装するときの行動原則

Backend: 層境界とDDDの固定

Frontend: UI原則とアクセシビリティ

Infra: Terraformの安全運用と必須設計観点

まとめ