cobusgreyling/loop-engineering

Loop Engineering – 자율적인 AI 에이전트 루프 설계, 실행 및 평가

무엇인가요 – CLI 기반 프레임워크로, 수동 프롬프트를 반복 가능한 "루프"로 대체하여 작업을 탐지하고, LLM 기반 에이전트(Claude, Grok, Codex, Opencode 등)에 위임하며, 출력을 검증하고 상태를 기록합니다. 어떤 코드 리포지토리에도 쉽게 연결 가능한 미리 준비된 패턴(일일 트리아주, PR 베이비시터, CI 스위퍼 등) 라이브러리를 제공하며, 로컬 또는 GitHub Actions에서 실행 가능합니다.

왜 중요한가요 – 신뢰할 수 있는 AI 에이전트 파이프라인을 구축하는 것은 어렵습니다. 루프가 언제 실행될지, 자신의 작업을 어떻게 평가할지, 비용을 어떻게 통제할지 결정해야 합니다. Loop Engineering은 구조화된 체크리스트, 루프의 지식을 추적하는 STATE.md 파일, 그리고 L1–L3 단계의 스코어링 시스템을 제공하여 "보고만"에서 완전히 감시되지 않는 자동화로 전환할 수 있는 시점을 명확히 알려줍니다.

---

핵심 개념

개념	설명
패턴	사전 정의된 워크플로우(예: daily-triage)로, 주기, 초기 안전 수준(L1–L3), 예상 비용을 지정합니다.
도구	에이전트에 사용되는 기반 LLM(claude 기본값, grok, codex, opencode 지원).
STATE.md	루프의 학습된 상태를 지속적으로 저장하는 마크다운 파일. CLI가 처음 실행 시 생성 절차를 안내합니다.
루프 준비 스코어	최근 실행이 더 높은 가중치를 가지며, 루프 설계의 품질을 수치로 반영합니다.
레벨	L1 = 보고만, L2 = 보조, L3 = 감시 없음. 일주일간 정확한 검증이 이루어진 후에만 승격 가능합니다.

---

시작하기 (5분 빠른 시작)

# 현재 리포지토리에 루프 초기화
npx @cobusgreyling/loop init . --pattern daily-triage --tool claude

# 건강 점검 실행
npx @cobusgreyling/loop doctor .

# 선택한 패턴의 비용 추정 보기
npx @cobusgreyling/loop cost --pattern daily-triage --level L1

--tool을 생략하면 CLI는 기본적으로 Claude를 사용합니다.

이 명령어는 STATE.md 파일과 루프가 모니터링할 항목(이슈, CI, 종속성 등)을 설명하는 소규모 설정 파일들을 생성합니다. 첫 번째 주가 끝나면 L1 보고서가 생성되어 루프가 어떤 작업을 수행했을지 확인할 수 있습니다. 검증이 일관되게 정확하면 레벨을 올려 자동으로 작동하도록 설정할 수 있습니다.

---

주요 패턴 (하나 선택하여 시작)

패턴	주기	1주차 출력	일반적인 비용
일일 트리아주	1일 – 2시간	리포지토리 건강 상태 L1 보고서	낮음
PR 베이비시터	5–15분	들어오는 PR의 L1 모니터링	높음
CI 스위퍼	5–15분	L2에서 신중한 불안정한 CI 수정	매우 높음
의존성 스위퍼	6시간–1일	L2에서 패치만 업데이트	중간
CHANGELOG 드래프터	1일 또는 태그 생성 시	L1 CHANGELOG 드래프트	낮음
머지 후 정리	1일–6시간	L1 비피크 시간 정리	낮음
이슈 트리아주	2시간–1일	L1 제안만 하는 이슈 처리	낮음

각 패턴은 patterns/ 디렉터리에 있으며, 마크다운 설명과 patterns/registry.yaml에 YAML 엔트리가 포함되어 있습니다. 인터랙티브 선택기는 쇼케이스 사이트에서 이용 가능합니다.

---

예시 워크플로우

• Claude Code – Claude를 사용해 코드 변경을 생성하고 VS Code 플러그인 포함.
• Grok 일일 트리아주 – 새 리포지토리에서 Grok 기반 트리아주 루프 실행.
• GitHub Actions 경량 루프 – 단일 워크플로우 파일로 리포지토리에 추가 가능. 추가 STATE.md 필요 없음.

모든 예시는 examples/ 디렉터리에 있으며, 동일한 CLI 명령어로 실행 가능합니다.

---

안전성 및 운영 가이드

• 실패 모드 – docs/failure-modes.md에 기록됨(예: 폭발적인 토큰 사용, 환상적인 수정).
• 안티패턴 – docs/anti-patterns.md에서 검증 없이 과도한 자동화와 같은 일반적인 함정을 확인.
• 안전성 체크리스트 – docs/loop-design-checklist.md는 레벨 승격 전에 루프를 검증하는 절차를 안내합니다.
• 스토리 – 실제 성공 사례와 실패 사례는 stories/에 수집되어 커뮤니티에서 배울 수 있도록 제공됩니다.

프로젝트는 루프가 인간의 판단을 강화한다고 강조합니다. 감시되지 않는 루프는 비용이 큰 실수를 할 수 있으므로, L1→L2→L3의 단계적 진화는 필수입니다.

---

커뮤니티 및 기여

• 도입자 목록 – "add-adopter" 이슈 템플릿을 통해 프로젝트를 추가.
• 초보자용 이슈 – 초보자에게 적합한 라벨이 지정되어 있으며, 유지보수자는 48시간 내에 응답을 목표로 합니다.
• 보조 리포지토리 – memory-engineering, outerloop 등은 루프가 신뢰성 있는 것을 입증한 후에 사용할 수 있는 선택적 확장 기능입니다.

---

라이선스

MIT – 자유롭게 사용, 수정, 배포 가능.

---

결론 – Loop Engineering은 LLM 에이전트를 코드베이스 주변의 반복 가능하고 감사 가능한 자동화 루프로 전환할 수 있는 실용적이고 패턴 기반의 툴킷입니다. 명확한 온보딩 경로, 안전성 지원 구조, 그리고 언제 루프가 스스로 행동할 수 있는지 알 수 있는 스코어링 시스템을 제공합니다.