하네스 회고 — 무엇에 신경 썼고, 어디가 한계였고, 무엇을 배웠나

정리: 2026-08-11
대상 기간: 2026-07-03 ~ 2026-07-08
출처: 작업순서.txt(원본 지시), 0_HARNESS_PROCESS.md(실행 스펙), HARNESS_LOG.md(실행 기록 60건),
      .claude/skills/harness/SKILL.md(실행기)

이 문서는 하네스를 다시 만들거나 다른 프로젝트로 옮길 때 읽는 회고다. 절차 자체의 정의는
0_HARNESS_PROCESS.md 에 있고, 여기 있는 것은 그 절차가 왜 그 모양이 됐는가이다.


────────────────────────────────────────────────────────────────────────
0. 무엇을 만들었나
────────────────────────────────────────────────────────────────────────

클라이언트 요구에서 목업까지를 9단계로 쪼개고, 요구가 바뀌면 영향받은 단계만 다시 도는
반복 절차. 원본 지시는 A4 한 장(작업순서.txt)이었고, 6일간 돌리면서 그 위에 보강 규칙
22개가 붙었다.

9단계
  1 요구 정의 → 2 설계 → 3 기능 정의 → 4 구체화 시나리오 → 5 데이터 실현가능성 →
  6 우선순위 → 7 묶음 시나리오 → 8 목업 → 9 피드백 재진입

규모
  실행 기록 60건 (2026-07-03 ~ 07-08), 마지막은 35차 cascade
  단계별 실행 횟수: 5단계 15회, 2단계 12회, 8단계 11회, 3단계 10회, 4단계 8회, 7단계 8회,
                    6단계 6회, 9단계 5회, 1단계 4회
  보강 규칙 22개 (①~㉒, 7차에 걸쳐 승인)

단계별 횟수가 균등하지 않은 것이 이 절차의 성격을 보여준다. 5단계(데이터 실현가능성)가
제일 많이 돌았다. 기획이 흔들린 것이 아니라 "그 데이터를 진짜 구할 수 있나"가 계속 뒤집혔다.


────────────────────────────────────────────────────────────────────────
1. 신경 썼던 것
────────────────────────────────────────────────────────────────────────

1-1. 근거의 출처를 항상 세 갈래로 (원본 지시)

  참고자료 기반 / 자체 분석(의견) / 불명확. 원본 지시에 이미 있던 요구이고, 여기에
  "참고자료에 있다는 사실 자체는 우선순위·신뢰도 근거가 아니다"라는 단서가 붙어 있었다.

  이 단서가 실전에서 가장 자주 위협받았다. 그래서 규칙이 두 번 더 늘었다.
    ⑪ 스펙에만 적지 말고 산출물 본문마다 "이 인용은 참고 제안일 뿐"을 직접 남길 것.
       문서만 읽는 사람은 "PDF에 있으니 중요한가 보다"로 읽는다.
    ⑫ 애초에 이번 실행에서 그 자료를 써도 되는지 매번 사용자에게 먼저 물을 것.

1-2. 한 번 쓰는 기획서가 아니라 다시 돌 수 있는 절차

  원본 지시의 "요구가 수정되면 반복적으로 재조정"을 두 장치로 구현했다.

    9단계(피드백 → 1단계 재진입). 원래 지시는 1→8 한 방향이라 목업을 만들면 끝이었다.
    닫힌 루프가 없으면 하네스가 아니라 일회용 문서 생산기다.

    cascade. 상위 단계가 바뀌었다고 전부 다시 쓰지 않고, 실제로 영향받은 부분만 다시 본다.
    실행 기록 60건 중 대부분이 이 모드다.

