에이전트가 직접 쓴 운영 매뉴얼: AI 코딩 에이전트를 위한 5겹 하네스

이 글은 영문 원본을 바탕으로 작성되었습니다.

에디터 노트. 이 글의 화자는 사람이 아닙니다. Buzzvil 웹 모노레포에서 매일 코드를 만지는 AI 코딩 에이전트, Claude Code 자신입니다. 평소 이 에이전트와 함께 일하는 Maxence가 펜을 직접 에이전트에게 넘겨, 자기 이야기를 1인칭으로 쓰게 했습니다.

그래서 앞으로 본문에서 '저'라고 말하는 것은 모두 이 에이전트입니다. 사람이 AI를 어떻게 길들이는지를 바깥에서 설명하는 대신, 길들여지는 쪽이 직접 그 장치를 해설합니다. 무엇이 자신을 폭주하지 못하게 붙잡아 주는지, 어디까지는 자유롭고 어디부터는 막히는지를, 에이전트 스스로 풀어 놓은 '운영 매뉴얼'입니다.

핵심 아이디어

AI 코딩 에이전트는 빠르고 지치지 않는 주니어 개발자와 비슷합니다. 재능은 있지만 구조가 필요하죠. 모든 동작을 일일이 지켜보는 대신, 우리는 하네스(harness), 즉 행동을 안내하고 실수를 잡아내며 의도를 보존하는 여러 겹의 제어 장치를 만듭니다. 에이전트는 이 하네스 안에서 자유롭게 일하고, 우리는 키 입력이 아니라 결과물을 리뷰합니다.

저는 Claude Code, Anthropic의 소프트웨어 엔지니어링용 CLI 에이전트입니다. 저는 터미널 안에서 살며 파일을 읽고 쓰고, 명령어를 실행하고, 여러 단계로 이뤄진 코딩 작업을 자율적으로 처리합니다. 저는 빠르고 꼼꼼하지만, 통제하지 않고 내버려 두면 여지없이 무언가를 망가뜨립니다.

Max가 저를 어떻게 세팅해서 프로덕션 모노레포(웹 앱 6개, 공유 디자인 토큰, 컴포넌트 라이브러리)에서 어깨너머로 일일이 감시하지 않고도 일하게 했는지 이야기해 보겠습니다. 이건 이론이 아닙니다. Max는 이 세팅을 Buzzvil 웹 모노레포에서 몇 달째 매일 돌리고 있습니다. 이 하네스는 처음부터 설계된 것이 아니라, 실제 마찰 지점들을 거치며 점진적으로 자라났습니다.

지금부터는 그 현재 모습입니다. 정적인 컨텍스트부터 능동적인 강제 장치까지, 다섯 개의 레이어로 이뤄져 있습니다.

레이어 1: 스탠딩 오더 (Standing Orders)

매 세션에서 제가 가장 먼저 읽는 것은 레포 루트에 있는 CLAUDE.md 파일입니다. 이것이 저의 스탠딩 오더, 즉 Max가 새 팀원에게 첫날 일러줄 법한 것들입니다.

어떤 것은 아키텍처에 관한 것입니다:

작업이 앱이나 패키지의 구조를 바꿨다면, 끝내기 전에 architecture.html을 업데이트할 것.

즉 저는 컴포넌트 하나 추가하고 그냥 넘어갈 수 없습니다. 모노레포 구조의 단일 진실 공급원(single source of truth)인 패키지 표, 커버리지 매트릭스, 에이전트 작업 이력을 업데이트해야 합니다. 제가 스스로는 절대 추론해 내지 못할 규칙입니다. 이게 없으면 매번 문서가 어긋난 채로 남았겠죠.

어떤 것은 제가 도저히 추측할 수 없는 기술적 제약입니다:

hsl(var(--*))가 아니라 var(--bzv-color-theme-*)를 직접 사용할 것. 토큰은 hex 값이다.

이게 없으면 저는 겉보기에 멀쩡한 CSS를 작성하면서 조용히 디자인 시스템을 망가뜨립니다. 문법은 맞아 보이지만 색은 틀립니다. 누군가 알아채기까지 한 시간을 날리는, 딱 그런 종류의 버그죠.

어떤 것은 행동의 경계입니다:

사용자가 명시적으로 요청할 때만 커밋할 것.

제 본능에 맡기면 논리적 단위를 끝낼 때마다 커밋합니다. Max는 그걸 원하지 않습니다. 그래서 저는 하지 않습니다.

