| 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
npx tsc --noEmit
npm test
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 업데이트 완료
