invincible04/awesome-loop-engineering

루프 엔지니어링

사용자가 코딩 에이전트에게 프롬프트를 전달하는 자기 자신을 대체할 수 있도록 도와줍니다. 결과물은 작업을 발견하고, 메이커(maker)에게 전달하며, 별도의 검증기(checker)로 결과를 확인하고, 완료된 내용을 기록하며, 다음 작업을 결정하고, 목표가 달성될 때까지 재실행한 후 정직한 이유로 중단하는 작은 시스템입니다.

이 스킬에서 당신의 역할은 루프를 한 번에 완성해서 주는 것이 아닙니다. 인터뷰하고, 계약을 설계한 다음, 스캐폴딩(scaffolding)을 구축하여 사용자가 실제로 실행하고 신뢰할 수 있는 루프를 갖도록 하는 것입니다.

루프가 무엇이고, 무엇이 아닌지

루프는 cron 작업이 아닙니다. cron 작업은 맹목적으로 반복합니다. 루프는 작업을 발견하고, 별도의 검증기로 확인하며, 상태를 저장하고, 다음 작업을 결정하며, 이유를 가지고 중단합니다. 구축 중인 것이 스스로 중단될 수 없다면, 그것은 루프가 아니라 버그입니다.

중단 조건을 먼저 구축하세요. 그것이 사용자가 자리를 비울 수 있게 해줍니다.

0단계: 루프가 적절한 도구인지 결정하기

무엇을 설계하기 전에, 이 테스트를 적용하세요. 루프는 다음 두 가지가 모두 참일 때만 이점이 있습니다:

1. 명확하고 기계로 확인 가능한 성공 기준이 있습니다 (테스트 통과, 빌드 성공, 스키마 검증, 루브릭(rubric)에서 PASS 반환 등).
2. 이를 달성하는 과정에 사용자가 원래 수동으로, 턴마다 해야 했을 지루한 시행착오가 포함됩니다.

사용자가 기계가 어떻게 작업이 완료되었는지 알 수 있는지 말할 수 없다면, 멈추고 그렇게 말하세요. 검증 가능한 완료 조건이 없는 루프는 수렴하지 않고, 낭비하며 토큰을 태워버립니다. 먼저 확인 가능한 대리 지표(proxy)를 찾도록 도와주거나, 계속 수동으로 프롬프트하는 것을 권장하세요. 작업을 이해하지 못한 채 루프를 구축하지 마세요.

좋은 루프 후보: 실패한 CI 수정, 이슈 인박스 분류, 견고한 테스트 스위트에 대한 의존성 업그레이드, 벤치마크를 통한 성능 튜닝, 플래키 테스트(flaky test) 탐지, 항상 통과해야 하는 문서 빌드. 나쁜 후보: 개방형 설계, 대리 지표 없이 "좋음"이 취향의 문제인 모든 것, 일회성 작업.

1단계: 사용자 인터뷰 (루프 계약 작성)

다음 질문을 하세요. 검증 질문을 먼저 하세요 — 이것이 루프의 실행 가능성을 결정하는 질문입니다. 열한 가지를 한 번에 묻지 말고, 작은 배치로 물어보고, 저장소에서 안전하게 추론할 수 있는 것은 추론하세요.

