[ Claude / Claude Code ]

Claude Code 新規プロジェクト onboarding — CLAUDE.md・specs・.claude/ の構成パターン

新規プロジェクトへの Claude Code onboarding は、CLAUDE.md・specs/・.claude/ の3層を最初に置くことから始まり、このシンプルな構成で AI がプロジェクト文脈を理解した上で動く環境が実現できる。

著者: 森本拓見 更新日: 2026年5月11日
#claude-code #ai-driven-dev #onboarding #project-structure

課題: AI のコンテキスト切れが生産性を蝕む

Claude Code を新しいプロジェクトに投入するとき、最初に何を置くかで後の生産性がほぼ決まる。

何も置かずに作業を始めると、AI は毎回プロジェクトの文脈を推測しながら動く。「Git のコミットメッセージは英語か日本語か」「フォーマットに決まりはあるか」「どのブランチで作業するか」「複数アカウントをどう使い分けるか」——こうした前提条件を毎度指示するのは徹底できない。指示漏れが起きると、修正に余計なコストがかかる。

さらに問題なのは、ルールの曖昧性が AI の判断を散らすことだ。ある日は正しく従い、ある日は「プロジェクトの意図」を忖度して別のやり方をする。人間がレビューするたびに「あ、これは直してほしかった」という齟齬が起きるパターンだ。

この記事の背景は、八雲で内製の業務基盤 Synapse と動画制作基盤 Montage を Claude Code で日常的に開発・運用する中で、「プロジェクトの文脈を AI に正確に渡すための最小構成」が整理されてきたということにある。

パターン定義: CLAUDE.md + specs/ + .claude/ の3層構成

解決策は、プロジェクトルートに以下の3つを最初に置くことだ。

project/
├── CLAUDE.md # プロジェクト設定（Claude Code が最初に読む）
├── specs/ # 仕様書ディレクトリ
│ ├── skills.md
│ ├── workflow-rules.md
│ └── （その他仕様）
└── .claude/
 ├── agents/ # エージェント定義
 ├── skills/ # スキル（スラッシュコマンド）定義
 └── settings.json # フック設定

それぞれの層が異なる責務を持つ。

CLAUDE.md は、すべての AI 実行に自動で適用されるプロジェクト設定ファイルだ。Claude Code が新しいセッションを開始するたびに、ここで定義されたルールを前提として動く。一度書けば、二度と同じ指示を繰り返す必要がない。

specs/ は、プロジェクトチーム全体（人間と AI）が参照する仕様書群だ。CLAUDE.md が「何をするか」の大枠を示すのに対し、specs/ はその「なぜ・どのように」を補完する。ドキュメント管理の単一の出処（SSOT）としても機能する。

.claude/ は、AI の振る舞いを定義するコード資産だ。エージェント（ロール定義）とスキル（再利用可能な作業手順）を配置し、settings.json で自動化フックを設定する。

設計の核: 各層に何を置くか

CLAUDE.md に書くべき4つの必須項目

1. コミュニケーション設定

## コミュニケーション
- 日本語で回答すること

これだけで AI の応答言語が統一される。シンプルだが、マルチ言語対応を必要とするプロジェクトでは重要だ。

2. Git ルール・アカウント管理

ブランチ戦略、コミット規約、マルチアカウント環境での認証確認を明示する。

## Git
- コミットメッセージ言語: 英語
- 作業ブランチ: develop（main への直接コミット禁止）
- GitHub アカウント確認:
 実行前に `gh auth status` でアクティブアカウントを確認する
 対象リポジトリのディレクトリとアカウントが一致しない場合は
 `gh auth switch --user <account>` で切り替える

複数アカウントを使う環境では、このルールを CLAUDE.md に書いておくと、認証ミス（間違ったアカウントで push するなど）を未然に防げる。

3. エージェント委任とタスク分類

どのタイプの作業をどのエージェント・スキルで実行するかを明示する。

## 実装委譲ルール
- コード実装・バグ修正: system-developer エージェント へ委任
- ウェブ制作（Astro・React）: web-developer エージェント へ委任
- 業務タスク（営業・提案）: 領域責任者エージェント経由で実行

業務として記事を扱う場合は、必ず責任者エージェント経由で実行。
メインスレッドから直接スキルを呼ぶのは禁止。

このルールを置かないと、AI が全タスクを同じ優先順位で判断し、判断ロジックが散在する。責任者エージェント経由という制約を入れることで、複数の AI 実行の判断履歴が自動で集約される。詳細は[「領域責任者エージェントパターン」](「HUMAN_INPUT[CROSS_LINK]: /blog/2026-05-area-director-agent-pattern へのリンクが存在するか確認」)を参照。