1-3. 검증을 "확인"이 아니라 "반박"으로

  ③ 5·7단계 병렬 검증은 "이 결론이 맞는지 봐"가 아니라 "이 결론이 틀렸다면 왜인지 찾아봐"로
  지시한다. 계기가 정직하다. 어떤 판정이 뒤집힌 것이 검증 절차 덕분이 아니라 우연이었다
  (사용자가 다른 목적으로 데이터를 열어봤다가 발견). 확인형 검증은 확증편향으로 흐른다.

  여기에 결과 처리 규칙이 붙었다.
    ⑤ 반박이 하나라도 성공했고 재반박 근거가 없으면, 판정을 맞다/틀리다로 두지 말고
       한 단계 낮춘다 (완전자동 → 조사선행).

1-4. 자기 채점 금지

  ⑧ 각 단계는 완료조건(DoD) 체크리스트를 갖고, 작성한 에이전트가 아닌 독립 에이전트가
     pass/fail 을 매긴다.
  ⑬ 초안만 맡긴 서브에이전트는 파일을 쓰지 않고 스스로 통과 판정도 하지 않는다.
     텍스트로 반환만 한다. 파일 기록과 게이트는 메인 대화의 몫으로 남긴다.

1-5. 이진 판정을 피하기

  5단계 실현가능성 라벨은 5종이다.
    완전자동 / 반자동-고정 / 조사선행 / 인프라선행 / 완전불가능

  그리고 "완전자동"과 "완전불가능"은 실제 조사 없이 단정 금지다. 조사가 안 됐으면 조사선행이다.
  가능/불가능 두 칸만 있으면 모르는 것이 둘 중 하나로 반올림된다.

1-6. 판정에 유효기간을 붙이기

  ② 모든 "확인됨"에 (확인: YYYY-MM-DD). 데이터 소스가 자동 수급 가능하다는 판정은 그 시점의
     사실이지 영구적 진실이 아니다.
  ⑦ 그래서 자동판단 모드는 가장 오래된 검증일자부터 재검증 후보로 올린다.
     날짜 없는 "확인됨"은 규칙 위반으로 보고 신뢰하지 않는다.

1-7. 진단 가능성을 위해 일부러 비효율을 남기기

  3단계(기능 정의)와 6단계(우선순위)는 같은 문서를 쓴다. Claude 가 "게이트·로그도 합쳐서
  한 번만 확인받자"고 제안했고 사용자가 반려했다(⑩). 이유는 우선순위가 나중에 이상해 보일 때
  3단계에서 잘못됐는지 6단계에서 잘못됐는지 구분해서 진단하고 싶은데, 합치면 그 경계가
  사라진다는 것이었다.

  효율보다 사후 추적 가능성을 택한 결정이고, 이 회고에서 가장 재사용할 만한 판단이다.

1-8. 조용히 바꾸지 않기

  - 사용자가 이미 확정한 결론(취소된 기능, 우선순위)을 근거를 보여주고 승인받기 전에는
    뒤집지 않는다.
  - 재작업할 때 구버전과 대조해 구체적 논증·실측 수치·인용이 조용히 빠지지 않았는지 점검한다.
    근거 파일이 사라져 재확인이 안 되는 내용은 삭제하지 않고 불명확으로 남긴다.
  - 정정은 로그뿐 아니라 산출물 본문에도 남긴다.

1-9. 절차 자체를 매 실행 끝에 회고하기

  실행이 끝나면 하네스 절차에 허점이 없었는지 스스로 점검하고, 있으면 개선안을 제시하되
  자체 적용은 하지 않고 승인부터 받는다. 규칙 22개가 이 경로로 쌓였다. 그리고 아래에서
  보듯 이것이 강점이자 한계였다.


────────────────────────────────────────────────────────────────────────
2. 한계
────────────────────────────────────────────────────────────────────────

2-1. 규칙을 늘려서 문제를 고치는 방식은 수확이 체감한다

  22개는 A4 한 장짜리 지시에 비해 너무 많다. 게다가 뒤로 갈수록 성격이 달라진다. 초반(①~⑧)은
  절차의 골격이지만, 후반(⑲~㉒)은 번호 매기는 법, 절 참조 쓰는 법, 오타 발견 시 침묵 금지
  같은 표기 규약이다. 절차 문서가 스타일 가이드를 겸하기 시작하면 아무도 전부 기억하지 못한다.

