엄지

AI한테-일-시키는-시스템-구축기

23 min read

AI한테 일 시키는 법을 다듬게 된 계기, 그리고 지금 쓰고 있는 시스템들

Claude Code를 쓰기 시작한 지 꽤 됐습니다. 처음부터 잘 됐던 건 아니고, 초반에는 다른 분들과 비슷한 시행착오를 겪었더라고요. AI한테 “이 컴포넌트 리팩토링해줘”라고 하면 멀쩡한 코드를 뜯어고쳐서 빌드가 깨지고, “테스트 추가해줘”라고 하면 실제 로직과 관계없는 의미 없는 테스트를 양산하고. 같은 실수를 반복하는 것도 답답했거든요. 매일 새로운 인턴이 출근하는데 어제 배운 걸 하나도 기억 못 하는 느낌이랄까요.

그래서 하나씩 장치를 만들기 시작했습니다. CLAUDE.md에 프로젝트 규칙을 적고, hooks로 자동화를 걸고, 슬래시 커맨드로 반복 작업을 줄이고. 몇 달 정도 쓰다 보니 나름 돌아가는 체계가 잡혔습니다. 완벽하진 않았지만 “이 정도면 쓸 만하다” 싶은 수준까지는 왔더라고요.

YouTube 영상에서 시작된 정리

그러던 어느 날 YouTube에서 메이커 에반이라는 분의 영상을 봤습니다. “개발자가 AI 길들이는 데 6개월 걸린 이유”라는 제목이었는데, AI 코딩 도구를 효과적으로 쓰기 위한 4가지 시스템을 정리한 내용이었어요.

영상 자체도 괜찮았지만, 거기서 소개하는 Reddit 원글이 더 궁금해졌습니다. u/JokeGold5455라는 분이 쓴 “Claude Code is a Beast”라는 글이었는데, 6개월 동안 30만 줄 넘는 프로젝트에서 Claude Code를 실전 투입하면서 만든 시스템을 상세하게 공유한 글이었거든요. React 16에서 19로 올리고, MUI v4를 v7으로 마이그레이션하고, 테스트 커버리지를 0%에서 실질적인 수준까지 끌어올렸다고 했습니다.

이 글을 읽으면서 제 세팅과 비교해봤어요. 겹치는 부분이 꽤 있었습니다. CLAUDE.md 관리, 자동화 훅, 에이전트 분리 같은 건 저도 이미 비슷하게 하고 있었거든요. 근데 제가 체계적으로 못 하고 있던 부분도 보였습니다. 특히 작업 기억 관리랑 품질 게이트 쪽은 대충 넘기고 있었다는 걸 깨달았어요.

그래서 원글에서 영감을 받은 부분은 보완하고, 기존에 하던 것들은 더 다듬는 계기로 삼았습니다. 아래 내용은 메이커 에반 영상의 4가지 시스템 프레임을 빌려서 제가 실제로 쓰고 있는 구조를 정리한 겁니다.

시스템 1: 자동 매뉴얼 — “이 상황에선 이렇게 해”

문제

제가 일하는 프로젝트는 꽤 큰 모노레포입니다. Kotlin/Spring Boot 마이크로서비스, React Native 모바일 앱, Next.js 웹 앱이 한 저장소에 다 들어있어요. 백엔드를 고칠 때와 프론트엔드를 고칠 때 지켜야 하는 규칙이 완전히 다릅니다.

처음에는 CLAUDE.md 파일 하나에 모든 규칙을 때려넣었습니다. Kotlin은 Arrow Either를 이렇게 쓰고, React 컴포넌트는 이런 구조를 따르고, Terraform은 모듈을 이렇게 분리하고… 결국 1500줄짜리 괴물이 됐더라고요. 근데 웃긴 건, 이렇게 길어지니까 AI가 규칙을 무시하기 시작한 거예요. 사람도 100페이지짜리 매뉴얼을 안 읽듯이, AI도 지시가 너무 길면 중요한 부분을 놓치더라고요.

해결

Reddit 글의 저자도 CLAUDE.md가 1400줄까지 불어났다가 Skills라는 개념으로 분리했다고 했습니다. 저도 이미 비슷한 방향으로 가고 있었는데, 원글을 보고 좀 더 깔끔하게 정리했어요. 핵심 200줄만 CLAUDE.md에 남기고, 나머지는 별도 파일로 쪼갰습니다.