4. ドキュメント自動更新ルール

CLAUDE.md の中でもとりわけ重要な項目だ。

## ドキュメント自動更新ルール
| 変更内容 | 更新対象 | SSOT |
|---|---|---|
| .claude/agents/ にエージェント追加 | specs/skills.md を更新 | specs/skills.md |
| scripts/ にスクリプト追加 | specs/scripts.md を更新 | specs/scripts.md |
| config/sites/corporate.json 変更 | 更新不要 | config/sites/corporate.json |

AI がコードを変更するたびにこの表を参照し、必要なドキュメント更新を自動で行う設計だ。設計の背景は[「ドキュメント自動更新ルールの設計」](「HUMAN_INPUT[CROSS_LINK]: /blog/2026-05-doc-update-policy へのリンク」)を参照。

重要な原則: SSOT の所在を明示する。たとえば「プロジェクト固有のルールは CLAUDE.md が SSOT」「全員が守るべき業務フローは specs/workflow-rules.md が SSOT」というように、各情報の唯一の出処を宣言しておく。これにより「どれが本当か」という迷いが消える。

specs/ — 仕様書ディレクトリの構成

Synapse で定着した構成は以下のとおりだ。

ファイル責務
skills.mdエージェント・スキル・フックの一覧と呼び出し方
workflow-rules.md業務で守るべき必須ルール（SSOT の所在・禁止事項・判断基準）
scripts.mdscripts/ 配下の全スクリプトの仕様・引数・戻り値
audience-tracks.md対象読者層の定義と判定ルール（ブログプロジェクト例）
naming-conventions.mdファイル名・識別子・フォルダ構造の命名規則
architecture.mdシステム全体の構成・依存関係・データフロー

重要なのは、各ファイルが「この情報を知りたいときはここを見る」という明確な役割を持つことだ。

.claude/ — agents / skills / settings.json の最小構成

agents/: エージェント定義は「判断が必要なロール」に絞る

Synapse の場合、事業責任者・営業責任者・開発責任者の3人に限定している。

.claude/agents/
├── director.md # 事業責任者（戦略判断）
├── sales-director.md # 営業責任者（営業案件判定）
└── dev-director.md # 開発責任者（実装ロードマップ）

各ファイルには、役割・使用可能なスキル・判断の基準を記述する。エージェントを増やす誘惑に負けないことが重要だ。「定型作業はスキルで十分」という原則を貫く。

トレードオフ: エージェント数を少なく保つことで、判断ロジックが集約されて追跡可能になる一方で、複雑な判断を1人のエージェントに集中させるリスクが生じる。Synapse では「判断が不可逆的な決定」（営業案件の着否、開発ロードマップの優先順位変更）だけをエージェント判断に委ねる方針でバランスを取っている。#### skills/: 再利用可能な作業手順を 1 スキル 1 ディレクトリで管理

.claude/skills/
├── scrape/ # 案件スクレイピング
├── propose/ # 提案書自動生成
├── submit/ # 案件提出フロー
└── pipeline/ # パイプライン可視化

1 スキル 1 ディレクトリの構造にすると、個別に編集・テスト・バージョン管理できる。スキルの概要と呼び出し方は specs/skills.md に書くが、実装詳細は .claude/skills/ に置く。二重管理を避けるため、specs/ には「何か」「どう使うか」だけ、.claude/ には「どう実装するか」を分離する。

settings.json: フックで「うっかり忘れ」を自動化する

{
 "hooks": {
 "SessionStart": [
 {
 "matcher": "",
 "hooks": [
 {
 "type": "command",
 "command": "gh auth status"
 }
 ]
 }
 ],
 "PostToolUse": [
 {
 "matcher": "Edit|Write",
 "hooks": [
 {
 "type": "command",
 "command": "確認スクリプト: ドキュメント更新の必要性"
 }
 ]
 }
 ]
 }
}

SessionStart フックで GWS 認証確認を、PostToolUse フックでファイル変更時のドキュメント更新リマインダーを設定している。フックはルールの「逃げ場」を塞ぐ仕組みだ。CLAUDE.md にルールを書いても、人間の指示で「急いでいるから今回はドキュメント更新スキップ」と言われることがある。フックをコード化しておくと、そうした例外を自動で検出できる。

設計の核: トレードオフと判断基準

この3層構成の背景にある判断基準を明示しておく。

CLAUDE.md は「起動時の前提」、specs/ は「参照時の詳細」

CLAUDE.md の目的は「セッション開始時に AI が即座に理解できる最小限のルール」を提供することだ。長くなると、AI が全体を把握しにくくなり、かえって指示を見落とすようになる。

