그날 하루 동안 AI 코딩 도구를 쓰다가 낯선 말과 자꾸 마주쳤습니다. 처음 걸린 건 서브에이전트였습니다.
AI 코딩 도구가 "서브에이전트 실행 중"이라고 뜨는 이유
세션 버그의 원인이 될 만한 파일이 한둘이 아니었습니다. "이 프로젝트 전체에서 세션 관련 로직 다 찾아서 원인 좀 짚어줘"라고 시켰더니, 화면에 이런 줄이 떴습니다.
bash
1$ claude "세션 끊김 버그 원인 찾아줘"
2Launching subagent: code-reviewer (Explore)...
3Launching subagent: file-search (Explore)...
내가 부른 적도 없는 AI가 하나 더 켜졌다는 뜻인 줄 알고 순간 멈칫했습니다. 내가 통제 못 하는 뭔가가 마음대로 움직이는 건가 싶었습니다.
찾아보니 걱정할 일이 아니었습니다. 새로운 AI가 독립적으로 튀어나온 게 아니라, 지금 대화하고 있는 바로 그 에이전트가 "이 부분은 제가 직접 안 보고, 전담 조수에게 맡기겠습니다"라고 선언하는 것뿐이었습니다. 회사로 치면 상사가 모든 걸 직접 처리하지 않고 "이 부분은 검토팀에 넘기겠습니다"라고 말하는 것과 비슷합니다.
메인 에이전트가 하위 작업을 서브에이전트에게 위임하고, 결과만 돌려받는 구조
실제로 이 방식 덕을 봤습니다. 서브에이전트 없이 메인 대화 하나로 수백 개 파일을 전부 열어봤다면, 관련 없는 내용까지 대화 기억에 쌓이면서 정작 중요한 맥락은 뒤로 밀려났을 겁니다.
대신 "코드 리뷰팀"과 "파일 탐색팀"을 따로 굴려서 각자 결과만 가져오게 했습니다. 세 파일에 흩어져 있던 원인을 메인 대화가 지저분해지지 않은 채로 짚어낼 수 있었습니다.
원인을 찾아 코드를 고치고 커밋하려던 순간, 이번엔 AI가 아니라 시스템 자체가 제 발목을 잡았습니다.
저는 시크릿 키를 커밋하라고 시킨 적이 없었습니다. 그래서 AI가 오작동해서 없는 걸 있다고 우기는 줄 알았습니다.
화면을 다시 보니 답은 이미 로그 안에 찍혀 있었습니다. .husky/pre-commit이라는 이름이었습니다. 디버깅하면서 임시로 .env.local에 실제 AWS 키를 하나 넣어뒀던 걸 깜빡한 채였는데, 이걸 잡아낸 건 AI가 아니라, 팀 관리자가 예전에 "커밋하기 직전엔 반드시 이 검사를 돌려라"라고 미리 걸어둔 훅이었습니다. AI는 그 규칙을 그냥 따랐을 뿐입니다.
"커밋 직전"이라는 시점에 미리 걸어둔 훅이 자동으로 실행됩니다
현관문에 "나가기 전에 가스불 껐는지 확인"이라는 문구를 붙여두면 문을 열 때마다 자동으로 눈에 들어오는 것과 비슷합니다. 특정 행동 직전에 자동으로 실행되도록 미리 걸어둔 장치입니다.
이 훅이 없었다면 그 키는 그대로 원격 저장소에 올라갔을 겁니다. 나중에 알아챘어도 이미 히스토리에 남아버려서 키를 통째로 폐기하고 새로 발급받는 일이 생겼을 겁니다. 사람이 매번 기억하는 대신 판단 자체를 자동화해둔 덕분에, 실수 하나가 사고로 번지지 않았습니다.
시크릿 키를 새로 발급받고 나니 이미 자정이 넘었습니다. 이제 커밋 메시지까지 써야 한다는 생각에 진이 다 빠졌습니다.
매번 커밋 컨벤션 설명하기 지쳤다면, 슬래시 커맨드가 대신 기억해줍니다
옆에 있던 동료가 "그냥 /commit이라고만 쳐"라고 알려줬습니다.
bash
1> /commit
2→ diff 분석 중...
3→ fix(auth): 세션 만료 시 자동 로그아웃 처리
4→ Committed: a1b2c3d
처음엔 그냥 자주 쓰는 명령어를 줄여 부르는 단축키인 줄 알았습니다.
매번 반복 설명하는 대신, 팀 규칙을 명령어 하나에 미리 저장해둔 구조
나중에 알고 보니 훨씬 더 중요한 역할이 있었습니다. 이 팀은 커밋 메시지에 정해진 규칙(타입, 스코프, 한국어 설명)이 있었습니다. 그 규칙을 매번 프롬프트로 길게 설명할 필요가 없어졌습니다. 팀 규칙이 /commit 명령어 하나에 이미 박혀 있었으니까요.
식당에서 "늘 먹던 걸로"라고 말하면 메뉴판을 보지 않아도 서로 정확히 무엇을 시키는지 아는 것과 같습니다. 저 혼자 쓰는 단축키가 아니라, 팀 전체가 같은 규칙으로 작업하게 만드는 장치였다는 게 핵심입니다.
합류한 지 얼마 안 돼서 컨벤션 문서를 아직 다 못 읽은 상태였습니다. /commit만 쳤을 뿐인데 팀 규칙에 맞는 커밋 메시지가 그대로 나왔습니다. 온보딩 문서를 정독하는 대신, 명령어 하나가 그 문서 역할을 대신 해준 셈이었습니다.
그날 하루, 서브에이전트도 훅도 슬래시커맨드도 전부 "내가 모르는 사이에 뭔가 알아서 움직인다"는 느낌을 줬습니다.
그런데 셋 다 파고들어 보면 실체는 같았습니다. AI가 제멋대로 구는 게 아니라, 개발자 자신이든 팀이든 누군가 미리 정해둔 규칙과 역할 안에서 움직이고 있었을 뿐입니다.
자주 묻는 질문
서브에이전트를 여러 개 부르면 더 오래 걸리나요?
직관과 달리 오히려 빨라지는 경우가 많습니다. 여러 조수가 동시에 각자 맡은 파일을 뒤지기 때문에, 하나의 AI가 순서대로 다 열어보는 것보다 전체 작업 시간이 줄어듭니다. 다만 조수 숫자가 지나치게 많아지면 결과를 취합하는 데 걸리는 시간이 늘어날 수 있어서, 무조건 많이 부른다고 좋은 건 아닙니다.
훅은 제가 끌 수 있나요?
네, 대부분의 도구는 설정 파일에서 훅을 켜고 끌 수 있게 해둡니다. 다만 이번처럼 시크릿 유출을 막는 훅같이 안전과 직결된 것들은 팀 차원에서 강제해두는 경우가 많아서, 개인이 임의로 끄면 오히려 사고를 막을 마지막 장치를 스스로 없애는 셈이 될 수 있습니다.
슬래시커맨드는 아무나 만들 수 있나요?
네, 프로젝트마다 자기만의 명령어를 정의할 수 있습니다. 팀에서 반복되는 절차(커밋 규칙, 코드 리뷰 체크리스트, 배포 전 확인 사항)가 있다면 슬래시커맨드로 만들어두는 걸 추천합니다. 새로 합류한 사람에게 문서를 읽히는 대신, 명령어 하나로 그 절차를 대신 실행하게 할 수 있습니다.
AI 코딩 도구 용어 사전 연작의 1편입니다. 다음 편에서는 AI가 "권한을 요청합니다"라고 할 때 실제로 벌어지는 일을 다룹니다. 권한 프롬프트, <a href="/glossary/sandbox" class="glossary-link" title="외부 시스템과 격리된 안전한 가상 환경으로, AI가 생성한 코드를 안전하게 실행하여 보안 위협을 차단하거나 새로운 서비스를 법적·기술적 제약 없이 실험하는 독립된 테스트 공간입니다.">샌드박스</a>, 체크포인트, 워크트리 격리, 컨텍스트 소진을 차례로 살펴봅니다.
