1편에서 하네스 엔지니어링이 무엇인지 개념을 다뤘고, 2편에서 산업혁명 비유와 실전 사례를 공개했습니다. 많은 분들이 "그래서 어떻게 시작하면 되느냐"고 질문하셨습니다. 오늘 3편에서는 하네스 엔지니어링 세팅을 처음부터 끝까지 단계별로 안내합니다.
코드를 줄줄이 나열하는 글이 아닙니다. 프로그래밍을 모르는 분도 "아, 이런 순서로 만들면 되겠구나" 감을 잡을 수 있도록 과정과 개념 중심으로 설명합니다.
이 방법론은 AI에게 일을 시키기 전에 "작업 환경"을 먼저 깔아두는 것입니다. 사람을 새로 채용했을 때 업무 매뉴얼과 조직도를 건네주는 것과 같습니다. 매뉴얼 없이 일을 시키면 매번 처음부터 설명해야 하고, 실수도 반복됩니다.
AI도 마찬가지입니다. 규칙서 없이 매번 대화를 시작하면 같은 실수를 끊임없이 반복합니다. 하네스 엔지니어링 세팅의 핵심은 "한 번 깔아두면, AI가 알아서 규칙을 따르게 만드는 것"입니다.
순서를 지키지 않으면 나중에 뜯어고치느라 더 오래 걸립니다. 아래 5단계를 그대로 따라가시면 됩니다.
하네스 엔지니어링 세팅의 첫 번째이자 가장 중요한 단계입니다. CLAUDE.md는 AI가 매 세션을 시작할 때 가장 먼저 읽는 파일입니다. 회사로 치면 사원 핸드북에 해당합니다.
이 파일에 적어야 할 내용은 크게 세 가지입니다.
첫째, 경계 설정입니다. "파일은 이 폴더에만 저장해라", "설정 파일은 절대 건드리지 마라", "환경 변수 파일(.env)은 수정 금지" 같은 규칙을 적습니다. AI가 하면 안 되는 행동을 명확히 정해두는 것입니다. 이것만 잘 적어도 치명적인 실수의 80%를 예방할 수 있습니다.
둘째, 시스템 구성 맵입니다. 내 작업 환경이 어떻게 생겼는지 지도를 그려주는 것입니다. "에이전트 파일은 이 폴더에 있고, 자동화 스크립트는 저 폴더에 있고, 슬래시 커맨드는 여기에 있다"는 식입니다. AI가 새로운 작업을 할 때 이 지도를 보고 어디에 뭘 만들어야 할지 스스로 판단하게 됩니다.
셋째, 작업 전 체크 순서입니다. "뭔가 새로 만들기 전에, 기존에 비슷한 게 있는지 먼저 찾아봐라." 이 규칙 하나만 적어도 중복 작업이 사라집니다. 기존 에이전트를 재사용하게 되니 시스템이 점점 깔끔해집니다.
처음부터 완벽하게 쓸 필요는 없습니다. 10줄이라도 좋으니 "이것만은 하지 마라"를 먼저 적고, 쓰면서 하나씩 추가하면 됩니다.
2편에서 산업혁명의 분업을 이야기했습니다. 한 사람이 모든 공정을 하던 수공업 시대에서, 각 공정을 전문 인력에게 나눠주는 분업 시대로 전환된 것이 생산성 혁명의 시작이었습니다.
에이전트 설계도 똑같은 원리입니다. "메시지 발송"만 전담하는 에이전트, "뉴스 수집"만 전담하는 에이전트, "글 요약"만 전담하는 에이전트를 각각 따로 만듭니다.
세팅 방법은 간단합니다. 에이전트 전용 폴더를 하나 만들고, 각 에이전트를 하나의 파일로 분리합니다. 파일 이름만 보면 무슨 역할인지 알 수 있게 짓습니다. 예를 들어 텔레그램 발송 에이전트, 뉴스 스크래핑 에이전트, 옵시디언 저장 에이전트 — 이런 식입니다.
여기서 핵심 원칙이 하나 있습니다. 하나의 에이전트는 하나의 일만 합니다. "뉴스를 수집하면서 동시에 요약도 하고 발송도 하는" 에이전트를 만들면, 나중에 수정할 때 전체가 깨집니다. 수집은 수집 에이전트가, 요약은 요약 에이전트가, 발송은 발송 에이전트가 각각 담당해야 합니다.
이렇게 분리해두면 나중에 새로운 작업이 생겼을 때 기존 에이전트를 조합만 하면 됩니다. 처음에는 번거로워 보이지만, 에이전트가 3~4개만 쌓여도 효율이 급격히 올라갑니다.
에이전트를 분리했으면, 서로 주고받는 형식을 정해야 합니다. 이것을 "인터페이스"라고 부릅니다.
공장의 컨베이어 벨트를 떠올리시면 됩니다. A 공정에서 나온 반제품이 B 공정으로 넘어갈 때, 크기와 규격이 맞아야 합니다. 에이전트도 마찬가지입니다.
뉴스 수집 에이전트가 기사 목록을 넘겨줄 때 "제목, URL, 본문 요약" 세 가지를 정해진 형태로 건네주기로 약속하는 것입니다. 그러면 요약 에이전트는 그 형태를 받아서 바로 처리할 수 있습니다.
실제 세팅할 때는 각 에이전트 파일 맨 위에 "이 에이전트는 무엇을 입력으로 받고, 무엇을 출력으로 내보내는지"를 몇 줄로 적어두면 됩니다. 거창한 문서가 필요한 것이 아닙니다. "입력: 키워드 1개 / 출력: 뉴스 기사 5건(제목, URL, 요약)" — 이 정도면 충분합니다.
이 단계를 건너뛰면 에이전트 A가 넘긴 결과를 에이전트 B가 못 읽는 상황이 생깁니다. 하네스 엔지니어링에서 가장 흔한 실패 원인 중 하나입니다.
개별 에이전트가 준비되었으면, 이제 이것들을 하나의 흐름으로 엮을 차례입니다. 이 연결 설계도를 "오케스트레이션"이라고 합니다.
예를 들어 블로그 글을 자동으로 쓰는 파이프라인은 이렇게 구성됩니다.
각 단계가 끝나면 다음 단계로 결과를 넘기고, 마지막까지 자동으로 흘러갑니다.
하네스 엔지니어링 세팅에서 오케스트레이션을 만드는 방법은 크게 두 가지입니다. 하나는 마크다운 파일로 단계별 지시를 적어두는 것이고, 다른 하나는 코드로 순서를 정의하는 것입니다. 비개발자라면 마크다운 방식을 추천합니다. "1단계: 이 에이전트를 실행해서 결과를 받아라. 2단계: 그 결과를 이 에이전트에 넣어라" — 이렇게 자연어로 적어도 AI가 이해합니다.
여기에 슬래시 커맨드까지 연결하면 더 편해집니다. "/블로그"라고 한 줄만 입력하면 위 4단계가 처음부터 끝까지 자동으로 실행됩니다. 매번 단계를 하나씩 지시할 필요가 없어집니다.
5단계가 가장 중요합니다. 하네스 엔지니어링은 한 번에 완성되지 않습니다. 반드시 실패합니다. 그리고 그 실패가 시스템을 더 단단하게 만듭니다.
AI가 엉뚱한 폴더에 파일을 저장했다면? CLAUDE.md에 "이 폴더에만 저장하라"는 규칙을 한 줄 추가합니다. AI가 문체를 마음대로 바꿨다면? "합쇼체만 사용하라"는 규칙을 추가합니다. AI가 세션이 바뀔 때마다 이전 작업을 까먹는다면? HANDOFF.md라는 인수인계 문서를 만들어서 "새 세션 시작할 때 반드시 이 파일을 먼저 읽어라"고 규칙을 추가합니다.
HANDOFF.md는 세션 간 기억을 연결하는 장치입니다. AI는 대화가 끊기면 이전 맥락을 잊어버리는데, 이 파일에 "지난 세션에서 뭘 했고, 뭐가 남았는지"를 기록해두면 새 세션에서도 바로 이어서 작업할 수 있습니다.
이 과정을 반복하면 규칙서가 점점 두꺼워지고, AI의 실수는 점점 줄어듭니다. 제 경우 처음 10줄이던 CLAUDE.md가 지금은 수백 줄이 되었습니다. 그만큼 AI가 실수 없이 정확하게 움직입니다.
실패를 피하려 하지 마시고, 실패할 때마다 규칙을 한 줄 추가하시면 됩니다. 이것이 하네스 엔지니어링 세팅의 진짜 핵심입니다.
Q. CLAUDE.md 파일은 어떻게 작성하나요?
프로젝트 루트 폴더에 CLAUDE.md라는 이름으로 텍스트 파일을 만들면 됩니다. 특별한 프로그램이 필요 없습니다. 메모장이나 노트 앱에서 작성해도 됩니다. "이 폴더에만 저장하라", "이 파일은 건드리지 마라", "새 작업 전에 기존 에이전트부터 확인하라" — 이런 규칙을 자연어로 적으면 됩니다. AI가 코드가 아니라 자연어를 읽고 이해합니다.
Q. 비개발자도 하네스 엔지니어링을 할 수 있나요?
가능합니다. 하네스 엔지니어링의 본질은 코딩이 아니라 "규칙을 정하고, 작업을 분리하고, 순서를 연결하는 것"입니다. 이것은 업무 매뉴얼을 만드는 것과 같습니다. 코딩 지식이 전혀 없어도 자연어로 규칙서를 작성할 수 있고, 마크다운 파일로 오케스트레이션을 구성할 수 있습니다.
Q. 하네스를 너무 많이 쌓으면 역효과가 나나요?
날 수 있습니다. 규칙이 서로 충돌하거나, 너무 세밀한 규칙이 AI의 유연성을 떨어뜨릴 수 있습니다. 해결 방법은 간단합니다. 규칙을 주기적으로 정리하면 됩니다. 한 달에 한 번 정도 CLAUDE.md를 읽으면서 "이 규칙은 아직 필요한가?"를 체크하시면 됩니다. 꼭 필요한 규칙만 남기고, 겹치는 규칙은 합치는 것이 좋습니다.
Q. 하네스 엔지니어링으로 실제 성과가 나나요?
2편에서 공개한 사례가 대표적입니다. 블로그 글 하나를 작성하는 데 2시간 이상 걸리던 작업이, 하네스 엔지니어링 세팅 후 슬래시 커맨드 한 줄로 줄었습니다. 뉴스 수집, 일정 정리, 텔레그램 발송 같은 반복 작업도 자동화하여 하루에 수 시간을 절약하고 있습니다. 핵심은 "시간이 지날수록 성과가 복리로 쌓인다"는 점입니다.
하네스 엔지니어링 세팅은 거창한 준비가 필요하지 않습니다. CLAUDE.md 파일 하나에 "하지 마라" 규칙 10줄을 적는 것, 그것이 시작입니다. 나머지는 실패할 때마다 한 줄씩 추가하면 됩니다.
전체 세팅 가이드 및 에이전트 구조는 GitHub(https://github.com/alice840126-ship-it/harness-engineering-guide)에 공개되어 있습니다.