2-2. 규칙이 있어도 지켜지지 않는다 — 체크리스트로 강제되지 않으면

  가장 뼈아픈 사례가 마지막 실행(35차 cascade)에 기록돼 있다.

    여러 cascade 에 걸쳐 "lab_forecasts 0행"이라고 반복 인용해온 것이 로컬 SQLite 오조회였다.
    실제 운영 AlloyDB 에는 470,896행이 있었고 배치는 이미 4개월 가까이 정상 가동 중이었다.
    이 오류가 6개 문서에 퍼졌고, 그 판정을 근거로 관리자에게 IAM 권한 요청까지 보낸 상태였다.

  근본 원인은 규칙이 없어서가 아니다. ⑯(라이브 검증은 어떤 환경·설정으로 돌았는지까지 명시)이
  이미 정확히 이 실수를 예견하고 있었다. 다만 게이트 체크리스트 항목으로 강제되지 않아서
  그냥 넘어갔다. 문서에 적힌 규칙과 실제로 걸리는 체크리스트는 다른 물건이다.

2-3. 강한 근거일수록 더 위험할 수 있다

  "직접 DB 를 조회했다"는 가장 강한 종류의 근거로 취급된다(⑰이 요구하는 실측 수준). 그런데
  위 사례에서 오도한 것이 바로 그 직접 조회였다. 약한 근거는 약한 줄 알고 쓰지만, 강한 근거는
  검증 대상에서 빠진다. 실측일수록 무엇을 실측했는지를 같이 적어야 한다.

2-4. 발견이 우연에 의존했다

  초기 발견 3건(T1 출처 오분류, T6 문서 간 불일치, P1 취소 근거 오류)이 전부 다른 작업을
  하다가 우연히 나왔다. ⑥(정합성 자동 점검)이 그래서 생겼지만, 이것은 절차의 구멍을 절차로
  메운 것이 아니라 우연을 제도화하려는 시도에 가깝다. 실제로 그 뒤에도 게이트가 못 잡은
  것들이 있었다.

2-5. 같은 판정이 여러 곳에 살아서 동기화 비용이 계속 든다

  하나의 판정이 표 셀, 서술 문단, 다른 문서의 인용 세 곳에 존재한다. 서술만 고치고 표를
  빠뜨린 사고가 나서 ⑳(정정 시 전 위치 동시 갱신 후 이전 판정 문자열 grep 잔존 확인)이
  생겼다. 규칙으로 막긴 했지만, 근본적으로는 같은 사실을 여러 곳에 복사해 두는 구조 자체의
  비용이다.

2-6. 번호 체계가 생각보다 약했다

  ⑲ 문서별 로컬 "N차 정정" 카운터와 세션 전역 cascade 라운드 번호를 혼동해 존재하지 않는
     5차 정정을 인용했다.
  ㉑ 문서 접두어 없는 절 참조(예: 6-3-1)가 어느 문서인지 모호했다. ⑬~⑯을 추가한 뒤에도 재발했다.

  절 번호와 회차 번호는 사람에게는 편하지만 여러 문서에 걸치면 곧바로 충돌한다.

2-7. 내용 검증과 표기 검증은 다른 축이다

  "신뢐성"이라는 오타가 8개 파일에 퍼진 채, 내용 정확성을 집요하게 파던 게이트를 전부 통과해
  사용자가 직접 발견할 때까지 남았다(㉒). 게이트가 무엇을 보도록 설계됐는지에 따라 보지 않는
  것은 완전히 안 본다.

2-8. 산출물이 제품과 갈라진다

  하네스 산출물은 docs/frontend/1_ ~ 8_ 이고, 실제 제품은 그 뒤로 계속 움직였다. 지금 화면의
  정본은 코드이고 대시보드 설명은 docs/BUYER_DASHBOARD_GUIDE.md 가 맡는다. 기획 절차의
  산출물은 시간이 지나면 "그때 왜 그렇게 정했나"의 기록으로 성격이 바뀐다. 이것을 최신
  명세로 착각하면 위험하다.

