Claude Code の hooks、かなり気持ちいいです。
PreToolUse で危ない command を止める。PostToolUse で edit 後に lint や test を走らせる。作業終了時に summary を残す。こういうのを入れ始めると、agent workflow が急に「自分の repo に馴染んだ道具」っぽくなります。
ただ、ここで一回ブレーキを踏んだ方がいいと思っています。
hook は便利設定ですが、repo に入れた瞬間に agent の実行経路になります。特に frontend repo では、format、test、browser preview、MCP、design tool、issue tracker などがつながりやすい。ちょっとした自動化のつもりが、team 全員の agent が通るルートになります。
なので、hooks と MCP は「動いたら便利」ではなく「review できる実行経路」として扱った方がいいです。
まず event を全部入れようとしない
hooks を見ると、いろいろ差し込みたくなります。
-
PreToolUse: tool 実行前 -
PostToolUse: tool 実行後 -
Notification: 通知や人間の介入ポイント -
Stop: agent の作業終了時 -
SubagentStop: subagent の作業終了時
最初から全部を使う必要はありません。
自分なら、まずこの 2 つだけで始めます。
-
PreToolUseで危ない shell command を止める -
PostToolUseで edit 後の targeted check を走らせる
たとえば frontend repo なら、いきなり全 test を毎回走らせるより、変更 file に近い check から始める方が続きます。
PreToolUse
- `rm -rf`
- `git reset --hard`
- `pnpm publish`
- `.env` を読む command
PostToolUse
- changed files を見る
- `pnpm lint` の対象を絞る
- component に近い test だけ走らせる
- 結果を stderr か log に残す
ここで大事なのは、完璧な policy を作ることではありません。agent が通る道を、reviewer が読める粒度にすることです。
project settings と local settings を混ぜない
Claude Code には project settings と local settings の分離があります。
team repo で見たいのは、だいたいこの線引きです。
.claude/settings.json
team で共有する設定。review 対象。
.claude/settings.local.json
個人環境の設定。commit しない。
これを曖昧にすると、個人の便利設定が team の実行経路になります。
たとえば、自分の machine では通る local path を hook に書いてしまう。
{
"hooks": {
"PostToolUse": [
{
"command": "/Users/me/bin/run-local-visual-check"
}
]
}
}
これは project settings に入れるべきではないです。CI でも他の人の machine でも意味が通りません。
project settings に置く command は、repo の中で説明できるものに寄せる。
{
"hooks": {
"PostToolUse": [
{
"command": "pnpm lint"
}
]
}
}
実際にはもっと条件を絞るとしても、考え方は同じです。team で共有する hook は、誰の環境で走っても意味がわかる command にする。local path、個人 token、private MCP server は local settings に逃がす。
MCP は「便利な context」ではなく write surface として見る
MCP は便利です。docs、issue、browser、database mock、design file みたいな context を agent に渡せる。
ただ、MCP server を増やすほど、agent の行動範囲も広がります。
readonly の docs context と、write できる issue tracker tool は別物です。browser preview を読むだけなのか、フォームを送信できるのかでも違います。filesystem に触れる MCP があるなら、もう code edit と同じ温度で review した方がいい。
PR template に、これくらいは残したいです。
## Agent execution note
- MCP servers used:
- Readonly context:
- Write-capable tools:
- External state touched:
- Human approval required for:
たとえば frontend の layout 修正なら、こう書けます。
## Agent execution note
- MCP servers used: browser preview, issue context
- Readonly context: issue thread, local preview
- Write-capable tools: none
- External state touched: none
- Human approval required for: package install, dependency upgrade, production deploy
これなら reviewer は安心しやすい。
逆に、こういう PR は温度を上げます。
## Agent execution note
- MCP servers used: browser preview, issue tracker
- Readonly context: issue thread
- Write-capable tools: issue comment writer
- External state touched: staging issue comment
- Human approval required for: not configured
code の diff が小さくても、外部 state に書ける tool があるなら review 対象は広がります。
frontend repo 用の最小 checklist
最初は大げさな governance より、repo に小さい checklist を置く方が効きます。
## Agent execution path checklist
- Project settings committed:
- Local-only settings excluded:
- Hook events used:
- Commands executed by hooks:
- MCP servers allowed:
- Write-capable tools:
- Logs left for review:
- Human approval required for:
- Rollback path:
記入例はこれくらいで十分です。
## Agent execution path checklist
- Project settings committed: `.claude/settings.json`
- Local-only settings excluded: `.claude/settings.local.json`
- Hook events used: `PreToolUse`, `PostToolUse`
- Commands executed by hooks: dangerous command blocker, `pnpm lint`
- MCP servers allowed: browser preview readonly, issue context readonly
- Write-capable tools: none by default
- Logs left for review: hook stderr, command result, changed files
- Human approval required for: package install, migration, external write
- Rollback path: revert one PR, no global config change
この checklist は、agent を縛るためだけのものではありません。あとで人間が読めるようにするためのものです。
「この hook は何の event で走るのか」
「この MCP は読むだけなのか」
「失敗したとき、どこを戻せばいいのか」
ここが見えるだけで、agent workflow の怖さはだいぶ下がります。
PostToolUse で全部解決しようとしない
PostToolUse に check を詰め込みすぎるのも微妙です。
たとえば edit のたびにこれを全部走らせる。
pnpm lint
pnpm test
pnpm build
pnpm playwright test
気持ちはわかるけど、すぐ重くなります。重い hook は無視されるか、local settings に逃げられるか、誰も触りたくない設定になります。
frontend repo では、段階を分けた方が使いやすいです。
軽い hook
- format check
- lint
- changed component の unit test
PR 前 checklist
- typecheck
- build
- 該当 route の Playwright
- mobile viewport screenshot
人間確認
- CSS selector scope
- visual regression
- browser-specific behavior
hook は自動化の入口です。review 全体の代替ではありません。
CODEOWNERS を .claude/** に置く
hooks、MCP、project settings は app code より危ないことがあります。
component の CSS を間違えると画面が崩れる。hook を間違えると、agent の作業経路が変わる。MCP の write tool を増やすと、repo の外に影響が出る。
なので、.claude/** や MCP config を CODEOWNERS に入れるのはかなり現実的です。
# .github/CODEOWNERS
.claude/** @frontend-platform-team
mcp.json @frontend-platform-team
PR checklist も少し足します。
## Agent config review
- [ ] New hook event is listed
- [ ] Command is repo-relative or documented
- [ ] Local-only values are not committed
- [ ] MCP server permission is readonly by default
- [ ] Write-capable tools require human approval
- [ ] Rollback path is one PR revert
これくらいなら、重すぎません。
hooks は agent workflow の public API になる
個人で使う hooks は、多少雑でもいいです。壊れたら自分で直せる。
でも team repo に commit した hooks は違います。agent がどの tool を呼ぶ前に止まり、どの tool の後で check され、どの MCP を使って、どの log を残すか。それはもう workflow の public API に近い。
だから、最初に作るべきなのは大きな agent platform ではなく、小さい execution path checklist だと思っています。
hooks は便利です。MCP も便利です。
便利だからこそ、repo に入れる前に一回だけ聞いた方がいい。
「これは設定か。それとも実行経路か」
team で使うなら、だいたい後者です。