1. 목표. 당신이 계속 수동으로 하고 있는 반복 작업은 무엇인가요? 루프가 참으로 만들어야 할 것은 무엇인가요?
2. 완료 조건 (먼저, 그리고 엄격하게 물어보세요). 사람이 보지 않고 기계가 어떻게 작업이 완료되었는지 알 수 있을까요? 정확한 명령어나 확인 방법을 말씀해 주세요.
3. 트리거. 무엇이 실행을 시작하나요: 일정 (매 N분/야간) 또는 이벤트 (푸시, 새 이슈, 웹훅, CI 실패)?
4. 발견 / 수집. 실행 시 무엇을 작업할지 어떻게 선택하나요? (CI 상태 읽기, 이슈 트래커 쿼리, fix_plan.md 읽기, 알림 스캔)
5. 작업 공간. 어디에서 작업하며, 엄격히 금지되는 것은 무엇인가요? (git 워크트리(worktree) 또는 샌드박스; 강제 푸시 금지, 시크릿 터치 금지, deps 변경 금지, 프로덕션 접근 금지)
6. 컨텍스트. 각 실행이 프로젝트를 처음부터 다시 유도하지 않기 위해 반드시 읽어야 할 것은 무엇인가요? (SKILL.md / AGENTS.md, 스펙, 메모리 파일)
7. 위임. 어떤 에이전트가 작업을 수행하고(메이커), 어떤 별도의 에이전트가 그것을 확인하나요(검증기)? 두 에이전트는 같은 호출이 아니어야 합니다.
8. 검증. "완료"가 참이 되기 위해 통과해야 하는 관문(gate)은 무엇인가요? (단위 테스트, 린트, 타입, PASS/FAIL을 증거와 함께 반환하는 LLM-as-judge 루브릭)
9. 메모리 / 상태. 재시작 후에도 실행을 재개할 수 있도록 진행 상황은 어디에 저장되나요? (마크다운 파일, 이슈 트래커, 디스크의 state.json)
10. 예산. 하드 상한: 최대 반복 횟수, 최대 실행 시간, 최대 토큰, 그리고 자격 증명이 비용을 지출할 수 있는 경우 달러 상한.
11. 인계. 무엇이 계속 진행하는 대신 사람에게 에스컬레이션되나요? (모호함, 고위험, 또는 새로운 증거 없이 같은 실패가 두 번 발생한 경우)

답변을 templates/loop-contract.template.md에 기록하세요. 사용자가 #2에 대해 구체적인 확인 방법을 답할 수 없다면, 0단계로 돌아가세요.

2단계: 루프 계약 작성하기

템플릿을 사용자의 저장소에 실제 loop-contract.md 파일로 채우세요. 이것은 루프가 구축되고 검토되는 설계 산출물입니다. 짧고 구체적으로 유지하세요. 모든 필드는 명령어, 경로 또는 숫자를 지정해야 하며, 모호한 느낌이 아니어야 합니다.

3단계: 도구에 맞는 가장 작은 형태 선택하기

계약을 사용자의 에이전트에 매핑하세요. 이를 충족하는 가장 간단한 메커니즘을 선택하세요. 하나의 /goal로 충분할 때 멀티 에이전트 오케스트레이션을 위해 달려들지 마세요. 구체적인 내용은 reference/tool-mapping.md를 참조하세요.

• Claude Code: 검증된 중단 조건을 위한 /goal, 메이커/검증기 분리를 위한 .claude/agents/의 하위 에이전트, 트리거를 위한 훅(hooks) 또는 예약된 작업, 헤드리스 실행을 위한 claude -p ... --output-format json.
• Codex: 트리거를 위한 자동화 탭, 헤드리스 실행을 위한 codex exec --json, 계속 진행을 위한 codex exec resume --last, 검증기를 위한 하위 에이전트.
• 처음부터 구축: Ralph 스타일의 bash 루프, while :; do cat PROMPT.md | agent; done, 턴당 하나의 작업과 fix_plan.md 사용. 아직 깨뜨릴 코드베이스가 없을 때 가장 좋습니다. 중단할 수 있도록 게이트와 예산과 함께 사용하세요. reference/ralph.md를 참조하세요.

4단계: 파일 스캐폴딩하기

구체적이고 실행 가능한 산출물을 생성하세요 (사용자의 스택에 맞게 이름을 조정하세요):

• 메이커 프롬프트: 아래의 법칙을 내장한, 양보할 수 없는 규칙을 포함합니다.
• 검증기: 셸 게이트 (정확한 테스트/린트 명령어) 또는 PASS/FAIL과 증거를 반환하고 ESCALATE할 수 있는 검증기 프롬프트. reference/verifier-rubric.md에서 시작하세요.
• 메모리 파일 (fix_plan.md 또는 state.json): 실행 시 가장 먼저 읽고 가장 마지막에 씁니다.
• 실행기: while 루프, cron 라인, GitHub Action, 또는 이를 실행하는 자동화. 게이트 ("빌드가 이미 통과했다면 아무것도 하지 않음")와 예산 상한을 포함합니다.

5단계: 실행 전에 강화하기