トレードオフ: 短く保つことで読み込み率が上がる一方で、詳細な説明がないため「なぜそのルールがあるのか」という背景理解が浅くなる。対策は、CLAUDE.md には「何をするか」だけ書き、「なぜ」は specs/ のリンク先に委ねることだ。

## Git ルール
コミットメッセージは英語。理由は spec/workflow-rules.md の「多言語チームでの SSOT 統一」を参照。

こうすることで、CLAUDE.md は簡潔に保ちながら、詳細を知りたい人は specs/ で背景を学べる。

SSOT を宣言しない状態の損失

SSOT が不明確だと、以下のような問題が起きる：

  • AI がコード内の値とドキュメント内の値の矛盾に気付いて「どちらを信じるべきか」と判断停止する
  • 人間がコードを変更したのに、ドキュメントが更新されず、次の AI 実行が古い情報で動く
  • ドキュメント自動更新ルールが「何を根拠に更新するか」を決められない

Synapse での事例：

対策: specs/workflow-rules.md に SSOT を宣言する表を置き、コード変更時は「この情報の SSOT は〇〇」と意識させる。

## 情報の SSOT（Single Source of Truth）
| 情報 | SSOT | 変更ルール |
|---|---|---|
| 顧客コード | config/clients.json | SSOT を変更したら specs/workflow-rules.md も更新 |
| ユーザー権限レベル | なし（SSOT はなし。その都度判断） | 権限変更は人間が社内運用ルールに従う |
| スキル一覧 | specs/skills.md | .claude/skills/ に追加したら自動更新フック実行 |

Yakumo の適用例: Synapse での実装パターン

実際に Synapse でこの構成をどう運用しているかを示す。

CLAUDE.md の実装例

Synapse の CLAUDE.md は約 300 行。以下は主要セクション：

# Synapse — Claude Code プロジェクト設定

## コミュニケーション
- 日本語で回答すること

## GitHub アカウント管理
2 つの GitHub アカウントをディレクトリで使い分ける。
実行前に `gh auth status` でアクティブアカウントを確認。
対象リポジトリとアカウントが一致しない場合は切り替える。

## エージェント委任（厳守）
- 営業案件判定: @sales-director へ委任
- 開発ロードマップ: @dev-director へ委任
- 定型作業（スクレイピング、提案書作成）: 直接スキル呼び出しで OK

メインから直接エージェントを呼ぶ際のチェックリスト:
1. その判断は「複数の案から選ぶ」か（YES なら委任）
2. その判断は「取り返しがつきにくい」か（YES なら委任）
3. その判断は「ドメイン知識が必要」か（YES なら委任）

すべて NO なら定型タスク。スキル化を検討。

## ドキュメント自動更新ルール
...（前述の表）

CLAUDE.md は GitHub で version control され、変更時は必ず レビューを通す。AI が誤って CLAUDE.md を編集することはできない（settings.json で禁止フックを設定）。

specs/workflow-rules.md での SSOT 宣言

# Synapse 業務ルール集

## SSOT（Single Source of Truth）
| 情報カテゴリ | SSOT | 更新者 | 更新頻度 |
|---|---|---|---|
| 営業案件の定義 | Google Sheets（営業責任者が管理） | 営業責任者 | リアルタイム |
| 案件ステップの仕様 | specs/workflows/ | @dev-director | 月次レビュー時 |
| スキル一覧 | specs/skills.md | 自動更新フック | コード変更時 |
| 顧客コード体系 | config/clients.json | 人間（CI で validate） | 案件追加時 |

### SSOT の使い方
- 「◯◯について AI に判断させたい」→ SSOT を参照してから指示を出す
- 「◯◯が SSOT に載っていない」→ SSOT に追加してから改めて実行
- 「SSOT の値が古い」→ SSOT を更新してから AI セッションを新規起動

.claude/agents/sales-director.md での判断基準の明記

# Sales Director Agent

営業案件の着否判定、提案スケジュール調整、顧客ニーズの初期分析を担当。

## 判断基準
1. 案件着否: sales/pipeline.json と過去 6 ヶ月の提案成功率を参照し、
 合致度 70% 以上なら着手。以下なら見送り推奨。
2. 優先順位: 案件規模（年額予算）× 成功確度 × 納期で rank。
3. リスク判定: 前回類似案件の失敗事例を参照。

## 使用可能なスキル
- /scrape: Web からの競合調査
- /propose: 提案書自動生成
- /check-pipeline: 営業パイプライン確認

settings.json での自動化フック

