execution-loop

name	execution-loop
description	구현 후 REJECTED 판정이 나오거나 '/execution-loop'을 입력하면 반드시 이 스킬을 사용할 것. 'fix it', 'retry', 'auto-fix', 'keep trying', 'iterate until passing', 'loop until approved'가 포함된 요청도 해당. 합격 기준 충족까지 수정→검증→반복을 자동화한다. 최대 5회 반복, 루프 상태를 .execution-loop-state 파일에 기록한다.

execution-loop 스킬

하네스 엔지니어링의 4대 구성 요소 중 하나인 실행 루프를 구현합니다. 단순히 기능을 만드는 것을 넘어, 합격 기준을 충족할 때까지 수정·검증·반복을 자동화합니다.

단계 0 — 스프린트 계약 사전 확인 (코드 작성 전 필수)

Anthropic $9 vs $200 연구 핵심: 단일 에이전트와 하네스의 가장 큰 차이는 "완료의 의미를 사전에 합의했는가"입니다.

스프린트 계약 없으면 코드 작성 금지. 아래 순서를 반드시 지킵니다:

1. .execution-loop-state 확인 → 이전 루프 미완료이면 이어서 진행
2. 스프린트 계약 확인 → 없으면 아래 템플릿으로 계약 작성
3. 사용자 승인 받기 → 승인 후 코드 작성 시작
4. 루프 시작 기록 → .execution-loop-state 파일 업데이트

스프린트 계약 템플릿 (계약 없으면 여기서 멈추고 작성):

스프린트 계약: [기능명]
contract_status: DRAFT → APPROVED (사용자 승인 후 변경)

완료 조건 (모두 작동해야 "완료"):
- [ ] [구체적이고 테스트 가능한 조건 1]
- [ ] [구체적이고 테스트 가능한 조건 2]

비완료 조건 (이번 범위 밖):
- [다음 스프린트로 미루는 항목]

.execution-loop-state 파일 포맷:

# 루프 시작 시 (계약 승인 후)
echo "루프 N/5 진행 중 — [기능명] — contract_status: APPROVED — $(date +%Y-%m-%d)" > .execution-loop-state

# 루프 완료 시
echo "완료 — [기능명] — VERDICT=APPROVED — $(date +%Y-%m-%d)" > .execution-loop-state

규칙: contract_status: APPROVED 없이 코드를 작성했다면 그 구현은 무효입니다. 계약 승인을 먼저 받으세요.

---

세션 시작 의식 (Session Init Protocol)

새 세션을 시작할 때, 코드 작성 전에 반드시 아래 순서를 실행합니다.

Anthropic $9 vs $200 연구: 중단된 세션을 맥락 없이 재개하면 이전 작업을 덮어쓰거나 중복 구현하는 실패가 반복됩니다.

1. progress.md 읽기       ← 현재 완료/진행/차단 상태 파악
2. architecture.md 읽기   ← 시스템 구조, 파일 위치 파악
3. 스프린트 계약 확인      ← 이번 세션의 완료 조건이 명시돼 있는가?
4. 마지막 커밋 확인        ← git log --oneline -5

스프린트 계약이 없으면 → 코드 작성 전에 계약부터 확정합니다 (아래 [스프린트 계약] 참조).

---

스프린트 계약 (Sprint Contract)

Anthropic 연구: 단일 에이전트($9)와 하네스($200)의 결정적 차이는 "완료의 의미를 사전에 합의했는가"였다.

루프 시작 전 반드시 측정 가능한 완료 조건을 합의합니다. 이것이 verify 단계의 채점 기준이 됩니다.

템플릿은 단계 0 참조. 모호한 조건("제대로 동작", "좋게") = 계약 무효. 재작성하세요.

---

루프 상태 추적

각 루프 시작/종료 시 .execution-loop-state 파일을 갱신한다. settings.json 훅이 세션 시작 시 이 파일을 읽어 현재 루프 상태를 표시한다.