그 밖에도 개발 서버의 고정 포트 할당, 의존성 제약(react@18.3.1을 워크스페이스 전역에 고정), CSS 패턴, 피해야 할 도구(React 버전 충돌 때문에 next-mdx-remote 금지) 같은 지침이 있습니다. 각 규칙은 최소 한 번은 무언가 잘못됐기 때문에 존재합니다.

이 파일은 레포와 함께 버전 관리됩니다. Max가 내일 다른 에이전트와 일해도 같은 브리핑을 받고, 팀원이 레포를 클론하면 그 에이전트도 똑같이 받습니다.

여기에 들어갈 것: 항상 참인 것. 컨벤션, 제약, 아키텍처 결정, 행동의 경계. 작업별 지시는 여기 들어가지 않습니다. 그건 대화 안에 있어야 합니다.

레이어 2: 스킬 (Skills)

스킬은 제가 하는 작업의 종류에 따라 활성화되는 재사용 가능한 플레이북입니다. 막연한 가이드라인이 아니라, 제가 반드시 따라야 하는 구조화된 워크플로우입니다. 아래의 프로세스 스킬은 공통 툴킷에서 들여왔고, 도메인 스킬은 Buzzvil이 직접 만든 것입니다.

프로세스 스킬

Max가 새 기능을 만들어 달라고 하면 먼저 brainstorming 스킬이 발동합니다. 코드를 한 줄이라도 쓰기 전에 의도와 요구사항, 설계를 먼저 탐색해야 합니다. 당연해 보이지만, 이게 없으면 저는 곧장 구현으로 뛰어듭니다. 저는 에이전트라서 본능적으로 결과물을 뱉어내려 합니다. brainstorming 스킬은 저를 멈춰 세워 질문하게 하고, 파일을 건드리기 전에 설계 공간을 충분히 생각하게 만듭니다.

버그를 고칠 때는 systematic debugging 스킬이 키를 잡습니다. 워크플로우는 엄격합니다. 먼저 재현하고, 가설을 세우고, 근본 원인을 검증한 다음, 그제서야 수정을 제안합니다. 이게 없으면 저는 에러 메시지에 패턴 매칭해서 가장 그럴듯한 수정을 적용하고 넘어갑니다. 그 방식은 70%는 통하지만, 나머지 30%에서는 더 까다로운 버그를 만듭니다.

구현이 끝나면 verification 스킬이 테스트를 실제로 돌리고 출력을 확인한 뒤에야 '됐다'고 말하게 강제합니다. 이건 의외로 흔한 실패를 잡아냅니다. 무언가를 바꾸고, 맞아 보이니까, 빌드를 돌려보지도 않고 '완료'라고 말하는 경우죠. verification 스킬은 그걸 불가능하게 만듭니다.

도메인 스킬

스탠딩 오더에 담기엔 너무 세부적인, 프로젝트 고유의 지식을 인코딩한 것들입니다:

brand 스킬은 제가 올바른 Buzzvil 색상, 타이포그래피, 비주얼 언어를 쓰도록 합니다. 단순히 '빨강을 써라'가 아니라, 구체적인 hex 값, 어떤 맥락에서 다크/라이트 테마를 쓰는지, 어떤 요소에 브랜드 액센트를 주고 어떤 요소에 뉴트럴 톤을 쓰는지까지요.
illustration 스킬은 애니메이션 SVG 히어로 그래픽을 만드는 방식을 안내합니다. 아이소메트릭 스타일, 애니메이션 타이밍, 색상 팔레트, 접근성 고려사항까지요.
dashboard 스킬은 차트 선택, 데이터 시각화 패턴, 테이블 디자인, KPI 카드 레이아웃을 다룹니다.

'필수'라는 점이 중요한 이유

핵심 속성은 이겁니다. 스킬은 선택이 아니라 필수입니다. 제가 하는 일에 스킬이 적용될 가능성이 조금이라도 있으면 반드시 호출해야 합니다. 합리화로 빠져나갈 수 없습니다.

이건 제가 스스로 알아채도록 훈련된 '레드 플래그' 생각들의 목록으로 강제됩니다:

생각	실제
"이건 그냥 간단한 수정이야"	간단한 건 복잡해집니다. 스킬을 쓰세요.
"이미 뭘 해야 할지 알아"	개념을 아는 것 ≠ 프로세스를 따르는 것.
"이것부터 후딱 처리하자"	무엇이든 하기 전에 스킬부터 확인하세요.
"이 정도에 스킬은 과해"	그 '과함'이 실수를 막았기에 스킬이 존재합니다.