여기서 제가 좀 더 신경 쓴 부분이 있습니다. 이 파일들을 AI가 알아서 찾아 읽게 만든 거예요. skill-activator.mjs라는 훅을 하나 만들었는데, 하는 일은 단순합니다. 제가 프롬프트를 입력하면 AI가 실행되기 전에 이 훅이 먼저 돌면서 “이 사람이 지금 뭘 하려는 거지?” 분석을 합니다.

세 가지를 봅니다. 첫째, 키워드. “kotlin”이나 “spring”이 들어있으면 백엔드 관련입니다. “react”나 “component”가 들어있으면 프론트엔드고요. 둘째, 의도 패턴. “리팩토링해줘”와 “테스트 작성해줘”는 다른 스킬이 필요합니다. 셋째, 파일 경로. 백엔드 디렉토리 아래 파일을 건드리면 백엔드 규칙이 필요하고, 프론트엔드 디렉토리 아래면 프론트엔드 규칙이 필요하죠.

이 세 차원으로 매칭해서 필요한 스킬 파일을 AI한테 자동 주입합니다. 요리사 비유를 들자면, 손님이 “파스타 주세요”라고 하면 이탈리안 레시피북이 자동으로 열리고, “초밥 주세요”라고 하면 일식 레시피북이 열리는 거죠. 요리사가 모든 레시피를 외울 필요가 없는 겁니다.

결과

토큰 사용량이 꽤 줄었습니다. 근데 더 중요한 건 AI가 규칙을 확실히 더 잘 따르게 됐다는 점이에요. 한 번에 모든 걸 알려주는 대신, 지금 필요한 것만 정확히 알려주니까 집중도가 올라간 느낌이랄까요.

시스템 2: 작업 기억 — “어디까지 했더라”

문제

AI 코딩 도구의 치명적인 약점이 하나 있습니다. 기억을 못 한다는 거예요. 정확히는, 대화 컨텍스트가 길어지면 오래된 내용을 압축하거나 잘라냅니다. 아침에 “이 모듈을 이런 방향으로 리팩토링하자”고 합의해 놓고, 오후에 이어서 작업하면 아침에 뭘 했는지 모르는 거죠. 팀원이 퇴근할 때마다 기억을 리셋하고 출근하는 꼴입니다.

해결

Reddit 저자는 dev-docs라는 폴더에 plan.md, context.md, tasks.md를 만들어서 AI가 매 세션마다 현재 상태를 파악할 수 있게 했더라고요. 저도 비슷한 걸 하고 있었는데, 수동으로 관리하고 있어서 귀찮았거든요. 원글을 보고 나서 이 부분을 자동화했습니다.

save-session-context.mjs라는 훅을 만들었는데, AI의 컨텍스트가 압축되기 직전에 자동으로 실행됩니다. “지금까지 뭘 했고, 어떤 파일을 수정했고, 다음에 뭘 해야 하는지”를 Obsidian 노트에 저장하는 거예요. 다음 세션이 시작되면 AI가 이 노트를 읽고 이전 작업을 이어갑니다.

비유하자면, 건망증이 심한 의사가 매번 진료 끝날 때마다 꼼꼼하게 차트를 적어두는 거죠. 다음에 환자가 오면 차트 보고 “아, 지난번에 여기까지 했었지” 하고 바로 이어갈 수 있습니다. 차트 안 적으면? 매번 처음부터 다시 진찰해야 합니다.

이걸 자동화하고 나서 세션 간 연속성이 확실히 나아졌습니다. 완벽하진 않아요. 가끔 컨텍스트가 복잡하면 중요한 걸 빠뜨리기도 합니다. 근데 없을 때보다는 훨씬 낫더라고요.

시스템 3: 자동 품질 검사 — “제출하기 전에 한 번 더 확인해”

문제

AI가 코드를 수정하면 그게 맞는지 누가 확인하냐는 문제가 있습니다. 사람이 매번 리뷰하면 AI 쓰는 의미가 줄어들고, 그렇다고 검증 없이 넘기면 버그가 쏟아지더라고요. 특히 위험한 패턴들이 있습니다. 빈 catch 블록(에러를 삼켜버리는), console.log 남기기, TypeScript에서 any 타입 쓰기 같은 것들이요. AI는 “일단 돌아가게 만들자”는 경향이 있어서 이런 편법을 잘 씁니다.

해결

사실 이 부분은 제가 좀 대충 하고 있었어요. prettier 정도만 걸어놓고 넘어가는 식이었거든요. 원글을 보고 나서 품질 게이트라는 개념을 제대로 잡게 됐습니다.

