---
name: luna-loop
description: 호출 시 Luna 검증자로 수정의 검증 및 재수정 루프를 돌린다.
---

# 수정-검증 루프

코드·설정·문서를 실제로 바꾸는 작업에서 완료 기준을 `수정함`으로 끝내지 않는다. 요청의 수용 조건을 정리하고, 변경 후 독립 검증을 거쳐 유효한 문제가 발견되면 원래 작업 맥락에서 재수정한 뒤 검증을 반복한다.

이 스킬은 사용자가 `$luna-loop`로 직접 호출한 경우에만 사용한다. 직접 호출된 경우에는 새 수정 작업뿐 아니라 현재 변경의 검증만 요청된 경우도 수행하며, 호출되지 않은 단순 설명·조사에는 적용하지 않는다.

## 적용 경계

- 구현·수정·버그 해결·리팩터링·UI 변경 또는 현재 변경 검증 요청에 적용한다.
- 검증만 요청된 경우에는 기준선 확인과 직접 검증·Luna 검증을 수행하고, 확정 문제가 있을 때만 수정을 진행한다.
- 커밋·푸시·배포·외부 시스템 변경은 사용자가 별도로 요청한 경우에만 수행한다.
- 기존 미커밋 변경은 기준선으로 보존하고, 이번 작업과 무관한 파일을 되돌리거나 정리하지 않는다.

## 핵심 운영 원칙

1. **주 편집자는 하나로 유지한다.** 검증 에이전트는 기본적으로 읽기 전용이며 파일을 수정하지 않는다. 여러 에이전트의 의견을 주 편집자가 원본 코드와 수용 조건으로 재확인한 뒤에만 수정한다.
2. **검증 대상과 기준선을 분리한다.** 시작 전에 저장소 지침, 현재 변경, 실행 중인 프로세스, 기존 실패를 확인하고 이번 작업에서 생긴 변경과 이미 존재하던 상태를 구분한다.
3. **추측을 결함으로 올리지 않는다.** 지적에는 기대 조건, 실제 코드 경로, 재현 방법 또는 사용자 영향이 모두 있어야 한다. 근거가 부족하면 `미확인`으로 남기고 무리하게 수정하지 않는다.
4. **검증 결과를 꾸며내지 않는다.** Luna를 호출하지 못했거나 테스트·빌드가 실행되지 않았으면 성공으로 표시하지 말고 그 한계를 보고한다.

## 실행 절차

### 1. 기준선과 수용 조건 확정

- 저장소의 `AGENTS.md`, `CLAUDE.md`, 기여 문서와 관련 지침을 먼저 읽는다.
- 현재 작업 디렉터리, 변경 파일, 실행 중인 프로세스, 기존 테스트·빌드 실패를 확인한다.
- 사용자의 요구를 관찰 가능한 수용 조건으로 바꾼다. 표시·상태·입력·저장·오류·성능 중 영향을 받는 축을 빠뜨리지 않는다.
- 변경 파일과 직접 영향을 받는 호출자·피호출자·테스트를 짧은 목록으로 고정한다.
- 수용 조건마다 가장 값싼 직접 검증 명령이나 실행 경로를 정한다.

### 1-1. Luna 실행 가능성 게이트

- 파일을 수정하기 전에 현재 호스트가 실제 `gpt-5.6-luna`를 위임 실행할 수 있는지 확인한다.
- 호출 수단은 제공자별로 다르지만 모델 확인 규칙은 하나다. 위임 도구의 반환값도, 검증자에게 모델을 물어 받은 답도 근거로 쓰지 않는다. 검증자는 자기 모델을 틀리게 답한다.
- Codex에서는 `collaboration.spawn_agent`에 `model`을 `gpt-5.6-luna`, `reasoning_effort`를 `high`로 넘긴다. 두 값을 덮어쓰려면 `fork_turns`를 `"none"` 또는 양의 정수 문자열로 함께 준다.
- Claude에서는 Codex CLI를 자식 프로세스로 실행해 위임한다. 파일을 수정하기 전에 아래 한 줄로 게이트를 확인한다.

  ```bash
  echo "OK만 출력하라." | codex exec -m gpt-5.6-luna \
    -c model_reasoning_effort="high" -s read-only --skip-git-repo-check --json - \
    > <게이트 로그 파일> 2>&1
  ```

