Share
Embed
Transcript
33 slides
-
README 本スライドをご覧いただく前に ▶ 本資料は @_awache が個人的に検証した結果のレポートです ▶ 検証パターンは 1パターンのみ で、複雑なタスクは扱っていません
▶ 結果に 偏り(バイアス) が含まれる可能性がある点をご了承ください ▶ あくまで 一検証事例 としてご参照ください -
自己紹介 mysql > SELECT * FROM me \G ******************* 1.
row ******************* name: 粟田 啓介 nickname: あわっち X(twitter): @_awache company: KINTO テクノロジーズ株式会社 role: DBRE/SRE MGR、KINTO Innovation Lab favorite: MySQL 1 rows in set (0.00 sec) -
なぜ .claude を設計するのか モデル単体では 安定した挙動は作れない • どのルールに従うか • どのツールを使用するか •
どの手順で作業するか • どの範囲まで操作を許可するか 外部構造を合わせて設計する .claude = Harness モデル × その外側の実行環境を ひとつのエージェントとして設計する領域。 プロジェクト単位で振る舞いを レイヤーごとに管理する。 ※ LangChain でも Agent = Model + Harness として整理されている .claude ディレクトリ: プロジェクトのルートに置くだけで Claude Code が毎回読み込む、規約・エージェント・手順を束ねた設定置き場 -
Model + Harness という捉え方 Agent = Model + Harness Harness(実行環境)
Claude (Model) + CLAUDE.md 前提 rules 規約 skills 手順 agents 分業 hooks 強制 settings 制御 Model だけでは決まらない判断を、外側の構造で明示する。 .claude はその Harness の一部。 -
ディレクトリ構成 repo/ ├─ .claude/ │ ├─ agents/ ← 分業 │
├─ CLAUDE.local.md │ ├─ hooks/ ← 強制 │ ├─ rules/ ← 規約 │ ├─ settings.json ← 制御 │ ├─ settings.local.json │ └─ skills/ ← 手順 ├─ CLAUDE.md ← 前提 ├─ docs/ │ └─ api.md, domain.md ... CLAUDE.md の配置 リポジトリ直下 / .claude/ 配下 のいずれも可。 セッション開始時にプロジェクト記憶として読まれる。 *.local.* は個人用上書き CLAUDE.local.md / settings.local.json は .gitignore 対象。共有設定とは分離して管理する。 本質:設定の分割ではなく、 振る舞いをレイヤーごとに 分けて管理する構造 -
6つのレイヤーの俯瞰 6つのレイヤーに責務を分けて設計する 推論に効くレイヤー (Claude の判断に影響) 実行環境レイヤー (推論とは独立に動作) CLAUDE.md 前提 常時参照する
プロジェクト記憶 rules 規約 繰り返し守らせたい 規約(条件付き適用可) skills 手順 再利用可能な 作業ワークフロー agents 分業 独立した実行主体 (subagent) hooks 強制 イベントに紐付けて必ず実行される処理。 危険コマンド拒否、フォーマット等。 settings.json 制御 permissions / 環境変数 / hooks 接続。 実行可能な範囲を外側から制御する。 -
CLAUDE.md と rules — 前提 vs 規約 「常時参照」と「条件付き適用」を分けて設計する CLAUDE.md 常時参照する最小限の前提
セッション開始時に読まれる。判断のベースだけを置く。 ✓ 書くべきもの • アーキテクチャ方針 • 基本的な設計原則 • 共通ルール • 利用頻度の高いコマンド ✗ 書かない • 詳細仕様(→ docs/) • 条件付き規約(→ rules/) • 長い手順(→ skills/) rules/ 繰り返し適用される規約 paths frontmatter で条件付き適用。トピック単位で分割。 ✓ 書くべきもの • 言語別コーディング規約 • API / スキーマ制約 • テストの書き方 • セキュリティ注意事項 ✗ 書かない • paths なしで全部置く (=常時ロードと同じ) • 長文の仕様書・手順書 -
skills と agents — 手順 vs 分業 「追加情報」ではなく「呼び出す単位」として設計する skills/ 再利用可能な作業ワークフロー
例: review-pr / release-check / incident-triage • SKILL.md の description で自動選択 • /skill-name で明示呼び出しも可能 • 1 skill = 1 目的 = 1 フロー ディレクトリ単位のパッケージ .claude/skills/review-pr/ ├─ SKILL.md ← エントリポイント ├─ examples/ ├─ template/ └─ scripts/ agents/ 独立した実行主体(subagent) 例: researcher / reviewer / fixer • 独自の context / prompt / tools / permissions • description に一致するタスクで自動委譲 • 1 agent = 1 役割 = 1 責務 決定的な違い skills は主会話の Claude に手順を追加するレイヤー。 agents は主会話とは別の独立した実行主体。 委譲すると context window が分かれる。 -
hooks と settings.json — 強制 vs 制御 推論とは独立に動く実行制御レイヤー — 文章指示ではなく仕組みで守らせる
hooks = いつ実行するか イベント単位で必ず処理を実行する。 主なイベント SessionStart / SessionEnd UserPromptSubmit PreToolUse / PostToolUse Stop / StopFailure 向いている用途 • 危険コマンドの拒否 • 自動フォーマット / lint • セキュリティ制約の強制 settings.json = 何を許可するか 静的に実行環境の境界を定義する。 扱うもの permissions(実行可能な操作) hooks の接続設定 環境変数 モデル設定 設計原則 • permissions は最小権限の原則 • settings.local.json に個人設定を分離 • 「動ける範囲」だけを定義する -
.claude 配下はどう読み込まれるか 配置しただけで全部が適用されるわけではない。適用条件 と 実行タイミング で挙動が決まる。 レイヤー 読み込まれ方 効き方 CLAUDE.md
セッション開始時に読まれるプロジェクト記憶 比較的強く効く rules paths / タスク内容に応じて条件的に適用 候補として存在 skills Claude が必要と判断、または /skill-name で呼び出し 候補として存在 agents 処理の分業が必要と判断されたときに利用 候補として存在 hooks イベントをトリガーに必ず実行(推論と独立) 確実に適用 settings permissions / hooks 接続で外側から制御 確実に適用 ※ 必ず守らせたい制約は hooks / settings へ寄せると安定する -
まとめ — 6つのレイヤーの設計方針 .claude は設定ファイルの集合ではなく、Claude をシステムとして設計する領域 前提 CLAUDE.md 常時参照する最小限の判断基準だけを置く 規約
rules paths で条件付き適用。トピック単位で分割 手順 skills 1 skill = 1 目的。呼び出し条件を明確に 分業 agents 独立した実行主体。責務と権限を絞る 強制 hooks 確実に実行したい処理を仕組みで担う 制御 settings.json 実行可能な範囲を最小権限で定義する 設計の鍵 各レイヤーの責務を意識し、「どこに書けば自然に効くか」で配置を判断する -
検証方法と評価軸 共通タスク: xRE グループ向け OKR Slack App を Claude Opus
4.6 4.7 を使って Go + Terraform で構築・AWS デプロイ baseline baseline リポジトリ • .claude/ は hooks のみ(最小構成) • rules / agents / docs なし • Claude Code 素の状態に近い • 初期コストほぼゼロ configured configured リポジトリ • .claude/ フル設計(rules + agents) • docs/guidelines/ 充実 • conventions.md で固有値を一元化 • 規約に沿った実装を誘導 評価軸 規約準拠度 命名・タグ・ディレクトリが conventions に沿っているか 完成度・動作 AWS 上で Slack コマンドが期待どおり動くか 工数・やり取り 指示回数 / 手戻り / 総所要時間 設計品質 責務分離・IAM 最小権限・State 分割などの妥当性 -
セッションサマリー 所要時間はほぼ同じ。コストは configured が +55%。その差分で何ができたかを次から見ていく 総コスト $206 baseline $320 configured
差分 +55% ターン数 31 baseline 27 configured 差分 −13% 実稼働時間 100分 baseline 105分 configured 差分 +5% 生成した文字量 642k baseline 892k configured 差分 +39% 並列で動いた作業者(サブエージェント)の数 baseline 5 / configured 10 configured は 1 ターンで 8 エージェントが 同時に動いた瞬間もあった プロンプトキャッシュのヒット率 baseline 97.5% / configured 95.8% どちらもほぼ上限。ルールは毎回読み直していない キャッシュで浮いた金額 baseline $1,079 / configured $1,475 もしキャッシュが効いていなければ baseline は $1,286、configured は $1,795 かかっていた Point ⚫ 時間はほぼ変わらない どちらも100分前後。「ルールを整えると遅くなる」は間違い ⚫ コスト差 $133 は投資 大半はコードが増えた分であり無駄遣いではない ⚫ configured は 1 ターンにまとめて動いた ルールやレビュー担当エージェントがあったので自律的に勧められた ⚫ コストが高い = 「悪」ではない 次スライド以降で「何が増えたか」「何が防げたか」をみていく -
コストの内訳:4 種類のトークン Claude API の課金は 4 種類に分かれる。Opus の単価を並べると「キャッシュ読み出し」だけ桁違いに安い 入力 input_tokens
単価(100万トークン当たり) $15 基準 Claude に今ターン新しく送ったテキ スト(指示文、コード、会話履歴の 差分など)。 出力 output_tokens 単価(100万トークン当たり) $75 入力の 5 倍 Claude が生成したテキスト(コー ド・説明・ツール呼び出し)。4種 の中で最も高い。 キャッシュ書き込み cache_creation_input_tokens 単価(100万トークン当たり) $18.75 入力の 1.25 倍 .claude/rules やガイドラインなど 「何度も使う大きな文脈」を初回に キャッシュへ書き込む時の料金。 キャッシュ読み出し cache_read_input_tokens 単価(100万トークン当たり) $1.50 入力の 1 / 10 2 ターン目以降、キャッシュ済みの 文脈を読み直す時の料金。桁違いに 安く、ここが節約の中心。 Pint 大きなルールを毎ターン普通に送ると入力 $15/1M の全額がかかる 一度キャッシュに入れると 1/10 の $1.50/1M で読める ─ 最大の節約ポイント 書き込みは 1.25 倍の $18.75 と割高だが、一度で済むのですぐ元が取れる ただし ─ キャッシュには有効期限がある TTL = 5 分 (デフォルト。1 時間のオプションあり) ターン間隔が 5 分を超えるとキャッシュは失効 次のターンで再び cache_creation(書き込み)が発生 最小 4,096 tokens 未満はキャッシュされない -
キャッシュ効果 キャッシュが効くことで 1 ターンあたり浮いているドル額 STEP 1 ─ configured が毎ターンキャッシュから読んでいるトークン数 109.29M
総 cache_read tokens ÷ 27 ターン数 = 4.05M tokens / ターン 1 ターンあたりキャッシュから読む量 STEP 2 ─ キャッシュから読むと 1/10 の値段 キャッシュなしで読むと $15.00 − cache_read 単価 $1.50 = 1M tokens あたりの節約 $13.50 STEP 3 ─ 掛け算すると 1 ターンあたりの節約額 4.05M tokens / ターン × $13.50 / 1M tokens = $54.64 / ターン ※ cache_read 単価は Claude Sonnet の公式料金(通常 input $15/1M、cache_read $1.50/1M)に基づく。4.05M tokens = configured 27 ターンの 総 cache_read 109.29M tokens ÷ 27 -
コストの中身 ─ $113 の差 コスト差 $113 の内訳 ─ 半分は「キャッシュ生成」、残りは「多く作った分」 何にいくらかかったか
費目 baseline configured 差分 input $0.02 $0.02 — cache_creation $38.39 $88.80 +$50.42 cache_read $119.94 $163.93 +$43.99 output $48.16 $66.90 +$18.74 合計 $206.50 $319.66 +$113.16 もしプロンプトキャッシュがなかったら 実際のコスト $206 $320 キャッシュなし推定 $1,286 $1,795 節約額 $1,079 (84%) $1,475 (82%) .claude の「キャッシュ生成」はいつ元が取れるか $50.42 準備にかかったキャッシュ生成コスト ルール・ガイドを最初に読ませる分 $54.64 1 ターンごとのキャッシュ効果 一度読ませたルールを毎回 1/10 の値段で読み返せる 0.92 ターン 何ターンで元が取れるか $50 ÷ $55 ─ 1ターン目の終わりにはもう黒字 ※ キャッシュの TTL は 5 分。ターン間隔が空くと失効し、次ターンで再キャッシュが発生(実測でも複数回観測) baseline configured -
作業の進み方 ─ 分散 vs 集中 同じ量の作業を、baseline は6ターンに分散、configured は1ターンで完結させた baseline(ルール整備なし) 大きな作業が
6 ターンに分かれた Turn 2 $37 Turn 3 $14 Turn 4 $40 Turn 7 $9 Turn 8 $20 Turn 9 $25 合計 $145 / 6 ターン configured(ルール整備あり) 同じ量の作業が 1 ターンに集中した Turn 2 $136 合計 $136 / 1 ターン(80 分・同時に 8 人並列) なぜ configured は 1 ターンで終えられたか 最初の一言で configured は「このアプリを作って、テスト用意して、レビューを動かして97点以上取って」と一括で依頼 レビュー担当(reviewer agent)が .claude に居た: ファイル作るたび自動でレビュー→修正→再レビューが回った つまり 「次はこれやって」と人が誘導する必要がなく、Claude が自分で最後まで進められた -
作ったコードの量と中身 configured は 40% 多いコードと 2.3 倍多い設定ファイルを作り、使い回し可能な部品も増やした Go のコード行数 +1,977
行(+40%) baseline 4,973 行 configured 6,950 行 Go ファイル数 +6 ファイル(+18%) baseline 33 configured 39 テストファイル数 +4 ファイル(+31%) baseline 13 configured 17 Terraform(AWS設定)ファイル数 +36 ファイル(+129%) baseline 28 configured 64 増えた分で、configured は何を作ったか 共通部品(slackclient) Slack操作の処理を1か所にまとめて、他のコ マンドからも使えるようにした Terraform の設定を細かく分割 backend / KMS / アラート / IAM など、baseline では省かれていた実運用向けの設定を追加 テストを全パッケージで充実 後で壊れたと気づくのではなく、最初から品 質を測れる状態に -
テストの手厚さ ─ 差が大きかった2か所 テストカバレッジで特に差が出た2か所を拡大 OKR を作るロジックの入口 okr-output/cmd baseline 0% configured
87% 差 +87 ポイント なぜ差がついたか baseline は AWS の本物と直接つながった書き方になっていて、テストが書 けなかった。configured は途中に「差し替え可能な口」を用意してあり、テ ストでは偽物を差し込める設計 Slack からの入り口 slack-app/cmd/api baseline 57% configured 88% 差 +31 ポイント なぜ差がついたか baseline は全機能が 1 ファイルに詰まっていて、まとめてしかテストできな かった。configured は役割ごとにファイルを分けていて、1 機能ずつテスト できる 教訓 ─ 「テストを追加して」では上がらない × 書き終わってから「カバレッジ低いからテスト足して」と言ってもコード構造が変わらず上がらない ◦ configured は最初から「テストできる書き方にする」ルールが .claude に入っていた → 1 回で書けた 後からやると数倍のコスト。上流でルール化しておくのが一番安い -
コードアウトプットの違い ─ 3つの実例 ① Slack からのリクエストが本物かの検証 baseline 40 行。エラー種類 2つ。テスト補助もなく、ガイドへの参照なし
configured 90 行。エラー種類 4つに細分化。定数で意図を明示。 テスト用の補助関数を用意。ガイド §2.2 への参照コメ ント付き → configured は「5分以内のずれまで許容」「定時間で比較」といった運用上の要点がルールから自動で反映された ② AI(Bedrock)呼び出しの処理 baseline 旧式のランダム関数を使用。使ったトークン数を返さない。 入力チェックなし configured 新しい標準ライブラリに更新。返値に使ったトークン 数を含む。入力を最初に検証する → 「使ったトークン数」は後でコスト計算やログ集計に必須。baseline では欠落していて運用時に困る ③ AWS の設定ファイル(Terraform) baseline 4 ファイル。設定の保存先はローカル(チームで共有不可)。 暗号化は AWS 任せ。監視なし configured 12 ファイル。設定の保存先は S3(チーム共有可)。自 前の暗号鍵。CloudWatch アラーム。Slack App 設定の自 動生成 → ガイド(terraform-guide.md や bedrock-iac-guide.md)の規約が .claude/rules/ 経由で自動適用された結果 -
事例: baseline での命名ミスとやり直し baseline 側で発生した 1 件の具体例。.claude がないと「見えないコスト」が発生する Turn 19
で発覚 「なんで別のリポジトリ用の名前になってるの? こっちは baseline なんだけど」 AWS に作られたリソース名が、別リポジトリ(configured 側)の名前に なっていた。 Claude が文脈から「それらしい名前」を補完してしまった結果 → terraform destroy(全部削除)→ 名前変更 → 再作成 のやり直しが必要に かかったコスト 直接かかった分(Turn 19〜22) Turn 19 原因調査 $0.32 Turn 20 コード修正 $1.25 Turn 21 確認 $0.59 Turn 22 追加修正 $0.47 直接コスト合計 $2.62 + 見えないコスト: AWSリソース全削除&再作成/S3 に残ったファイルの手動削除 /Slack トークン再登録/待ち時間 configured で起きなかった理由 別リポジトリの conventions.md に「AWS リソース名は <prefix>-◯◯-<env> にする」と書いてあった rules/terraform.md に「.tf ファイルを書くときはこのルールに従う」と指定されていた つまり Claude は「推測」ではなく「確認」で命名を決められた ─ ミスが起きる余地がなかった プロンプトに書くだけでは会話が進むと忘れる。ルールとして永続化することが効く -
評価軸 4つの評価軸ごとのまとめ。コストは baseline、それ以外は configured が優勢 baseline 優勢 A. 開発コスト baseline
が −35%($206 vs $320) やり取りの回数 36 vs 27 完成までの時間 100分 vs 105分 総コスト $206 vs $320 キャッシュなし換算 $1,286 vs $1,795 configured 優勢 B. コードの品質 configured がカバレッジで大差 go vet エラー 0 vs 0 テスト通過率 100% vs 100% カバレッジ平均 約82% vs 約95% configured 優勢 C. 出力としての完成度 運用に必要な要素が configured だけ揃っている AI 呼び出し実装 ◦ vs ◦ 使ったトークン数の記録 なし vs あり 会話の継続(スレッド) ◦ vs ◦ Slack App 設定の自動生成 なし vs あり configured 優勢 D. 安定性・運用耐性 ルール違反ゼロ、本番向け設定も揃う 命名ミス 1件(やり直し) vs 0件 設定ファイルの置き場 ローカル vs S3で共有可 暗号化(KMS) AWS管理キー vs 自前キー CloudWatch アラーム なし vs あり -
ルール整備のコストは 1 ターンで元が取れる 発見 ① 「最初に整備する手間がもったいない」と思いきや、1 ターン目から元は取れている 投資回収の計算 $50.42 最初に払う「準備コスト」
ルールやガイドを最初に読ませる分 $54.64 1 ターンごとにキャッシュによって浮く節約額 2 回目以降は 1/10 の値段で読み返せるため 0.92 ターン 回収までにかかるターン数 $50.42 ÷ $54.64。Turn 1 が終わる前に元が取れる計算 なぜ安くなるのか Claude には、一度読んだ長い資料を 1/10 の価格で読み返せる仕組み(プロンプトキャッシュ)がある。 .claude にルールを書いておくと、最初の 1 ターンで「書き込み」、以降は格安で「読み返し」が続く。 ルールが大きいほど読み返しの節約が効くので、きちんと整備した方が長く見ると得になる。 気をつけたい点 読み返しの割引が効くのは 5 分間だけ。ターンの間隔が空くと、また最初から読み込み直しになる(実際のセッションでも何度か起きていた) 会話が長いほど節約は効く。短いセッションだと元を取りきれないこともある セッションを細切れにせず、できるだけ続けて進めた方が結果的に安く済む -
コストが1ヶ所に集まるのは「設計が効いた」証拠 発見 ② 「コストが1ターンに集中している」=Claude が自分で判断して最後まで進められた証拠 コストの「偏り具合」 baseline 37% Top 2
ターンで $77 configured 79% Top 2 ターンで $251 上位2ターンがセッション全体コストに占める割合 どう読むか 偏りが大きい(configured) 一度の指示で大仕事を最後までやり切れた。人が途中で誘導していない 偏りが小さい(baseline) 人が「次はこれ」「次はあれ」と毎回舵を取っていた 同じ量の仕事・結果でも コストの「形」が、自律性の度合いを映している 「制御を手放す」ということとのトレードオフでもある configured の Turn 2 は 1 ターンで $136、80 分かかった。途中で止めたくても、進捗が見えにくい baseline のように小刻みに進めれば、途中で「思っていたのと違う」と気づいて方向転換しやすい 自律性(速い・安い)と制御性(安全・読みやすい)はトレードオフ プロジェクトの性質によって使い分け。新規作成は configured 型、未知の探索は baseline 型が向く -
Claude の「それっぽい推測」は制御できる 発見 ③ Claude は書かれていないことを「それっぽく」埋める傾向がある。その方向を決めるのがルール .claude なし(baseline) Claude が「それらしい名前」を自分で推測
1 周辺のコード・他のリポジトリを参照 2 「よくある名前」を自分で決める 3 書いた本人(Claude)は間違いに気づかない 4 問題が発覚するのは後工程(運用・デプロイ) .claude あり(configured) Claude が「書かれたルール」を読んで確認 1 conventions.md に命名規則を明記 2 rules/terraform.md に「.tf 書く時は従え」と指定 3 対象ファイルを書くたびに自動で参照される 4 「推測」ではなく「確認」で命名を決められる 「プロンプトに書く」では解決しない理由 プロンプト(指示文)は会話が進むほど履歴の奥に押し込まれ、効き目が薄くなる rules/ に「どのファイルを書く時に参照するか」を指定しておけば、対象を触るたびに必ず参照される つまり「一度言った」ではなく「必要なときに自動で目に入る」仕組みにすることが決定的 これが .claude の本質的な役割 ─ Claude の自由度を適切に制約すること -
レビュー担当(review agent)の効果 「ファイル作るたびにレビュー担当を呼び、97点以上になるまで直す」仕組みが効いた決定的な証拠 全ファイルをレビュー担当が採点した結果(100点満点) baseline(レビュー担当なし) 78.9 点 最低 58 点
/ 97点以上は 0 ファイル configured(レビュー担当あり) 98.95 点 最低 98 点 / 22 ファイル全てが 97 点以上(100点は 10 ファイル) 平均 +20.05 点 指摘された問題の件数(深刻度別) Critical 致命的(設計やり直しレベル) baseline 1 件 → configured 0 件 Major 重要(機能・安全性に影響) baseline 25 件 → configured 0 件 Minor 軽微(可読性・細部) baseline 35 件 → configured 12 件 特に効いたのは「知らないと書けない」類のチェック Slack の呼び出し回数制限(Rate Limit)への対応 ─ ガイドを読まないと必要性に気づかない 署名検証は定時間比較(hmac.Equal)で ─ 普通に書くとタイミング攻撃の穴ができる AI へのプロンプトにユーザー入力を混ぜる時の入力検証 ─ プロンプト乗っ取りの対策 エラーを _ で捨てない/gofmt の未準拠 ─ baseline は複数ファイルで横断的に発生していた -
なぜレビュー担当が効いたか 2つの仕組みが噛み合って機能した ─ 「根拠付き指摘」と「実装ループへの組み込み」 ①指摘には必ずガイドの参照が付く 個人の好みや文体ではなく、合意されたガイドラインに根ざす。議論にな らず、再現性がある 指摘の例(ガイド節番号付き) ・ §6.3
「エラーを _ で捨てない」 ・ §8.4 Slack の Rate Limit 対応が必要 ・ §2.2 署名検証は hmac.Equal(定時間比較) ・ §11.1 プロンプトへのユーザー入力はサニタイズ ②最初の一言に「97点取るまで」が入っていた 人が「次はこれ直して」と指示する必要がなく、Claude が自分で基準達成 までループできた 実装 レビュー 修正 97点以上 baseline は実装のみで完了扱い → 指摘が出る機会なく蓄積した 最初の一言の差(実際のプロンプト) baseline 「このアプリを作って」 configured 「このアプリを作って、テスト用意して、レビューを動かして 97 点以上取得して」 ただし限界もある ガイドに書かれていないこと(ビジネスロジックの正しさ、性能特性)は指摘できない configured にも Minor 12 件が残った(APIの名前非対称・コメント不足など、機能には影響しない軽微なもの) -
まとめ 「Claude を使う」から「Claude が動く環境を設計する」へ $113 多く払って、configured は何を得たのか +2,633 行のコード /
カバレッジ +13pt / Terraform +36ファイル(KMS・アラート・リモート state・Slack manifest) / 命名ミス 1件の回避 ① 準備コストは1ターンで元が取れる 設計した方が遅い・高いは誤解。 0.92 ター ン目に黒字化 ② コスト集中は設計が効いた証拠 Top 2 ターン比率 79% は、Claude が自律的に 動けた指標 ③ 「それっぽい推測」は制御できる プロンプトではなく rules/ で書くことが決 定的 実務への落とし込み 長く続く開発・複数人で触るコードベース → .claude を整備する投資が確実に回収される 単発の探索・プロトタイプ・使い捨て → ルール整備の手間は不要。最小限で十分 セッション設計: 大きな作業は 1 ターンでまとめる。無駄に会話を途切れさせない(キャッシュが切れる) ルールの書き方: 「paths: でどのファイルに適用するか」を指定。プロンプトに書くだけでは足りない -
ここから何をするか モデルは勝手に賢くなる。人が整えるのは「その手前」の部分。 ハーネスを育てる ─ モデルの力を引き出す側の仕事 AI は勝手に賢くなる。賢くなった AI に "何をやってほしいか"
を伝える器が、ハーネス。 01 必要なことを言語化する モデルがどれだけ賢くなっても、 「何をやりたいか/やるべきか」を決めるのは人 命名規則・設計方針・テスト基準・レビュー観点 ─ 暗黙知を書き起こし、ハーネスの形に押し込む 02 ハーネスを育てる rules・agents・guidelines を書き足していくたびに、 同じモデルから引き出せる力が上がる。 今回の検証では configured の初期投資 $50 が 1 ターン未満で 回収された。 育てるほどリターンが積み上がる資産。 モデルの進化を "自分たちの進化" に変えるのは、ハーネスを書ける人たち。 -
参考文献 / References 本資料で引用した Anthropic 公式ドキュメント 1 Prompt Caching https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
主な参照内容 cache_creation / cache_read の仕組み、TTL(5 分 / 1 時間オプション)、 価格倍率(入力の 1.25 倍・1/10 倍)、最小トークン閾値(Opus: 4,096 tokens) 参照スライド スライド 14「コストの内訳:4 種類のトークン」、15「コストの中身 ─ $113 の差は何か」、21「ルール整備のコストは 1 ターンで元が取れる」 2 Claude Code Agents https://docs.anthropic.com/en/docs/claude-code/agents 主な参照内容 .claude/agents/ によるカスタム subagent の定義、並列実行、tool アクセス制御。 「Main conversation compaction」「Auto-compaction」(コンテキスト ~95% での自動発火、CLAUDE_AUTOCOMPACT_PCT_OVERRIDE) 参照スライド スライド 22「コストが1ヶ所に集まるのは『設計が効いた』証拠」、23「見えない処理 ─ 43 秒で $115 の正体」 3 Claude Code Memory and Rules https://docs.anthropic.com/en/docs/claude-code/memory 主な参照内容 .claude/rules/ の paths スコープ(glob パターンによる対象ファイルへの自動適用)、CLAUDE.md の階層構造、チーム共有と個人設定の分離 参照スライド スライド 24「Claude の『それっぽい推測』は制御できる」 ※ 本資料中の数値(単価・TTL・課金項目)は上記の Anthropic 公式ドキュメントに基づく。 Claude Opus の料金体系(2026 年 4 月時点)を採用している。