sxivansx/loop-engineering

루프 엔지니어링

루프를 설정합니다: 에이전트가 스스로 동작하도록 유도하는 자율 시스템입니다. 목표와 중단 조건을 한 번 정의하면, 루프가 작업을 찾고, 수행하고, 검사하고, 결과를 기록한 후 목표가 달성될 때까지 다시 실행합니다. 이 스킬은 기존 프로젝트 내에 루프를 구축합니다: 테스트, 빌드, 작업 추적 방식을 읽어들여 일반적인 규칙을 강제하지 않고 프로젝트의 관례에 맞춰 루프를 적용합니다.

루프는 여섯 가지 기본 요소로 구성됩니다. 목표에 필요한 요소만 설정하십시오.

기본 요소	루프에서의 역할	Claude Code 메커니즘
트리거	각 주기를 시작합니다. 일정 또는 이벤트 기반	/goal (조건이 충족될 때까지 여러 턴에 걸쳐 작업), /loop, 예약된 작업, 훅, GitHub Actions
상태	주기 사이의 루프 메모리. 디스크에 저장	마크다운 파일(LOOP.md) 또는 MCP를 통한 이슈 트래커
발견	이번 주기에 작업할 내용을 찾습니다	CI, 이슈, diff, 대기열을 읽는 트라이지 단계
제작자	작업 단위 하나를 수행합니다	.claude/agents/ 디렉토리의 서브에이전트
검사자	제작자를 독립적으로 검증합니다	.claude/agents/ 디렉토리의 다른 서브에이전트
중단 조건	루프를 종료하는 규칙	검사자가 실행하는 검증 가능한 검사

무인 실행되는 모든 루프에는 모니터를 추가하십시오: 루프 전체를 감시하고 드리프트(목표 이탈), 스피닝(순 진행 없음), 또는 제한 초과(너무 많은 사이클, 너무 긴 시간) 발생 시 중단시키는 감독 에이전트입니다. 제작자와 검사자는 각 항목의 정확성을 보장하고, 모니터는 루프 전체가 목표를 향하도록 유지하여 조용히 표류하며 몇 시간 동안 실행되는 것을 방지합니다.

두 가지 선택적 추가 기능: 워크트리(git worktree)는 병렬 제작자가 동일한 파일을 편집하지 못하도록 격리하며, MCP 커넥터는 루프가 실제 도구(PR 열기, 티켓 업데이트, 상태 게시)에 접근할 수 있게 합니다. 목표에 병렬 처리 또는 외부 부수 효과가 필요할 때 추가하십시오.

설정 절차

기존 프로젝트 내에서 실행됩니다. 호출되면 다음 단계를 따르십시오. 부수 효과(예약된 작업, 푸시, 티켓 쓰기, 배포)가 있는 모든 작업은 사용자에게 확인을 받으십시오.

1. 프로젝트를 먼저 읽으십시오. 스캐폴딩 전에 저장소를 파악하십시오: 테스트, 빌드, 린트 실행 방법(package.json, Makefile, CI 설정, CLAUDE.md 확인); 이미 존재하는 관례, 기존 스킬 또는 .claude/agents/; 작업이 어디서 오는지(CI, 이슈 트래커, 백로그, 대기열). 루프는 이 프로젝트에 맞춰져야 합니다. 실제 명령어와 관례를 재사용하고 새로운 것을 발명하지 마십시오.

2. 목표와 중단 조건을 확정하십시오. 사용자에게 루프의 단일 목표와 검증 가능한 완료 조건(테스트 종료 코드 0, 대기열 비움, 실패 검사 0)을 물어보십시오. 중단 조건이 없는 루프는 절대 배포해서는 안 됩니다. 사용자가 하나를 지정할 수 없으면 제한된 대체 조건(N 사이클 후 중단)을 설정하고 명시적으로 알리십시오. Claude Code에서 /goal <조건>은 이를 실행 가능하게 만듭니다: Claude는 조건이 충족될 때까지 여러 턴에 걸쳐 작업하며, /goal clear는 조기 종료합니다.