- 성공과 실패는 출력 JSONL의 최상위 이벤트 유형으로만 판정한다. `turn.completed`가 있고 `error`·`turn.failed`가 없어야 통과다. 실패해도 종료 코드는 0이 나오므로 종료 코드를 판정 근거로 쓰지 않는다.

  ```bash
  grep -o '^{"type":"[a-z._]*"' <로그 파일> | sort -u
  ```

- 로그 전체를 문자열로 검색하지 않는다. 검증자가 이 문서를 읽으면 본문에 적힌 실패 신호가 로그에 그대로 실려 오탐이 된다. 줄 시작 기준으로만 판정한다.
- 실제 실행 모델은 로컬 세션 기록으로만 확정한다. 확인 절차는 [제공자 호환 안내](references/provider-compatibility.md)의 `실행 모델 확인`을 따른다.
- `--ephemeral`은 세션 기록을 남기지 않아 모델 확인을 막으므로 검증 실행에 쓰지 않는다.
- Codex CLI가 없거나 인증되지 않았거나 모델이 거부되면 Claude 계열 모델이나 직접 검증으로 대체하지 않는다.
- 게이트를 통과하지 못하면 새 수정은 시작하지 않고 `Luna 검증 불가` 사유와 필요한 연결 상태만 보고한다. 이미 존재하는 변경은 읽기 전용으로 확인할 수 있지만 완료로 판정하지 않는다.

### 2. 최소 범위로 수정

- 기준선과 수용 조건을 벗어나지 않는 가장 작은 일관된 변경을 적용한다.
- 검증을 쉽게 하려고 무관한 리팩터링, 형식 정리, 테스트 삭제를 끼워 넣지 않는다.
- 수정 직후 변경 목록과 수용 조건의 대응을 다시 대조한다.

### 3. 주 편집자의 직접 검증

- 가능한 경우 변경 지점에 가장 가까운 단위 테스트·정적 검사·빌드·실행 확인을 먼저 한다.
- 실패는 `이번 변경의 실패`, `기준선도 실패`, `환경상 실행 불가`로 나눠 기록한다.
- 직접 검증이 통과해도 독립 검증을 생략하지 않는다. 직접 검증은 실행 가능성, Luna 검증은 놓친 계약·회귀·경계 조건을 확인하는 역할이다.

### 4. Luna 독립 검증

- 실행 가능성 게이트를 통과한 뒤에만 검증 에이전트를 생성한다. 모든 검증자는 실제 `gpt-5.6-luna`로 실행돼야 하며, Luna를 사용할 수 없으면 대체 검증 없이 중단한다.
- 검증자에게는 요청 요약, 수용 조건, 변경 파일·관련 코드 범위, 기준선 정보, 이미 실행한 검사만 전달한다. 주 편집자의 의심 결론이나 원하는 판정을 전달하지 않는다.
- 각 검증자는 읽기 전용으로 동작하게 하고, 근거 없는 광범위 탐색이나 파일 수정을 금지한다.
- Claude에서는 검증자 하나가 Codex CLI 실행 한 번이다. 요청문을 파일로 쓰고 아래 형태로 실행한다.

  ```bash
  codex exec -m gpt-5.6-luna -c model_reasoning_effort="high" \
    -s read-only --skip-git-repo-check \
    -C <저장소 경로> -o <결과 파일> --json - < <요청문 파일> > <로그 파일> 2>&1
  ```

