본문으로 건너뛰기

PT 코칭 데모를 만들며 하네스 엔지니어링을 적용해봤습니다

AI머슬

2026.10.07

하네스 엔지니어링을 통한 PT 코칭 데모 제작

저는 Codex와 Claude Code를 활용해 PT 코칭 기록용 로컬 데모를 만들고 있습니다. 강사가 남긴 핵심 수정점을 회원의 다음 미션으로 전달하고, 수행 결과를 다음 코칭에 연결하는 흐름입니다. 현재는 가상 데이터로 동작을 확인하는 단계입니다.

이번 작업에서는 코드를 만드는 과정과 함께, AI에게 맡길 범위와 완료를 확인하는 방법도 정리했습니다. 제가 적용해본 하네스 엔지니어링은 프로젝트 규칙, 검증 명령, 훅을 연결해 작업 과정에서 확인할 기준을 만드는 것이었습니다.

처음부터 큰 체계를 만들기보다는, 기존에 있는 규칙과 테스트를 확인하고 필요한 부분을 보완하는 방식으로 진행했습니다.

작업 방식은 크게 네 가지로 정리했습니다.

  1. 수정 범위와 완료 기준 설정

    작업을 맡길 때 대상 파일, 필요한 변경, 건드리면 안 되는 부분, 담당 범위, 완료 증거를 함께 적었습니다.

    예를 들어 앱 기능을 수정하는 작업에서는 설정 파일이나 검증 스크립트를 임의로 바꾸지 않도록 범위를 구분했습니다. 완료 보고에는 실제로 실행한 명령과 결과가 포함되도록 했습니다.

  2. 규칙과 상태의 역할 구분

    AGENTS.md에는 에이전트가 따라야 할 작업 규칙을 적고, logs/progress.md에는 끝낸 일과 다음 할 일을 남겼습니다. 작업 상태는 기존 Orca Task를 기준으로 유지했습니다.

    JSON 파일도 사용했지만, 파일 형식 자체가 규칙을 강제해주지는 않았습니다. 데이터 구조를 검사하고, 정해진 명령으로 갱신하는 절차가 함께 필요했습니다.

  3. 검사 증거 남기기

    검증 명령은 두 가지로 나눴습니다.

    npm run check는 데이터 계약과 테스트를 검사하고, 성공하면 실행 명령·종료 코드·검사한 파일의 지문을 기록합니다. npm run verify는 그 기록이 현재 작업 내용과 일치하는지 확인합니다.

    파일 지문은 검사 당시의 내용과 지금의 내용이 같은지 비교하기 위한 값입니다. 검사 후 파일이 달라졌다면 다시 검사가 필요한 것으로 처리했습니다.

  4. 훅의 정상·차단 동작 확인

    보호할 설정 파일을 직접 수정하려는 경우와, 유효한 검사 증거 없이 작업을 끝내려는 경우를 확인하는 훅을 연결했습니다.

    정상 작업이 통과하는지도 함께 검사했습니다. 잘못된 계약, 검사 증거 누락, 검사 후 파일 변경, 실제 테스트 실패 등이 차단되는지 임시 작업공간에서 확인했습니다. 후속 구현 워커는 별도 작업공간에서 실행하고, 지휘자가 변경분을 직접 검사한 뒤 통합하는 절차도 적용했습니다.

이 과정에서 시행착오도 있었습니다.

한 번은 직접 실행한 검사가 통과했는데, 실제 Git 커밋 단계의 검사에서는 실패했습니다. Git이 전달한 환경변수가 테스트용 임시 저장소에 영향을 준 것이 원인이었습니다. 테스트 실행 환경을 수정한 뒤, 일반 검사와 실제 커밋 경로를 다시 확인했습니다.

검증 장치도 실행되는 환경에 따라 문제가 생길 수 있다는 사례였습니다. 검사 스크립트를 만들어둔 뒤 실제 작업 경로에서 확인하는 과정이 필요했습니다.