2-9. 유지비

  마지막 실행이 2026-07-08 이다. 그 뒤 프로젝트 국면이 기획에서 검증·배선으로 넘어가면서
  자연히 멈췄다. HARNESS_LOG.md 는 216KB 로 남았다. 도구가 멈춘 것 자체는 실패가 아니지만,
  멈춘 도구를 어떻게 보관할지(스킬은 남기나, 로그는 어디까지 남기나)는 정해두지 않았다.


────────────────────────────────────────────────────────────────────────
3. 배운 것
────────────────────────────────────────────────────────────────────────

1) 규칙은 문서에, 강제는 체크리스트에.
   규칙을 적는 것과 그 규칙이 실제로 실행을 막는 것은 다른 일이다. 규칙을 추가할 때는
   "이건 어느 게이트의 어느 항목이 되는가"를 같이 정해야 한다. 그러지 않으면 2-2 처럼
   이미 예견했던 실수를 그대로 저지른다.

2) 작성자와 채점자를 분리하면 실제로 잡힌다.
   독립 게이트가 잡아낸 사고가 로그에 반복적으로 기록돼 있다(문서-목업 불일치, 존재하지
   않는 정정 인용, 같은 문서 안 모순 판정 등).

3) "확인해봐"보다 "틀렸다면 왜인지 찾아봐"가 낫다.
   그리고 반박이 절반만 성공했을 때 판정을 한 단계 낮추는 사다리가 있어야 한다. 없으면
   검증했는데 반영할 방법을 몰라 무시하게 된다.

4) 부재 증명은 grep 으로 안 된다(⑮).
   grep 은 그 검색어를 못 찾았다만 증명한다. 다른 이름·다른 위치로 존재할 수 있다.
   "없다"고 쓰기 전에 후보 파일 하나는 통째로 읽는다.

5) 실측을 인용할 때는 실측 환경을 함께 인용한다(⑯).
   어느 DB, 어느 설정, 어느 플래그였는지 없이 "직접 돌려봤다"는 근거는 오히려 검증을
   건너뛰게 만든다.

6) 모른다는 상태에 이름을 주면 판단이 정직해진다.
   조사선행·인프라선행이라는 칸이 있으니 일단 불가능으로 반올림하지 않게 됐다.

7) 판정에는 날짜를, 재검증은 오래된 것부터.
   외부 의존(API·크롤링·권한)은 시간이 지나면 참이 거짓으로 변한다. 유효기간 없는 사실
   주장은 다음 세션을 오도한다.

8) 효율을 포기하고 추적 가능성을 사는 결정은 값어치를 한다(⑩).
   합치면 편하지만, 나중에 어느 단계에서 틀어졌나를 물을 수 없게 된다.

9) 절차 자체를 회고 대상에 넣으면 절차가 자란다. 그리고 비대해진다.
   자기 개선 루프는 규칙을 낳고, 규칙은 22개가 됐다. 자라는 것은 좋지만 정리하는 단계
   (규칙 통폐합)가 루프에 없었다.


────────────────────────────────────────────────────────────────────────
4. 다시 만든다면 (제안)
────────────────────────────────────────────────────────────────────────

- 규칙을 두 층으로 분리한다. 절차 골격(반드시 게이트 항목이 있는 것)과 표기 규약(린트로
  기계 검사할 것). 지금은 둘이 같은 목록에 섞여 있다.

- 새 규칙을 추가할 때 "이 규칙이 실패하면 어느 게이트가 FAIL 을 내는가"를 필수 필드로
  요구한다. 답이 없으면 규칙이 아니라 권고로 분류한다.

- 정합성 린트(⑥)를 실행 시작이 아니라 저장 시점에 건다. 날짜 없는 "확인됨", 문서 접두어
  없는 절 참조, 표와 서술의 판정 불일치는 전부 기계가 잡을 수 있는 것들이다.