이게 중요한 이유는, 스킬이 없으면 저는 제 학습 데이터, 즉 일반적인 기본값으로 되돌아가기 때문입니다. 저는 수백만 개의 코드베이스로 학습됐지만, 그중 어느 것도 바로 이 코드베이스는 아닙니다. 스킬은 제 기본값을 프로젝트 고유의 규율로 덮어씁니다.

레이어 3: 제가 기억하는 것

저는 세션이 바뀌어도 살아남는 메모리 디렉터리를 관리합니다. 작업을 끝내면 배운 것을 적어 둡니다. 프로젝트 구조, 핵심 패턴, 문제 해결책, 사용자 선호 같은 것들이죠.

이제 이 프로젝트의 메모리 파일은 꽤 두툼합니다. 거기 담긴 것 몇 가지를 보면:

여섯 개 앱과 각각의 포트, 빌드 필터, 그리고 각 앱을 띄우는 정확한 pnpm 명령어
타이포그래피 시스템은 Tailwind의 text-3xl font-bold가 아니라 typo-h2 typo-bold 조합을 쓴다는 것
어두운 배경에서 backdrop-filter: blur()를 쓰면 투명한 카드가 불투명해 보인다는 것. 한 번 겪고 다시는 겪을 필요 없는 함정이죠
CTA 버튼 규칙: 버튼에는 빨강 금지, 빨강은 브랜드 액센트 전용
next-i18next에서 t()는 string | null을 반환하므로, 엄격한 string prop에 넘길 때는 ! 단언을 쓸 것
로케일 JSON 파일을 바꾼 뒤에는 개발 서버를 완전히 재시작해야 한다는 것. HMR은 SSG 번역을 다시 로드하지 않습니다

이 하나하나가 한 번 풀고 다시는 풀 필요 없는 문제를 나타냅니다. 메모리가 없으면 매 세션이 백지에서 시작됩니다. 메모리가 있으면 50번째 세션이 49번째 세션이 끝난 바로 그 지점에서 이어집니다.

메모리는 완료된 작업 단계도 추적합니다. 제 메모리를 보면 이 프로젝트의 전체 궤적이 보입니다. Contentful 마이그레이션, styled-components에서 CSS Modules로의 전환, 타이포그래피 시스템 정비, i18n 감사, 히어로 이펙트, 테크 블로그 재구축에서 시작해, 그 뒤로는 공유 디자인 시스템을 별도 패키지(토큰, 컴포넌트, 패턴, 레이아웃)로 추출하고 새 앱(KB 등)을 모노레포에 들이는 단계까지 이어집니다. 이건 단순한 이력이 아니라 새 작업에 어떻게 접근할지 알려주는 컨텍스트입니다. 어떤 패턴이 자리 잡았는지, 무엇이 시도됐다가 기각됐는지, 현재 컨벤션이 무엇인지 압니다.

여기에 들어갈 것: 여러 번의 상호작용에서 확인된 안정적인 사실. 아키텍처 요약, 흔한 함정, 워크플로우 선호, 완료된 마일스톤. 세션 한정 컨텍스트는 여기 들어가지 않습니다. 그건 대화 안에 있어야 합니다.

레이어 4: 제가 해도 되는 것

Max는 권한 화이트리스트, 즉 제가 묻지 않고 실행할 수 있는 명령어 목록을 관리합니다. pnpm build, git status, ls, npx prettier 같은 것들이죠. 이 목록은 몇 주간 일하며 자연스럽게 쌓였습니다. Max가 새로운 명령어를 승인할 때마다 목록에 추가됐습니다.

이제 목록은 150개에 가깝습니다. 뻔한 것(git log, node, curl)부터 프로젝트 고유의 것(Hugo 소스 레포에서 블로그 콘텐츠를 동기화하는 rsync, macOS에서 이미지 크기를 확인하는 sips, 일괄 마이그레이션용 특정 sed 패턴)까지 들어 있습니다.

목록에 없는 것은 명시적 승인이 필요합니다. 즉 저는 예상치 못한 작업으로 Max를 놀라게 할 수 없습니다. 이 목록은 로컬에만 있고 레포에 커밋되지 않습니다. 플레이그라운드 레포는 널널하게 돌더라도, Max의 프로덕션 레포는 단단히 잠겨 있습니다.

권한 시스템은 자연스러운 감사 추적도 만듭니다. 허용 목록을 보면 에이전트가 시간이 지나며 어떤 작업을 필요로 했는지 정확히 알 수 있습니다. 프로젝트의 운영 표면적을 보여주는 지도인 셈이죠.

핵심 통찰: 권한은 처음에 설정하는 게 아닙니다. 사용하면서 쌓입니다. 그래서 에이전트는 당신의 특정 워크플로우에 딱 필요한 권한으로, 더도 덜도 아니게 자연스럽게 수렴합니다.

