DenisSergeevitch/repo-task-proof-loop

리포지토리 작업 증명 루프 (Repo Task Proof Loop)

이 스킬은 사용자가 반복 가능하고 감사 가능한 구현 워크플로우를 원할 때, 특히 리포지토리 로컬 증거를 .agent/tasks/<TASK_ID>/에 남겨야 하는 기능, 리팩터링, 마이그레이션 또는 버그 수정과 같은 중요한 코딩 작업에 사용합니다.

이 워크플로우에 의해 생성된 모든 작업 아티팩트는 리포지토리 내에 유지되어야 합니다.

아래 예제에서 scripts/task_loop.py를 언급할 때, 해당 경로는 이 스킬 루트를 기준으로 합니다. 셸 작업 디렉토리가 대상 리포지토리 내에 있는 상태에서 실행하세요.

이 스킬이 하는 일

1. .agent/tasks/<TASK_ID>/ 아래에 엄격한 리포지토리 로컬 작업 폴더를 초기화합니다.
2. 필요한 아티팩트 파일을 시드하거나 업데이트합니다.
3. 프로젝트 범위의 Codex 및 Claude 하위 에이전트 템플릿을 .codex/agents/ 및 .claude/agents/에 설치합니다.
4. 리포지토리 루트의 AGENTS.md Codex 기준선과 리포지토리의 Claude 가이드 파일(CLAUDE.md 또는 .claude/CLAUDE.md)을 워크플로우를 설명하는 관리 블록으로 업데이트합니다.
5. 엄격한 루프를 통해 에이전트를 안내합니다:
   • 스펙 고정 (spec freeze)
   • 빌더 구현 (builder implementation)
   • 증거 패킹 (evidence packing)
   • 새 검증 (fresh verification)
   • 최소 수정 (minimal fix)
   • PASS가 나올 때까지 다시 새 검증 (fresh verification again)

참조:

• references/REFERENCE.md
• references/COMMANDS.md
• references/SUBAGENTS.md
• references/SCHEMAS.md

이 스킬이 지원하는 명령어

사용자가 이 스킬을 호출할 때 다음 단어를 명령어로 처리합니다:

• init <TASK_ID>: .agent/tasks/<TASK_ID>/를 생성하고, 하위 에이전트 템플릿을 설치 또는 새로고침하며, AGENTS.md와 리포지토리의 Claude 가이드 파일을 업데이트합니다.
• freeze <TASK_ID>: 사용자 작업, 작업 파일 및 리포지토리 지침을 바탕으로 spec.md를 생성하거나 개선합니다.
• build <TASK_ID>: 고정된 스펙을 대상으로 작업을 구현합니다.
• evidence <TASK_ID>: 프로덕션 코드를 변경하지 않고 evidence.md, evidence.json 및 원시 아티팩트를 생성하거나 새로고침합니다.
• verify <TASK_ID>: 새 검증기 패스를 실행하고 verdict.json을 작성하며, 필요한 경우 problems.md도 작성합니다.
• fix <TASK_ID>: problems.md에서 가장 작은 안전한 수정 세트를 적용한 후 증거 번들을 새로고침합니다.
• run <TASK_ID>: 스펙 고정부터 검증까지 전체 루프를 실행합니다.
• status <TASK_ID>: 현재 아티팩트 상태를 요약합니다.

사용자가 명령어를 제공하지 않으면, 리포지토리 상태에서 다음 단계를 추론합니다:

• 작업 폴더가 없으면 먼저 init을 실행합니다. 사용자가 명확하게 초기화만 원하면 그곳에서 멈춥니다. 그렇지 않으면 init이 성공하고 .agent/tasks/<TASK_ID>/spec.md가 존재하면, 같은 턴에서 리포지토리 상태를 다시 평가하여 계속 진행합니다. init을 freeze, build, evidence, verify, fix, validate, status 또는 하위 에이전트 작업과 중첩시키지 마세요.
• spec.md가 없거나 플레이스홀더만 있으면 freeze를 수행합니다.
• 구현이 아직 완료되지 않았으면 build를 수행합니다.
• 증거가 오래되었거나 없으면 evidence를 수행합니다.
• 새 평결(verdict)이 없으면 verify를 수행합니다.
• 평결이 PASS가 아니면 fix를 수행합니다.

