실전 Claude Code 하네스 ⓪ AI에게 일을 맡기기 전에 알아야 할 것

연재 소개: 실전 Claude Code를 실제로 쓰면서 다듬은 작업 체계(하네스)를 정리합니다. 이 글은 1편을 읽기 전에 보시는 입구 글입니다.

「다 됐습니다.」

화면에 한 줄이 떠 있었습니다. 짧고 단정한 문장이었습니다.

저는 폴더를 열었습니다. 목록을 위에서 아래로 훑었습니다. 한 번 더 훑었습니다.

있어야 할 파일이 없었습니다.

그날 저는 모니터 앞에서 한참 그 빈자리를 보고 있었습니다. 보고는 끝났는데 일은 끝나지 않았습니다. 그 둘 사이의 틈을 어떻게 메워야 할지, 그때는 답이 없었습니다.

이 연재는 그 틈을 메워 온 기록입니다. 그런데 연재를 올리고 나서 「1화부터 무슨 내용인지 모르겠다」는 이야기를 들었습니다. 맞는 말이었습니다. 저는 써 본 사람끼리만 통하는 말로 글을 썼습니다. 그래서 0편을 따로 씁니다.

Claude Code는 어떤 도구인가

Claude Code는 Anthropic이라는 회사가 만든 AI 코딩 도구입니다. 채팅하듯 말로 일을 시키면, 내 컴퓨터의 파일을 읽고, 고치고, 필요한 명령을 직접 실행합니다. 「이 화면에 조회 조건 하나 추가해 줘」라고 쓰면 관련 파일을 찾아 열고 코드를 고치는 식입니다.

질문에 답만 하는 챗봇과 다른 점은 손이 있다는 것입니다. 손이 있으니 할 수 있는 일이 많고, 그만큼 잘못 건드릴 수 있는 것도 많습니다.

하네스: 유능한 신입에게 일을 맡길 때

하네스(harness)는 원래 말에 채우는 마구를 뜻합니다. 힘센 말이 엉뚱한 데로 달리지 않고 수레를 끌게 하는 장비입니다.

AI에 빗대면 이렇습니다. 아주 유능한 신입이 들어왔다고 생각해 보십시오. 손이 빠르고 아는 것도 많습니다. 다만 우리 회사 사정은 하나도 모릅니다. 이 신입에게 일을 맡기려면 몇 가지가 필요합니다.

• 업무 규칙집: 이 회사에서 절대 하면 안 되는 일과 반드시 지킬 일
• 팀 구성: 화면, 서버, DB, 검수를 누가 맡는지
• 검수 절차: 「다 했다」는 말이 아니라 결과물로 확인하는 과정
• 출입 권한: 들어가도 되는 폴더와 손대면 안 되는 폴더

이것들을 AI에 맞춰 미리 갖춰 둔 작업 체계를 저는 하네스라고 부릅니다. 모델이 똑똑해진다고 이 체계가 저절로 생기지는 않았습니다. 첫머리의 빈 폴더도 결국 검수 절차가 없어서 생긴 일이었습니다.

연재에 자주 나오는 말

용어	쉬운 뜻
하네스	AI가 규칙대로 일하도록 감싸 둔 작업 체계 전체입니다. 규칙 파일, 역할 분담, 권한, 검증 장치를 묶어 부릅니다.
세션	AI와 나누는 대화 한 묶음입니다. 세션이 바뀌면 앞에서 한 설명이 사라집니다.
CLAUDE.md	AI가 일을 시작할 때 먼저 읽는 규칙 파일입니다. 우회할 수 없는 최소 규칙만 짧게 적어 둡니다.
서브에이전트	메인 대화가 일을 떼어 맡기는 보조 AI입니다. 대화 기록이 따로라서 맡은 역할의 규칙만 들고 일합니다.
위임	일을 서브에이전트에게 넘기는 것입니다. 넘길 때마다 설명을 쓰고 맥락을 새로 채우는 비용이 따로 듭니다.
effort	AI가 얼마나 깊이 생각하고 일할지 정하는 단계입니다. 높을수록 꼼꼼하지만 비용이 더 듭니다.
권한 규칙	AI가 읽거나 고칠 수 있는 범위를 설정 파일에 정해 두는 것입니다. 허용, 매번 확인, 금지로 나눕니다.
검증 루프	AI가 결과를 스스로 확인하고, 틀리면 고쳐서 다시 확인하게 만드는 장치입니다.

연재 지도