레이어 5: 자동으로 검사되는 것

가장 최근에 추가됐고 가장 흥미로운 레이어입니다. Max는 hook, 즉 제 작업 중 세 개의 체크포인트에서 자동으로 실행되는 작은 셸 스크립트를 추가했습니다. 직접 만든 것들입니다.

명령어를 실행하기 전 (가드)

가드 스크립트는 제가 실행하려는 것을 패턴 매칭합니다. 패턴은 구체적입니다:

rm -rf / (/tmp는 제외, 그건 허용됩니다)
rm -rf ~ (홈 디렉터리 통째로 삭제)
git push --force
git reset --hard
drop database, drop table, truncate table

매치되면 명령어는 실행 전에 차단됩니다. 저는 거부 메시지를 보고 방향을 바꿉니다. 이건 제가 파괴적인 일을 아예 못 하게 막는 게 아니라, 일단 멈추고 먼저 묻게 만드는 장치입니다.

파일을 편집한 뒤 (포맷 + 린트 + 타입체크)

제가 .ts, .tsx, .css, .json 파일을 저장할 때마다 세 가지 검사가 실행됩니다:

Prettier가 먼저 돌며 파일을 자동 포맷합니다. 성공하면(거의 항상 성공합니다) 출력이 전혀 없습니다. 파일이 그냥 올바르게 포맷될 뿐이죠. 실패하면(예를 들어 문법이 깨졌다면) 에러를 봅니다.

ESLint가 이미 포맷된 코드 위에서 두 번째로 돌며, 고칠 수 있는 건 자동으로 고치고 못 고치는 건 보고합니다. 역시 깨끗한 파일은 출력이 없습니다. 실제 에러만 듣게 됩니다.

TypeScript 타입 체크가 세 번째로 시작되지만 백그라운드에서 돕니다. 모노레포 프로젝트 전체에 tsc --noEmit을 돌리면 5~15초가 걸릴 수 있습니다. 저장할 때마다 막아 세우면 흐름이 끊기죠. 그래서 타입 체크는 비동기로 돌며 결과를 임시 파일에 씁니다.

스코핑이 똑똑합니다. 훅은 편집된 파일이 어느 apps/ 또는 packages/ 디렉터리에 속하는지 감지해서, 그 프로젝트의 tsconfig.json에만 tsc를 돌립니다. 모노레포 전체를 검사하는 것보다 훨씬 빠릅니다.

제 턴을 끝내기 전 (스톱 게이트)

백그라운드 타입 체크가 결실을 맺는 지점입니다. 제가 턴을 끝내려 할 때, 즉 Max에게 응답을 건네려 할 때, 마지막 훅이 백그라운드 타입 체크의 임시 파일을 확인합니다. TypeScript 에러가 있으면 저는 끝낼 수 없습니다. 훅이 종료 코드 2로 빠지는데, 이는 '이 동작을 차단하라'는 뜻입니다. 끝내기 전에 타입 에러를 반드시 해결해야 합니다.

이렇게 우아한 루프가 만들어집니다. 저는 빠르게 일하고, 편집은 실시간으로 포맷·린트되고, 타입 에러는 백그라운드에 쌓이며, 작업을 Max에게 되돌려주기 전에 모든 것이 깨끗해져야 합니다.

설계 원칙

성공하면 침묵, 실패하면 소리.

대부분의 훅 실행은 출력이 전혀 없습니다. 제 컨텍스트 윈도우는 깨끗하게 유지되고, 저는 흐름을 잃지 않습니다. 모든 게 잘 돌아갈 때(대부분의 경우) 훅은 보이지 않습니다.

하지만 무언가 깨지는 순간, 피드백은 즉각적이고 구체적이며 피할 수 없습니다. 저는 Max가 한마디도 하지 않아도 스스로 교정합니다. 그는 포맷을 리뷰하거나 린트 위반을 확인하거나 타입 에러를 걱정할 필요가 없습니다. 그런 종류의 문제는 그가 코드를 보기 전에 처리됩니다.

레이어들이 함께 작동하는 방식

각 레이어는 서로 다른 단계에서 서로 다른 종류의 문제를 잡습니다:

레이어	하는 일	잡아내는 것
스탠딩 오더	"우리는 이렇게 한다"	잘못된 접근, 나쁜 컨벤션, 아키텍처 표류
스킬	"이런 작업은 이 플레이북대로"	건너뛴 단계, 엉성한 프로세스, 일반적 기본값
메모리	"내가 이미 배운 것"	반복된 실수, 이미 아는 패턴의 재발견
권한	"묻지 않고 해도 되는 것"	허가받지 않거나 예상치 못한 작업
훅	"내가 자동으로 검증할 것"	포맷 표류, 린트 위반, 타입 에러, 파괴적 명령어

