운영 교훈 · 문제 해결

하네스를 운영하며 실제로 부딪힌 것들입니다. 새 프로젝트에서 같은 데서 넘어지지 않도록 증상 → 원인 → 대처 순으로 적습니다.

에이전트 · 러너

증상	원인	대처
처리가 자꾸 중간에 끊긴다	모델이 배포를 기다리다 턴을 끝내거나 머지 타임아웃 — 실패 9번 모두 「모델이 운전하던 주변」	모델은 `plan.json` 까지만, 나머지는 스크립트로
GitHub self-hosted job 이 버려지고 에이전트도 죽는다	Mac 의 러너 연결이 15~25분마다 끊김	러너를 GitHub job 밖 launchd 로
launchd 에서 저장소를 못 읽는다	macOS 보호 폴더(Desktop 등) 접근 제한	신뢰 사본을 홈 아래 숨김 폴더에
러너가 머지했는데 검사 · 배포가 안 돈다	`GITHUB_TOKEN` 으로 만든 이벤트는 다른 워크플로를 깨우지 않음	러너 Mac 의 gh 로그인 사용
allow 규칙이 적용되지 않는다	그 폴더에서 신뢰 창을 수락하지 않음	사본 폴더에서 `claude` 를 한 번 열어 수락
같은 작업을 재시도하면 「시작하지 않음」	두 번째 에이전트가 첫 번째의 파일을 보고 미커밋 변경으로 판단	재시도하는 오케스트레이터 대신 단일 실행 · 깨끗한 트리
막힌 명령이 다른 꼴로 실행됐다	권한 규칙은 문자열 대조	지시문에 「꼴 바꿔 재시도 금지」, 산출물 경계 검사로 이중 차단

처음 생각	재 보니	바꾼 것
Figma 호출이 느리다	호출은 0.2초, 23분의 원인은 모델이 옮겨 적는 코드 분량	빌더를 문서에 한 번 저장 + 해시 검사 → 42단계 → 23단계
「조각 내용이 바뀌었다」 오류는 파일 문제	단계 파일은 모두 일관됨, 모델의 전사 실수	단계 상한을 줄이고, 의심되면 로컬에서 해시를 다시 계산해 본다
Figma 를 거치면 화면이 더 정확하다	A/B: 요청과 어긋난 곳 4~5건 vs 0~1건	Figma 는 정본이 아니다 → 처리 흐름에서 제거
단계 순서를 묶어 빨리 돌리자	뒤 단계의 부모가 앞 단계에서 정해짐	단계는 절대 재배열 · 생략하지 않는다

검사가 안 돌고 있는 줄 몰랐다. 루트 check 가 한 앱만 빌드 · 테스트해서 생성 화면 테스트가 CI 에 없었습니다. 리뷰어 에이전트가 찾았습니다. 「무엇을 검사하는지」도 검사 대상입니다.
같은 나무를 두 번 재지 않는다. dev 에서 검사한 커밋을 main 에서 또 검사하지 않습니다(네 번 → 두 번). 볼 것 없는 실행은 취소합니다.
gh pr checks --watch 는 너무 일찍 끝날 수 있다. PR 을 만든 직후엔 검사가 아직 등록되지 않아 「없음」으로 끝납니다. head SHA 로 실행 목록을 먼저 확인합니다.
브라우저 검사는 포트를 나눈다. 여러 캡처를 동시에 돌리면 기본 DevTools 포트가 겹쳐 멈춥니다. 명령마다 포트를 따로 줍니다.
에이전트 worktree 는 디스크를 먹는다. .claude/worktrees/ 를 gitignore 하고 끝나면 정리합니다.

빌드는 초록인데 색이 빈다 → 브랜드 변수 주입 누락. 새 프로젝트 A 단계 참고.
이름과 실제가 다른 변형 → 리뷰에서 「…·medium」 이름이 실제로는 small 로 그려지는 것을 찾았습니다. 견본은 이름이 아니라 렌더 결과로 검사합니다.
Base UI 상태 속성은 빈 문자열 → data-checked="" 이므로 값 비교가 아니라 hasAttribute 로 봅니다.
테스트에서 라벨 이중 매칭 → 체크박스 필드는 getByLabelText 가 두 개를 잡습니다. getByRole("checkbox") 를 씁니다.