초기화 단계

리포지토리 루트 또는 리포지토리 내의 현재 작업 디렉토리에서 번들된 초기화기를 실행하세요:

scripts/task_loop.py init --task-id <TASK_ID>

선택적 작업 시딩(seeding):

scripts/task_loop.py init --task-id <TASK_ID> --task-file path/to/task.md
scripts/task_loop.py init --task-id <TASK_ID> --task-text "User task text"

초기화기는 다음을 수행합니다:

• 리포지토리 루트를 확인합니다.
• .agent/tasks/<TASK_ID>/를 생성합니다.
• raw/ 아래의 플레이스홀더를 포함하여 필요한 모든 아티팩트를 생성합니다.
• 프로젝트 범위의 하위 에이전트 파일을 설치합니다.
• AGENTS.md와 리포지토리의 Claude 가이드 파일에 관리형 워크플로우 블록을 삽입하거나 새로고침합니다.

Codex의 경우, 초기화기는 리포지토리 루트 AGENTS.md에 관리형 워크플로우 블록을 유지합니다. Codex는 AGENTS.override.md와 구성된 폴백 가이드 파일 이름도 지원합니다. 코드에 더 가까운 중첩 파일이 여전히 우선하며, 이 스킬은 의도적으로 이를 덮어쓰지 않습니다. init이 실행 중인 Codex 세션 중에 AGENTS.md를 생성하거나 다시 쓰는 경우, 업데이트된 지침에 의존하기 전에 새 Codex 세션을 시작하세요. Codex는 세션 시작 시 프로젝트 문서 지침을 스냅샷합니다.

