하네스 엔지니어링 9단계 베스트 프랙티스 #5. 자동 트리거와 완료 조건

시리즈 맥락 복기

Step 0~4까지는 "사람이 명령을 치면 에이전트가 안전하게 실행한다"는 구조를 만들었습니다. 하지만 완전한 자동화는 사람 없이도 루프가 시작되고, 사람 없이도 완료가 판정되는 형태입니다. Step 5가 바로 이 두 가지 — 자동 시작과 자동 종료 — 를 담당합니다.

1. #0 업무 프로세스 매핑
2. #1 프로젝트 규칙 설정
3. #2 Code Wiki 작성
4. #3 Skill 정의
5. #4 검증(Hook)
6. #5 자동 트리거 + 완료 조건 ← 이번 편
7. #6 HITL 정책
8. ... (#8까지)

이 단계의 의미 — 하네스에서 Step 5의 역할

Step 5는 루프의 자율성을 높이는 단계입니다. 말에 비유하면, 지금까지는 기수(사람)가 항상 고삐를 쥐고 있었다면, 이제는 시간·이벤트·신호가 말을 출발시키도록 훈련하는 과정에 해당합니다. 동시에 "결승선 통과"를 기수가 아니라 기계가 판정하도록 조건을 설계합니다.

해결하려는 문제

• 반복적 시작 부담: "매일 아침 일정 동기화"를 사람이 매일 눌러야 한다면 자동화가 반쪽입니다.
• "이거 됐나?" 의심의 비용: 완료가 주관적이면 매번 눈으로 확인해야 합니다.
• 미묘한 실패 누락: 린트 경고 10개를 넘겨도 "돌아가긴 한다"며 넘어가는 경우.

효과 — 이게 되면 진짜 달라지는 것

자동 트리거 + 기계적 완료 조건이 결합되면, 사람은 예외 상황에만 개입하는 구조가 완성됩니다. 루프가 스스로 돌고, 통과 조건을 기계가 확인하니까요. 개인 경험상 여기까지 오면 "자동화가 정말 생산성을 올린다"는 실감이 확 듭니다.

자동 트리거 — 루프를 시작하는 5가지 이벤트 유형

트리거 유형	예시	적합한 작업
시간 (cron)	매일 새벽 2시, 15분마다	데이터 수집, 정기 정리, 헬스체크
GitHub 이벤트	PR 생성, Issue 등록, 코멘트	코드 리뷰, 이슈 분류, 라벨링
파일 변경 (watch)	특정 디렉토리 추가/수정	파일 인입 처리, 로그 분석
웹훅	Slack/Discord 메시지, CI 완료	배포 후 검증, 알림 기반 작업
메시지 기반	Telegram 메시지, 이메일 수신	원격 명령, 모바일에서 트리거

실제 운용 예시 — cron 기반

# 개인 서버 crontab 예시
0 1 * * *   일정 동기화
0 2 * * *   벡터 DB 재색인
0 3 * * *   사진 inbox 처리
*/15 * * * * GPU 유휴 작업 정리

트리거 설계 3원칙

1. 멱등(idempotent)하게: 같은 트리거가 두 번 걸려도 결과가 달라지지 않도록. 파일 처리 시 이미 처리된 건은 스킵.
2. 시간 간격으로 충돌 방지: 같은 자원을 쓰는 작업은 5~15분 간격을 두세요. 우리 예시에선 PR은 10:00, Issue는 10:05.
3. 실패 재시도 가능한 구조: 한 파일이 실패해도 다음 파일은 진행. 부분 실패가 전체를 막지 않게.

완료 조건 — "끝났다"를 기계가 판정하기

사람이 "됐다"라고 말할 필요 없이, 숫자나 exit code로 완료를 정의합니다.

완료 조건	판정 방법	적합한 작업
유닛 테스트 통과	pytest / jest exit 0	코드 변경 후 자동 검증
빌드 성공	make / npm run build exit 0	컴파일 가능 상태 보장
린트 통과	eslint / ruff 경고 0	스타일 준수 확인
타입 체크 통과	mypy / tsc 에러 0	타입 안전성 보장
커버리지 기준 충족	커버리지 N% 이상	테스트 충분성 보장
E2E 시나리오 통과	Playwright/Cypress 전체 성공	사용자 흐름 확인
보안 스캔 통과	trivy / snyk 취약점 0	보안 요구사항
diff 없음	git diff --exit-code	자동 생성물 최신 상태

"diff 없음"은 왜 완료 조건이 되는가

표의 다른 항목(테스트 통과, 빌드 성공 등)은 직관적인데, "diff 없음"만은 처음 보면 이게 검증과 무슨 상관인가 싶습니다. 핵심만 먼저 말하면 이렇습니다. git diff --exit-code는 "작업 디렉토리에 커밋 안 된 변경이 있으면 exit 1, 없으면 exit 0"을 돌려주는 명령입니다. 이걸 완료 조건으로 쓰는 이유는 "자동 생성물이 원본과 싱크가 맞는가"를 기계적으로 검증하기 위해서입니다.

무슨 말인지 구체 시나리오로 풀어보죠. 현대 프로젝트에는 사람이 직접 쓰지 않고, 스크립트가 만들어내는 파일이 많습니다.

• protobuf → Python/TypeScript 스텁: .proto 원본을 고치면 *_pb2.py를 다시 생성해야 함.
• OpenAPI spec → 클라이언트 코드: spec을 고치면 클라이언트 SDK를 재생성해야 함.
• ORM 스키마 → 타입 파일: Prisma·SQLAlchemy 스키마를 고치면 타입이 자동 생성됨.
• 포매터 자동 수정: ruff format, prettier --write 같은 것도 비슷한 성격.

이런 "원본이 바뀌면 자동으로 재생성되어야 하는 파일"이 있을 때, 실수로 원본만 고치고 재생성을 안 돌리는 사고가 자주 납니다. 이 경우 자동 생성물은 현실과 어긋난 스테일(stale) 상태가 되죠.

그래서 CI나 Hook에서 이런 2단계 파이프라인을 두면 해결됩니다.

# 1. 자동 생성 스크립트를 돌린다
make generate         # 또는 prisma generate, openapi-gen 등

# 2. 그 결과 diff가 생기면 실패
git diff --exit-code

자동 생성물이 원본과 싱크가 맞았다면, 스크립트를 돌려도 파일 내용이 그대로라 diff가 없습니다(exit 0). 반대로 누군가 원본만 고치고 재생성을 안 돌린 상태라면, 스크립트가 돌린 결과로 파일이 변하면서 diff가 생기고(exit 1) 즉시 실패합니다.

하네스 관점에서 이 검증이 특히 유용한 이유는, AI가 "다 수정했다"라고 주장하는 순간에도 객관적으로 확인할 수 있기 때문입니다. 원본 스키마를 건드렸으면서 자동 생성물을 재생성하지 않았다면, git diff --exit-code가 exit 1을 돌려줘 "아직 완료 아님"을 알려줍니다. 포매터도 마찬가지로 "이 코드는 포맷 규칙에 맞는가"를 같은 방식으로 검증할 수 있습니다.

조합 예시 — PR 완료 조건

개별 조건을 AND로 묶으면 강력한 품질 게이트가 됩니다.

빌드 성공 AND 테스트 전체 통과 AND 린트 경고 0 AND 타입 에러 0

이 조건들을 CI에 넣으면 사람 리뷰 전에 기계가 먼저 거릅니다. Hook에 넣으면 AI가 작업 완료를 주장하기 전에 기계가 확인합니다.

완료 조건 설계 3원칙

1. 숫자나 exit code로 판정: "잘 되는 것 같다"는 완료 조건이 아닙니다. exit 0 여부가 유일한 기준.
2. 여러 조건을 AND로 묶기: 테스트만 통과하고 린트를 안 보면 완료가 아닙니다.
3. 실패 시 구체적 이유 전달: "3번째 테스트에서 AssertionError" 식으로 전달해야 AI가 자동 수정할 수 있습니다.

자주 빠지는 실수

• "루프가 돌고 있다"는 착각: cron 등록만 하고 실제 실행 로그를 안 보면, 한 달째 실패 중인 작업을 모를 수 있습니다. #7 감사 로그 단계에서 이를 보완합니다.
• 완료 조건을 너무 느슨하게: "오류 없으면 OK"만 두면 경고를 무시합니다. 경고도 지표로 둬야 품질이 유지됩니다.
• 트리거끼리 자원 충돌: cron 여러 개가 동시에 GPU를 잡으려 할 때 스케줄러(GPU 스케줄러)가 없으면 쓰러집니다.

다음 단계 예고 — Step 6 HITL 정책

자동 트리거가 늘어날수록 "사람의 개입 지점을 어디에 둘 것인가"가 중요해집니다. 다음 편에서는 위험도 공식(비가역성 × 영향 범위)과 이중 방어 설계를 통해 Allow/Ask/Deny를 구조화하는 방법을 다룹니다.

한 줄 요약: "자동화는 '사람이 시작하지 않아도 되는 루프'와 '사람이 확인하지 않아도 되는 완료 조건'이 만나야 완성된다."

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.