- 검증자마다 결과 파일과 로그 파일을 서로 다른 경로로 지정한다. 이벤트 판정은 로그 파일로, 검토 내용 확인은 결과 파일로 한다.
- 로그 파일에서 `thread_id`를 뽑아 두고, 검증이 끝난 뒤 그 값으로 세션 기록을 찾아 실행 모델과 추론 강도를 확인한다.

  ```bash
  grep -o '"thread_id":"[^"]*"' <로그 파일> | head -1
  ```

- 병렬 검증은 검증자마다 위 명령을 별도 프로세스로 동시에 띄워 얻는다. Claude 계열 서브에이전트로 검증자를 대신하지 않는다.
- 검증자 하나를 셸 호출 하나로 띄운다. 한 호출 안에서 여러 개를 묶어 띄우면 진행 표시가 하나로 합쳐져 검증자별 상태를 볼 수 없다.
- `-s read-only`가 검증자의 쓰기를 호스트 차원에서 막으므로 이 옵션을 빼지 않는다.
- 각 검증자의 종료 판정은 게이트와 같은 명령과 같은 신호 집합을 쓴다. 최상위 이벤트에 `turn.completed`가 있고 `turn.failed`·`error`가 없어야 완료이며, 그렇지 않으면 해당 범위를 미완료로 기록한다.
- 이벤트가 정상이어도 결과 파일이 없거나 비어 있거나 검토 내용이 담기지 않았으면 완료로 보지 않는다. 결과 파일을 읽어 실제 지적이나 문제 없음 판정이 있는지 확인한다.
- 검증자별로 실행 모델과 추론 강도를 확인한 뒤에만 그 결과를 종합 대상에 넣는다. `gpt-5.6-luna`와 `high`를 확인하지 못한 범위는 미완료로 다룬다.
- 수정과 직접 검증이 끝난 직후, 완료 직전의 최종 검증 패널로 최소 2개의 Luna 검증자를 서로 다른 관점에서 동시에 생성한다.
- 변경 범위가 크면 독립 범위를 3~4개로 나눈다. 한 번에 띄우는 수는 제공자의 가용 슬롯을 넘기지 않으며, 슬롯이 부족하면 범위를 유지한 채 나눠 실행한다. 제공자별 슬롯은 [제공자 호환 안내](references/provider-compatibility.md)를 따른다. 다음 중 하나라도 해당하면 큰 변경으로 본다.
  - 변경 파일이 5개 이상이다.
  - 서로 다른 하위 시스템이 2개 이상이다.
  - UI와 상태·저장·통신 로직이 함께 바뀐다.
  - 수용 조건이 서로 다른 동작 축 3개 이상으로 나뉜다.
- 병렬 검증의 범위는 겹치지 않게 나눈다. 적합한 축은 `정상 사용 흐름·요구사항`, `회귀·상태·오류 경로`, `테스트·빌드·호환성`, `UI·입력·접근성`이다. UI가 없으면 마지막 축을 만들지 않는다.
- 모든 검증자의 결과를 받은 뒤 한 번에 종합한다. 같은 문제를 반복 보고한 수는 확신도의 근거가 아니라 한 건의 근거 묶음으로 취급한다.
- 생성한 각 검증자의 종료 상태를 확인한다. `완료`가 아닌 `오류`·`중단`·`시간 초과`·`상태 미확인`은 해당 범위의 검증 미완료로 기록한다.
- 이벤트는 정상이지만 결과 파일이 없거나 비어 있거나 검토 내용이 없으면 `검증 결과 미확인`으로 기록하고 아래 재시도 규칙을 그대로 적용한다.
- `오류`·`중단`·`시간 초과`·`상태 미확인`·`Luna 모델 미확인`·`검증 결과 미확인` 범위는 같은 범위의 새 Luna 검증자로 한 번만 재시도한다. 재시도도 완료되지 않으면 추가 재시도·직접 검증·다른 모델 대체 없이 즉시 중단하고 실행 불가 사유와 영향 범위를 보고한다.
- 검증자가 일부만 끝났다면 끝난 결과는 잠정 결과로만 사용한다. 누락 범위가 있으면 같은 범위의 Luna 검증자를 새로 실행하며, 직접 검증이나 다른 모델로 대체하지 않는다.
- 병렬 결과가 하나라도 미완료인 채로 남으면 전체를 통과로 판정하지 않는다. 새 Luna 검증자도 실패하면 해당 범위의 실행 불가 사유와 영향 범위를 보고하고 중단한다.