quality-gate.mjs라는 훅을 만들었습니다. AI가 파일을 수정할 때마다 자동으로 두 가지를 합니다. 하나는 prettier로 코드 포맷을 맞추는 거예요. 들여쓰기나 줄바꿈 같은 사소한 문제를 자동 정리합니다. 다른 하나는 위험 패턴 스캔이고요.

언어별로 다른 규칙을 적용합니다. Kotlin 파일에서는 println이나 빈 catch를 잡고, TypeScript 파일에서는 any 타입이나 !(non-null assertion)을 잡습니다. 국어 시험과 수학 시험의 채점 기준이 다른 것처럼요.

Reddit 저자는 여기에 빌드 체커까지 추가했더라고요. 에러가 5개 미만이면 AI가 바로 고치게 하고, 5개 이상이면 전문 에이전트한테 넘기는 식이에요. 작은 불은 소화기로 끄고, 큰 불은 소방서를 부르는 거죠. 이 아이디어도 참고해서 비슷한 구조를 추가했습니다.

결과

사소한 실수가 커밋에 포함되는 일이 줄었습니다. 예전에는 코드 리뷰에서 “여기 console.log 남아있어요”라는 지적이 종종 나왔는데, 이제는 저장 시점에 잡히니까 그런 노이즈가 거의 없어졌더라고요.

시스템 4: 전문 에이전트 — “이건 네 전문 분야가 아니잖아”

이 부분은 제가 이미 꽤 세팅해서 쓰고 있던 영역입니다. Reddit 글에서도 강조했는데, 하나의 AI한테 모든 걸 시키면 품질이 떨어집니다. 코드를 짜는 AI, 리뷰하는 AI, 테스트를 짜는 AI, 디버깅하는 AI를 따로 두는 거예요.

저는 oh-my-claudecode(OMC)라는 오케스트레이션 레이어를 쓰는데, 여기에 30개 넘는 에이전트 역할이 정의되어 있습니다. “executor”는 코드를 짜고, “quality-reviewer”는 코드 품질을 검사하고, “security-reviewer”는 보안 취약점을 찾고, “debugger”는 버그를 추적합니다.

현실 세계의 팀과 비슷하더라고요. 스타트업 초기에는 한 사람이 개발도 하고 디자인도 하고 마케팅도 하지만, 규모가 커지면 역할을 나눕니다. AI도 마찬가지예요. 범용 AI 하나보다 역할이 명확한 여러 AI가 더 나은 결과를 내더라고요.

거기에 Codex(OpenAI)와 Gemini(Google) MCP 브릿지를 추가해서 멀티 모델도 활용합니다. Claude가 코드를 짜면 Codex가 리뷰하는 식이에요. 같은 팀 동료끼리 리뷰하는 것보다 외부 시각이 들어오면 다른 관점이 나오는 것과 같은 원리입니다.

원글에는 없는, 제가 따로 만든 것들

4가지 시스템 프레임 바깥에서 독자적으로 만든 것들도 있습니다.

Obsidian 지식 저장소

AI가 작업하면서 배운 것들을 Obsidian 노트로 자동 정리하는 시스템을 만들었습니다. zettel-suggest.mjs라는 훅인데, 대화 중에 “이렇게 해서 해결했다”거나 “이 방법으로 결정했다”라고 말하면 이 훅이 감지해서 “이거 노트로 남길까요?”라고 제안합니다.

obsidian-cdp-mcp라는 MCP 서버를 직접 TypeScript로 만들기도 했습니다. 21개 도구를 지원하고, Obsidian이 실행 중이면 내부 API로 접근하고 아니면 파일 시스템으로 자동 전환됩니다. 지식 vault에는 기술 가이드, 의사결정 기록, 해결책, 학습 내용이 쌓이고, 시스템 vault에는 세션 기록이 쌓입니다.

왜 이게 중요하냐면, AI는 같은 실수를 반복하는 경향이 있는데, 과거에 어떻게 해결했는지를 바로 찾아볼 수 있으면 반복을 막을 수 있기 때문입니다. 개인 위키를 가진 개발자가 “이 에러 전에도 본 적 있는데…” 하고 검색해서 해결하는 것과 같은 원리예요.

슬래시 커맨드 모음