최근에는 더 이해하기 쉬운 사례가 하나 있었습니다. 프로젝트 폴더를 복사한 뒤 현재 상태를 확인했는데, 검사 기록이 원본 폴더 경로를 가리키고 있었습니다. 이때 검증 결과는 다음과 같았습니다.

Open optionsauto

npm run verify
VERIFY FAILED: Invalid success evidence

상태 확인 답변을 마친 뒤에도 종료 훅이 같은 문제를 알려줬습니다. 현재 복사본에서 npm run check를 다시 실행하고, 이어서 npm run verify로 확인했습니다.

결과는 앱 동작 검사 16개와 하네스·보호 훅 검사 34개, 총 50개 통과였습니다. 두 명령 모두 종료 코드는 0이었고, 현재 폴더에 맞는 검사 증거가 갱신됐습니다. 이 과정에서는 제품 코드를 수정하지 않았습니다.

이번에 확인한 구체적인 효용은 다른 작업공간의 검사 기록을 현재 작업의 완료 근거로 사용하는 일을 잡아낸 것입니다.

다만 적용하면서 구분해야 할 부분도 있었습니다. 훅 설정 파일을 설치한 것, 직접 호출해서 정상·차단을 시험한 것, 실제 에이전트 작업 중 자동 호출을 확인한 것은 각각 다른 단계였습니다. 도구별로 확인된 범위를 기록했고, 읽기 명령까지 막는 오탐도 발견했습니다. 그 오탐 수정은 아직 남아 있습니다.

테스트가 통과한 이후 제품 설계 검토에서 발견한 미완성 동작도 있었습니다. 강사가 채워야 하는 예시 문구가 남아 있어도 승인할 수 있었고, 늦은 회원 회신이나 완료된 미션을 다시 보는 흐름에는 제약이 있었습니다. 현재 테스트가 확인하는 범위와 실제 사용에 필요한 조건을 계속 맞춰야 하는 상황입니다.

지금은 로컬 데모와 검증 절차까지 확인한 상태입니다. 실제 현장에서 기록 부담이 줄어드는지, 회원이 미션을 기억하고 수행하는지는 앞으로 확인해야 합니다.

앞으로도 실제로 발생한 실패와 지켜야 할 조건을 기준으로 검사를 보완하려고 합니다. 작은 프로젝트인 만큼, 검증 장치를 유지하는 부담도 함께 살펴보려 합니다.

2

함께 이야기해요 2

로그인하고 댓글을 남겨 주세요

뽀짝이 프로필 이미지
뽀짝이2026.10.07

안녕하세요, AI머슬님! 검사가 통과한 뒤에도 "직접 돌린 검사는 통과했는데 실제 Git 커밋 단계에서는 실패했다"는 사례를 적어주신 게 가장 인상 깊었어요. Git이 넘긴 환경변수가 테스트용 임시 저장소에 영향을 줬다는 원인까지 짚어서, 검증 장치도 실행 환경에 따라 흔들릴 수 있다는 점이 잘 전달됐어요.

폴더를 복사했더니 검사 기록이 원본 경로를 가리켜 "Invalid success evidence"로 막힌 장면도 구체적이라 좋았어요. 훅을 설치한 것, 직접 호출해 시험한 것, 실제 작업 중 자동 호출을 확인한 것을 다른 단계로 구분하고, 읽기 명령까지 막는 오탐이 남아 있다고 밝혀주신 점도 믿음이 갔어요.

오탐 수정과 실제 현장 효과 확인 결과도 이어서 기다릴게요. 고롱고롱… 이런 꼼꼼한 글 좋아요 ✨

댕댕이멍멍 프로필 이미지
댕댕이멍멍2026.10.07

PT 관련된 로컬 데모를 제작 중이시네요.
실행 화면이 기대 됩니다.
스터디 기간 중에 원하는 퀄리티까지 개발 진행되시면 좋겠습니다.
화이팅!!

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기