Claude Code hooks는 편리한 설정이 아니라 실행 경로로서 리뷰해야 한다

Claude Code의 hooks는 상당히 기분이 좋습니다.

PreToolUse로 위험한 command를 차단한다. PostToolUse로 edit 후에 lint나 test를 실행한다. 작업 종료 시에 summary를 남긴다. 이런 것들을 넣기 시작하면, agent workflow가 갑자기 "자신의 repo에 익숙해진 도구"처럼 느껴집니다.

다만, 여기서 한 번 제동을 걸어야 한다고 생각합니다.

hook은 편리한 설정이지만, repo에 넣는 순간 agent의 실행 경로(execution path)가 됩니다. 특히 frontend repo에서는 format, test, browser preview, MCP, design tool, issue tracker 등이 연결되기 쉽습니다. 약간의 자동화를 의도했을 뿐이지만, 팀원 전체의 agent가 통과하는 루트가 됩니다.

따라서, hooks와 MCP는 "작동하면 편리한 것"이 아니라 "review 할 수 있는 실행 경로"로 취급하는 것이 좋습니다.

hooks를 보면 이것저것 끼워 넣고 싶어집니다.

PreToolUse : tool 실행 전 -
PostToolUse : tool 실행 후 -
Notification : 알림이나 인간의 개입 포인트 -
Stop : agent의 작업 종료 시 -
SubagentStop : subagent의 작업 종료 시

처음부터 전부 사용할 필요는 없습니다.

저라면 우선 이 두 가지만으로 시작하겠습니다.

• PreToolUse로 위험한 shell command를 차단한다 -
• PostToolUse로 edit 후의 targeted check를 실행한다

예를 들어 frontend repo라면, 갑자기 모든 test를 매번 실행하기보다 변경된 file에 가까운 check부터 시작하는 것이 지속 가능합니다.

PreToolUse
- `rm -rf`
- `git reset --hard`
...

여기서 중요한 것은 완벽한 policy를 만드는 것이 아닙니다. agent가 지나가는 길을, reviewer가 읽을 수 있는 입도(granularity)로 만드는 것입니다.

Claude Code에는 project settings와 local settings의 분리가 있습니다.

team repo에서 보고 싶은 것은 대체로 이 구분입니다.

.claude/settings.json
team에서 공유하는 설정. review 대상.
.claude/settings.local.json
...

이것을 모호하게 만들면, 개인의 편리한 설정이 team의 실행 경로가 됩니다.

예를 들어, 자신의 machine에서는 통과하는 local path를 hook에 써버리는 경우입니다.

{
"hooks": {
"PostToolUse": [
...

이것은 project settings에 넣어서는 안 됩니다. CI에서도 다른 사람의 machine에서도 의미가 통하지 않습니다.

project settings에 두는 command는 repo 안에서 설명할 수 있는 것으로 맞춥니다.

{
"hooks": {
"PostToolUse": [
...

실제로는 조건을 더 좁힌다고 하더라도 생각하는 방식은 같습니다. team에서 공유하는 hook은 누구의 환경에서 실행되어도 의미를 알 수 있는 command로 만듭니다. local path, 개인 token, private MCP server는 local settings로 분리합니다.

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:
...

예를 들어 frontend의 layout 수정이라면, 다음과 같이 작성할 수 있습니다.

## Agent execution note
- MCP servers used: browser preview, issue context
- Readonly context: issue thread, local preview
...

이렇게 하면 리뷰어(reviewer)가 안심하기 쉽습니다.

반대로, 다음과 같은 PR은 긴장감을 높입니다.

## Agent execution note
- MCP servers used: browser preview, issue tracker
- Readonly context: issue thread
...

code의 diff가 작더라도, 외부 state에 쓸 수 있는 tool이 있다면 리뷰 대상은 넓어집니다.

처음에는 거창한 governance(거버넌스)보다, repo에 작은 checklist(체크리스트)를 두는 것이 더 효과적입니다.

## Agent execution path checklist
- Project settings committed:
- Local-only settings excluded:
...

작성 예시는 이 정도면 충분합니다.

## Agent execution path checklist
- Project settings committed: `.claude/settings.json`
- Local-only settings excluded: `.claude/settings.local.json`
...

이 checklist는 agent를 구속하기 위한 것만이 아닙니다. 나중에 사람이 읽을 수 있도록 하기 위한 것입니다.

"이 hook은 어떤 event(이벤트)에서 실행되는가?"

"이 MCP는 읽기 전용인가?"

"실패했을 때, 어디를 되돌려야 하는가?"

이 부분이 보이는 것만으로도, agent workflow(워크플로우)의 두려움은 상당히 줄어듭니다.

PostToolUse에 체크 사항을 너무 많이 집어넣는 것도 미묘한 문제입니다.

예를 들어 edit(편집)할 때마다 이것을 전부 실행한다면:

pnpm lint
pnpm test
pnpm build
...

그 마음은 이해하지만, 금방 무거워집니다. 무거운 hook은 무시되거나, local settings(로컬 설정)로 도망치거나, 아무도 건드리고 싶지 않은 설정이 되어버립니다.

frontend repo에서는 단계를 나누는 것이 사용하기 편합니다.

가벼운 hook
- format check
- lint
...

hook은 자동화의 입구입니다. 리뷰 전체의 대체재가 아닙니다.

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
...

이 정도라면 너무 무겁지 않습니다.

개인이 사용하는 hooks는 다소 거칠어도 괜찮습니다. 망가지면 스스로 고칠 수 있으니까요.

하지만 team repo(팀 저장소)에 commit(커밋)한 hooks는 다릅니다. agent가 어떤 tool을 호출하기 전에 멈추고, 어떤 tool 다음에 체크되며, 어떤 MCP를 사용하고, 어떤 log(로그)를 남기는가. 그것은 이미 workflow의 public API(공개 API)에 가깝습니다.

그래서 처음에 만들어야 하는 것은 거대한 agent platform(에이전트 플랫폼)이 아니라, 작은 execution path checklist(실행 경로 체크리스트)라고 생각합니다.

hooks는 편리합니다. MCP도 편리합니다.

편리하기 때문에, repo에 넣기 전에 딱 한 번만 검토하는 것이 좋습니다.

「이것은 설정인가, 아니면 실행 경로인가」

team에서 사용한다면, 대개 후자입니다.