# 루프 시작 시
echo "루프 N/5 진행 중 — [기능명] — $(date +%Y-%m-%d)" > .execution-loop-state

# 루프 완료 시
echo "완료 — [기능명] — VERDICT=$(bash .claude/skills/verify/verify.sh 2>/dev/null | grep -oE 'VERDICT=[A-Z]+') — $(date +%Y-%m-%d)" > .execution-loop-state

이 파일이 있으면 새 세션 시작 시 "이전 루프가 미완료 상태입니다" 알림이 표시됨.

---

사용 방법

/execution-loop [기능 설명]을 구현해줘.
예: /execution-loop 학생 퀴즈 응시 기능을 구현해줘.

---

실행 루프 구조

┌─────────────────────────────────────────┐
│             실행 루프 시작               │
│    (세션 시작 의식 + 스프린트 계약 후)   │
└──────────────────┬──────────────────────┘
                   │
          ┌────────▼────────┐
          │  1. Planner     │  계획 수립 + 사용자 승인
          │  작업 분해      │  (3단계 이상이면 승인 필수)
          └────────┬────────┘
                   │ 승인
          ┌────────▼────────┐
          │  2. Coder       │  구현 + 단위 테스트 작성
          │  코드 작성      │
          └────────┬────────┘
                   │
          ┌────────▼────────┐
          │  3. 검증 단계   │  자동 검증 실행
          │  (멀티 관점)    │
          └────────┬────────┘
                   │
          ┌────────▼────────┐
          │  합격 기준 충족?│
          └──┬──────────────┘
             │          │
           아니요       예
             │          │
    ┌────────▼──┐  ┌────▼────────────┐
    │  수정 목록 │  │  완료 + 보고서  │
    │  작성      │  │  progress.md    │
    └────────┬──┘  │  업데이트       │
             │     └─────────────────┘
             │ (최대 5회)
    ┌────────▼────────┐
    │  2. Coder로 복귀│
    └─────────────────┘

---

검증 단계 상세

각 루프의 검증은 6개 차원 루브릭 (docs/verification-rubric.md)을 따릅니다.

A. 자동 검증 (즉시 실행 — 차원 1, 2, 5 일부)

pre-commit 훅이 자동 처리하는 항목:

npm run lint          # 차원 1: 코드 품질
npx tsc --noEmit      # 차원 1: 타입 안전성
npm test              # 차원 1: 테스트
# + 차원 2: 평가 무결성 (isCorrect 노출 감지)
# + 차원 5: 비밀 정보 하드코딩 감지
# + 차원 3: 부정적 피드백 메시지 경고

B. verify 스킬 실행 (6개 차원 전체)

/verify [기능명]을 검증해줘.

결과: APPROVED / CONDITIONAL / REJECTED 판정 + 차원별 상세 보고

C. Pedagogy Reviewer (교육 기능 해당 시만)

verify 스킬에서 교육학적 항목에 의문이 생길 때 추가 실행:

[Pedagogy Reviewer] 방금 구현한 기능을 검토해줘.
docs/education-principles.md를 기준으로 교육적으로 해로운 요소를 찾아줘.

---

합격 기준 (루프 종료 조건)

docs/verification-rubric.md의 합격 조건 기준:

✅ APPROVED 판정 조건
   - [ ] CRITICAL 항목 0개 실패 (차원 2 평가 무결성, 차원 5 보안)
   - [ ] HIGH 항목 100% 통과 (또는 예외 documented)
   - [ ] MEDIUM 항목 80% 이상 통과

✅ 작업 정리
   - [ ] progress.md 업데이트 완료
   - [ ] .execution-loop-state 파일에 완료 상태 기록
   - [ ] 변경 요약 한 문장으로 작성

CONDITIONAL 판정 (MEDIUM 미통과) → 기술 부채 등록 후 진행 가능

---

무한 루프 방지

최대 반복 횟수: 5회