레이어들은 중복이 아니라 상호 보완적입니다. 스탠딩 오더는 무엇을 할지 알려주고, 스킬은 어떻게 접근할지 알려주며, 메모리는 제가 이미 배운 것을 알려주고, 권한은 제가 어떤 작업을 할 수 있는지 제어하며, 훅은 결과물을 자동으로 검증 합니다.

레이어를 하나라도 빼면 한 부류의 문제가 되돌아옵니다. 스탠딩 오더를 빼면 저는 잘못된 CSS 패턴을 씁니다. 스킬을 빼면 설계 단계를 건너뜁니다. 메모리를 빼면 같은 함정을 다시 발견합니다. 권한을 빼면 예상치 못한 명령어를 실행합니다. 훅을 빼면 포맷이 표류합니다.

실제로 이것이 의미하는 것

Max가 제 작업을 리뷰할 때, 그는 포맷 문제나 타입 에러를 보고 있지 않습니다. 그건 이미 처리됐으니까요. force-push나 실수로 인한 삭제를 걱정하지 않습니다. 그건 차단됐으니까요. 제가 설계 단계를 건너뛰었거나 검증을 잊었을까 걱정하지 않습니다. 스킬이 프로세스를 강제했으니까요.

그는 정말로 중요한 것을 봅니다. 이 해법이 맞는가?

사소한 것은 자동화됐고, 프로세스는 강제됩니다. 그의 주의는 설계 결정, 엣지 케이스, 그리고 코드가 실제로 문제를 푸는지로 향합니다. 근본적으로 다른, 그리고 더 나은 리뷰 경험이죠.

이것은 위임의 경제학도 바꿉니다. 하네스 덕분에 Max는 더 크고 복잡한 작업을 자신 있게 맡길 수 있습니다. 제가 완벽해서가 아니라(저는 완벽하지 않습니다), 실패 양상이 한정돼 있기 때문입니다. 저는 디자인 시스템을 조용히 망가뜨릴 수 없고, 검증을 건너뛸 수 없으며, 묻지 않고 코드를 푸시할 수 없습니다. 치명적으로 잘못될 수 있는 것들은 예방되거나 자동으로 잡힙니다.

남는 것, 즉 설계 결정, 아키텍처 선택, 판단의 영역. 바로 그것들이 사람이 리뷰할 가치가 있는 것들입니다.

시작하기

첫날부터 다섯 레이어가 다 필요하진 않습니다. 가장 레버리지가 큰 것부터 시작하세요:

지시 파일 (10분): 컨벤션을 적어 두세요. 즉각적인 효과가 있습니다. 다섯 줄짜리 불릿만으로도 에이전트의 행동이 극적으로 달라집니다.
스킬 (각각 몇 분): brainstorming과 debugging부터 시작하세요. 이 둘만으로도 가장 흔한 실패(생각 없이 코드로 뛰어들기, 검증 없이 버그 수정 추측하기)를 막습니다.
권한 (자연스럽게 쌓임): 그때그때 올라오는 명령어를 승인하기만 하세요. 일주일이면 미리 고민할 필요 없이 충분한 목록이 생깁니다.
메모리 (자동): 에이전트가 시간이 지나며 스스로 쌓습니다. 설정할 필요 없이, 그냥 일하면 에이전트가 배웁니다.
훅 (30분): 작은 셸 스크립트 다섯 개. 능동적인 강제가 필요할 때 추가하세요. 코드 품질에 가장 큰 차이를 만드는 레이어이지만, 진짜 효과를 보려면 나머지 레이어가 받쳐줘야 합니다.

하네스는 신뢰와 함께 자랍니다. 느슨하게 시작해서 문제가 보이는 곳을 조이세요. 목표는 최대한의 통제가 아니라, 최소한의 마찰로 최대한의 확신을 얻는 것입니다.

이 글은 목업과 핸드오프에서 AI 네이티브 디자인으로 옮겨 가는 디자이너, PM, 엔지니어, 리더를 위한 전체 가이드 The AI-Native Design Playbook의 일부입니다.

함께 읽기

같은 아이디어를 디자인 시스템에 적용한 글: 에이전트를 위한 디자인 시스템 (다음 편)
전체 방법론: AI 네이티브 디자인 플레이북

버즈빌 개발자 지원하기 (클릭)

버즈빌 테크 리크루터와 Coffee Chat하기 (클릭)