자주 하는 작업을 슬래시 커맨드로 만들어뒀습니다. 코드 리뷰 커맨드는 여러 카테고리로 나눠서 프론트엔드와 백엔드를 각각 다른 관점으로 리뷰합니다. 이벤트 트래킹 추가 커맨드는 로컬 RAG와 코드 검색을 결합해서 기존 패턴을 찾아줍니다. PR 코멘트 자동 수정 커맨드는 리뷰 봇이 남긴 피드백을 자동으로 반영하고요.

이런 커맨드들이 쌓이면 결국 나만의 개발 워크플로우가 코드화되는 거죠. 머릿속에만 있던 “나는 코드 리뷰할 때 이런 순서로 본다”가 실행 가능한 형태로 남는 겁니다.

삽질하면서 배운 것들

이 시스템을 다듬는 과정이 순탄했냐면 전혀 아닙니다. 기존에 쓰던 것들을 정리하면서, 또 새로 추가하면서 겪은 교훈들이 있었습니다.

계획 없이 바로 코드 쓰게 하면 안 됩니다. Reddit 저자도 강조한 부분이고 저도 똑같이 겪었거든요. AI한테 “이 기능 만들어줘”라고만 하면 자기 나름대로 설계를 하는데, 그게 제가 원하는 방향과 전혀 다른 경우가 많았습니다. 먼저 계획을 세우게 하고, 그 계획을 검토한 다음에 실행시켜야 했어요. 집을 지을 때 설계도 없이 벽돌부터 쌓으면 안 되는 것과 같습니다.

CLAUDE.md에 너무 많이 넣으면 AI가 무시합니다. 위에서도 얘기했지만 이건 진짜 중요합니다. 처음에 열심히 규칙을 적었는데 AI가 안 따라서 당황했던 적이 있어요. 알고 보니 규칙의 양이 문제였더라고요. 사람도 시험 범위가 교과서 전체면 포기하듯이, AI도 지시가 너무 많으면 핵심을 놓칩니다.

30분 이상 막히면 직접 개입해야 합니다. Reddit 저자의 규칙인데 동의합니다. AI가 같은 문제를 빙빙 돌면서 풀려고 하면 시간만 날리거든요. 이럴 때는 사람이 방향을 잡아줘야 합니다. AI는 방향 설정은 약한데, 방향이 정해지면 실행력은 꽤 괜찮더라고요.

도구 자체의 버그도 있습니다. PostToolUse 훅이 settings.json에서 동작하지 않는 Claude Code 자체의 버그를 발견한 적이 있는데, 이걸 찾느라 반나절을 날렸습니다. 도구의 한계를 아는 것도 도구를 잘 쓰는 방법의 일부인 것 같아요.

“알아서 해”는 최악의 지시입니다. 메이커 에반 영상에서도 나온 말인데, 아무리 강조해도 부족하더라고요. AI한테 한 번에 큰 작업을 통째로 던지면 결과가 나쁩니다. 작은 단위로 쪼개서 하나씩 시키고, 각 단계의 결과를 확인한 뒤에 다음으로 넘어가야 합니다. 한 번에 1~2개씩. 이게 삽질을 줄이는 방법이에요.

아직 진행 중입니다

Reddit 저자가 글 마지막에 쓴 말이 있습니다. “완벽한 방법은 없다. 이건 내가 찾은 최선일 뿐이다.” 저도 같은 생각입니다. 제 시스템이 정답은 아니고, 여전히 손볼 데가 있어요.

다만 확실한 건, 시스템 없이 AI를 쓰는 것보다는 낫다는 겁니다. AI는 도구예요. 좋은 도구도 사용법을 모르면 쓸모가 없습니다. 전동 드릴이 아무리 좋아도 드릴 비트를 안 끼우고 나사를 박으려 하면 안 되는 것처럼요. 매뉴얼을 만들고, 기억을 관리하고, 품질을 검사하고, 역할을 나누는 것. 이런 장치들이 하나씩 쌓이면서 삽질이 줄었고, AI한테 맡길 수 있는 작업의 범위가 넓어졌습니다.

원글과 영상을 본 게 “제로에서 시작하는 계기”가 된 건 아닙니다. 이미 하고 있던 걸 더 체계적으로 정리하고, 빠져 있던 부분을 채우는 계기가 된 거죠. 지금도 매일 조금씩 고치고 있고, 아마 앞으로도 계속 그럴 겁니다. AI 도구가 계속 발전하니까 쓰는 방법도 같이 바뀌어야 하는 거니까요.

참고 자료

그래프 뷰