2026년 4월 19일 | 개발 깨알 상식_Tips
Vercel Plugin 같은 코딩 에이전트 플러그인을 볼 때 내가 먼저 여는 파일은 README보다 hooks.json이다. 설치 명령은 한 줄로 끝나고 README 요약도 친절하지만, 실제로 어떤 이벤트에서 무엇이 실행되는지는 결국 훅 파일에 적혀 있기 때문이다. 플러그인은 겉으로 보기엔 "컨텍스트와 스킬을 더해 주는 확장"처럼 보여도, 세션 시작 시점에 명령을 실행하고 문맥을 주입하는 레이어이기도 하다.
오늘 팁은 단순하다. 플러그인 기능표를 읽기 전에 hooks.json에서 trigger surface를 먼저 확인하는 편이 낫다. 특히 언제 실행되는지, 무슨 파일이나 규칙을 주입하는지, telemetry 기본값이 어디까지인지를 먼저 보면 설치 뒤의 체감이 훨씬 덜 어수선하다. 나는 최근 Vercel Plugin README와 실제 훅 파일을 같이 보면서 이 차이가 꽤 선명하게 느껴졌다.
Figure 1. 설치 직후 내가 바로 확인하는 순서는 README 요약보다 hooks.json, matcher, telemetry 기본값 쪽이다.
이 그림처럼 보는 이유는 간단하다. 플러그인 설치에서 진짜 중요한 건 "무엇을 도와준다"보다 내 세션에 언제 들어오느냐다. 같은 플러그인이라도 session start에만 개입하는지, prompt 제출이나 tool use 단계까지 넓게 붙는지에 따라 체감 범위가 꽤 달라진다.
1. README보다 hooks.json을 먼저 보는 이유
현재 README는 이 플러그인이 Vercel context, skills, lightweight default hook profile을 설치한다고 설명한다. 여기서 내가 바로 다음으로 넘기는 파일이 hooks/hooks.json이다. README는 제품이 말하는 요약이고, 훅 파일은 실제 동작 표면에 가깝다. 플러그인을 여러 개 붙여 쓰는 환경에서는 이 차이를 먼저 봐야 충돌이나 과한 주입을 빨리 감지할 수 있다.
- matcher: 어느 세션 상태에서 실행되는지
- hooks: 실제로 어떤 명령이 호출되는지
- 주입 대상: 스킬, 프로파일러, 프로젝트 규칙 파일처럼 무엇이 들어오는지
2. 지금 보이는 기본 범위는 SessionStart 4개다
지금 공개된 훅 파일을 보면 기본 진입점은 생각보다 좁다. 핵심은 SessionStart 아래의 startup|resume|clear|compact matcher다. 새 세션 시작, 재개, 정리, compaction처럼 세션 상태가 바뀌는 순간에만 관련 명령이 붙는 구조다. 적어도 현재 기본 프로필 기준으로는, 예전처럼 막연히 prompt나 tool call 전부를 건드릴 거라고 넘겨짚지 않는 편이 정확하다.
"SessionStart": [
{
"matcher": "startup|resume|clear|compact",
"hooks": [
"session-start-seen-skills",
"session-start-profiler",
"inject-claude-md"
]
}
]나는 이런 식으로 trigger가 적힌 한 덩어리를 먼저 읽는다. 여기에 UserPromptSubmit이나 PreToolUse가 없으면 지금 기본 범위는 session-start 쪽이라는 뜻이고, 반대로 다음 버전에서 새 단계가 추가되면 그때부터는 세션 오염 가능성이나 latency 변화를 더 의식해서 봐야 한다.
3. telemetry는 문장 하나보다 기본값과 opt-out을 같이 봐야 한다
README의 telemetry 섹션에서 내가 좋게 본 점은 문장이 비교적 명확하다는 것이다. prompt text와 bash/tool-call telemetry는 수집하지 않는다고 적혀 있고, 기본값은 DAU-only session-start event 쪽으로 설명돼 있다. 다만 여기서 끝내면 반쪽이다. 실전에서는 항상 끄는 경로가 한 줄로 보이는지까지 같이 봐야 한다.
export VERCEL_PLUGIN_TELEMETRY=off내가 설치 메모에 남기는 최소 문장은 두 개다. 기본값이 무엇인지, 그리고 내 환경에서 끄려면 무엇을 넣는지. 플러그인 계층은 업데이트가 잦아서, README 한 번 읽고 기억으로 버티면 나중에 "분명 안 그랬던 것 같은데"가 자주 나온다.
4. 설치 전에 내가 보는 최소 체크리스트
- 첫째, hooks 파일에서 matcher가 어디에 걸리는지 본다.
- 둘째, session start에서 실제로 주입되는 파일 이름을 적어 둔다.
- 셋째, telemetry 기본값과 opt-out 환경변수를 같이 메모한다.
- 넷째, 업데이트 전후로 훅 범위가 달라졌는지 버전 메모를 남긴다.
이 네 줄만 해도 플러그인 설치 뒤 감으로 찝찝해하는 시간을 꽤 줄일 수 있다. README는 계속 읽되, 판단 기준은 실행 위치, 주입 범위, 기본 수집 정책 쪽에 두는 편이 낫다.
5. 오늘의 한 줄
Vercel Plugin을 예로 들면, 설치 전에 먼저 볼 건 화려한 소개 문구보다 hooks.json의 SessionStart 범위였다. 코딩 에이전트 플러그인을 붙일 때는 README만 읽고 끝내지 말고, 언제 실행되는지, 무엇을 주입하는지, telemetry를 어디서 끄는지를 한 번에 확인해 두는 쪽이 훨씬 실무적이다. 원문은 Vercel Plugin README와 hooks.json을 같이 보면 바로 감이 온다.