검증자에게 전달할 기본 요청은 [검증자 계약](references/verifier-contract.md)을 따른다.

### 5. 문제 판정과 재수정

- 각 지적을 원본 코드, 수용 조건, 실행 결과로 다시 확인한다. 검증자의 말만으로 수정하지 않는다.
- 유효한 지적만 `확정 문제`로 채택하고, 의도 확인이 필요한 내용은 `확인 요청`, 근거가 약한 내용은 `미확인`으로 분리한다.
- 요청·기획·기존 계약을 확인해야만 결정할 수 있는 `확인 요청`은 결함으로 단정하지 않는다. 사용자의 답이 없으면 해당 항목을 완료 차단 사유로 남긴다.
- 확정 문제를 주 편집자가 수정한 뒤, 영향을 받은 직접 검증을 다시 실행한다.
- 확정 문제가 하나라도 있으면 수정과 직접 검증을 끝낸 뒤 최종 Luna 검증 패널 전체를 같은 관점으로 다시 병렬 실행한다. 고립된 수정이어도 일부 검증자만 생략하지 않는다.
- 재검증에서 새로운 확정 문제가 나오면 기본 최대 3회의 수정-검증 회차 안에서 같은 루프를 반복한다. 3회 뒤에도 확정 문제가 남으면 아래 종료 규칙에 따라 중단하며 완료하지 않는다.
- 반복마다 회차, 채택·기각한 지적과 근거, 새로 바뀐 범위, 실행한 검사를 기록한다. 이전에 통과한 검사를 결과 없이 재사용하지 않는다.

### 6. 종료 판정

다음 조건을 모두 만족할 때만 완료로 판정한다.

- 수용 조건을 위반하는 확정 문제가 남아 있지 않다.
- 사용자 판단이 필요한 `확인 요청`이 남아 있지 않다. 남아 있다면 완료가 아니라 명시적 중단·질문 상태로 보고한다.
- 필수 직접 검증이 통과했거나, 실행 불가 사유와 영향 범위가 명확히 기록됐다.
- 마지막 변경 범위에 대해 실제 실행 모델이 `gpt-5.6-luna`, 추론 강도가 `high`로 확인된 Luna 검증이 끝났다.
- 기존 실패·미확인 런타임·사용자 확인 필요 항목이 성공으로 숨겨지지 않았다.

기본 수정-검증 회차는 3회까지다. 3회 뒤에도 확정 문제가 남거나 같은 검증이 반복해서 모순되면 무한 재시도하지 말고, 남은 문제·시도한 수정·차단된 검증·사용자에게 필요한 결정을 보고한다. 사용자가 더 반복하라고 명시한 경우에만 회차를 늘린다.

## 제공자 차이

공통 본문은 Codex와 Claude에서 읽을 수 있게 작성한다. 위임 도구와 모델 이름은 [제공자 호환 안내](references/provider-compatibility.md)를 먼저 확인하고, 현재 호스트에 실제로 노출된 기능만 사용한다.

## 결과 보고

최종 보고에는 최소한 `확인된 원인`, `사용자 영향`, `실제 조치`, `직접 검증`, `Luna 검증`, `남은 한계`를 포함한다. 파일 경로·기술 식별자는 원인과 검증 근거를 판단하는 데 필요한 범위만 쓴다.
