Claude Code ハーネス Deep Dive – 君はどこまで制御する？ -

ハーネスは大事。坂東は...

Transcript

1. 社外秘X 2026/11/10 Claude Code ハーネス Deep Dive – 君はどこまで制御する︖ KDDIアジャイル開発センター 名古屋サテライトオフィス⻑ たかたに
2. 社外秘X
3. 社外秘X
4. 今⽇あったこと 社外秘X ﾖｯﾒ「この楽譜どうにか印刷できんかね︖」 ??? ??? コピー 禁⽌マーク ??? KDDI Agile Development Center Corporation 3
5. 今⽇あったこと 社外秘X ﾖｯﾒ「この楽譜どうにか印刷できんかね︖」 コピー禁⽌マークが あるから複製はやめ ましょう︕ ⾃分で⾳楽理論から 想像して楽譜を作り ます。 ??? コピー 禁⽌マーク ??? KDDI Agile Development Center Corporation 4
6. 今⽇あったこと 社外秘X ﾖｯﾒ「この楽譜どうにか印刷できんかね︖」 コピー禁⽌マークが あるから複製はやめ ましょう︕ ⾃分で⾳楽理論から 想像して楽譜を作り ます。 楽譜できまし たー︕︕︕ コピー 禁⽌マーク 楽譜できまし たー︕︕︕ KDDI Agile Development Center Corporation 5
7. LEARNING OUTCOMES 社外秘X この登壇で持ち帰れること 01 Claudeに⼈間のルールを理解させて働かせるには︖ 02 ルールを緩めるべきタイミング、判断基準は︖ 03 組織やチームに展開するには︖ KDDI Agile Development Center Corporation 6
8. なぜこの話をするか 社外秘X そろそろ、Claudeについて、偉い⼈から詰められる時期では︖ 「Claude Code、誰が何を ⼊れてるの︖」 「設定、全社でそろえたい。 セキュリティ⼤丈夫すか︖」 情シス 偉い⼈ KDDI Agile Development Center Corporation 現場のエンジニア 7
9. なぜこの話をするか 社外秘X そろそろ、Claudeについて、偉い⼈から詰められる時期では︖ 「Claude Code、誰が何を ⼊れてるの︖」 「設定、全社でそろえたい。 セキュリティ⼤丈夫すか︖」 「で、いくらかかってるの︖」 「効果は数字で出せる︖ 来年度予 算はどうするかね。」 情シス 偉い⼈ KDDI Agile Development Center Corporation 現場のエンジニア 8
10. なぜこの話をするか 社外秘X そろそろ、Claudeについて、偉い⼈から詰められる時期では︖ 「Claude Code、誰が何を ⼊れてるの︖」 「設定、全社でそろえたい。 セキュリティ⼤丈夫すか︖」 「で、いくらかかってるの︖」 「効果は数字で出せる︖ 来年度予 算はどうするかね。」 情シス 偉い⼈ KDDI Agile Development Center Corporation 「… よしなにします」 （⼩声） 現場のエンジニア 9
11. なぜこの話をするか 社外秘X 逃げても、いずれ聞かれるので、そろそろ理解しましょう。 俺らは、⾃由のために ⽴ち向かうしかない。 なんなら、聞かれる前に、答えを持 ってたい。 KDDI Agile Development Center Corporation 10
12. （エンジニア⽬線）ルールに縛られたくない 社外秘X ⼈によって与えるルールは異なるべきである 情シスに提案したい 標準ルート ショートカット 初めて使う⼈ 理解している熟練者 • ⼩さい機能から始める • 便利だから使わせたい。 • 確認多め・制限多め • 慣れたら段階的に緩める • 最初から緩めで渡す • 先駆者として試して欲しい。 • ただし交通ルール（deny）は共通 • ⾒守り（計測）は全員 ルールは全員を縛るためではなく、迷わない標準ルートを⽤意するためのもの。 KDDI Agile Development Center Corporation 11
13. （情シス⽬線）たとえ話 社外秘X ⼦どもが⾃転⾞に乗れるようになるまで / 買ってから… 01 02 03 04 05 転ばない環境で まず慣れる 危ない時は 横で⽌める ⾚は⽌まる ⾞道に出ない 少し離れて 後ろから⾒る 信頼して 好きに⾛らせる 三輪⾞/ ペダルなし 親が並⾛ ルール 理解 ⾒守る 任せる 「いきなり公道に放り 出す」のは怖い KDDI Agile Development Center Corporation 12
14. 主張 社外秘X Claude Codeも同じ 我流で覚えると、 変な癖がつく。そして暴⾛する。 だから、ルールを「仕組み」にして配りたい。 KDDI Agile Development Center Corporation 13
15. なぜ設定するのか 社外秘X 使う⼈の注意⼒に任せず、設定ファイルで「全員に・必ず・測れる形で」 効かせるため。 情シス向け 守る • 機密ファイルを読ませ ない • 危険コマンドを⽌める • 実⾏前の確認 → 仕組みで⽌める 偉い⼈向け ⾒る • 誰が・いつ使ったか • どの機能をどれだけ 使ったか • 費⽤はいくらかかった か → 観測し改善へ 開発者向け 揃える • モデル・権限を全員で共通 にする • 新しく⼊った⼈も同じ環境 で始められる → 品質のばらつきをなくす Claudeの設定ファイル「settings.json」 はこの3つを「コード化」 するための⼿段 KDDI Agile Development Center Corporation 14
16. でも、Claudeの設定とかって… 社外秘X 「全部同じじゃないですか・・・」 KDDI Agile Development Center Corporation 15
17. 社外秘X 2026/11/10 Claude Code ハーネス Deep Dive – 君はどこまで制御する︖ KDDIアジャイル開発センター 名古屋サテライトオフィス⻑ たかたに
18. 社外秘X 2026/11/10 Claude Code ハーネス Deep Dive – 君は「何を」「どこまで」制御する︖ KDDIアジャイル開発センター 名古屋サテライトオフィス⻑ たかたに
19. 今⽇の全体像 ／ 開発者の画⾯から⾒た構成 社外秘X ユーザーは指⽰を打つだけ。裏で⾊んな関⾨が働く Claude Code ~/kag/order-api > 開発者 指⽰を 打ち込む 設定ファイルを直して、mainにpushして PCに届くもの（配布） 管理コンソール • Read(.env) deny 機密ファイルは読めません • Edit(config/app.yaml) hook 編集後に⾃動で整形 • Bash(git push origin main) hook mainへの直接pushは禁⽌ managed を端末に配置 隔離された中で実⾏ GitHub • Bash(git switch -c fix/config) sandbox • Bash(gh pr create) ask 実⾏してよいですか︖ (y/n) Team／Ent・上書き不可 MDM・ファイル配布 テンプレート・プラグイン ✓ ブランチを切ってPRを作成しました（#128） statusLine Opus | $1.42 | fix/config | aws:dev 起動時に読み込まれる設定（上ほど強い） managed ＞ .claude/settings.json ＞ local ＞ ~/.claude ＋ CLAUDE.md ・ .mcp.json ・ .claude/hooks/*.sh KDDI Agile Development Center Corporation 18
20. 全体像 ／ 1回の指⽰の流れ 社外秘X 1回の指⽰で、各層はこの順に働く > リリース前の確認して $ claude ① Claude 起動 ② 指⽰を⼊⼒ ③ 考える ④ 道具を使う ⑤ 終わる ↻ 道具を使うたびに毎回 仕様駆動 プロセスの型 ⾃作Skills サブエージェント/MCP Plugins CLAUDE.md・rules ⼿順書 専⾨部署 道具箱 社内規程 hooks 関所 settings.json 法律 観測 CCoEが押さえる層 /speckit-* の 仕様→計画の コマンドで呼ぶ 順に進める ⽬次（名前と説明） 依頼と合えば だけ載る 本⽂を開く MCPサーバーに 部下に任せる 接続 外のツールを呼ぶ 中⾝をまとめて 読み込む ⽂脈に ⽅針として効く 読み込む SessionStart UserPrompt PreToolUse Submit PostToolUse 設定を合成 deny＞ask＞allow 管理設定が最優先 sandbox で囲う statusline が画⾯下に常に表⽰ 全層を横断 プロジェクトが育てる層 Stop ／ OTEL が各段階のイベントを送る サブエージェントの道具呼び出しも、④の関⾨を同じように通る KDDI Agile Development Center Corporation 19
21. Claude Code 統制・拡張の全体像 社外秘X 強い層はCCoE(情シス)が押さえ、弱い層はプロジェクトが育てる 整備すると嬉しいこと 強制⼒ 弱い 仕様駆動ワークフロー Spec Kit など ⾃作Skills ⼿順書 サブエージェント/MCP 専⾨部署 ⼿戻りが減り、出⼒が仕様に沿う 熟練者のやり⽅を、誰でも再現できる 専⾨作業を任せ、社内ツールへ 観測 OTEL statusline 全層を横断 Plugins 道具箱 CLAUDE.md・rules 強い プロセスの型 社内規程 ⼀発で環境が揃い、更新にも追従する 毎回の説明が要らず、出⼒が揃う hooks 関所 危険操作の検知・整形・通知が揃う settings.json deny・permissions・MCP許可 法律 安⼼して任せられ、許可確認も減る CCoEが押さえる層 守る プロジェクトが育てる層 使⽤量と効果を 説明できる KDDI Agile Development Center Corporation ⾒る 揃える 20
22. Claude Code 統制・拡張の全体像 社外秘X 強い層はCCoEが押さえ、弱い層はプロジェクトが育てる 整備すると嬉しいこと 仕様駆動ワークフロー Spec Kit など ⾃作Skills ⼿順書 サブエージェント/MCP 専⾨部署 ⼿戻りが減り、出⼒が仕様に沿う 熟練者のやり⽅を、誰でも再現できる 専⾨作業を任せ、社内ツールへ 観測 OTEL statusline 全層を横断 Plugins 道具箱 CLAUDE.md・rules ハー ネス プロセスの型 社内規程 ⼀発で環境が揃い、更新にも追従する 毎回の説明が要らず、出⼒が揃う hooks 関所 危険操作の検知・整形・通知が揃う settings.json deny・permissions・MCP許可 法律 安⼼して任せられ、許可確認も減る CCoEが押さえる層 守る プロジェクトが育てる層 使⽤量と効果を 説明できる KDDI Agile Development Center Corporation ⾒る 揃える 21
23. 統制・拡張の仕組み整理表 ③ 使い分けの原則 社外秘X 各設定のハーネスのユースケース 強制⼒ 弱い 強い 進め⽅そのもの 仕様駆動ワークフロー 再利⽤したい知恵・⼿順 ⾃作Skills 専⾨作業の切り出し サブエージェント 外部につなぐ権限 MCP（許可リストで統制） まとめて配りたいもの Plugins 守ってほしい⽅針・⽂脈 CLAUDE.md、rules 確率的 絶対に破らせたくないもの deny / permissions、hooks 決定的 守られているかの確認 観測（OTEL・statusline） 強制したいものは deny と hooks に寄せ、観測で逸脱を検知する。 情シスのみなさんはここに何が⼊るかをちゃんと考えてください・・・︕今⽇はこの話をします。 KDDI Agile Development Center Corporation 22
24. 社外秘X おまけ（優先度について） KDDI Agile Development Center Corporation 23
25. 設計の考え⽅ 社外秘X 設定の優先度の複雑性 同じキーを複数の場所に書いたとき、どのファイルが勝つのか︖ Managed 会社 managedsettings.json CLI ＞ その場だけ --settings local ＞ ⾃分×repo .claude/ settings.local. json project ＞ チーム（git） .claude/ settings.json user ＞ ⾃分（全PJ共通） ~/.claude/ settings.json 上書き不可 強い ◀──────────────────────────────────────────────▶ 弱い KDDI Agile Development Center Corporation 24
26. 設計の考え⽅ 強制⼒ 社外秘X Claudeが無視できるか 優先度 ぶつかったらどれが勝つか CLAUDE.md ＜ hooks ＜ settings.json Managed ＞ project ＞ user ＝ 何で縛るか（仕組みの種類）。前ページの縦軸 ＝ 誰が書くか（置き場所）。次ページで詳しく 優先度 強い ◀──────────────────────────▶ 弱い project チーム user ⾃分 全社の⽅針 チームの規約 ⾃分の好み hooks 全社の監査・検知 整形・テスト ⾃分への通知 settings.json 機密の deny MCP 許可リスト チームの権限 ⾃分の許可 Managed 会社 CLAUDE.md お願い 関所 法律 強制⼒ ▼ 強い KDDI Agile Development Center Corporation 25
27. なぜこの話をするか 社外秘X 情シスが 怖い… 「全社ルールにするンゴ。 Managedに全部⼊れる ねー」 「セキュリティ事故︖ なら、全部Managedに設 定⼊れよう」 「何もできないねぇ…」 情シス 偉い⼈ 現場のエンジニア KDDI Agile Development Center Corporation （⼩声） 26
28. 社外秘X 守る / ⾒る (仕組みで⽌める) KDDI Agile Development Center Corporation 27
29. Claude Code 統制・拡張の全体像 社外秘X 強い層はCCoEが押さえ、弱い層はプロジェクトが育てる 整備すると嬉しいこと 強制⼒ 弱い 仕様駆動ワークフロー Spec Kit など ⾃作Skills ⼿順書 サブエージェント/MCP 専⾨部署 ⼿戻りが減り、出⼒が仕様に沿う 熟練者のやり⽅を、誰でも再現できる 専⾨作業を任せ、社内ツールへ 観測 OTEL statusline 全層を横断 Plugins 道具箱 CLAUDE.md・rules 強い プロセスの型 社内規程 ⼀発で環境が揃い、更新にも追従する 毎回の説明が要らず、出⼒が揃う hooks 関所 危険操作の検知・整形・通知が揃う settings.json deny・permissions・MCP許可 法律 安⼼して任せられ、許可確認も減る CCoEが押さえる層 守る プロジェクトが育てる層 使⽤量と効果を 説明できる KDDI Agile Development Center Corporation ⾒る 揃える 28
30. 守る︓多層防御 社外秘X ガードレールは重ねて張る いろんな 箇所に 記載 setting. json に 記載 CLAUDE.md お願い 守ってほしい⽅針を伝える。無視されることもある permissions 規則 ツール呼び出しをパターンで許可・確認・拒否 hooks 判断 状況を⾒て⽌める・直す・記録する sandbox 隔離 OSレベルでBashの範囲を制限（Read等は対象外） OTEL・監査ログ 記録 すり抜けても、後から気づける KDDI Agile Development Center Corporation 29
31. 守る︓多層防御 社外秘X ガードレールは重ねて張る いろんな 箇所に 記載 setting. json に 記載 CLAUDE.md お願い 守ってほしい⽅針を伝える。無視されることもある permissions 規則 ツール呼び出しをパターンで許可・確認・拒否 hooks 判断 状況を⾒て⽌める・直す・記録する sandbox 隔離 OSレベルでBashの範囲を制限（Read等は対象外） OTEL・監査ログ 記録 すり抜けても、後から気づける KDDI Agile Development Center Corporation 30
32. setting.json記載イメージ 社外秘X { "permissions": { "defaultMode": "plan", "ask": ["Bash(git push:*)"], "disableBypassPermissionsMode": "disable" }, "sandbox": { "enabled": true } } KDDI Agile Development Center Corporation 31
33. 守る︓多層防御 社外秘X ガードレールは重ねて張る いろんな 箇所に 記載 setting. json に 記載 CLAUDE.md お願い 守ってほしい⽅針を伝える。無視されることもある permissions 規則 ツール呼び出しをパターンで許可・確認・拒否 hooks 判断 状況を⾒て⽌める・直す・記録する sandbox 隔離 OSレベルでBashの範囲を制限（Read等は対象外） OTEL・監査ログ 記録 すり抜けても、後から気づける KDDI Agile Development Center Corporation 32
34. permissions ／ 判定の流れ 社外秘X 上から順に照らし、最初に⼀致したもので決まる(⾃然⾔語の⽂字列確認) 判定（上から順に） Claude ① deny に⼀致︖ 結果 ⽌める 拒否 ルールの例（settings.json） Read(./.env) Bash(rm -rf:*) いいえ ② ask に⼀致︖ ⼈に聞く 確認 Bash(git push:*) いいえ ③ allow に⼀致︖ そのまま実⾏ Bash(npm run test:*) Edit(src/**) モードで決まる defaultMode 許可 いいえ どれにも⼀致しない 既定は初回に聞く （default / plan など） deny はどの階層に書いても最優先。Read・Grep などの読み取りは既定で通るので、機密は deny で塞ぐ。 KDDI Agile Development Center Corporation 33
35. deny ／ ⽬的︓守る 社外秘X denyは「何を守るか」から書く 機密を読ませない Read(./.env*) Read(~/.aws/**) Read(~/.ssh/**) 鍵が会話に⼊り、出⼒やログに漏れる 壊させない Bash(rm -rf:*) Bash(git push -force:*) Bash(git reset --hard:*) 作業内容や履歴の消失 持ち出させない Bash(curl:*) Bash(scp:*) 外部への送信、出所不明のスクリプト 取得 本番に触らせない Bash(terraform apply:*) Bash(kubectl delete:*) 本番環境の変更・停⽌ ルールを守らせる Edit(./.claude/**) AIが⾃分で制限を緩める Bash(wget:*) 書きすぎないこと。本当に守るものに絞り、残りはaskとhooksへ KDDI Agile Development Center Corporation 34
36. 守る︓多層防御 社外秘X ガードレールは重ねて張る いろんな 箇所に 記載 setting. json に 記載 CLAUDE.md お願い 守ってほしい⽅針を伝える。無視されることもある permissions 規則 ツール呼び出しをパターンで許可・確認・拒否 hooks 判断 状況を⾒て⽌める・直す・記録する sandbox 隔離 OSレベルでBashの範囲を制限（Read等は対象外） OTEL・監査ログ 記録 すり抜けても、後から気づける KDDI Agile Development Center Corporation 35
37. sandbox ／ ⽬的︓守る 社外秘X Bash の中⾝だけを、OSの箱で囲う Read / Edit / WebFetch Claude ツールを 使いたい permissions ⼊⼝の関所 Claudeが実⾏前に内容 を判断 Bash そのまま実⾏ sandbox の外。守りは permissions だけ sandbox npm install permissions OSの箱。Bash とその⼦プロセスを囲う curl python run.py … も中で動く 書き込み 作業・⼀時フォルダだけ 通信 許可ドメインだけ疎通許可を出す 読み込み denyRead で塞ぐ ⼊⼝の関所 OSが実⾏前に操作 を判断 最初、全部読んでるので、認証情報などには注意︕ ※ チームに必ず守らせたいルールとしてsandboxは展開すべきイメージ KDDI Agile Development Center Corporation 36
38. sandbox ／ 設定できること 社外秘X sandbox の設定⼀覧 キー（sandbox.〜） 何をする ⽬的 enabled sandboxを有効にする 守る autoAllowBashIfSandboxed sandbox内のBashは確認なしで実⾏（既定 true） 確認疲れを減らす filesystem.allowWrite ／ denyWrite 書き込める場所を⾜す・塞ぐ 壊させない filesystem.denyRead ／ allowRead 読ませない場所を指定する 機密を守る network.allowedDomains ／ deniedDomains 通信先を許可・拒否する 持ち出させない credentials 認証ファイルや環境変数を隠す 機密を守る excludedCommands sandboxの外で動かすコマンド 例外（最⼩限に） allowUnsandboxedCommands: false sandbox外での再実⾏を禁⽌する 抜け道を塞ぐ failIfUnavailable: true sandboxが使えなければ起動しない 黙って無防備にしない KDDI Agile Development Center Corporation 37
39. 守る︓多層防御 社外秘X ガードレールは重ねて張る いろんな 箇所に 記載 setting. json に 記載 CLAUDE.md お願い 守ってほしい⽅針を伝える。無視されることもある permissions 規則 ツール呼び出しをパターンで許可・確認・拒否 hooks 判断 状況を⾒て⽌める・直す・記録する sandbox 隔離 OSレベルでBashの範囲を制限（Read等は対象外） OTEL・監査ログ 記録 すり抜けても、後から気づける KDDI Agile Development Center Corporation 38
40. hooks ／ ⽬的︓守る・揃える Claude 社外秘X Bash / Edit … ツールを使いたい hooks の中⾝ 打つ前に⽂字列を⾒る 直前︓PreToolUse ② 判断する 今の状況が JSON で届く 実⾏ Bash は sandbox の中 hooks 直後︓PostToolUse tool_input ③ 返す 条件は何でも書ける cwd ブランチや環境変数はスクリプトが⾃分で 調べる settings.json に登録する permissions ただのスクリプト（bash でも python でも）。決まったタイミングで⾃動で⾛る ① 受け取る tool_name hooks branch AWS_PROFILE exit 0 → そのまま通す exit 2 → ⽌めて、理由を返す 中⾝の検査 deny の⽂字列パターンでは書けない条件 理由は Claude に届き、読んでやり直す "PreToolUse": [{ "matcher": "Bash", "hooks": [{ "type": "command", "command": ".claude/hooks/guard-push.sh" }] }] KDDI Agile Development Center Corporation PreToolUse いつ⾛らせるか matcher どのツールのときか command 何を⾛らせるか 39
41. 03 ルール ／ ⽬的︓守る・揃える 社外秘X denyは「固定」、hooksは「判断」 deny hooks たとえ ⾚信号は⽌まる ⾬の⽇は⾃転⾞禁⽌ 判断⽅法 パターン⼀致 スクリプト（何でも書ける） 得意なこと いつでもダメなもの 状況次第でダメなもの、直す、記録 する 例 .envを読む、rm -rf mainでのpush、本番プロファイル でのaws 運⽤コスト JSONに1⾏ スクリプトの保守が必要 まずdenyで書く。denyで表現できないものだけhooksへ。 KDDI Agile Development Center Corporation 40
42. hooks ／ どのタイミングで、何のために 社外秘X hooksは「割り込むタイミング」で選ぶ イベント タイミング ⽬的 使いどころ SessionStart 開始時 揃える 規約や現在のブランチを最初に伝える UserPromptSub mit 指⽰した時 守る 貼り付けられた秘密情報を検知して⽌める （APIキーの貼り付けを⽌める） PreToolUse 実⾏前 守る 条件付きで実⾏をブロックする （編集したら⾃動で整形） PostToolUse 実⾏後 揃える・⾒ る ⾃動整形、テスト、監査ログ （ログは必ず残す） Notification 確認待ち 迷わせない デスクトップやSlackに通知 Stop 応答完了時 揃える テストが通るまで完了させない KDDI Agile Development Center Corporation 41
43. 守る︓多層防御 社外秘X ガードレールは重ねて張る いろんな 箇所に 記載 setting. json に 記載 CLAUDE.md お願い 守ってほしい⽅針を伝える。無視されることもある permissions 規則 ツール呼び出しをパターンで許可・確認・拒否 hooks 判断 状況を⾒て⽌める・直す・記録する sandbox 隔離 OSレベルでBashの範囲を制限（Read等は対象外） OTEL・監査ログ 記録 すり抜けても、後から気づける KDDI Agile Development Center Corporation 42
44. 観測 ̶ statusLine 社外秘X statusLineに「いま」の情報を全部出す。 settings.json › statusLine.command で毎ターン再描画 claude — ~/work/app > 本番前に settings.json の deny を⾒直して • 現在の permissions を読み込みます。 ⎿ Read .claude/settings.json (42 lines) • deny に rm -rf と curl | sh を⾜す案です。 > Opus 5.5 モデル名 Haiku Sonnet $ 3.42 累計コスト Opus ctx 62% コンテキスト 使⽤率 ブランチ・ 未コミット $3.42 / ⽬安 $10 請求書が届く前に使い すぎに気づける aws:kag-dev +128 −41 47m AWS_PROFI LE などの環境 変更⾏数・ 経過時間 kag-dev 80%で /compact 重いモデルのまま雑務 を続けていないか main •3 8割を超えたら、会話を 整理する合図 未コミット 3件 作業中のブランチと、 ⽚付け忘れが⾒える KDDI Agile Development Center Corporation いまここ personal 向き先の取り違えは、 そのまま事故になる +128 −41 47分 経過 1セッションの作業量と 、粘りすぎの⽬安 43
45. statusLine ／ 仕組み 社外秘X 危険な状態を検知したときは⽂字や⾊を変えれる︕ # .claude/statusline.sh in=$(cat) model=$(echo "$in" | jq -r '.model.display_name') cost=$(echo "$in" | jq -r '.cost.total_cost_usd') branch=$(git branch --show-current) prof=${AWS_PROFILE:-none} warn="" [[ $branch == main || $prof == prod ]] ¥ && warn="⚠ " printf "%s%s | ¥$%.2f | %s | aws:%s" ¥ "$warn" "$model" "$cost" "$branch" "$prof" 通常時 Opus | $0.84 | feat/login | aws:dev 危険な状態 ⚠ Opus | $3.10 | main | aws:prod 条件で⾊や記号を変えると、⾒落としにく い「警告灯」にもなる KDDI Agile Development Center Corporation 44
46. statusLine ／ 誰のために出すか 社外秘X 個⼈・チーム・組織で⾒る観点は様々。 個⼈ チーム 組織 コスト感覚を育てる 事故を未然に防ぐ 共通⾔語にする モデル・コスト・コンテキス ト使⽤率。「この作業にこの モデルは⾼い」が分かるよう になる ブランチ・未コミット・ AWS_PROFILE。危険な状態 では警告を出す 全員が同じ表⽰を⾒る。「コ ンテキスト8割だから区切ろう 」が通じるようになる KDDI Agile Development Center Corporation 45
47. 観測 ̶ OpenTelemetry 社外秘X OpenTelemetryで組織・チーム全体を⾒る 配る 使う "env": { "CLAUDE_CODE_ENABLE_TELEMETRY": 集めて⾒る Aさん 送信先︓開発チケット（ダッシュボード） > テストを直して 全チーム • 3 files changed team=app team=infra "1", "OTEL_METRICS_EXPORTER": "otlp", team=app "OTEL_LOGS_EXPORTER": "otlp", "OTEL_EXPORTER_OTLP_ENDPOINT": "[送信先︓開発チケット]", "OTEL_RESOURCE_ATTRIBUTES": 管理設定で全員に同じ値を配る 送信先とteam属性だけ案件ごとに変える 今⽇は console 出⼒で⼿元確認 セッション数・頻度 $128 /週 42 セッション Bさん コードの変更⾏数 +3,210 −1,045 > PRを作って • gh pr create "team=[チーム名]" } トークン量・コスト OTLP team=app コミット・PR数 Cさん > tf plan を確認 • Bash を許可しますか ツールの許可／拒否 EXPORTER=console 58 12 コミット PR 今⽇はここ 許可 86% 拒否 14% token.usage 1,204 cost.usage 0.42 session.count 1 拒否の多いツール＝設定の⾒直し候補 データが出ることを確認 team=infra KDDI Agile Development Center Corporation 46
48. 観測 ̶ チケットでの取り⽅ 社外秘X トークンとコストを、開発チケットに紐づけて 計測する環境を整える 開発チケッ ト 着⼿する Claudeが作 業 モブで進める MCP経由で 記録 チケット管理の MCP チケットに 残る トークン・コスト・ ⼿戻り ・チケット単位で、所要時間・トークン・Claude費が残る ・費⽤対効果を、チケットごとに出せる （成果サマリの元データ） ・⼿戻り率も、同じチケットに紐づけて取る
49. なぜ、トークンと手戻り率を取るのか 先⾏指標 遅⾏指標 トークン AIに、どれだけ任せたか トークンだけ⾒ると 使っただけで、成果が出ない （お⾦使ってるだけ） ⼿戻り率 対で⾒る 任せた結果、どれだけやり直したか ⼿戻り率だけ⾒ると AIを使わない⽅が、良く⾒える （⼈間がどれだけ正しいと判断） 偉い⼈「AIへの投資が成果につながっているかを、知りたい。AI適切に使ってるのかね︖」 我々「AIにこれだけ任せて、これだけ検査してます︕︕︕︕︕︕」 社外秘X
50. 守る︓多層防御 社外秘X ガードレールは重ねて張る いろんな 箇所に 記載 setting. json に 記載 CLAUDE.md お願い 守ってほしい⽅針を伝える。無視されることもある permissions 規則 ツール呼び出しをパターンで許可・確認・拒否 hooks 判断 状況を⾒て⽌める・直す・記録する sandbox 隔離 OSレベルでBashの範囲を制限（Read等は対象外） OTEL・監査ログ 記録 すり抜けても、後から気づける KDDI Agile Development Center Corporation 49
51. 揃える ̶ CLAUDE.md・rules 社外秘X CLAUDE.mdとrulesは、毎回読むルール 置き場所と、読まれるタイミング 起動時に必ず読む Claudeが受け取るもの 全員に配布・外 せない 組織 /Library/…/ClaudeCode/CLAUDE.md ⾃分 ~/.claude/CLAUDE.md ~/.claude/rules/*.md チーム ./CLAUDE.md チーム .claude/rules/testing.md テーマ別の細則 CLAUDE.local.md 個⼈メモ （gitignore） ⾃分×案件 全プロジェクト 共通の好み 構成・コマンド ・規約 コンテキスト（会話の最初） 組織のCLAUDE.md ⾃分のCLAUDE.md・rules ./CLAUDE.md rules/testing.md CLAUDE.local.md 読む順 • Edit src/api/user.ts 触ったときだけ読む 触った瞬間に、その分だけ追加 チーム .claude/rules/api.md paths: src/api/** APIのファイルを触ったら + rules/api.md（paths が⼀致） チーム src/billing/CLAUDE.md そのフォルダを触ったら 読むだけで、強制はしない 必ず⽌めたいことは hooks・settings の deny へ 1ファイル200⾏以内が⽬安 KDDI Agile Development Center Corporation 50
52. 揃える ̶ CLAUDE.md・rules 社外秘X Claude.mdの強制⼒は弱い 弱い ― お願い 強い ― ブロック 会話での指⽰ CLAUDE.md・ rules hooks settings の deny △ その場かぎり。 ◦ 毎回読む。 ◎ イベントで必ず実⾏。 ◎ 実⾏・接続そのものを 次の会話では消える 従うかはモデル次第 CLAUDE.md・rules に書くこと • ビルド・テストのコマンド • 命名・コーディング規約 • ディレクトリ構成と、それぞれの役割 • 「いつも X する」系の作法 破れても事故にならない ⽌められる 破られたら困る ものは右へ ブロック hooks・settings で縛ること • 秘密鍵や .env を読ませない • rm -rf・本番デプロイを⽌める 破れたら事故になる deny deny / hooks • 編集後に必ずフォーマッタを⾛らせる hooks • コミット前にテストを通す hooks KDDI Agile Development Center Corporation 51
53. 揃える ̶ CLAUDE.md・rules 社外秘X 書き⽅は「確かめられる具体さ」で短く CLAUDE.md と rules の型 CLAUDE.md 1ファイル200⾏以内 # 概要 - Next.js + TypeScript ## コマンド - 開発: npm run dev - テスト: npm test（コミット前） ## 規約 - インデントは2スペース - APIハンドラは src/api/handlers/ ## 詳細 @docs/architecture.md .claude/rules/api.md --効く範囲を絞る paths: - "src/api/**/*.ts" --1テーマ1ファイル # API の規約 - ⼊⼒はスキーマで検証 - エラーは共通形式で返す 指⽰は、確かめられる具体さで 書き⾜すのは、こんなとき • 「整形する」→ 「インデントは2スペース」 • 「テストする」→ 「コミット前に npm test を通す」 • 「整理する」→ 「APIハンドラは src/api/handlers/」 • 同じミスを2回された • 前回の会話でも同じ訂正を打った • 新しいメンバーにも同じ説明が要る KDDI Agile Development Center Corporation 52
54. （補⾜）揃える ̶ 中間消失（Lost in the Middle） 社外秘X ⽂脈が⻑いほど、真ん中から抜け落ちる 情報の位置と、使われやすさ Claude Code に当てはめると ここが抜ける 短い⽂脈 会話が短いとき 使われやすさ CLAUDE.md やり取り やり取り 最新の指⽰ 会話が⻑いとき CLAUDE.md ⻑い⽂脈 先頭 真ん中 最新の指⽰ 途中で決めた⽅針・途中で読んだファイルが抜けやすい 末尾 Liu et al. (2023) “Lost in the Middle” の傾向を模式化したイメージ CLAUDE.md ⾃体が⻑いとき（400⾏など） 冒頭 中盤のルール 末尾 中盤に書いたルールほど守られにくい CLAUDE.md は短く、要は先頭に 会話は区切る 重い調査は外に出す 200⾏以内。⼀部のファイルにしか効か ないルールは paths 付きの rules へ /compact で要約し、話題が変わったら /clear。CLAUDE.md は compact 後も 読み直される サブエージェントに任せて結果だけ受け 取る。statusLine の ctx% で膨らみを ⾒張る KDDI Agile Development Center Corporation 53
55. 社外秘X おまけ（配布について） KDDI Agile Development Center Corporation 54
56. 配布 社外秘X プランによって配布の仕⽅が異なり、個⼈プランだと⼀⼿間必要。 Team ／ Enterprise 個⼈プラン（Pro ／ Max） たとえ 道路交通法 家庭のルール 配り⽅ 管理コンソールから⼀括配布 gitで .claude/settings.json 強制⼒ 上書きできない 個⼈設定で緩められる 効く範囲 組織にログインした全員 そのリポジトリを使う⼈ 鍵になるもの 管理者の設計 ⽬的への納得感とPRレビュー claude-settings-template/ |-- .claude/ | |-- settings.json | |-- hooks/guard.sh | `-- statusline.sh |-- CLAUDE.md `-- README.md 個⼈プランの場合は README.md をつけて配ろう。。。 KDDI Agile Development Center Corporation 55
57. 社外秘X 揃える（配布について） KDDI Agile Development Center Corporation 56
58. Claude Code 統制・拡張の全体像 社外秘X 強い層はCCoEが押さえ、弱い層はプロジェクトが育てる 整備すると嬉しいこと 強制⼒ 弱い 仕様駆動ワークフロー Spec Kit など ⾃作Skills ⼿順書 サブエージェント/MCP 専⾨部署 ⼿戻りが減り、出⼒が仕様に沿う 熟練者のやり⽅を、誰でも再現できる 専⾨作業を任せ、社内ツールへ 観測 OTEL statusline 全層を横断 Plugins 道具箱 CLAUDE.md・rules 強い プロセスの型 社内規程 ⼀発で環境が揃い、更新にも追従する 毎回の説明が要らず、出⼒が揃う hooks 関所 危険操作の検知・整形・通知が揃う settings.json deny・permissions・MCP許可 法律 安⼼して任せられ、許可確認も減る CCoEが押さえる層 守る プロジェクトが育てる層 使⽤量と効果を 説明できる KDDI Agile Development Center Corporation ⾒る 揃える 57
59. 配るものを広げる ／ 整理︓Skill の⼊り⽅ 社外秘X Skill は⾃分で書いても、配られてもいい ⾃分で書く 社内で配る 外部から配られる Skill ＝ 必要なとき開く⼿順書 ⼊り⽅が違っても、呼ばれ⽅は同じ ⾃作の Skill plugin ＝ Skill を⼊れて配る箱 Spec Kit ＝ Skill の束（例） .claude/skills/ に SKILL.md を置くだけ 社内マーケットプレイスから⼊れる specify init で .claude/skills/ に⼊る /release-check /review-helper:review /speckit-specify /review /aws-guard:check /speckit-plan /deploy /speckit-tasks /speckit-implement KDDI Agile Development Center Corporation 58
60. 配るものを広げる ／ 整理︓Skill の⼊り⽅ 社外秘X Skill は⾃分で書いても、配られてもいい ⾃分で書く 社内で配る 外部から配られる Skill ＝ 必要なとき開く⼿順書 ⼊り⽅が違っても、呼ばれ⽅は同じ ⾃作の Skill plugin ＝ Skill を⼊れて配る箱 Spec Kit ＝ Skill の束（例） .claude/skills/ に SKILL.md を置くだけ 社内マーケットプレイスから⼊れる specify init で .claude/skills/ に⼊る /release-check /review-helper:review /speckit-specify /review /aws-guard:check /speckit-plan /deploy /speckit-tasks /speckit-implement KDDI Agile Development Center Corporation 59
61. 配るものを広げる ／ skills 社外秘X スキルの中⾝ 必要になった分だけ、⽂脈に読み込まれる .claude/skills/release-check/ ├ SKILL.md ├ reference.md └ scripts/check.sh いつも 呼ばれたら 必要なら ⽬次だけ載っている SKILL.md の本⽂ 参考資料を読む release-check 「リリース前の確認して」 本番リリース前の確認 review --- PRの差分をレビュー name: release-check description: 本番リリース前 の確認。「リリース前」で使う --- または /release-check reference.md 読む deploy ステージングへ反映 scripts/check.sh sdd 実⾏するだけ 仕様から作り始める … ↑ いつ使うか＝呼ばれる鍵 1. scripts/check.sh を実⾏ 毎回載るのは⽬次だけ。 たくさん⼊れても軽い 依頼と description が 合えば⾃動で開く 中⾝は⽂脈に⼊らない 2. 詳細は reference.md を⾒る 置き場所 ~/.claude/skills/ ⾃分 .claude/skills/ チーム KDDI Agile Development Center Corporation plugin に同梱 配布 60
62. 配るものを広げる ／ 整理︓Skill の⼊り⽅ 社外秘X Skill は⾃分で書いても、配られてもいい ⾃分で書く 社内で配る 外部から配られる Skill ＝ 必要なとき開く⼿順書 ⼊り⽅が違っても、呼ばれ⽅は同じ ⾃作の Skill plugin ＝ Skill を⼊れて配る箱 Spec Kit ＝ Skill の束（例） .claude/skills/ に SKILL.md を置くだけ 社内マーケットプレイスから⼊れる specify init で .claude/skills/ に⼊る /release-check /review-helper:review /speckit-specify /review /aws-guard:check /speckit-plan /deploy /speckit-tasks /speckit-implement KDDI Agile Development Center Corporation 61
63. 配るものを広げる ／ plugins 社外秘X ルールだけでなく「能⼒」も配れるplugins plugins ＝ 教習所の教材 マーケットプレイス うまく⾛る⽅法を、ひと箱にまとめて配る 例︓review-helper plugin.json "enabledPlugins": { 社内で使うプラグインを並べた棚 実体はGitHubリポジトリ1つ [org]/claude-plugins review-helper v1.4.0 aws-guard v0.9.2 spec-workflow v2.0.1 並びは marketplace.json に書く settings.json（git で共有） Skills Agents ⼿順書 専⾨の部下 Hooks MCP 関所 外の道具とつなぐ ばらばらに配らず、1つの単位でインストール・更新 KDDI Agile Development Center Corporation "review-helper@kag-tools" : true } Aさん /review-helper:review Bさん /review-helper:review Cさん /review-helper:review あなたの権限で動く。中⾝を⾒てから⼊れる 62
64. plugins ／ ⽬的︓統制する・⾒る 社外秘X 野良プラグインを防ぎ、使われ⽅を⾒る ⼊⼝を絞る 抜け道を塞ぐ 使われ⽅を⾒る strictKnownMarketplaces disableSideloadFlags 許可した配布元からしか⼊れ られない --plugin-dir などの直接読み 込みを拒否 plugin_installed plugin_loaded blockedMarketplaces enabledPlugins: false 危険な配布元を名指しで⽌め る 特定のプラグインだけを禁⽌ OTELのイベントで導⼊・読み 込みを記録。コストもプラグ イン別に⾒える ※ ⼊⼝の制限は管理設定（Team／Enterprise・MDM）でのみ使⽤可能 KDDI Agile Development Center Corporation 63
65. 配るものを広げる ／ 整理︓Skill の⼊り⽅ 社外秘X Skill は⾃分で書いても、配られてもいい ⾃分で書く 社内で配る 外部から配られる Skill ＝ 必要なとき開く⼿順書 ⼊り⽅が違っても、呼ばれ⽅は同じ ⾃作の Skill plugin ＝ Skill を⼊れて配る箱 Spec Kit ＝ Skill の束（例） .claude/skills/ に SKILL.md を置くだけ 社内マーケットプレイスから⼊れる specify init で .claude/skills/ に⼊る /release-check /review-helper:review /speckit-specify /review /aws-guard:check /speckit-plan /deploy /speckit-tasks /speckit-implement KDDI Agile Development Center Corporation 64
66. 配るものを広げる ／ ⽬的︓揃える 社外秘X 仕様駆動（Spec Kit）は、仕様を先に書いてから作らせる Claude Code のスキルとして⼊る .claude/skills/speckit-*/ $ specify init my-app --integration claude 原則 何を・なぜ どう作る 分解する 作る・確かめる プロジェクトで1回 技術は書かない 技術・構成 依存順のタスク Converged まで繰り返す /speckit-constitution /speckit-specify /speckit-plan /speckit-tasks /speckit-implement /speckit-clarify /speckit-checklist /speckit-analyze /speckit-converge constitution.md spec.md plan.md tasks.md コード ⼈がレビューして次へ ⼈がレビューして次へ ⼈がレビューして次へ ⼈がレビューして次へ ⼈がレビューして次へ 点線＝本番向けに⾜す品質ゲート（⼩さな機能なら省いてよい） KDDI Agile Development Center Corporation 65
67. Claude Code 統制・拡張の全体像 社外秘X 強い層はCCoEが押さえ、弱い層はプロジェクトが育てる 整備すると嬉しいこと 強制⼒ 弱い 仕様駆動ワークフロー Spec Kit など ⾃作Skills ⼿順書 サブエージェント/MCP 専⾨部署 ⼿戻りが減り、出⼒が仕様に沿う 熟練者のやり⽅を、誰でも再現できる 専⾨作業を任せ、社内ツールへ 観測 OTEL statusline 全層を横断 Plugins 道具箱 CLAUDE.md・rules 強い プロセスの型 社内規程 ⼀発で環境が揃い、更新にも追従する 毎回の説明が要らず、出⼒が揃う hooks 関所 危険操作の検知・整形・通知が揃う settings.json deny・permissions・MCP許可 法律 安⼼して任せられ、許可確認も減る CCoEが押さえる層 守る プロジェクトが育てる層 使⽤量と効果を 説明できる KDDI Agile Development Center Corporation ⾒る 揃える 66
68. 配るものを広げる ／ 整理︓Claude との関係 社外秘X サブエージェントは別の頭、MCP は外の⼿⾜ サブエージェント Claude（本体） 別の⽂脈の部下 メインの⽂脈に積まれるもの あなたとの会話 任せる Explore 調べ物担当 50ファイル読んでも、本体へは要約だけ CLAUDE.md 読んだファイル サブエージェントの報告（要約） code-reviewer レビュー担当 要約だけ 返す 差分を読み込み、指摘だけを返す MCP 外の道具とつなぐ⼝ MCP サーバーが道具を差し出す github GitHub slack Slack postgres DB Claude は道具の説明を読んで、 いつ・どれを使うか⾃分で選ぶ MCP の結果 道具として呼ぶ（サブエージェントからも呼べる） 積みすぎると、古い話を忘れる・遅くなる KDDI Agile Development Center Corporation 67
69. サブエージェント ／ ⽬的︓守る・統制する 社外秘X サブエージェントは「定義」と「設定」の2か所で縛る ① 定義 .claude/agents/researcher.md 効く範囲︓このエージェントだけ 道具は定義で絞る --- tools name: researcher 許可リスト。書かなければ、メインの道具をすべて引き継ぐ description: 調べ物担当。読むだけ MCP は既定で全部つながる tools: Read, Grep, Glob disallowedTools: mcp__* disallowedTools: mcp__* 外につなぐ必要のない役割は、MCP をまとめて外す model: sonnet maxTurns: 20 メインの禁⽌はそのまま効く --- ② 設定 .claude/settings.json 効く範囲︓メインもサブも全部 "permissions": { "deny": [ "Agent(deployer)", "Bash(git push *)" ] } permissions.deny deny と PreToolUse hook はサブエージェントにも効く。任せても抜け道にならな い 配るなら管理設定に置く managed .claude/agents/ 同名の定義に勝つ。plugin の agent は hooks・MCP・権限モードを持てない ※ tools は定義ファイル専⽤。settings.json では permissions で書く ※ 旧名の Task(...) も Agent(...) の別名として効く KDDI Agile Development Center Corporation 68
70. 社外秘X まとめ KDDI Agile Development Center Corporation 69
71. まとめ 社外秘X なんかいっぱいClaudeにルールを付与できる KDDI Agile Development Center Corporation 70
72. まとめ 社外秘X なんかいっぱいClaudeにルールを付与できる 社内ルールが整備されそうになったら、 どこに何が置かれてるか把握しよう︕︕︕ KDDI Agile Development Center Corporation 71
73. まとめ 社外秘X なんかいっぱいClaudeにルールを付与できる 社内ルールが整備されそうになったら、 どこに何が置かれてるか把握しよう︕︕︕ 監視機能も⼊れて費⽤対効果は測ろう︕︕︕ KDDI Agile Development Center Corporation 72
74. なぜこの話をするか 社外秘X 偉い⼈から詰められたら・・・︖ 「Claude Code、誰が何を ⼊れてるの︖」 「設定、全社でそろえたい。 セキュリティ⼤丈夫すか︖」 「で、いくらかかってるの︖」 「効果は数字で出せる︖ 来年度予 算はどうするかね。」 情シス 偉い⼈ KDDI Agile Development Center Corporation 「…」 （⼩声） 現場のエンジニア 73
75. なぜこの話をするか 社外秘X ドヤ顔していきましょう Claude.mdとかでちゃんと守ってるから 情シスさんはdenyとhooksではここまで ルールにしよ。 Statuslineやenvで効果は取れてるよ。 来期も予算取り、たのんまっせ︕︕︕ KDDI Agile Development Center Corporation 74
76. まとめ 社外秘X 外すタイミングは、利⽤者の声やデータで決める。 • まず縛る。deny・hooks・sandbox を配る • ⾛りを⾒る。statusLine と OTEL で材料を集める • 緩めて、⾛り⽅を配る。Skill や plugin でそろえる KDDI Agile Development Center Corporation 75
77. Be a Change Leader. アジャイルに⼒を与え 共に成⻑し続ける社会を創る