CTS-KB
AI駆動開発 📚 シリーズ 5/9

コンテキスト設計編：AI に渡すコンテキストを最適化する skills と prepare-context

⏱ 約 7 分で読めます
#ステアリング駆動開発 #コンテキストエンジニアリング #Prompt Caching #Claude Code #skills
実装・完了編：TodoWrite 連携と tasklist.md 同時更新、アーカイブ運用 品質ゲート編：doc-reviewer、テスト品質チェック、受入テスト

🧠 AI 駆動開発の勝負はコンテキストで決まる

AI コーディングツールの出力品質は、渡すコンテキストの品質でほぼ決まります。逆に言えば 「全部読ませれば賢くなる」は誤り です。

  • ドキュメント全読み → トークン消費が増え、重要情報が薄まる
  • 揮発情報を冒頭に貼る → Prompt Cache が毎ターン無効化する
  • 無計画な /compact → 重要な合意事項と変数名が消える

シリーズ第 5 回では、CTS-EC の .claude/skills/ と /prepare-context 運用を軸に、AI に渡すコンテキストをどう最適化するかを解説します。

🧱 Context Engineering の 3 本柱

CTS-EC では以下の 3 本柱でコンテキストを設計しています。

柱目的対応ツール
skills 設計必要な時だけスキルをロード、不要時は読まない.claude/skills/*/SKILL.md
Iterative Retrievalキーワードベースで必要最小限だけ収集/prepare-context + context-preparer agent
Prompt Cache 温存5 分 TTL を超えない起動順序と compact タイミングprompt-cache / strategic-compact skill

📚 ドキュメント 2 層アーキテクチャの再確認

コンテキスト設計は、ドキュメント階層の設計が前提です。

docs/specs/（全体仕様 = 北極星・参照用）
     │
     │ 参照・抽出（prepare-context が担当）
     ↓
.steering/[タスク]/（詳細仕様 = 実装入力）
     │
     │ TDD 実装
     ↓
コード完成

docs/specs/ は そのまま読み込ませない。Grep で該当行のみ抽出し、.steering/ に詳細化してから実装に渡します。これだけでトークン消費は一桁変わります。

🛰️ /prepare-context と context-preparer エージェント

実装前のコンテキスト収集は /prepare-context [キーワード] に集約しています。背後で context-preparer（Haiku 4.5 ベース）が Iterative Retrieval パターンで段階的に検索します。

Cycle 1: DISPATCH（広い検索）

Step 1: キーワード抽出         "StoreCategory のテナント対応"
                                   ↓
                               StoreCategory, テナント, Tenant

Step 2: 用語確認               Grep "StoreCategory|テナント" docs/glossary.md
Step 3: 関連仕様特定           Grep "store-category" docs/specs/INDEX.md
Step 4: 過去ステアリング検索   archive/ から類似タスク
Step 5: 参照実装候補抽出       過去 design.md の §参照実装テーブル

返却される要約（50〜100 トークン）

メインエージェントにはファイルパス + 50〜100 トークン要約のみが返却されます。必要なときだけメインが Read し、不要なものは読まない構造です。

これにより、以下が達成されます：

  • ドキュメント総なめの禁止（手動で全 Read しない）
  • 参照実装候補が自動的に提示される
  • 代替コマンド/エージェントがある場合はそちらを提案

⚡ Prompt Cache 5 分 TTL を意識した配置

Anthropic Prompt Caching の 5 分 TTL は、読み込みコストを基本入力の 0.1 倍まで下げる 最重要機能です。CTS-EC では運用側で cache 温存を意識しています。

cacheable vs volatile の分離

分類配置内容例
cacheable（前半）システムプロンプト、CLAUDE.md、SKILL.md、agent 定義、glossary変化しない、複数ターンで再利用
cacheable（中盤）過去の確定したツール結果（Read / grep）ターン間で不変
volatile（末尾）TodoWrite ステータス、直近の Edit 差分1 ターンで書き換わる
volatile（避ける）時刻・ランダム値・ユーザー識別子cache prefix が毎回変わる

NG / OK パターン

❌ 会話冒頭に「現在時刻 YYYY-MM-DD HH:MM」を常に貼る
   → 毎ターン prefix が変わり cache 全無効化

❌ CLAUDE.md の先頭に「今日の TODO: ...」等の揮発情報を書く
   → グローバル指示が毎日変わり cache miss

✅ 揮発情報は会話末尾・TodoWrite 内に限定
✅ SKILL.md / CLAUDE.md は「原則・参照先」のみ、状態は含めない
✅ 長い Read 結果は中盤に固定、以降は参照のみ

🪃 サブエージェント起動は「5 分以内に一気に」

サブエージェントは独立コンテキストで実行されますが、起動タイミングを揃えることで cache を活かせます。

場面推奨アクション
複数 Agent を立て続けに使う予定5 分以内に一気に起動（並列 or 短時間シーケンシャル）
長い Read 直後に Agent 起動Read → Agent を 同じ turn 内で実行
compact の直前に Agent 起動予定compact 前に Agent を先に起動（cache 温存）
連続タスクの間に長い待機ScheduleWakeup(delaySeconds: 270) で 5 分 TTL 内に復帰

ScheduleWakeup で 300 秒ではなく 270 秒を選ぶのは、cache TTL をまたがせないための実運用テクニックです。

🗜️ Strategic Compact：compact タイミング判断

/compact は 5 分 TTL の cache を 全無効化します（再構築は書き込み × 1.25）。無計画に叩くとコストが増え、直近の合意事項が消えます。CTS-EC では strategic-compact スキルで判断を体系化しています。

圧縮すべきタイミング

フェーズ移行理由保存先
ステアリング作成 → 実装開始仕様策定の対話は重いtasklist.md
調査・分析 → 設計Read / WebSearch の出力が残るdecision.md
デバッグ完了 → 次タスクデバッグトレースが次タスクを汚染修正コミット
/review-docs 完了 → 実装レビュー結果は修正済み修正反映済み
/pre-push 完了 → Pushゲート結果は成否のみ重要スタンプファイル

圧縮すべきでないタイミング

  • 実装の途中（変数名・ファイルパスを保持中）
  • テスト失敗の修正中（スタックトレースが必要）
  • 複数ファイルのリファクタリング中（一貫性が崩れる）
  • 設計対話の最中（合意事項を失う）

提案テンプレート

💡 コンパクション推奨ポイントです。
現在のフェーズ: [調査 → 設計] に移行しました。

保存済み情報:
- tasklist.md: 10/15 タスク完了
- decision.md: OAuth ライブラリ選定を記録済み
- git: コミット a1b2c3

/compact を実行しますか？

compact 提案前に TodoWrite / tasklist.md / git の 3 点が最新かを必ずチェックします。

🧰 skills 設計の指針

.claude/skills/ に置くスキルは以下の指針で設計します。

指針内容
when-to-use を明記自動起動条件 / 起動しない条件を SKILL.md の冒頭に書く
関係のないタスクでロードしない/steering など明示コマンドでのみ起動する
user-invocable は必要時のみ会話で明示呼び出しするスキルだけ user-invocable: true
状態を含めないSKILL.md は原則と参照先のみ。進捗・時刻は書かない

when-to-use 例（brainstorming）

### 自動起動条件
- /steering [タイトル] 実行時の Step 0
- ユーザーが「壁打ちしたい」と発言したとき
- 新規ステアリング作成前で、要件が不明確なとき
- L 規模タスクの設計前

### 起動しない条件
- 単純なバグ修正（S 規模）
- 既に詳細仕様が存在する作業の継続
- 機械的なリファクタリング

この明示により、S 規模の軽量作業で brainstorming が暴発するのを防げます。

🧊 1M context window モードと 200K モード

Opus 4.7 / 4.6・Sonnet 4.6 の 1M mode では compact 閾値が大きく変わります。

モードcompact 提案閾値備考
200K mode（Sonnet 4.5 / Haiku / 通常 Opus）80K / 160K トークン従来運用
1M mode（Opus 4.7 / 4.6・Sonnet 4.6）500K トークン大きく引き上げ

1M mode では compact しない時間が長くなるため、**cache TTL を 1 時間オプション（cache_control: ephemeral, ttl: "1h"）**へ切り替える価値が上がります。書き込みコストは 2.0 倍ですが、読み込みは 0.1 倍のまま維持できます。

⚠️ コンテキスト設計でやってはいけないこと

  • docs/specs/ 配下を一括 Read で全部読み込ませる
  • 揮発情報（時刻・進捗・ランダム値）を会話冒頭に置く
  • 無計画に /compact を叩く（cache 全無効化 + 直近記憶消失）
  • 実装の途中で compact（変数名・ファイルパスを失う）
  • SKILL.md に状態（進捗・TODO）を書き込む
  • 300 秒の ScheduleWakeup を使う（5 分 TTL を少し超える。270 秒にする）

📚 シリーズ記事

#タイトル内容
1概要ステアリング駆動開発の全体像
2壁打ち・規模判定編壁打ちの進め方、ADR の書き方、規模判定の基準
3ステアリング作成編M/L 規模のドキュメント作成、TDD タスク分解
4実装・完了編TodoWrite 連携、進捗管理、アーカイブ運用
5コンテキスト設計編（本記事）AI に渡すコンテキストの最適化、skills 設計
6品質ゲート編doc-reviewer、テスト品質チェック、受入テスト
7Claude Code ベストプラクティスCLAUDE.md 設計、hooks、commands、rules、skills
8Agent Teams 編agents 定義、チーム構成、マルチエージェント協調
9Remote Control 編スマホ・Web から CLI セッションを操る席拘束からの解放

🔗 関連記事

📖 関連用語