AI에게 '모든 것을 맡기면' 무섭습니다. '모든 것을 확인하면' 느립니다. 둘 다 3일 만에 지칩니다😇

게다가 열정적으로 만든 '하네스 사양서'는 단 3시간 만에 구식이 되어 쓰레기통으로 갔습니다.

일본 주식 AI 종목 스크리닝 및 지속 학습 터미널인 "ALPHA FORGE(알파포지)"를 Claude Code와 함께 개인 개발하고 있습니다. 이번에는 [하네스] 편입니다. AI가 기분 좋게 돌아가도록 어디에 선을 긋고, 어떤 메커니즘으로 멈추게 할지 전부 보여드리겠습니다🛠️

※본 기사는 note 연재 [ALPHA FORGE 개발 비화 #19]의 기술적인 부분을 Claude Code를 사용하는 개발자들을 위해 재구성한 것입니다.

📏 모든 것을 맡길까? 모든 것을 확인할까? 둘 다 힘들다

AI 에이전트와 개발하면서 가장 먼저 부딪히는 고민이 이것입니다.

너무 많이 맡기면 무섭고, 너무 많이 확인하면 느리다. 양극단은 어느 쪽도 오래가기 어렵다

모든 것을 맡기면 빠르지만 '어디서 멈출지' 알 수 없습니다. 정신 차려보니 이미 푸시되었거나, 결제된... 같은 상상을 하면 깜짝 놀랍니다😱

반대로 파일을 한 줄 고칠 때마다 "괜찮습니까?"라고 물으면, 제가 도장 찍는 역할을 하게 되어 AI의 속도가 망가집니다.

그래서 그 사이에 선을 하나 긋기로 했습니다.

'되돌릴 수 있는지'와 '외부로 나가는지'로 선을 긋는다

기준은 '되돌릴 수 있는지'와 '외부로 나가는지' 두 가지뿐입니다. 코드 편집은 git으로 되돌릴 수 있고, 테스트는 몇 번 돌려도 아무도 곤란해하지 않습니다. 반면, 푸시된 기록, 공개한 것, 삭제한 파일, 지불한 요금은 되돌리거나 되돌리는 것이 매우 어렵습니다. 여기만은 AI가 아무리 자신만만해도 사람이 마지막에 봐야 합니다🧐

이 선 긋기는 모든 프로젝트 공통의 글로벌 지침(사용자 단위의 CLAUDE.md)에 작성해 두었습니다. 프로젝트마다 쓰면, 프로젝트를 넘나들 때 선이 흐트러지기 때문입니다.

🚦 선 위에 '멈출 장소'를 놓다

선을 그어도 지켜지지 않으면 그저 낙서일 뿐입니다. 그래서 작업 단계별로 멈출 장소를 두었습니다.

만들기 전・매번・내보내기 전. 단계별로 멈출 장소를 두고, 마지막 문은 사람이 열게 한다

🗺️ 계획 모드 (만들기 전에 멈춤)

여러 파일에 걸친 변경은 갑자기 시키지 않습니다. 계획 모드로 '무엇을 어떻게 바꿀지'의 설계만 받아서 제가 승인한 후에 구현에 들어갑니다. 지난번(제18화)의 '시험 가동' 모드도 이 흐름으로 만들었습니다.

설계가 무거울 때는 더 강력한 모델에게 계획만 생각하게 하기도 합니다. 생각하는 역할과 쓰는 역할을 분리하는 이미지입니다.

🪝 후크 (매번, 반드시 실행)

후크는 AI의 판단과는 관계없이 정해진 타이밍에 반드시 실행되는 처리입니다. ALPHA FORGE에서는 클라우드 작업 환경(Claude Code on the web)에서 대화를 시작하는 순간, Celery의 브로커에 사용하는 Redis 등을 갖추는 '세션 시작 후크'를 두었습니다.

{
"hooks": {
"SessionStart": [
...

스크립트 맨 앞에서는 "클라우드가 아니면 아무것도 하지 않고 끝난다"처럼 만들었습니다. 손에 있는 Windows는 다른 절차로 시작하고 있기 때문입니다.

set -euo pipefail
if [ "${CLAUDE_CODE_REMOTE:-}" != "true" ]; then
exit 0
...

Redis는 '이미 실행되었다면 아무것도 하지 않는' 형태로 만들어, 몇 번을 돌려도 같은 결과가 나오는 (멱등한) 구조로 만들었습니다.

AI에게 '매번 이거 해줘'라고 부탁하는 것이 아니라, 메커니즘으로 매번 작동하게 합니다. 부탁은 AI가 잊을 수 있지만, 후크는 잊지 않습니다📜

🔁 /loop (기다리는 동안 맡김)

머신러닝 학습은 몇 시간이나 걸릴 때가 있습니다. 9월 20일에는 4가지 종류의 모델 학습 진행 상황을 /loop
으로 주기적으로 지켜보게 했습니다.

감시자를 맡기고, 인간은 멈췄을 때만 움직인다

실제로 입력한 것은 이것뿐입니다.

/loop 학습 진행 상황(xgboost/random_forest/lstm/transformer의 4개 모델 타입)을 주기적으로 확인한다

사람은 화면에 붙어있지 않아도 괜찮습니다. 멈췄다고 알려주는 것만으로도 충분히 고맙죠☕

🧩 워크트리(Worktree)와 서브 에이전트 (섞지 않기)

병렬로 진행하고 싶은 작업은, 작업용 복사본(git worktree)이나 다른 AI(서브 에이전트)에게 분리합니다. 끝나면 통합하고, 작업장은 정리합니다. 같은 작업 트리에 두 가지 변경 사항이 뒤죽박죽 되는 사고를 막아줍니다.

💰 마지막 관문: 로컬 CI와 결제 전 한 마디

푸시(push)하기 전에 GitHub Actions와 동일한 검사를 현지에서 모두 통과시킵니다.

이 절차는 프로젝트의 스킬(local-ci)에 정리되어 있으며, AI는 매번 이것을 실행한 후 '푸시해도 될까요?'라고 묻습니다. 그래도 CI가 실패하면 'CI 통과시켜'라는 한마디로 원인을 조사하고 고치게 합니다.

그리고 비용이 발생하는 작업 직전의 한 마디. 계획을 승인했더라도, 실제로 돈이 움직이는 실행(실제 LLM을 호출하는 E2E 검증 등) 전에는 다시 한번 확인받습니다.

📄 실수담: 하네스 사양서, 3시간 만에 수명을 다하다

실패한 것도 제대로 기록해둡니다😅

읽히지 않는 곳에 적은 약속은 금방 낡는다

9월 22일 15:00 AI와 함께, 하네스 설정을 정리한 '사양서'를 CLAUDE.md와는 별도의 파일로 추가했습니다. 깔끔하게 정리되어 있어 '좋은 것을 만들었다!'라고 생각했습니다 -
같은 날 정기 실행(celery-beat)의 시작 방침을 변경했습니다. AI는 CLAUDE.md를 고쳤지만, 사양서는 그대로였습니다. 게다가 사양서 안에서 표와 본문이 다른 상태가 되었습니다. 어디에서도 참조되지 않아 아무도 알아차리지 못했습니다👻 -
저녁 제가 'MD 파일에 중복 기술이 있으니 분류/정리하고 불필요한 것은 삭제해 달라'고 요청했습니다. AI가 모든 MD 파일(16개)을 재고 조사하여, 사양서가 CLAUDE.md와 거의 통째로 중복된다고 보고했습니다 -
18:11 가치가 있던 일부 정보(벡터 검색 API가 멈췄을 때의 증상)만 운영 문서로 옮긴 후 삭제했습니다. 만들고 나서 약 3시간밖에 안 되는 짧은 수명이었습니다🪦

한 일 / 못 한 일

한 일: 하네스의 약속은 AI가 매번 읽는 CLAUDE.md에 하나만 둡니다. 역할이 다른 계획서(동결)와 운영 문서(지속 업데이트)는 중복으로 간주하지 않고 남겨둡니다 -
못 한 일: 사양서를 고치고 두 권을 동기화하는 방안. 어디에서도 읽히지 않는 문서는, 고쳐도 다음 변경에 또 버려질 것이기 때문입니다 -
결정한 것은 인간: 정리와 삭제를 부탁하고, 남길 것과 지울 것의 경계를 승인한 것은 저였습니다. AI는 재고 조사와 정보를 잃지 않게 옮기는 것을 담당했습니다 - 삭제는
git rm

이므로, 내용은 git 히스토리에서 복원할 수 있습니다.

읽히지 않는 곳에 적은 약속은 금방 낡습니다. 그리고 오래된 약속은 AI를 '제대로 틀리게' 만듭니다.

🧰 시스템 선택 가이드 요약표

하네스는 사슬이 아니라 난간

🤝 요약: 이번 역할 분담

인간이 선을 그리고, AI가 선 앞에서 전력 질주한다

선을 그은 것은 인간🧭: 맡길 범위와 막을 범위, 어떤 시스템을 사용할지, 계획 승인과 결제 허가 -
달린 것은 AI🛠️: 계획 수립, 훅 스크립트, /loop에서의 감시, 로컬 CI 실행 및 수정 -
함께 실수한 것은 양쪽🤝: 이중 관리의 사양서. 만든 것도 둘이었습니다. 중복을 발견하고 정리를 부탁한 것은 인간, 재고 조사를 하여 정리한 것은 AI

다음은 【사건 기록】 편입니다. '타임머신으로 학습하기 - 과거일 리플레이 학습과 예산 15달러'. 과거의 시세를 하루씩 되돌려 AI에게 학습시키는 이야기입니다⏰

☕ note.com에서 개발 비화와 매일 아침 검증 로그 연재 중

note.com에서는 'ALPHA FORGE'의 개발 비화와, 매일 아침 알고리즘 검증 로그를 공개하고 있습니다.

👉 원문 기사 (note 연재 19화):

Discussion