🧭 .claude/ は「AI の開発者体験」そのもの
ステアリング駆動開発を支えるのは Claude Code の .claude/ 設定です。ここが貧弱なら、どれだけ素晴らしい仕様を書いても AI は毎回「再学習」からやり直します。逆に言えば、.claude/ を丁寧に設計すれば 「何度セッションを再開してもプロジェクトルール通りに動く AI」 が手に入ります。
シリーズ第 7 回では、CTS-EC の .claude/ 構成をベースに、CLAUDE.md・hooks・commands・skills の 4 つを統合運用するベストプラクティスを解説します。
🗂️ .claude/ ディレクトリ構成の全体像
.claude/
├── CLAUDE.md ← プロジェクトの必須ルール（10 個）
├── SKILLS.md ← skills / commands のナビゲーション
├── settings.json ← permissions / hooks
├── settings.local.json ← 個人の上書き（git 管理外）
├── agents/ ← サブエージェント（12 体）
├── commands/ ← スラッシュコマンド（11 個）
├── skills/ ← スキル（when-to-use で自動発火）
│ ├── common/ ← 常時適用
│ ├── dotnet/ ← dotnet/**/* で発火
│ ├── frontend/ ← frontend/**/* で発火
│ ├── python/ ← python/**/* で発火
│ ├── steering/ ← タスク管理
│ └── ...
├── agent-memory/ ← サブエージェントの project memory
├── document/ ← 参考資料（CSV / PDF / DOCX など）
└── templates/ ← 進捗報告 / blockers / test-summary2026-04 時点で CTS-EC の .claude/ 配下は 3,500 行超に達しています。このボリュームを「毎回読ませる」のは非現実的。paths: frontmatter と hooks で 必要な時だけロード する構造が肝です。
📜 CLAUDE.md 設計：10 の必須ルールだけに絞る
CLAUDE.md はセッション冒頭に常時ロードされるため、 書きすぎると cache プレフィックスが肥大化します。CTS-EC では 10 個の必須ルールだけに絞っています。
| # | 必須ルール | 違反時の挙動 |
|---|---|---|
| 0 | pre-push/lint FAIL を「無関係」と判断するな | 生ログ確認を強制 |
| 1 | main への直接 Push 禁止 | hook で自動 block |
| 2 | Push と MR 作成は同時に実行 | パイプライン重複防止 |
| 3 | Push 前にテスト実行 | CI コスト削減 |
| 4 | TDD 必須 | テストなし変更は即取り消し |
| 5 | ステアリング作成後はレビュー + オーナー承認必須 | 2 段レビューゲート |
| 6 | GCP インフラは Terraform 経由 | gcloud CLI 直接作成禁止 |
| 7 | 仕様準拠・推測禁止・指摘即対応 | tdd-spec-gate で強制 |
| 8 | 実装前調査必須 | 公式ドキュメント + ログ追加 |
| 9 | 実装完成度（TODO / stub 残し禁止） | implementation-validator で検出 |
| 10 | Skill 自動起動の原則（Skill-First） | when-to-use マッチで起動 |
詳細は各スキル / ドキュメントに委譲し、CLAUDE.md 本体は クイックリファレンス に徹します。
🪝 hooks：人間のレビュー漏れを補う 6 ゲート
.claude/settings.json の hooks で、人間の確認漏れを構造的に防ぎます。CTS-EC では 6 つのフックを運用しています。
| イベント | matcher | 処理 | 目的 |
|---|---|---|---|
| SessionStart | — | steering-auto-load.sh | アクティブステアリングの自動ロード |
| SessionStart | — | ensure-watch-running.sh | ファイル監視プロセスの常駐確認 |
| UserPromptSubmit | — | evidence-gate-detector.sh | 「確認」キーワード検出時にツール実行強制 |
| PreToolUse | Bash(git push*) | pre-push-main-guard.sh | main 直接 Push を block |
| PreToolUse | Bash(git push*) | check-push-readiness.sh | /pre-push 未実施を警告 |
| PreToolUse | Bash(./scripts/test-all.sh*) | block 判定 | test-all.sh 直接実行を禁止（/test を強制） |
| PostToolUse | Edit | post-edit-format.sh | 編集直後に自動フォーマット |
| PostToolUse | Write | post-write-steering-check.sh | 新規ファイル書き込み時にステアリング整合を確認 |
| Stop | — | session-learning.sh | セッション終了時の学習ログ収集 |
main ガード hook の具体例
# PreToolUse: Bash(git push*) にマッチ
./scripts/hooks/pre-push-main-guard.sh
# 内部で以下を判定
git diff --name-only HEAD~1 HEAD \
| grep -vE '^(docs/|\.claude/|\.steering/|.*\.md$|.*\.mmd$)'
# コード変更が検出されたら block（手動スキップ不可）--no-verify でスキップされないよう、CTS-EC では settings.json の permissions 側で --no-verify を禁止する方針も検討中です。
🧨 permissions：deny リストで事故を構造的に防ぐ
.claude/settings.json の deny は、AI が誤って破壊的操作を実行しないための ハードガード です。
"deny": [
"Bash(rm -rf /*)",
"Bash(rm -rf /)",
"Bash(rm -rf ~*)",
"Bash(rm -rf $HOME*)",
"Bash(git push --force*)",
"Bash(git push -f*)",
"Bash(git reset --hard*)",
"Bash(git clean -fd*)",
"Bash(git branch -D*)",
"Bash(dropdb:*)",
"Bash(psql*DROP DATABASE*)",
"Bash(psql*DROP TABLE*)",
"Bash(gcloud*delete*)",
"Bash(terraform destroy*)"
]「ユーザーが承認しなければ実行できない」のは建前ですが、deny に書いておくと AI は承認プロンプトすら出さずに拒否 します。事故率が明確に下がります。
⚡ commands：責務を分割した 11 個のスラッシュコマンド
.claude/commands/ は 11 個のコマンドで構成されています。責務分割が徹底されており、1 コマンド = 1 目的です。
| コマンド | 責務 | 関連エージェント |
|---|---|---|
/steering | 壁打ち〜規模判定〜ステアリング作成 | brainstorming skill |
/steering-status | 進捗確認 + 次フェーズを TodoWrite に自動転記 | - |
/steering-complete | tasklist 最終確認 → archive 移動 → Serena メモリ保存 | - |
/resume | 前回セッションの続きを再開 | - |
/prepare-context | キーワードベースでコンテキスト事前収集 | context-preparer |
/test | テスト実行（スタンプ管理） | test-runner |
/check-test-quality | 型別テスト網羅性チェック | test-quality-checker |
/review-docs | ドキュメント品質レビュー | doc-reviewer |
/review-code | コードレビュー（TDD/DDD/SOLID） | code-reviewer |
/pre-push | Push 前統合ゲート | test-runner + code-reviewer + validator |
/daily-report | 日次進捗レポート生成 | daily-reporter |
/pre-push が統合ゲートの要
/pre-push は単独の品質チェックではなく、複数エージェントを順次起動する統合ゲート です。Step 1 ブランチ確認 → Step 2 未コミット確認 → Step 3 テスト → Step 4 code-reviewer → Step 5 implementation-validator → Step 6 スタンプ発行、という流れで、 どれか 1 つでも失敗したら即中断 します。
🧪 skills：.claude/rules/ を統合した「paths:」ベースの条件ロード
Cursor 由来の .claude/rules/ ディレクトリを、2026-04-17 に skills へ統合しました（常時ロード -27%、-145 MB）。
paths: frontmatter による条件ロード
---
name: dotnet
description: .NET プロジェクトでのコーディング規約・TDD パターン
paths:
- "dotnet/**/*"
allowed-tools: Read, Edit, Bash(dotnet:*)
---paths にマッチするファイルを編集 / 読み込みしたときだけスキルが発火します。常時ロードする common/ と、条件発火の dotnet/ / frontend/ / python/ を使い分けることで、cache プレフィックスを太らせずに済みます。
when-to-use を必ず書く
Skill-First 原則（CLAUDE.md §10）により、SKILL.md の冒頭には when-to-use セクションが必須です。自動起動できない「死にスキル」を防ぎます。
## when-to-use
### 自動起動条件
- ユーザーが「壁打ちしたい」と発言
- L 規模タスクの設計前
### 起動しない条件
- 単純なバグ修正（S 規模）
- 既に詳細仕様が存在する作業の継続📘 SKILLS.md は「ナビゲーション」、SSoT は context-engineering.md
.claude/SKILLS.md は 10 行の薄いナビゲーションファイルです。コマンド・サブエージェントの SSoT は docs/context-engineering.md に集約しています。
理由は 2 つ：
- SKILLS.md を肥大化させると cache プレフィックスが重くなる
- 実運用の正として ADR・運用改善履歴が混ざるのは
docs/側が向いている
🧩 agent-memory：サブエージェントに project memory を持たせる
各エージェント（code-reviewer / doc-reviewer / test-quality-checker 等）は agent-memory/[agent-name]/ に project memory を持ちます。
.claude/agent-memory/
├── code-reviewer/
├── design-reviewer/
├── doc-reviewer/
├── implementation-validator/
└── test-runner/memory: project の宣言
---
name: doc-reviewer
description: ドキュメントの詳細レビュー
model: claude-sonnet-4-6
tools: [Read, Grep, Glob]
memory: project
---memory: project を宣言すると、プロジェクト単位でレビュー傾向や過去指摘を記憶します。 同じ指摘を 2 回しない ためのしくみです。
🛠️ templates：進捗報告・ブロッカー・テストサマリー
.claude/templates/ に 3 つのテンプレートを置いています。
| テンプレート | 用途 |
|---|---|
progress-template.md | 月 2 回の顧客向け進捗報告 |
blockers-template.md | ブロッカー発生時の起票 |
test-summary-template.md | テスト結果サマリー |
docs/progress-reports/YYYY-MM-DD.md はこのテンプレートを元に生成されます。
🧊 1 ファイルに 1 責務：肥大化を避ける運用
.claude/ を運用していると、つい 1 ファイルに機能を追加し続けてしまいます。CTS-EC では以下のしきい値を目安にしています。
| ファイル | 推奨サイズ | 超過時の対処 |
|---|---|---|
| CLAUDE.md | 200 行以内 | 詳細は skills / commands に切り出す |
| SKILL.md | 500 行以内 | 機能単位で分割（templates/ を別ファイルに） |
| コマンド | 200 行以内 | 細分化（/steering-complete は別コマンド化済） |
| エージェント | 300 行以内 | 責務分割（code-reviewer と implementation-validator） |
⚠️ .claude/ 運用でやってはいけないこと
- CLAUDE.md に「今日の TODO」など揮発情報を書く（cache プレフィックス汚染）
- すべてのスキルを常時ロードにする（
pathsで条件分岐する） - when-to-use のないスキルを新規作成（自動起動できない）
- hooks を
--no-verifyでスキップする - deny リストを書かずに AI に destructive command を許可する
- コマンドを 1 本に統合する（責務分割して
/pre-pushのように組み合わせる）
📚 シリーズ記事
| # | タイトル | 内容 |
|---|---|---|
| 1 | 概要 | ステアリング駆動開発の全体像 |
| 2 | 壁打ち・規模判定編 | 壁打ちの進め方、ADR の書き方、規模判定の基準 |
| 3 | ステアリング作成編 | M/L 規模のドキュメント作成、TDD タスク分解 |
| 4 | 実装・完了編 | TodoWrite 連携、進捗管理、アーカイブ運用 |
| 5 | コンテキスト設計編 | AI に渡すコンテキストの最適化、skills 設計 |
| 6 | 品質ゲート編 | doc-reviewer、テスト品質チェック、受入テスト |
| 7 | Claude Code ベストプラクティス（本記事） | CLAUDE.md 設計、hooks、commands、rules、skills |
| 8 | Agent Teams 編 | agents 定義、チーム構成、マルチエージェント協調 |
| 9 | Remote Control 編 | スマホ・Web から CLI セッションを操る席拘束からの解放 |
🔗 関連記事
- Claude Code 7層ハーネスエンジニアリング — 7 層ハーネスの視点からの
.claude/解説 - コンテキスト設計編 — cache プレフィックス最適化の詳細
- Agent Teams 編 — サブエージェントの協調パターン
📖 関連用語
- コンテキストエンジニアリング — CLAUDE.md・skills の配置戦略の上位概念
- ハーネスエンジニアリング — hooks・commands・agents で構築する恒久的な運用基盤
- tmux — Agent Teams で使う端末多重化ツール