5회 후에도 합격 기준 미충족 시:
→ 현재 상태 보고
→ 미충족 항목 목록 제시
→ 사용자에게 방향 결정 요청
→ 루프 일시 중단

재개 명령: "/execution-loop 이전 루프를 이어서 계속해줘."

---

루프 보고서 형식

루프 완료 또는 중단 시 다음 형식으로 보고합니다:

실행 루프 보고: [기능명]

반복 횟수: N회
최종 상태: 완료 / 중단 (이유)

이번 루프에서 수정된 항목:
- [수정 내용 1]
- [수정 내용 2]

미해결 항목 (다음 루프 또는 기술 부채):
- [항목 1]: [이유]

progress.md 업데이트 완료: [날짜]

---

오류 유형 분류 및 계층적 복구 전략

arXiv 2603.06847 "Characterizing Faults in Agentic AI" 기반 3분류 체계

오류 유형 판별 기준 (증상 → 유형 매핑)

증상	오류 유형	설명
JSON 파싱 실패, 스키마 불일치, 출력 형식 오류	Parse Error	구조화 출력 형식 위반
도구 호출 실패, 파일 없음, 권한 오류, API 타임아웃	Tool Error	외부 시스템 상호작용 실패
테스트 실패, 로직 오류, 예상치 못한 동작, 무한 루프	Logic Error	알고리즘·비즈니스 로직 결함

Parse Error — 계층적 복구

Level 1 (재시도): 출력 형식을 명시적으로 재지시 후 재생성
Level 2 (체크포인트 롤백): bash .claude/hooks/harness-checkpoint.sh restore
Level 3 (규칙 폴백): CLAUDE.md 코딩 규칙 섹션으로 복귀 후 최소 구현
Level 4 (사용자 에스컬레이션): "Parse Error 반복 — 스키마 정의 확인 필요" 보고 후 중단

Tool Error — 계층적 복구

Level 1 (재시도): 동일 도구를 다른 파라미터로 재시도 (경로, 권한 확인)
Level 2 (체크포인트 롤백): 상태 오염 가능성이 있으면 즉시 롤백
Level 3 (규칙 폴백): 대체 도구 사용 (Bash → Read, Edit → Write)
Level 4 (사용자 에스컬레이션): "Tool Error — 외부 시스템 접근 불가" 보고 후 중단

Logic Error — 계층적 복구

Level 1 (재시도): 실패한 테스트 케이스를 분석 후 로직 수정 재시도
Level 2 (체크포인트 롤백): 동일 오류 3회 반복 시 → 즉시 롤백 후 재설계
Level 3 (규칙 폴백): /execution-loop 루프 상태 초기화 후 최소 기능부터 재시작
Level 4 (사용자 에스컬레이션): "Logic Error 반복 — 요구사항 재확인 필요" 보고 후 중단

규칙: 같은 오류 유형이 3회 연속 발생하면 즉시 Level 2 이상으로 에스컬레이션. Level 1 루프 고착 금지.

---

실전 예시

퀴즈 응시 기능 구현

/execution-loop 학생 퀴즈 응시 기능을 구현해줘.
형성평가로 설계해줘.
합격 기준: 린트 통과, 테스트 통과, Pedagogy Reviewer 승인.

루프 1:

• Planner → 구현 계획 수립 (승인 후 진행)
• Coder → QuizSession 컴포넌트 + API 구현
• 자동 검증 → 타입 오류 2개 발견
• 수정 → 타입 오류 수정

루프 2:

• 자동 검증 → 통과
• Reviewer → "총괄평가에 isCorrect가 API 응답에 포함됨" CRITICAL
• 수정 → 서버 사이드 채점으로 변경

루프 3:

• 자동 검증 → 통과
• Reviewer → CRITICAL 0개, HIGH 1개 (기술 부채로 기록)
• Pedagogy Reviewer → "재시도 버튼 없음" 이슈
• 수정 → 재시도 버튼 추가

루프 4:

• 모든 합격 기준 충족 → 루프 종료
• progress.md 업데이트 완료