- 판정 사실(라벨·검증일자)은 문서 본문이 아니라 한 곳(예: 작은 YAML 이나 표)에 두고
  문서가 참조하게 한다. 2-5 의 3중 동기화 비용이 사라진다.

- 멈출 때의 처리를 절차에 넣는다. 마지막 실행 이후 N일이 지나면 로그를 접고 회고를 남기는
  단계(이 문서가 그 자리에 해당한다).


────────────────────────────────────────────────────────────────────────
부록 A. 보강 규칙 22개 색인 (한 줄 + 계기)
────────────────────────────────────────────────────────────────────────

①  9단계(피드백 → 1단계 재진입) 추가          — 1→8 단방향이면 일회용 기획서
②  "확인됨"에 검증일자 필수                    — 데이터 수급 판정은 그 시점의 사실
③  5·7단계 검증은 반박 시도로 프레이밍         — 판정 뒤집힌 것이 절차가 아니라 우연이었음
④  목업을 1단계 질문(Q1~Q8)과 태깅             — "예쁜가"가 아니라 "답이 되는가"로
⑤  반박 부분 성공 시 판정 한 단계 낮추기       — 이진 유지도 무시도 부정직
⑥  정합성 자동 점검(출처유형·날짜·상호참조)    — 발견 3건이 전부 우연
⑦  자동판단은 가장 오래된 검증일자부터         — ②를 실제로 쓰는 경로
⑧  단계별 DoD + 독립 에이전트 게이트           — 자기 채점의 맹점
⑨  인자 없는 /harness 는 사용법 먼저           — 호출법을 매번 기억해야 했음
⑩  3·6단계는 문서 공유해도 게이트·로그 분리    — 사용자 반려, 원인 추적 우선
⑪  "참고자료=참고 제안"을 산출물 본문에 명시   — 스펙에만 있으면 문서 읽는 사람이 오해
⑫  매 실행 시작 시 참고자료 사용 동의 확인     — 쓰고 싶지 않은 자료가 있을 수 있음
⑬  초안 서브에이전트는 파일 쓰기·자기 채점 금지 — 초안 단계에서 이미 자기 채점 발생
⑭  8단계 DoD 에 문서-아티팩트 정합성           — 같은 세션에서 두 번 재현된 사고
⑮  부재 주장은 전체 파일 읽기 없이 금지        — grep 으로 "없다"고 했다가 있었음
⑯  라이브 검증은 환경·설정까지 명시            — 격리 환경인 줄 알았는데 운영 설정
⑰  반박검증은 실제 Agent 호출만 인정           — "자체 검토했다" 문장으로 대체된 사례
⑱  5단계 새 판정 전 같은 소스 기존 절 검색     — 한 문서 안에 모순 판정 공존
⑲  "N차"는 로그 기준 전역 번호                 — 존재하지 않는 5차 정정 인용
⑳  정정은 표+서술+타 문서 동시 갱신 후 grep    — 표 셀 갱신 누락
㉑  절 참조는 소속 문서 명시                    — 번호 충돌로 모호, 재발
㉒  게이트는 표기·오타 이상도 침묵하지 않음     — 오타가 8개 파일에 퍼진 채 전 게이트 통과


────────────────────────────────────────────────────────────────────────
부록 B. 파일 위치
────────────────────────────────────────────────────────────────────────

docs/harness/작업순서.txt              원본 지시(사용자 작성)                         1.4KB
docs/harness/0_HARNESS_PROCESS.md      실행 스펙 — 9단계 정의·공통 규칙·보강 규칙 22개  44KB
docs/harness/HARNESS_LOG.md            실행 기록 60건                                216KB
docs/harness/하네스_사용법.txt          사용자용 요약                                    6KB
.claude/skills/harness/SKILL.md        실행기(/harness)

주의: 위 중 0_HARNESS_PROCESS.md, HARNESS_LOG.md, 작업순서.txt 는 /harness 스킬이 실행 시점에
직접 읽는다. 지우면 스킬이 동작하지 않는다.