Claude Code의 경우, 초기화기는 리포지토리 루트 CLAUDE.md에 관리형 워크플로우 블록을 유지합니다. Claude Code는 .claude/CLAUDE.md, .claude/rules/*.md, CLAUDE.local.md도 지원하지만, 이 스킬은 루트 CLAUDE.md를 기본 프로젝트 가이드로 취급합니다. Claude가 이를 직접 표시하기 때문입니다.

Claude Code에서 init이 현재 세션 중에 .claude/agents/*를 방금 작성했거나 새로고쳤다면, 업데이트된 에이전트가 세션 중간에 이미 사용 가능하다고 가정하지 마세요.

init을 직렬 사전 조건으로 취급하세요. 절대 freeze, build, evidence, verify, fix, validate, status 또는 자식 에이전트 생성과 중첩시키지 마세요.

대규모 작업 기본 워크플로우

대규모 작업의 경우, 사용자 대면 요청을 간단하게 유지하세요. Codex에서는 사용자가 명시적으로 위임 또는 병렬 에이전트 작업을 요청하지 않는 한 직렬로 계속 진행하세요. 해당 승인 후에는 현재 제품 표면이 위임을 지원하고 작업 형태가 정당할 때 스킬이 내부 자식 설정을 자동으로 선택할 수 있습니다.

선호하는 위임 순서

1. 필요한 경우 init <TASK_ID>를 실행하세요. 완료될 때까지 기다린 후, 계속하기 전에 .agent/tasks/<TASK_ID>/spec.md와 리포지토리 로컬 작업 구조가 존재하는지 확인하세요.
2. init이 완료된 후에만 정확히 하나의 스펙 고정기 하위 에이전트를 생성하고 기다리세요.
3. 정확히 하나의 빌더 하위 에이전트를 생성하고 구현하도록 하세요.
4. 동일한 빌더 세션으로 증거 패킹을 계속 진행하세요.
5. 정확히 하나의 새 검증기 하위 에이전트를 생성하고 기다리세요.
6. 평결이 PASS가 아니면 정확히 하나의 수정기 하위 에이전트를 생성하세요.
7. 다시 정확히 하나의 새 검증기 하위 에이전트를 생성하세요.
8. 검증기가 PASS를 반환하거나 사용자가 루프를 중지할 때까지 6-7단계를 반복하세요.

Codex 적응형 파인아웃 (Adaptive fan-out)

사용자가 Codex 위임을 명시적으로 승인하고 작업이 제한된 병렬 작업으로 이점을 얻을 수 있을 만큼 광범위한 경우에만 사용하세요. 좁은 작업의 경우 위의 더 간단한 직렬 순서를 사용하세요.

적합한 경우:

• 스펙이 안정화되기 전에 여러 독립적인 코드베이스 질문에 답해야 함
• 구현이 분리된 쓰기 범위로 분할될 수 있음
• 증명을 위해 여러 다른 표면에 걸친 여러 독립적인 읽기 전용 검사가 필요함

Codex 패턴:

1. init은 직렬로 유지됩니다.
2. 작업이 여전히 모호한 경우, 최대 3개의 내장 explorer 자식을 병렬로 파인아웃합니다. 각각에 단일 질문, 서브시스템 또는 경로 범위를 부여합니다. 완료될 때까지 기다린 후 스펙을 고정합니다.
3. 하나의 스펙 고정기 자식을 생성하고 기다립니다.
4. 하나의 task-builder 자식을 통합 소유자로 생성합니다.
5. 구현이 깔끔하게 분할되면, 상위는 제한된 내장 worker 자식을 병렬로 생성할 수도 있습니다. 각 작업자는 명시적인 파일 또는 모듈 소유권을 가져야 하며 evidence.md, evidence.json, verdict.json 또는 problems.md를 작성해서는 안 됩니다.
6. send_input 또는 동등한 후속 조치 표면을 사용하여 통합 빌더를 증거 패킹을 위해 활성 상태로 유지합니다. 빌더는 증거 번들의 단일 소유자로 남습니다.
7. 추가 증명이 필요한 경우, 상위는 작은 제한된 읽기 전용 explorer 자식 세트를 병렬로 파인아웃하여 분리된 검사를 다시 실행하거나 별도의 증명 격차를 조사할 수 있습니다. 해당 자식은 명령어, 출력 및 결과를 보고할 수 있지만 verdict.json을 작성하지는 않습니다.
8. 각 검증 패스에 대해 정확히 하나의 새 검증기 자식을 실행합니다.

플랫폼 동작

• Codex에서, 일반 경로는 init 후에 직렬 및 자동 모드 우선으로 유지합니다. 작업에 실질적인 영향을 미치지 않는 한 위임 내부를 표면화하지 마세요.
• Codex에서, 사용자가 명시적으로 하위 에이전트, 위임 또는 병렬 에이전트 작업을 요청하는 경우에만 제한된 하위 에이전트를 생성하세요.
• Codex에서, 위임이 승인되면 스킬은 일치하는 자식 역할과 한 번에 하나의 자식 또는 제한된 파인아웃 중에서 선택할 수 있습니다. 사용자는 특정 자식 역할이나 슬래시 명령어를 지정할 필요가 없어야 합니다.
• Codex에서, 자식 생성은 여전히 명시적인 상위 오케스트레이터 작업입니다. 현재 Codex 표면이 위임을 차단하는 경우, 작업에 실질적인 영향을 미칠 때만 간략히 언급한 후 직렬로 계속 진행하세요.
• Codex에서, 작업 트리를 얕게 유지하세요. 상위 세션은 연구자, 빌더, 수정기 및 검증기 자식을 직접 생성해야 하며, 사용자 정의 작업 자식 하나에게 더 많은 자식을 오케스트레이션하도록 요청하지 마세요.
• Codex에서, 위임이 승인되면 고정된 스펙, 리포지토리 형태 및 현재 위임 표면에서 한 번에 하나의 자식 위임과 제한된 파인아웃 중에서 선택하세요. init, 증거 소유권 및 모든 검증기 패스는 어느 쪽이든 직렬화하세요.
• Codex에서, 도우미 파인아웃을 적당하고 웨이브 기반으로 유지하세요. 한 번에 최대 3개의 병렬 도우미 자식을 선호하고, 해당 웨이브가 완료될 때까지 기다린 후 다음 단계를 결정하세요.
• Codex에서, 내장 explorer는 읽기 전용 리포지토리 발견 및 증명 프로브를 위한 첫 번째 선택입니다. 내장 worker는 명시적 소유권을 할당할 수 있을 때 제한된 분리 구현 또는 검사 재실행에 적합합니다.
• Codex에서, 후속 조치 명령어를 보내어 라이브 빌더 자식을 증거 패킹에 재사용하세요. 검증기 패스는 새 자식 또는 새 세션을 사용해야 합니다. 이전 검증기를 재개하여 검증기 새로움을 충족시키지 마세요. 빌더 및 수정기 자식은 의도적으로 해당 컨텍스트를 다시 원할 때 재사용하거나 재개할 수 있습니다.
• Codex에서, 자식을 재사용하거나 재개하기 전에 현재 자식 스레드 목록을 검사하세요. Codex CLI에서 /agent 또는 현재 Codex 제품 표면에서 사용 가능한 동등한 자식 스레드 인벤토리 표면을 사용하세요.
• Codex에서, update_plan의 계획/할 일 체크리스트 UI는 선택적 세션 지침일 뿐입니다. 실시간 진행 상황 표시에 유용하지만, 이 워크플로우의 진실 공급원(source of truth)은 아닙니다.
• Claude Code에서, 스킬은 메인 스레드에 머물지 또는 메인 Claude 세션이 init 후에 현재 단계를 일치하는 내장 또는 프로젝트 하위 에이전트에 자동 위임하도록 할지 결정해야 합니다. 사용자는 별도로 특정 Claude 하위 에이전트나 위임 모드를 요청할 필요가 없어야 합니다.
• Claude Code에서, TodoWrite 또는 가시적인 작업/할 일 UI는 선택적 세션 범위의 진행 상황 표시일 뿐입니다. 현재 세션에서 실시간 추적에 도움이 될 수 있지만, 이 워크플로우의 진실 공급원은 아닙니다.
• Claude Code에서, .claude/agents/에서 설치된 프로젝트 하위 에이전트를 선호하며, 설명은 일치하는 증명 루프 단계에 대한 사전 트리거 조건으로 작성하세요. Claude의 메인 세션은 작업 요청, 하위 에이전트 설명 및 현재 컨텍스트에 따라 라우팅하므로 각 단계 프롬프트를 자연어로 명확하게 유지하세요. 기본적으로 증거 단계에 동일한 빌더 자식을 재사용하세요. 원래 빌더 세션을 사용할 수 없거나 의도적으로 폐기한 경우에만 증거 전용 모드로 새 빌더를 실행하세요. init이 현재 Claude 세션 중에 .claude/agents/*를 방금 새로고쳤다면, 새로고침된 에이전트가 즉시 사용 가능하다고 가정하는 대신 메인 스레드 또는 이미 보이는 에이전트로 폴백하세요.
• Claude Code에서, 오케스트레이션을 평평하게 유지하세요: 메인 세션 자동 위임은 괜찮지만, 증명 루프 워크플로우 에이전트 자체는 리프 역할입니다. 상위 세션은 사용자 정의 작업 에이전트 하나가 다른 에이전트를 생성하도록 요청하는 대신 증명 루프 단계 전환을 소유해야 합니다.
• Claude Code에서, 표준적인 지속 상태는 항상 .agent/tasks/<TASK_ID>/ 아래의 리포지토리 로컬 아티팩트 세트, 특히 spec.md, evidence.md, evidence.json, verdict.json 및 problems.md입니다.
• 하위 에이전트를 사용할 수 없는 경우, 현재 세션에서 별도의 세션 또는 명확한 모드 변경에 걸쳐 동일한 역할 분리를 유지하세요.

references/COMMANDS.md에서 정확한 역할 프롬프트를 사용하세요.

스펙 고정 요구 사항

spec.md는 최소한 다음을 포함해야 합니다:

• 원래 작업 설명
• AC1, AC2, ...로 표시된 명시적인 승인 기준
• 제약 조건
• 비목표 (non-goals)

다음도 포함할 수 있습니다:

• 리포지토리 지침 소스
• 검증 계획
• 사용자 요청에서 좁게 해결된 가정

스펙 고정 중에는 프로덕션 코드를 편집하지 마세요.

증거 패킹 요구 사항

evidence.md와 evidence.json은 각 승인 기준을 다음 중 하나로 독립적으로 판단해야 합니다:

• PASS
• FAIL
• UNKNOWN

증거 패킹은 누락된 검사를 실행할 수 있지만, 프로덕션 코드를 계속 변경해서는 안 됩니다.

모든 PASS는 다음과 같은 구체적인 증거를 인용해야 합니다:

• 파일 경로
• 실행된 명령어
• 종료 코드
• 출력 요약
• raw/ 아래의 아티팩트 경로

모든 승인 기준이 PASS가 아닌 한 증거 번들에서 전체 PASS를 주장하지 마세요.

새 검증 요구 사항

검증기는 새 세션 또는 새 하위 에이전트여야 합니다. Codex에서, 이 요구 사항을 이전 검증기 자식을 재개하여 충족시키지 마세요.

검증기는 현재 리포지토리 상태와 현재 재실행 결과를 판단해야 하며, 빌더의 설명이 아닙니다.

검증기가 작성합니다:

• .agent/tasks/<TASK_ID>/verdict.json
• .agent/tasks/<TASK_ID>/problems.md (전체 평결이 PASS가 아닌 경우에만)

problems.md는 각 PASS가 아닌 기준에 대해 다음을 포함해야 합니다:

• 기준 ID 및 텍스트
• 상태
• 증명되지 않은 이유
• 최소 재현 단계
• 예상 vs 실제
• 영향받는 파일
• 가장 작은 안전한 수정
• 1-3문장의 교정 힌트

검증기는 프로덕션 코드를 수정하거나 증거 번들을 백필(backfill)해서는 안 됩니다.

수정기 요구 사항

수정기는 다음만 읽습니다:

• spec.md
• verdict.json
• problems.md

수정기는 다음을 수행해야 합니다:

• 편집 전에 코드베이스에서 각 나열된 문제를 재확인합니다.
• 가장 작은 안전한 변경 세트를 만듭니다.
• 이미 통과한 기준을 회귀시키지 않습니다.
• evidence.md, evidence.json 및 원시 아티팩트를 재생성합니다.
• 최종 서명 없이 중지합니다.

검증

워크플로우가 올바르게 초기화되었거나 아티팩트 세트가 완전하다고 주장하기 전에 다음을 실행하세요:

scripts/task_loop.py validate --task-id <TASK_ID>

init이 완전히 완료된 후에만 validate를 실행하세요. 초기화가 진행 중이라고 보고하면, 해당 결과를 안정적인 작업 실패로 처리하는 대신 기다렸다가 다시 실행하세요.

빠른 요약을 위해:

scripts/task_loop.py status --task-id <TASK_ID>

안정적인 작업 상태가 필요할 때 init이 완전히 완료된 후에만 status를 실행하세요. init_in_progress: true를 보고하면 나중에 다시 시도해야 하는 조건으로 처리하세요.

가드레일 (Guardrails)

• .agent/tasks/<TASK_ID>/를 리포지토리 내에 유지하세요.
• Codex todo/체크리스트 UI를 임시 진행 상황으로만 취급하세요. 지속적인 상태는 리포지토리 로컬 아티팩트입니다.