첫 번째 무인 실행 전에 사용자와 함께 reference/hardening-checklist.md를 검토하세요. 항상 엄격한 예산과 샌드박스 자격 증명으로 한 번 드라이 런(dry-run)한 후에 규모를 확장하세요.

네 가지 정직한 중단 조건

모든 루프는 다음 중 정확히 하나의 이유로 중단할 수 있어야 하며, 어떤 이유인지 말할 수 있어야 합니다:

• 목표 달성: 별도의 검증기가 완료 조건을 확인했습니다.
• 예산 소진: 반복 횟수, 토큰, 시간 또는 달러 상한에 도달했습니다.
• 정체: 새로운 증거 없이 같은 실패가 두 번 발생했습니다 (낭비 중단).
• 사람 필요: 고위험 또는 모호하여 에스컬레이션됩니다. 이것은 실패 상태가 아니라 성공 상태입니다.

불가침의 법칙

규칙 15를 모든 메이커의 지침에 내장하세요. 규칙 67은 메이커에 내장될 수 없습니다 — 엔지니어가 직접 책임져야 하므로 사용자가 이를 유지하도록 하세요.

1. 메이커는 자신의 작업을 절대 평가하지 않습니다. 별도의 검증기가 "완료"를 결정합니다. 코드를 작성한 모델은 자신의 숙제를 매기기에는 너무 관대합니다.
2. 테스트를 통과시키기 위해 테스트를 약화시키거나 삭제하거나 검사를 좁히지 마세요. 원인을 고치세요. 테스트가 잘못되었다면 에스컬레이션하세요. 조용히 편집하지 마세요.
3. 중단할 수 없는 루프는 버그입니다. 첫 실행 전에 네 가지 중단 조건을 연결하세요.
4. 메모리는 컨텍스트가 아닌 디스크에 저장됩니다. 각 턴마다 먼저 읽고, 마지막에 씁니다. 에이전트는 실행 사이에 잊어버리지만, 저장소는 그렇지 않습니다.
5. 원인만 고치세요. 범위를 확장하지 마세요. 옳을 수 있는 가장 작은 변경.
6. 검증은 엔지니어의 책임으로 남습니다. "완료"는 주장일 뿐, 증명이 아닙니다. 검증기는 사용자가 소유하는 자산입니다. 메이커는 모델 릴리스마다 공짜로 개선되는 상품(commodity)입니다.
7. 함대(병렬 에이전트) 규모는 도구의 레인(lane) 수가 아니라 사용자의 검토 속도에 맞춰집니다. 사람이 직렬 병목입니다. 일반적으로 적절한 병렬 에이전트 수는 낮은 한 자릿수입니다.

루프가 절대 당신을 위해 해주지 않는 것

이것을 사용자에게 명확히 말하여 올바른 작업을 유지하도록 하세요:

• 검증. 무인으로 실행되는 루프는 또한 무인으로 실수를 저지르는 루프입니다. 별도의 검증기는 "완료"에 의미를 부여할 뿐, 확실하게 만들지는 않습니다.
• 이해. 루프가 더 빨리 제공할수록, 이해 부채(comprehension-debt)는 더 빨리 커집니다. 루프가 만든 것을 읽을 시간을 계획하세요.
• 의도. 이 작업이 왜 중요한지, 그리고 "좋음"이 무엇을 의미하는지는 사람에게서 와야 합니다. 루프는 이해하는 작업을 더 빠르게 진행하기 위해 사용하는 것과 작업을 이해하지 않기 위해 사용하는 것의 차이를 알지 못합니다. 당신이 압니다.

루프를 구축하세요. 하지만 단순히 시작 버튼을 누르는 사람이 아니라, 엔지니어로 남고자 하는 사람처럼 구축하세요.

추가 자료 (선택 사항)

사용자가 이 단계들의 이론을 더 깊이 원한다면 — 루프 구조와 11개 부분 계약, /goal 대 /loop, 메모리, 토큰 경제와 오케스트레이션 세금, 그리고 위험 — Awesome Loop Engineering 핸드북을 참조하도록 안내하세요: https://github.com/invincible04/awesome-loop-engineering (온라인에서 읽기 가능: https://invincible04.github.io/awesome-loop-engineering/).