## Intro - 바이브코딩 용어정리 두 번째! 두 번째 포스팅에서는 HOOKS, SubAgent(+ Claude Teams), Harness가 무엇인지에 대해 알아보도록 하자.🔥 > [!note] > - CLAUDE.md(=AGENTS.md) > - Slash Commands > - SKILLS > - HOOKS ✅ > - Subagent + Agent Teams ✅ > - Harness ✅ - 이번에도 개념 설명은 Claude Code 위주로 진행해본다.🧑🏻‍💻
# 1. HOOKS 🪝 - Hook이라는 개념은 옛날부터 있었지만 Agent에서 hook을 설정하고 사용한 것은 Claude Code가 원조다. 공식 문서에서 클로드는 훅을 아래와 같이 설명하고 있다. > "Claude Code 라이프사이클의 특정 지점에서 자동으로 실행되는 사용자 정의 셸 명령, HTTP 엔드포인트 또는 LLM 프롬프트입니다." - HOOK은 낚싯바늘, 갈고리처럼 "무언가가 지나가는 흐름을 낚아채는 것"을 뜻한다.🎣 어디서 뭘 낚냐면, 코드나 세션, AI 작업을 마쳤을 때 등의 **"특정 Event가 실행되기 전이나 후의 순간을 낚는다"**⚡️고 생각하면 된다. - 예를 들어, Agent가 '작업을 완료했으면 Slack으로 알림을 보내기'라던가, '코드를 새로 만들거나 수정이 끝나면 Lint 자동 확인 후 에러가 없을 때까지 고치기' 등등의 일들을 할 수 있다. - HOOK의 가장 큰 장점은 아무래도, > Skill과는 다르게 실행이 될 수도 있고 안될 수도 있는 확률적인 기술이 아니라,
**예외 없이 항상 실행을 강제할 수 있는. 결정론적인 세팅을 가능하게 해준다는 것**이다. 👍 - HOOKS는 26년 3월 현재 Claude Code가 원조인만큼 총 18개 이벤트에 대해 지원이 가능하고, (계속 늘어날 것 같다.) **Antigravity는 해당 기능이 불가능한 상태**다.😭 ~~일해라 구글🦹‍♂️!~~ - Gemini Cli, Cursor, OpenCode, Codex CLI 정도가 현재는 HOOK을 지원하기 시작했거나 지원하고 있다고 한다. ## HOOKS 종류 - Claude Code에서는 26년 3월 6일 현재 [공식 Docs](https://code.claude.com/docs/en/hooks-guide)에서는 아래의 Event를 포함한 총 18개 이벤트에 Hook을 설정할 수 있게 지원하고 있다.👀 아래는 자주 쓰는 5개 이벤트만 써봤다. | Event | When it fires | |---|---| | `PreToolUse` | 툴 호출이 실행되기 전. 차단 가능 | | `PostToolUse` | 툴 호출이 성공한 후 | | `PostToolUseFailure` | 툴 호출이 실패한 후 | | `Notification` | Claude Code가 알림을 보낼 때 | | `Stop` | Claude가 응답을 완료했을 때 | ## Hook 생성 방법 with example 📍 - Hook은 아래와 같이 .claude 폴더 아래에 `settings.json / settings.local.json` 파일을 생성하는 것으로 등록할 수 있다. Hook이 settings.json에서 사용하는 파일들을 `.claude/hooks` 폴더 하위에 Hook 별로 필요한 파일을 등록하는 식으로 설정한다. ![스크린샷 2026-03-07 오후 3.22.32](https://pub-08bdc1f395e14377951ac0c9c22ba795.r2.dev/posts/user_38T3Ty5uKeRndW9PUwTFHGYZxwP/g7tk8ms6qrj------------2026-03-07------3.22.32.webp) - 간단한 예시로 작업이 완료 됐을 때, 내 슬랙으로 작업 완료 알림을 보내게 설정하는 Hook은 아래와 같이 설정할 수 있다. 💬 `.claude/settings.json` ```json { "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "/Users/peter/Desktop/claude_project/.claude/hooks/slack-notify.sh '작업이 완료되었습니다.🧞‍♂️'", "timeout": 5 } ] } ] } } ``` - 위 예시를 설명하면 아래와 같다. > [!tip] > - Event - `STOP`: 작업이 끝났을 때를 Trigger로 사용. > - Type은 `command` > - Type은 Event의 종류에 따라 사용할 수 있는 Type이 정해져있다. [Docs 참고](https://code.claude.com/docs/en/hooks#prompt-based-hooks) > - command 내용은, .claude/hooks/notify-done.sh 를 bash로 실행하라는 내용. > - 그래서 실제로 `.claude/hooks/` 폴더 아래에 `notify-done.sh` 파일이 있어야 실행 가능. > - `timeout` - Slack에서 혹시 응답이 안되는 경우 무한정 기다리지 않도록 5초 타임아웃 설정. - notify-done.sh 파일은 "작업이 완료되었습니다.🧞‍♂️" 메세지를 Slack으로 보내는 코드가 적혀있고 hook에서 실행한다. - 결론적으로 파일 구조는 아래와 같이 생겼다.
![스크린샷 2026-03-07 오후 3.31.42](https://pub-08bdc1f395e14377951ac0c9c22ba795.r2.dev/posts/user_38T3Ty5uKeRndW9PUwTFHGYZxwP/molwcpya0xj------------2026-03-07------3.31.42.webp) ## matcher 🏐 - 사실 위 예시는 문제가 있다. 코드 수정을 하지 않고 그냥 대화만 해도 대화가 끝나면 STOP 이벤트가 발생하고 작동하기 때문이다. 쓸데없는 알림이 오지않고, 실제로 Agent가 코드를 수정/생성했을 때만 슬랙으로 메세지가 갈 수 있도록 `PostToolUse`을 하나 더 아래와 같이 추가해줬다. - 여기서 위 예시에서 언급되지 않은 개념이 있는데, 바로 [matcher](https://code.claude.com/docs/en/hooks#matcher-patterns)다. Matcher는 특정 상황에 해당될 때인지 한 단계 더 분별하여(=match시켜서) Hook을 동작하게 하는 필터역할을 한다. ```json { "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "/Users/peter/Desktop/claude_project/.claude/hooks/slack-notify.sh '작업이 완료되었습니다.🧞‍♂️'", "timeout": 5 } ] } ], "PostToolUse": [ { "matcher": "Write|Edit", # 👈 matcher! "hooks": [ { "type": "command", "command": "/Users/peter/Desktop/claude_project/.claude/hooks/mark-changed.sh", "timeout": 3 } ] } ] } } ``` - 이 Matcher는 사용하는 Event에 따라 적을 수 있는 옵션이 다 다르다. 각 이벤트마다 사용할 수 있는 matcher는 [여기를 참고](https://code.claude.com/docs/en/hooks#matcher-patterns)하자.📍 - 위의 PostToolUse 이벤트에 설정한 Hook은 코드가 생성되거나 수정된 상황. 즉, `Write|Edit` 일 때만 mark-changed.sh 스크립트를 실행시켜서 수정이 됐다 = 슬랙 알림을 보내라는 Flag를 심는 역할을 하게했다. 플래그가 없다면 코드의 수정이나 생성이 된 상황이 아니기 때문에 슬랙 메세지를 보내지 않을 것이다. - 맨 처음 작성한 Stop 이벤트 훅의 경우는 matcher가 아예 존재하지 않는데, 이와 같이 1. 아예 비어있거나, 2. `matcher: "*"` 3. `matcher: ""`
인 경우는 **모든 Stop** 상황에 항상 실행되게 설정한 것이다. - 아주 잘 된다. 😎✨ ![스크린샷 2026-03-07 오후 4.05.37](https://pub-08bdc1f395e14377951ac0c9c22ba795.r2.dev/posts/user_38T3Ty5uKeRndW9PUwTFHGYZxwP/zip7xxhwzcq------------2026-03-07------4.05.37.webp)
## 2. Subagent와 Agent Teams 🦸‍♂️ - Subagent, Agent team은 개념 위주로만 알아본다. ### Subagent 만들기 🤖 - Subagent는 메인 에이전트 혼자 하기엔 너무 크거나, 동시에 여러 건의 일을 처리해야 할 때 쓴다고 생각할 수 있다. 즉, 병렬로 일처리를 해서 빠르게 결과를 취합해서 보고자 할 때 유용하다. - 그래서 주로 메인 에이전트가 스스로 판단해서 Task를 나눠서 작업하지만, 좀 더 빠른 결과를 보기 위해서 명시적으로 아래 코드팩토리님처럼 "use 10 parrallel subgents to research independently as fast as possible" 써주면 좀 더 빠르게 Subagent들이 일을 나눠서 하고 메인 에이전트에게 결과를 전달하면 취합하면서 일이 끝나게 된다. ![스크린샷 2026-03-07 오후 9.08.36](https://pub-08bdc1f395e14377951ac0c9c22ba795.r2.dev/posts/user_38T3Ty5uKeRndW9PUwTFHGYZxwP/o4bl320jiy------------2026-03-07------9.08.36.webp) - 아래와 같이 Task가 여러개 생기는 것을 볼 수 있는데, 각각의 Task가 Subagent들이라고 생각하면 된다. - 실제로 속도가 병렬로 사용하는 Subagents 숫자와 선형적으로 빨라지는 느낌을 받을 수 있다. 아, 물론 같은 배속으로 토큰이 녹는 것도 느낄 수 있다.😉
![스크린샷 2026-03-07 오후 9.51.47](https://pub-08bdc1f395e14377951ac0c9c22ba795.r2.dev/posts/user_38T3Ty5uKeRndW9PUwTFHGYZxwP/ybgnmluhhk------------2026-03-07------9.51.47.webp) ### Custom Subagent 만들기 🪄 - 내 용도에 적합한 별도의 Subagent를 내가 따로 만들 수도 있다! 아래와 같이 `.claude/subagents` 폴더 아래에 에이전트의 이름으로 .md 파일을 생성해주기만 하면 된다! 생성한 뒤에 클로드 코드를 다시 재시작하면 사용할 수 있다. @Subagent-name 으로 따로 지정해서 대화를 하거나 명령을 내릴 수도 있다. ![스크린샷 2026-03-07 오후 9.31.30](https://pub-08bdc1f395e14377951ac0c9c22ba795.r2.dev/posts/user_38T3Ty5uKeRndW9PUwTFHGYZxwP/2tjnnki9kv2------------2026-03-07------9.31.30.webp) - 심지어 앞에 글에서 봤던 것처럼 Skill을 만드는 것과 형태가 매우 유사하다. Metadata(=Frontmatter)를 YAML형식으로 정해진 키워드로 작성해주고, Body는 markdown으로 작성해주면 된다. - Subagent도 name, description만 필수로 적어줘야하고, 어떤 모델을 사용할지, 어떤 툴/스킬/MCP를 사용할 수 있는지 등등을 더 많이 설정할 수 있는데, 더 자세한 내용은 [여기를 참고](https://code.claude.com/docs/en/sub-agents#supported-frontmatter-fields)하자. ✔ - Antigravity에서는 2026년 3월 현재, 개발 하면서 Chrome이 떠서 작동을 검사할 수 있는 Browser Agent가 사용할 수 있는 유일한 Subagent이고 OpenAI Codex에서는 Multi-agent라는 이름으로 사용할 수 있다고 한다. ### Agent Teams 🤝 - Agent Teams 기능도 현재는 Claude Code에서만 사용할 수 있다. Codex를 비롯한 다른 서비스들에서는 아직까지 Agent Teams 기능과 같은 기능은 현재 없다.🫢 - Subagent와 클로드 팀의 가장 큰 차이는 아래와 같다. ![subagents-vs-agent-teams-dark](https://pub-08bdc1f395e14377951ac0c9c22ba795.r2.dev/posts/user_38T3Ty5uKeRndW9PUwTFHGYZxwP/2onyboyl3t5-subagents-vs-agent-teams-dark.webp) - Subagent는 맡은 일을 다하고 메인 에이전트에게 결과를 돌려줄 뿐이지만, Agent Team은 Task List를 공유하고 각각의 Team mate들이 서로 이야기하고 의견을 주고받을 수 있다는 것이 가장 큰 차이다. - 좀 더 직관적인 예시를 들면, 게시판 기능을 만든다고 했을 때 Front - Back - DB 최소 3가지 영역의 에이전트가 필요하고, + Test & Lint 검증 에이전트까지 4개가 필요하다고 할 수 있다. - 이 상황일 때, **각각의 Agent는 서로가 만든 기능들이 서로 잘 동작하는지 서로의 상태를 체크해가면서 자신의 순서를 기다리면서 만들어야 한다.** 특히 모노레포라면 더 그럴 것이고 이 Claude Team 기능이 더 유용할 것이라 생각한다. ### Claude Team 활성화 방법📍 - Claude Team 활성화 방법은 간단하다. 내가 사용하고자 하는 환경 범위에 있는 `.claude/settings.json` 파일 아래에 아래와 같이 추가해주면 끝! ```json ... "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }, "teammatemode": "tmux" } ``` - teammatemode 옵션은 "tumx"와 "in-process" 두 가지 옵션이 있는데, team mate들이 Claude 코드에서 Terminal을 나눠서 각자 실행하는 것을 탭 방식으로 볼 것인지(in-process), 창을 tmux 방식으로 나눠서 볼 것인지 설정하는 것이다. - 활성화를 해 놨으면 Claude Code를 껏다가 재실행 하면, 예를 들어 **'4명 팀원으로 구성된 Team을 만들어서 실행해줘'**라는 명령만 해도 팀을 구성해서 작업하는 것을 볼 수가 있다. 실제 사용하면 어떻게 되는지 궁금한 분들은 코드팩토리님의 [영상](https://www.youtube.com/watch?v=Gb2VMWrUmZ0&t=647s)을 참고하시길.😊 ~~쓰기 힘들어서 그런건 아니고..~~
## 3. Harness Engineering? - 후, 드디어 마지막 키워드까지 왔다!🔥 `Harness`라는 키워드는 마구(馬具)에서 온 단어다. 말을 제어하는 고삐 + 안장 + 재갈 + 멍에 같은 장비들을 총칭하는 단어 되시겠다. - 그러니까, 사실 이 미쳐 날뛰는 AI Agent를 잘 다루지 못하면, 이녀석들은 미친듯이 이상향 방향으로 개발을 막 해버려서 결국에는 영화 터미네이터가 되어도 안이상하다는 것을 느낄 수 있는. 그런 특이점이 온 시대에 적절한 단어같기도 하다. - 그런 의미로 `Harness Engineering` = **강력하지만 제멋대로인 AI를 올바른 방향으로 제어하는 시스템을 설계하는 것**을 뜻한다. - 어떻게 설계를 하냐고? 우리가 두 번의 포스팅에 걸쳐 함께 살펴본, Commands, Skills, Hooks 등을 아주 엄밀하게 설계해서 Plugin을 만든다거나 하는 것이 2026년 3월 현재 말하고 있는 Harness Engineering의 의미라고 해석해도 무리는 없을 것 같다. ### Harness Plugin 추천 🔖 - 개인적으로 판단했을 때 추천하고 싶은 Harness들을 추천해본다. #### 1. [Superpowers](https://github.com/obra/superpowers) 💪 - 현재 Github Star가 73k를 기록하고 있는 엄청난 Harness다. - 개인적으로 가장 멋진 점은 TDD를 기반으로 코드를 작성하고 스스로 Test를 끝낼 수 있게 코딩을 하게 만드는 Harness라는 것.👀 너무 멋지다. TDD 기반 하네스는 아직 이것 말고 본 적이 없다. - Claude Code, Codex, Cursor, OpenCode 사용가능. #### 2. Oh-my-family 🏠 - 클로드 코드를 사용한다면 [Oh-my-Claudecode](https://yeachan-heo.github.io/oh-my-claudecode-website/)🔥, Codex를 사용한다면 [Oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex)🤖, OpenCode를 사용한다면 [Oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent)🪨를 추천한다. - 하나같이 잘 만들어진 Subagents과 Commands, Skills들이 빛나는 하네스다.✨ #### 3. [Ouroboros](https://github.com/Q00/ouroboros?tab=readme-ov-file) 🧘 - 사용자가 원하는 바의 본질을 소크라테스의 질문 방식으로 이끌어내고. Ambiguity나 Agent가 똑같은 질문을 헤어나오지 못하는 상태(Oscillation) 등을 수치로 표현하여 Agent가 아주 똑똑하게 일을하고 일을 멈추지 않고 제대로 일하게 하는 멋진 .. 반해버린 하네스..🫢 - Claude Code 전용.
## 마무리 🍳 - 너무나 많은 고수분들이 날뛰고(?) 있다. 특히 인문학적 통찰과 사유까지 깊어서,, 철학적인 생각을 코드로 구현하고 AI에게 적용할 수 있는 분들이 가장 큰 파워를 가진 시대가 되었다. 이런 분들은 물만난 물고기처럼 너무나 신나게 이 바이브코딩 시대를 즐기고 있는게 느껴진다. ~~너무 부러워서 화남😭~~ - 나같은 보통의 인간은 그 분들이 만들어내는 것들을 받아 써보기도 급급한 시대가 되어버렸지만, 그런 플러그인들과 스킬들. 즉, Harness Engineering이 어떻게 구성되어 있고, 어떤 설정을 어떻게 했는지 빠르게 이해하기 위해서라도 이정도 기본 지식은 필수인 시대라 생각이 된다. - 이제 기본적인 지식은 알았으니 각자의 용도에 맞게, 회사 팀만을 위한 Commands, Skills, Hooks 등등을 잘 엮어서 Harness를 구축할 수도 있을 것이다.😎

✨HAPPY BUILDING!👷‍♂️ ### References - [datacamp.com](https://www.datacamp.com/tutorial/claude-code-hooks) - [Claude Code Docs - Hooks](https://code.claude.com/docs/ko/hooks) - [코드팩토리](https://www.youtube.com/@codefactory_official)

Vibe Coding Terms - Part 2

0 comments