3. 상태 파일을 작성하십시오. ${CLAUDE_SKILL_DIR}/templates/LOOP.md를 저장소 루트에 복사하고 목표, 중단 조건, 주기, 인간 게이트를 채우십시오. 루프가 유지 관리하는 세 개의 활성 섹션이 있습니다: ## Open (발견됨, 완료되지 않음), ## Done (검증 증거 포함), ## Blocked (인간 필요), 그리고 루프의 모든 에이전트가 따르는 상위 지침 세트인 ## Rules 섹션. 루프는 매 사이클마다 이 파일을 먼저 읽고 마지막에 씁니다.

4. 제작자 서브에이전트를 생성하십시오. ${CLAUDE_SKILL_DIR}/templates/loop-maker.md를 .claude/agents/loop-maker.md에 복사하고 1단계에서 찾은 관례와 테스트 명령어를 가리키게 하십시오. ## Open에서 정확히 하나의 항목을 수행하며, 프로젝트의 기존 스킬과 관례를 따르고, 자신의 작업을 완료로 표시하지 않습니다. 동일한 이름의 파일이 이미 있으면 덮어쓰지 말고 업데이트하십시오.

5. 검사자 서브에이전트를 생성하십시오. ${CLAUDE_SKILL_DIR}/templates/loop-checker.md를 .claude/agents/loop-checker.md에 복사하십시오. 제작자와 다른 에이전트이며, 프로젝트의 실제 검증(1단계의 실제 테스트, 빌드 또는 린트 명령어, 설명 아님)을 실행하고, 항목을 ## Done으로 이동할 수 있는 유일한 에이전트입니다.

6. 모니터 서브에이전트를 생성하십시오(무인 루프에 권장됨). ${CLAUDE_SKILL_DIR}/templates/loop-monitor.md를 .claude/agents/loop-monitor.md에 복사하고, 몇 사이클마다 또는 루프보다 느린 타이머로 실행하십시오. 단일 항목이 아닌 루프 전체를 관찰합니다: 루프가 여전히 목표에 수렴하고 있는지 확인하고, 드리프트(목표에 도움이 되지 않는 작업), 스피닝(순 진행 없음, 항목이 Open과 Blocked 사이를 오감), 또는 제한 초과 시 루프를 중단하고 인간에게 에스컬레이션합니다. 이것이 루프가 조용히 표류하여 몇 시간 동안 실행되는 것을 막습니다.

7. 코드 리뷰 및 보안 감사 주기를 설정하십시오(사용자에게 문의). 루프가 각각을 얼마나 자주 실행해야 하는지 사용자에게 묻고 둘 다 LOOP.md에 기록하십시오. 명확한 옵션을 제공하고 항상 안 함을 포함하십시오:

   • 코드 리뷰(/code-review): 모든 변경 시, 각 PR 또는 병합 전, N 사이클마다, 주별, 또는 안 함.
   • 보안 감사(/security-review): 모든 변경 시, 각 PR 또는 병합 전, 주별, 월별, 또는 안 함.

   선택한 주기에 따라 루프는 해당 내장 패스를 실행하고 발견한 내용을 ## Open에 새 작업 항목으로 기록하여 제작자가 수정하고 검사자가 수정을 확인합니다. 사용자가 안 함을 선택하면 해당 패스를 완전히 건너뛰고 LOOP.md에 안 함을 기록하여 루프가 다시 도입하지 않도록 합니다.

8. 발견을 정의하십시오. 매 사이클마다 ## Open을 프로젝트 작업이 실제로 존재하는 곳(CI 상태, 열린 이슈, 최근 커밋, 작업 대기열)에서 채우는 트라이지 단계와 발견한 내용을 개별적으로 검사 가능한 항목으로 변환하는 방법을 작성하십시오. 가능한 한 결정론적으로 만드십시오.

9. 격리 선택(선택 사항). 사이클당 둘 이상의 제작자가 실행되는 경우 각각에 고유한 git worktree와 브랜치를 제공하여 동일한 파일을 쓰지 않도록 하십시오. 항목당 하나의 워크트리입니다.

10. 커넥터 연결(선택 사항). 루프가 PR을 열거나, 티켓을 업데이트하거나, 상태를 게시해야 하는 경우 일치하는 MCP 서버를 연결하십시오. 그렇지 않으면 루프의 출력은 로컬에 유지되고 인간이 전달합니다.

