하네스 엔지니어링, 지시문을 구조로 옮겨 개선하기
오또니
회사에서 이번년도 초 부터 클로드 코드를 적극적으로 사용하면서 바이브 코딩을 진행하고 있다. 최근에 나온 Fable5 모델을 주로 사용하고 있는데 Fable5 모델은 토근 사용량이 Opus5 모델보다 현저히 적어 Fable5에 모든 작업을 온전히 맡길 경우 빠르게 토큰이 소진되는 문제가 있어 업무를 진행하는데 불편함을 느꼈다.
그래서 분석,검증 부분은 Fable5에 맡기고 기능 구현은 Opus5 모델에게 맡기는 전략을 적용하기로 했다.
이번 글은 Fable5 모델을 최대한 잘 사용하기 위해 하네스 엔지니어링과 오케스트레이션 전략에 대해 고민하고 토큰을 아끼기 위해 고민한 것을 공유하기 위한 글이다.
이번 글은 Fable5 모델을 최대한 잘 사용하기 위해 하네스 엔지니어링과 오케스트레이션 전략에 대해 고민하고 토큰을 아끼기 위해 고민한 것을 공유하기 위한 글이다.
개선한 내용을 설명하기에 앞서, 하네스 엔지니어링과 오케스트레이션이 무엇인지 설명을 간단하게 하고 넘어가고자 한다.
하네스 엔지니어링(Harness Engineering)은 AI 에이전트가 오작동하지 않고 안전하고 안정적으로 자율 업무를 수행할 수 있도록, 외부에서 작업 환경, 가드레일, 피드백 루프를 함께 설계하고 제어하는 운용 체계 구축 기술을 뜻한다.
AI 오케스트레이션(AI Orchestration)은 여러 AI 모델, 에이전트, 데이터, 도구를 오케스트라의 지휘자처럼 유기적으로 연결하고 조율하여 하나의 복잡한 작업을 수행하도록 관리하는 기술을 뜻한다.
하네스 엔지니어링부터 적용하기
AI 코딩 에이전트에게 "하지 마"라고 적어두는 것과, 하려는 순간 AI가 막도록 만드는 것은 다른 일이다. 바이브 코딩을 통해 개발하면서 자주 지시문으로 지시했던 것을 뽑아 규칙들로 정의하고 훅,상태,절차로 옮겨서 적용하려고 했다.
클로드 코드를 쓰다 보면 CLAUDE.md(프로젝트 지시문)에 규칙이 쌓인다. "커밋 메시지에 AI 흔적 넣지 마", "main 에 직접 커밋하지 마", "검증 끝나기 전에 커밋하지 마". 등등.. 문제는 이 규칙들이 확률적으로만 지켜진다는 것이다. 컨텍스트가 길어지면 잊히고, 병행 세션이 돌면 서로의 상태를 모르고, 모델이 바뀌면 준수율이 달라진다.
그래서 규칙을 두 층으로 나누기로 했다.
•
판단이 필요한 규칙 → 지시문으로 남긴다 (예: "버그는 재현 테스트부터")
•
판단이 필요 없는 규칙 → 훅·도구·상태 파일로 강제한다 (예: "main 직접 커밋 금지")
이 구분 작업이 전체적으로 본다면 하네스 엔지니어링이라고 할 수 있다. 실제 내가 AI와 대화하면서 중복으로 지시했던 부분을 규칙을 추출했고 오케스트레이션(분석→구현 위임→독립 검증)을 돌려 한 번 더 검증했다.
하네스 엔지니어링 적용을 위한 규칙
커밋 규약: 지시문 → PreToolUse 훅을 생성
적용 전, CLAUDE.md 에 "Co-Authored-By 트레일러 금지, main 직접 커밋 금지"라고 적어뒀다. 대체로 지켜졌지만 "대체로"가 문제다. 지시문 준수는 컨텍스트 상태에 따라 흔들리고, 위반은 커밋이 만들어진 뒤에야 발견된다.
적용 후, git commit 실행 전에 개입하는 PreToolUse 훅(commit-guard.mjs)을 만들었다. AI 작성 문구, main 브랜치 직접 커밋을 실행 전에 차단하고, 차단 메시지에 복구 경로까지 넣었다. "지금 git checkout -b feature/... 를 실행하면 워킹 트리 변경을 유지한 채 새 브랜치로 옮겨진다". 에이전트는 이 메시지를 읽고 스스로 복구한다. 도입 당일 세션에서 훅이 여러번 차단하는 현상이 발생했다. 즉, 지시문만으로는 토큰이 새고 있었다는 뜻이다.
설계 원칙, 가드 실패가 작업을 막으면 안 된다. 훅이 입력을 못 읽거나 브랜치 판정에 실패하면 차단하지 않고 통과시킨다.
여러 세션에서 하나의 프로젝트를 작업할 경우, 상태 파일 + 훅으로 시퀀스 강제
적용 전. 오케스트레이션 절차는 "독립 검증 판정이 나온 뒤 커밋"이었다. 그런데 같은 워킹 트리에 세션 여러 개가 붙어 있던 날, 검증 판정이 09:59 에 나왔는데 커밋이 09:57 에 먼저 만들어지는 현상이 발생했다. 절차는 세션 안에서만 유효했고, 세션 사이를 묶는 장치가 없어서 발생한 문제였다.
적용 후. 오케스트레이션 진입 시 .orchestrate/<이슈키>.md 상태 파일을 만들고 첫 줄에 기계 판독용 상태(분석-중 → 구현-중 → 검증-대기 → 완료)를 적는다. 커밋 훅이 이 파일을 읽어 검증-대기 상태면 리포의 모든 git commit 을 차단한다. 어느 세션이 커밋하든 상관없다. 상태가 파일에 있으므로 병행 세션도 같은 게이트에 걸린다.
인수인계 상태: 대화 문맥 → 파일
적용 전, 구현 에이전트에게 넘기는 인수인계서(문제·근본원인·수용 기준)를 대화 문맥에만 두었다. 긴 세션에서 컨텍스트가 요약되면 수용 기준의 정밀도가 떨어졌고, 토큰 소진으로 구현 에이전트가 중간에 중단되면서 인수인계서를 /handoff 스킬을 통해 재작성해야 했다.
적용 후, 인수인계서 전문을 상태 파일에 쓰고, 이후 모든 단계(구현 프롬프트·검증 기준 전달·최종 판정)가 대화가 아니라 이 파일을 원본으로 참조한다. 세션이 끊겨도 사이클 중간 상태가 남는다.
맹점 분리: 구현 에이전트는 구현만, 검증 에이전트에게 맡기기
적용 전, 분석→구현→검증을 한 문맥이 다 하면, 구현한 문맥이 자기 결과를 "의도한 대로" 읽는 편향이 생긴다. 깨진 코드를 읽어버린다.
적용 후, 구현은 implementer 에이전트, 검증은 별도 문맥의 contract-reviewer 에이전트로 분리했다. 검증 에이전트에는 평가를 주지 않고 수용 기준과 diff 범위만 준다. 자기 평가를 같이 주면 검증 에이전트가 해당 평가 안에서만 확인만 하게 된다.
버그 재현 우선: 추측 수정 금지
적용 전, 버그 리포트를 받으면 코드를 먼저 고치고 테스트를 나중에 붙이는 흐름이 반복됐고, "고쳤다"고 보고한 현상에 "여전히 그렇다"는 재지적이 오면 관측 없이 두 번째 수정안을 내는 패턴이 반복됐다.
적용 후, 지시문에 규칙으로 올려 조작 절차가 있으면 실패하는 테스트를 먼저 만들어 빨간 것을 확인하고, 재현이 안 되면 추측 수정 대신 "재현 실패 + 확인 필요한 조건"을 보고한다. 재지적을 받으면 코드를 다시 손대기 전에 사용자의 조작 순서를 그대로 재현해 실패를 직접 관측한다.
이번에 추가한 규칙들을 적용하고나서 가장 크게 느낀 점은 토큰 소모량이 많이 줄었다는 점이다. 에이전트가 토큰을 가장 많이 소모하는 순간은 코드를 작성할 때 보다 잘못 작성된 코드를 되돌릴 때 소모량을 많은 걸 알 수 있었다.
그래서 재작업을 구조적으로 줄여 토큰을 많이 아낄 수 있었다. 판단이 필요 없는 규칙을 훅으로 내려보내면 규칙을 지키는데 소모되는 토큰 소모량은 0에 가깝다. 지시문은 컨텍스트를 차지하며 확률적으로 지켜지겠지만 훅은 컨텍스트를 쓰지 않고 100% 지켜지기 때문에 토큰 소모를 하지 않을 수 있다.
훅은 늘릴수록 좋은게 아니라서 실제로 내가 반복 작업하는 부분을 뽑는게 중요한 것 같다.
앞으로도 반복 작업이 늘어날 수록 커스텀 훅을 추가하면서 토큰 소모량을 줄일 수 있는 방법을 고민할 것 같다.
앞으로도 반복 작업이 늘어날 수록 커스텀 훅을 추가하면서 토큰 소모량을 줄일 수 있는 방법을 고민할 것 같다.