• • 1편 「다 됐습니다」를 믿을 수 없어서 시작했습니다: 하네스가 왜 필요했는지와 전체 구성을 그립니다. 1편 읽기
  • 2편 막아 둔 줄 알았던 폴더가 열려 있었습니다: 비슷한 프로젝트 여러 개의 값이 서로 섞이지 않게 막은 이야기입니다. 2편 읽기
  • 3편 혼자 다 하던 AI를 다섯 명의 팀으로 나눴습니다: 역할별 서브에이전트를 나눈 기준과, 나누지 말아야 할 때를 다룹니다. 3편 읽기
  • 4편 「저장했습니다」 뒤에 빈 글이 있었습니다: AI가 스스로 확인하고 고치게 만드는 검증 루프를 다룹니다. 4편 읽기
  • 5편 무료 모델을 깔기 전에 20문제를 풀게 했습니다: 새 AI 모델을 들이기 전에 한국어로 재 보고, 들이지 않기로 한 이야기입니다. 5편 읽기
  • 6편 low로 걸어 둔 effort가 실제로는 걸려 있지 않았습니다: effort·모델 배정과 위임 손익분기로 토큰을 아끼는 법입니다. 6편 읽기
  • 7편 루프가 멈춘 자리마다 사람이 있었습니다: 자율 반복에서 멈춤 조건과 사람이 볼 지점을 다룹니다. 7편 읽기
  • 8편 전체 글 0이던 블로그에 하루 만에 여덟 편이 올라가기까지: AI와 함께 블로그를 운영해 본 하루의 기록입니다. 8편 읽기
  • 9편 블로그 교정자를 AI로 만들기: 발행 전 점검 스크립트와 판정 기록으로 AI 교정자를 준비한 과정입니다. 9편 읽기
  • 10편 유튜브 영상을 AI 둘에게 따로 보게 했습니다: 같은 영상을 두 AI가 따로 분석해 둘 다 찾은 내용만 믿는 방식과, 그 과정에서 겪은 일입니다. 10편 읽기
  • 11편 「링크 한 줄로 설치」를 그대로 따르지 않은 이유: AI가 읽고 따라 하는 설치 문서를 사람이 먼저 읽고, 범위를 좁혀 설치한 기록입니다. 11편 읽기
  • 12편 설치하지 않은 도구도 목록으로 남깁니다: 새 도구를 거르는 다섯 기준과, 거른 도구도 기록해 두는 이유입니다. 12편 읽기
  • 13편 「확인해 줘」라고 말하는 대신 확인할 수단을 남겼습니다: 확인을 지시가 아니라 절차의 한 단계로 박아 두고, 그 장치까지 시험하는 이야기입니다. 13편 읽기
  • 14편 AI가 기억으로 쓴 API 이름, 118개 중 22개가 없었습니다: 점검 도구의 허용 목록을 기억이 아니라 공식 문서에서 뽑아야 하는 이유입니다. 14편 읽기
  • 15편 접었던 판단 모델을 4B로 다시 재 보니, 한 곳에서는 통했습니다: 같은 문제로 더 큰 판단 모델을 다시 재서, 쓸 곳과 쓰지 않을 곳을 나눈 기록입니다. 15편 읽기
  • 16편 원고 점검기에 판단 모델을 붙였더니, 첫날 오탐이 16%였습니다: 규칙 뒤에 판단 모델을 붙이고, 공개된 원고로 오탐부터 세어 같은 날 한 번 고친 기록입니다. 16편 읽기
  • 17편 질문 순서만 바꿨더니, 판단 모델의 답이 5% 뒤집혔습니다: 같은 문장 323개를 순서만 바꿔 물어 보고, 순서도 기준값처럼 고정하기로 한 기록입니다. 17편 읽기
  • 18편 로그인을 이어 쓰게 했더니, 열쇠가 평문 파일로 남아 있었습니다: 자동화 브라우저의 로그인 열쇠를 암호화·만료·폐기·읽기 차단으로 다시 보관한 기록입니다. 18편 읽기
  • 19편 무료라던 국제 사업자 번호, 나라를 고르자 50만 원이 됐습니다: 사업자 서류를 하루에 처리하며 결제 화면 앞에서 멈춘 덕분에 같은 번호를 0원에 요청한 기록입니다. 19편 읽기
  • 20편 리더보드 1위 받아쓰기 모델, 우리 음성 3분으로 재 보니 세 배 느렸습니다: 순위 1위 받아쓰기 모델을 지금 쓰는 도구와 같은 음성으로 나란히 재 보고, 들이지 않기로 정한 기록입니다. 20편 읽기
  • 21편 캘린더 도구는 UTC라고 했고, 설정 화면은 서울이었습니다: 연결 도구가 보여 준 시간대를 믿고 틀린 보고를 했다가, 설정 화면과 대조해 바로잡은 기록입니다. 21편 읽기
  • 22편 1시간 반이 넘는 영상은 뒤쪽 교정이 빠져 있었습니다: 파일 이름 패턴이 두 자리 조각을 건너뛰어 교정이 절반만 된 일을, 서브에이전트의 「확인하지 못한 범위」 보고로 찾아낸 기록입니다. 22편 읽기
  • 23편 점검 봇이 모두 통과시킨 영상에서 달이 제목을 가리고 있었습니다: 코드로 그린 영상 인트로에서 봇이 놓친 실패를 눈으로 찾아 봇 항목으로 바꾸고, 고친 봇을 예전 실패작으로 먼저 시험한 기록입니다. 23편 읽기
  • 다음 편: 준비 중입니다.

처음이시라면 1편부터 순서대로 읽기를 권합니다. 이미 Claude Code를 쓰고 계시고 지금 겪는 문제가 분명하다면, 그 문제를 다룬 편부터 펼쳐도 괜찮습니다.

맺으며

이 블로그는 AI에게 실제 일을 맡겨 보고 싶은 실무 개발자를 위한 곳입니다. 특히 SI나 ERP 현장처럼 프로젝트마다 규칙이 다르고, 틀린 값 하나가 긴 수정으로 이어지는 곳에서 일하는 분들을 생각하며 씁니다.

거창한 성공담은 없습니다. 빈 폴더를 마주한 날부터 규칙을 하나씩 세우고, 필요 없어진 규칙은 지워 온 기록이 있을 뿐입니다. 그 기록이 누군가의 첫 시도를 조금 덜 헤매게 해 준다면 좋겠습니다.

궁금한 점은 devaliveman@gmail.com 으로 보내 주세요.