Architect Foundations ドメイン3: Claude Code の設定とワークフロー（20%）
この章で学ぶこと: CLAUDE.md の階層とモジュール化、カスタムのスラッシュコマンドとスキル、パス別ルール、plan mode と直接実行の使い分け、反復改善の手法、CI/CD への組み込み。
本番の60問のうち約12問が出ます。Developer Foundations では 3.1% でしたが、ここでは5分の1を占めます。
| タスクステートメント | この章の節 |
|---|---|
| 3.1 CLAUDE.md の階層・範囲・モジュール構成 | 第1節 |
| 3.2 カスタムのスラッシュコマンドとスキル | 第2節 |
| 3.3 パス別ルール | 第3節 |
| 3.4 plan mode と直接実行 | 第4節 |
| 3.5 反復改善の手法 | 第5節 |
| 3.6 CI/CD への組み込み | 第6節 |
Developer Foundations で学んだ基本（ここでは繰り返しません）:
- 部品（Rules、Skills、Commands、Agents、Agent Memory）と読み込みのタイミング → Developer D3 第1節
- CLAUDE.md の読み込み方（上のディレクトリはつなげて読む、下は扱ったとき） → Developer D3 第2節
- SKILL.md の frontmatter の一覧 → Developer D3 第4.3節
- 組み込みのサブエージェント（Explore、Plan）、セッション管理 → Developer D3 第5節・第7節
- ヘッドレスモード
-p、--output-format、--json-schema、--bare→ Developer D3 第9節 - CLAUDE.md の範囲と settings.json の優先順位 → Developer D2 第6節
1. CLAUDE.md の階層とモジュール化（3.1）
1.1 3つの階層
| 階層 | 場所 | だれに効くか | チームに共有されるか |
|---|---|---|---|
| ユーザー単位 | ~/.claude/CLAUDE.md |
自分の全プロジェクト | されない |
| プロジェクト単位 | .claude/CLAUDE.md またはルートの CLAUDE.md |
このリポジトリの全員 | される（バージョン管理） |
| ディレクトリ単位 | サブディレクトリの CLAUDE.md |
そのディレクトリのファイルを扱うとき | される |
ほかに、組織の管理用 CLAUDE.md と、自分だけのプロジェクト用 CLAUDE.local.md（.gitignore に入れる）もあります。
1.2 よくある階層の問題
例: ベテランの開発者の Claude Code は社内の決まりを守るのに、新しく入ったメンバーの Claude Code は守らない。
原因: 決まりがベテランの ~/.claude/CLAUDE.md（ユーザー単位）に書いてあり、リポジトリに入っていない。新メンバーには届かない。
対策: チームの決まりは、プロジェクト単位の CLAUDE.md（または .claude/rules/）に移してコミットする。
1.3 @import でモジュール化する
# packages/billing/CLAUDE.md
このパッケージは請求の計算を扱う。
@../../docs/conventions/money-handling.md
@../../docs/conventions/api-errors.md
@path/to/fileで別のファイルを読み込む。相対パスは、読み込む側のファイルからの位置- 読み込んだファイルがさらに読み込むこともできる（最大4段）
- パッケージごとに、関係する規約ファイルだけを選んで含める（担当者の知識で選ぶ）
- 注意（公式）: import は整理には役立つが、コンテキストの量は減らない。読み込んだファイルは一緒に全部入る。量を減らしたいなら、パス別ルール（第3節）かスキルにする
1.4 大きな CLAUDE.md を .claude/rules/ に分ける
.claude/
├── CLAUDE.md
└── rules/
├── testing.md
├── api-conventions.md
└── deployment.md
公式の目安は、1つの CLAUDE.md を200行未満にすることです。長いほどコンテキストを使い、守られにくくなります。
1.5 読み込まれているか確かめる
| コマンド | 何ができるか |
|---|---|
/memory |
ユーザー単位とプロジェクト単位の CLAUDE.md などのメモリファイルを一覧し、開いて編集する。auto memory の切り替えもできる |
/context all |
今のセッションに実際に読み込まれたファイルを「Memory files」の一覧で確かめる（今の公式ドキュメントが勧める確認方法） |
試験ガイドは「/memory で読み込まれているメモリファイルを確かめ、セッションごとの振る舞いの違いを診断する」と書きます。今の公式ドキュメントでは、読み込みの確認には /context all も使います。両方おぼえておきます。
2. カスタムのスラッシュコマンドとスキル（3.2）
2.1 置き場所
| 用途 | コマンド（古い形式） | スキル（今の推奨） |
|---|---|---|
| チームで共有 | .claude/commands/<名前>.md |
.claude/skills/<名前>/SKILL.md |
| 自分だけ | ~/.claude/commands/<名前>.md |
~/.claude/skills/<名前>/SKILL.md |
- どちらも
/名前で呼べる。今の公式ドキュメントでは、コマンドはスキルに統合された。.claude/commands/もそのまま動く - 試験ガイドのサンプル問題では「チーム全員が使う
/reviewは.claude/commands/」が正解。今なら.claude/skills/review/SKILL.mdも同じ働き - 誤答の定番:
~/.claude/commands/（個人用で共有されない）、CLAUDE.md に書く（コマンドの定義ではない）、.claude/config.json（そのような仕組みはない）
2.2 個人用の変種
チームのスキル /review を自分好みに変えたいときは、~/.claude/skills/ に別の名前（例: /review-strict）で作ります。チームのスキルを書き換えると全員に影響します。
2.3 frontmatter の3つの設定（試験の範囲）
---
name: analyze-codebase
description: コードベース全体の構造を調べ、主要なモジュールと依存関係を報告する
context: fork
agent: Explore
argument-hint: "[対象のディレクトリ]"
allowed-tools: Read Grep Glob
---
$ARGUMENTS の構造を調べ、要約だけを返す。
| 設定 | 意味 | 使いどころ |
|---|---|---|
context: fork |
スキルを分離されたサブエージェントのコンテキストで動かす。出力はメインの会話を汚さない（要約だけ戻る）。agent でサブエージェントの種類を選べる |
出力が多い分析、探索的なブレインストーミング |
allowed-tools |
ツールの制御（下の注意） | 破壊的な操作を防ぐ |
argument-hint |
引数の入力を促すヒント（補完のときに表示） | 引数が必要なスキル |
allowed-toolsの意味の違いに注意: 試験ガイドは「allowed-toolsでスキル実行中のツールを制限する」と書きます。今の公式ドキュメントでは、allowed-toolsは「このスキルを呼んだターンの間、確認なしで使えるツール」（事前の許可）です。ほかのツールが使えなくなるわけではありません。ツールを使えなくするのはdisallowed-toolsです。試験ではガイドの言い方（制限）で答え、実務ではdisallowed-toolsや権限ルールも使います。
2.4 スキルと CLAUDE.md の使い分け
| CLAUDE.md | スキル | |
|---|---|---|
| 読み込み | 毎セッション、常に | 呼ばれたとき（または関係すると Claude が判断したとき） |
| 中身 | どこでも守る共通の決まり | 特定の作業の手順 |
| 例 | ビルドコマンド、命名規則 | リリースの手順、コードレビューのチェックリスト |
3. パス別ルール（3.3）
3.1 書き方
---
paths:
- "**/*.test.tsx"
- "**/*.test.ts"
---
- テストは「準備・実行・確認」の3段に分ける
- 外部 API は必ずモックにする
---
paths: ["terraform/**/*"]
---
- リソース名には必ず環境名の接頭辞を付ける
.claude/rules/のファイルの YAML frontmatter にpaths（glob パターン）を書く- 合うファイルを Read・Write・Edit するときだけ読み込まれる。関係ない作業ではコンテキストとトークンを使わない
pathsを書かないルールは、起動時にいつも読み込まれる
3.2 ディレクトリの CLAUDE.md か、パス別ルールか
| 規約の対象 | 選ぶもの |
|---|---|
1つのディレクトリにまとまっている（例: infra/ の中だけ） |
そのディレクトリの CLAUDE.md、またはパス別ルール |
| コード全体に散らばっている（例: 各コンポーネントの横にあるテストファイル） | glob のパス別ルール（**/*.test.tsx） |
ディレクトリの CLAUDE.md はディレクトリに縛られるので、あちこちに散らばったファイルには向きません。スキルで規約を持たせる案も、呼ばれないと読み込まれないので「自動で必ず当てたい」要件に合いません。
4. plan mode と直接実行（3.4）
4.1 使い分け
| plan mode を選ぶ | 直接実行を選ぶ |
|---|---|
| 大きな変更（例: モノリスをマイクロサービスに） | 単純で範囲がはっきりした変更 |
| 妥当な方法が複数ある | 方法が1つに決まっている |
| 設計上の判断がある（サービスの境界、インフラの違う統合方法の選択） | スタックトレースが明確な単一ファイルのバグ修正 |
| 多くのファイルに及ぶ（例: 45以上のファイルのライブラリ移行） | 関数に検証の条件を1つ足す |
plan mode では、Claude はコードを読んで調べますが、ソースファイルは編集しません（権限モードの plan）。変更を確定する前に、安全に探索と設計ができ、高くつく手戻りを防げます。CLI では Shift+Tab で切り替えられます。
4.2 誤答の定番
| 誤答 | なぜだめか |
|---|---|
| 直接実行で少しずつ変えて、実装から境界を見つける | 依存関係が後でわかり、手戻りが大きい |
| 直接実行に、詳しい指示を最初に全部書く | コードを調べずに正しい構造がわかっている前提になっている |
| 直接実行で始め、困ったら plan mode に切り替える | 複雑さは最初から要件に書いてある |
4.3 組み合わせる
- 調査と計画は plan mode、実装は直接実行。例: ライブラリ移行の計画を plan mode で作り、承認してから、その方針で実行する
4.4 Explore サブエージェントで探索を分離する
多段階の仕事の探索フェーズでは、組み込みの Explore サブエージェントに調べさせます。
- Explore は読むだけで、変更しない
- 大量の探索の出力は Explore のコンテキストに残り、メインには要約だけが戻る
- メインのコンテキストウィンドウが探索の結果で埋まるのを防ぐ（第5章 5.4 とつながる）
5. 反復改善の手法（3.5）
5.1 4つの手法
| 手法 | いつ使うか | やり方 |
|---|---|---|
| 具体的な入出力例 | 文章で説明すると解釈がぶれる | 2〜3個の「この入力 → この出力」を見せる |
| テスト駆動の反復 | 期待する動きをはっきりさせたい | 実装の前に、期待動作・例外ケース・性能要件のテストを書く。失敗したテストの結果を Claude に見せて直させる |
| インタビューパターン | なじみのない分野 | 実装の前に、Claude に質問させる。例: 「キャッシュの無効化はいつ？」「失敗したらどうする？」 |
| 具体的なテストケースで例外を直す | 例外ケースの扱いが違う | 例: 移行スクリプトで null の値が来たときの入力と期待出力を渡す |
5.2 1つのメッセージで伝えるか、順番に直すか
| 問題の関係 | 伝え方 |
|---|---|
| 互いに影響する（例: データの形を変えると、検証とエラー処理も変わる） | 1つの詳しいメッセージにまとめて伝える |
| 独立している（例: ログの文言と、別の画面の並び順） | 1つずつ順番に直す |
互いに影響する修正をバラバラに頼むと、後の修正が前の修正を壊すことがあります。
6. CI/CD への組み込み（3.6）
6.1 必要なフラグ
| フラグ | 意味 |
|---|---|
-p（--print） |
非対話モード。プロンプトを処理して結果を標準出力に出し、終わる。入力待ちで止まらない |
--output-format json |
結果、セッション ID、メタデータを JSON で出す |
--json-schema '<スキーマ>' |
--output-format json と一緒に使う。スキーマに合う結果が structured_output の項目に入る |
--bare |
スクリプトや CI では推奨。ホストのフック、プラグイン、auto memory、CLAUDE.md の自動読み込みを飛ばす |
claude -p "この PR の差分をレビューし、問題をスキーマどおりに返して" \
--output-format json \
--json-schema "$(cat review-schema.json)" > review.json
# review.json の structured_output を読んで、PR のインラインコメントとして投稿する
誤答の定番（サンプル問題より）: CLAUDE_HEADLESS=true という環境変数や --batch フラグは存在しません。< /dev/null で標準入力をふさぐのも正しいやり方ではありません。
注意: Claude が依頼を断った場合などは structured_output が入りません。スクリプトは項目があるか確かめてから使います。
6.2 CI の Claude Code に文脈を与えるのは CLAUDE.md
CI から呼ばれた Claude Code も、プロジェクトの CLAUDE.md を読みます（--bare を付けない場合）。テスト規約、フィクスチャの慣習、レビューの基準、価値のあるテストの基準、使えるフィクスチャを書いておくと、テスト生成とレビューの質が上がります。
--bare を付けるときは CLAUDE.md が自動では読み込まれないので、必要な文脈をプロンプトや --append-system-prompt で渡します（筆者の補足）。
6.3 生成とレビューのセッションを分ける
コードを生成したのと同じセッションは、自分の変更のレビューが苦手です。生成のときの推論がコンテキストに残っていて、自分の判断を疑いにくいからです。レビューは、生成の文脈を持たない別のインスタンス（別の claude -p の実行）にします（第4章 4.6）。
6.4 重複を減らす
| 場面 | やり方 |
|---|---|
| 新しいコミットの後の再レビュー | 前回の指摘をコンテキストに入れ、「新しい問題」と「まだ直っていない問題」だけを報告させる。同じコメントが何度も付くのを防ぐ |
| テスト生成 | 既存のテストファイルをコンテキストに渡し、すでにあるシナリオを重複して提案させない |
7. 試験に向けたまとめ
| 問われ方 | 答えの考え方 |
|---|---|
| 新メンバーにだけ決まりが効かない | 決まりがユーザー単位（~/.claude/CLAUDE.md）にある。プロジェクト単位に移す |
| パッケージごとに関係する規約だけ | @import で選んで含める |
| 巨大な CLAUDE.md | .claude/rules/ のトピック別ファイル |
| 何が読み込まれているか | /memory（今は /context all でも確認） |
チーム全員の /review |
.claude/commands/（今は .claude/skills/ も） |
| 自分だけの変種 | ~/.claude/skills/ に別名で |
| 出力が多いスキル | context: fork |
| スキル中のツールを制限 | ガイドでは allowed-tools（今は disallowed-tools で外す、allowed-tools は事前許可） |
| 引数を促す | argument-hint |
| 散らばったテストファイルに同じ規約 | .claude/rules/ に paths: ["**/*.test.tsx"] |
| マイクロサービス化、45ファイルの移行 | plan mode |
| 明確な1ファイルのバグ | 直接実行 |
| 探索でコンテキストが埋まる | Explore サブエージェント |
| 説明で伝わらない変換 | 2〜3個の入出力例 |
| 互いに影響する修正 | 1つの詳しいメッセージ |
| CI で止まる | -p |
| CI で機械が読む結果 | --output-format json と --json-schema |
| 再レビューで同じコメント | 前回の指摘を渡し、新規と未修正だけ |
8. 用語集
| 用語 | 意味 |
|---|---|
| ユーザー単位 / プロジェクト単位 | 自分だけに効く設定 / リポジトリの全員に効く設定 |
@import |
CLAUDE.md の中で別のファイルを読み込む書き方 |
| パス別ルール | paths を持ち、合うファイルを扱うときだけ読み込まれるルール |
context: fork |
スキルを別のサブエージェントで動かす設定 |
| plan mode | 読んで計画するが、編集はしないモード |
| 直接実行 | 計画のフェーズを置かず、すぐに変更するやり方 |
| インタビューパターン | 実装の前に Claude に質問させるやり方 |
出典
- Claude Certified Architect – Foundations Exam Guide（PDF、Version 1.0、2026年7月）: 第6章 ドメイン3、第9章のサンプル問題
- Memory（Claude Code Docs）: CLAUDE.md の場所、
@pathの import（最大4段、コンテキストは減らない）、.claude/rules/とpaths、200行の目安、/memory、/context all - Skills（Claude Code Docs）: コマンドとスキルの統合、
context: fork、agent、allowed-tools（事前の許可）、disallowed-tools、argument-hint - Subagents（Claude Code Docs）: Explore と Plan
- Permission modes（Claude Code Docs）: plan モード、Shift+Tab
- Run Claude Code programmatically（Claude Code Docs）:
-p、--output-format json、--json-schemaとstructured_output、CI での--bare - Claude Code best practices（Anthropic Engineering）: 調べて計画してから実装する、テスト駆動、具体的な例を渡す
内容は2026年11月時点のものです。Claude Code は更新が速いので、本番前に公式ドキュメントで確かめてください。上の出典を要約・言い換えたものです（ライセンスに配慮して書き直しています）。