11. 트리거를 설정하십시오. 주기에 가장 적합한 가장 가벼운 메커니즘을 선택하십시오:

    • 이 세션에서 목표가 달성될 때까지 실행 → /goal <중단 조건> (조건이 참이 될 때까지 Claude가 여러 턴에 걸쳐 작업; /goal clear로 조기 종료)
    • 주기적으로 반복, 요청 시 → /loop
    • 정기적 및 무인 → 예약된 작업 (또는 CI 측 루프의 경우 cron / GitHub Action)
    • 이벤트(푸시, PR, 파일 변경)에 반응 → 훅 또는 GitHub Action

예약된 작업을 생성하기 전에 사용자에게 확인을 받으십시오.

12. 수동 실행, 확인 후 활성화하십시오. 한 사이클을 수동으로 실행하십시오. 생성된 모든 것을 읽으십시오. 검사자가 잘못된 출력을 실제로 차단하고 상태가 기록되었는지 확인하십시오. 그런 다음에만 트리거를 활성화하십시오.

가드레일(논의 불가)

• 검사자는 절대 제작자가 될 수 없습니다. 코드를 작성한 에이전트가 코드를 올바르다고 선언할 수 없습니다.
• 중단 조건은 검증 가능해야 하며, 감이 아니어야 합니다. "완료된 것처럼 보임"은 중단 조건이 아닙니다. 종료 코드 0을 반환하는 명령어가 중단 조건입니다.
• 상태는 매 사이클마다 기록됩니다. 루프가 시도한 것을 잊어버리면 반복하게 됩니다. 모델은 잊어버리지만 파일은 그렇지 않습니다.
• 되돌릴 수 없는 작업에는 인간 게이트가 유지되어야 합니다. 배송, 배포, 삭제, 비용 지출. 루프가 초안을 작성하고 사람이 확인합니다. 무인 루프는 무인 실수를 만듭니다.
• 차단됨은 추측보다 낫습니다. 루프가 확인할 수 없거나 진행할 수 없으면 ## Blocked에 기록하고 해당 항목을 중단합니다. 추측을 배송하지 않습니다.
• 긴 루프는 감시되고 제한됩니다. 모든 무인 루프는 모니터와 제한과 함께 실행됩니다. 목표에서 벗어나거나 제한을 초과하면 모니터가 중단하고 에스컬레이션합니다. 루프가 잘못된 방향으로 영원히 실행되는 일은 없어야 합니다.

설정 후 루프의 모습

your-project/
├── LOOP.md                   # 목표, 중단 조건, 제한, 규칙, Open/Done/Blocked
├── .claude/
│   └── agents/
│       ├── loop-maker.md      # 작업 단위 하나를 수행
│       ├── loop-checker.md    # 독립적으로 검증
│       └── loop-monitor.md    # 전체 루프를 드리프트 및 폭주로부터 감시
└── (트리거: /goal, /loop, 예약된 작업 또는 GitHub Action)

안티 패턴: 이것들은 배포하지 마십시오

• 중단 조건이 없는 루프(영원히 실행되고 토큰을 소모함).
• 자신의 작업을 작성하고 평가하는 단일 에이전트.
• 상태 파일이 없는 루프(모든 것을 재도출하고, 작업을 반복하며, 실패한 것을 잊어버림).
• 모니터 또는 제한이 없는 무인 루프(목표에서 벗어나 누군가 알아차리기 전에 몇 시간 동안 실행됨).
• 되돌릴 수 없는 작업에 인간 게이트가 없는 무인 배송.
• 하나의 루프가 많은 관련 없는 작업을 수행하는 경우. 하나의 루프, 하나의 목표, 하나의 중단 조건. 나머지는 각각의 자체 루프로 분할하십시오.

이 스킬의 파일

• templates/LOOP.md: 대상 저장소에 복사할 상태 파일.
• templates/loop-maker.md: 제작자 서브에이전트 정의.
• templates/loop-checker.md: 검사자 서브에이전트 정의.
• templates/loop-monitor.md: 모니터 서브에이전트 정의(드리프트 및 폭주 방지).
• examples/keep-ci-green.md: 목표에서 트리거까지, 완전히 작업된 예제 루프.