{
 "hooks": {
 "SessionStart": [
 {
 "matcher": "",
 "hooks": [
 {
 "type": "command",
 "command": "gh auth status"
 },
 {
 "type": "command",
 "command": "echo 'CLAUDE.md を読み込みました。実行前に gh auth status の結果を確認してください'"
 }
 ]
 }
 ],
 "PostToolUse": [
 {
 "matcher": "Write.*specs/",
 "hooks": [
 {
 "type": "command",
 "command": "echo '[Warning] specs/ 直下のファイルを変更しました。必ずレビューを通してから merge してください'"
 }
 ]
 }
 ],
 "SubagentStop": [
 {
 "matcher": "@sales-director",
 "hooks": [
 {
 "type": "command",
 "command": "echo '営業判定が完了しました。結果は specs/sales-director-decisions.md に記録されます'"
 }
 ]
 }
 ]
 }
}

落とし穴: 運用で陥りやすい失敗パターン

落とし穴 1: CLAUDE.md に詳細ルールを詰め込む

最初は「あれも書かなければ」とすべてのルールを CLAUDE.md に詰め込む傾向がある。しかし、CLAUDE.md が長くなるほど AI が全体を把握しにくくなり、重要なルールが埋もれる。

運用の知見: CLAUDE.md は 300 行前後が限界。それ以上なら specs/ へ詳細を移動させ、CLAUDE.md には「〇〇は specs/workflow-rules.md を参照」とだけ書く。セッション開始時に AI が「全体を読める長さ」を基準に、分割を判断する。

落とし穴 2: 二重管理が生まれる

「CLAUDE.md にも書いた、Notion にも書いた、specs/skills.md にも書いた」という状態になると、どれが最新かわからなくなる。

対策: 各情報の SSOT を 1 箇所に決め、それ以外の場所には「〇〇を参照」とだけ書く。SSOT の所在自体を specs/workflow-rules.md に記録しておくと、後から新しいメンバーや AI も迷いにくい。

Synapse では、CLAUDE.md の「ドキュメント自動更新ルール」テーブルが SSOT 宣言を兼ねている。

落とし穴 3: フックが多すぎてノイズになる

settings.json のフックは強力だが、すべてのファイル変更に細かく反応させると警告が頻発し、やがて無視されるようになる。

運用の知見: 「本当に見落とすとまずいもの」だけをフック対象にする。Synapse では：

  • ✅ フック対象：specs/ への変更（ドメイン知識が必須、AI が自動更新しても OK）
  • ✅ フック対象：CLAUDE.md への変更試行（禁止。設定として機能させるため）
  • ❌ フック非対象：config/ への変更（マシンリーダブルなので CI で validate 可能）
  • ❌ フック非対象：ブログ記事本文の編集（AI が見出しを忘れることはないので警告不要）

判断基準は「AI のうっかりミスで致命的になるか」「人間のレビューで必ず引っかかるか」。両方 YES なら、フック化して自動化する。

まとめ

新規プロジェクトへの Claude Code onboarding は、CLAUDE.md・specs/・.claude/ の3層を最初に置くことから始まる。

  • CLAUDE.md: コミュニケーション・Git・委任ルール・ドキュメント更新ルール（300 行以内）
  • specs/: 仕様書群と SSOT 宣言（参照時に詳細を補完）
  • .claude/: エージェント定義・スキル・フック（自動化の実装）

重要な設計判断は：

  1. 「何をするか」と「なぜするか」を分離する。CLAUDE.md は「何」、specs/ は「なぜ」。
  2. SSOT を明示する。各情報の唯一の出処を宣言しておくと、AI も人間も判断に迷わない。
  3. 多機能より保守性。エージェントやフックを増やすより、薄く始めて必要なものだけ足す方が長期的に安定する。

最初の設定に 2〜3 日かかるが、その後の毎日の指示コスト削減とレビュー効率化を考えると、この投資は数週間で回収できる。

関連記事：

ShareX でシェア

関連記事

[ Claude / Claude Code ]

AI メモリーシステム運用 — 記憶を 4 種類に分類する設計

Claude Code でメモリを user / feedback / project / reference の 4 分類で整理することで、AI の判断精度を高めながら陳腐化と肥大化を防ぐことができる。

[ Claude / Claude Code ]

プロジェクト間でエージェント・スキルを再利用する設計

複数プロジェクトで似たエージェント定義が増殖する問題を、グローバル定義とプロジェクトローカルの2層に分離して解決した八雲の設計パターンと運用知見を整理する。

[ Claude / Claude Code ]

議事録自動化 — Google Docs と Claude Code で会議記録を構造化する

テンプレート構造と Claude Code による要点抽出で、議事録作成の摩擦を最小化し、決定事項の記録を確実にする。