이 레포가 무엇을 하는 물건인가.
loop-engineering은 "AI 코딩 에이전트를 혼자 작동하게 만드는 시스템(루프)을 설계하는 패턴 레퍼런스"다. 루프가 프롬프트를 대신 생성하고, 작업을 발견하고, 결과를 검증하고, 다음 루프를 이어간다. 당신은 그 루프 자체를 설계하는 엔지니어가 된다.
실행 가능한 앱이 아니라 설계 지식 모음이다 — 패턴, 체크리스트, 실패 사례, CLI 도구, 복사해서 쓸 수 있는 스타터 키트가 하나의 레포에 체계화되어 있다.
'vibe coding'에서 'agentic engineering'으로의 패러다임 전환.
트렌딩의 배경에는 명확한 시대적 맥락이 있다. 2025~2026년에 Claude Code, Grok Build, Codex CLI 등 "터미널에서 도는 AI 코딩 에이전트"가 실용화 단계에 진입했다. 초기에는 "AI한테 잘 물어보는 법(프롬프트 엔지니어링)"이 핵심 스킬처럼 여겨졌다. 그러나 에이전트를 하루 종일 쓰다 보니 새로운 병목이 드러났다: 사람이 직접 프롬프트를 치는 것 자체가 병목이다.
이 레포는 그 병목을 정면 공략한다. Peter Steinberger("더 이상 코딩 에이전트에게 직접 프롬프트하면 안 된다, 에이전트를 프롬프트하는 루프를 설계해야 한다")와 Boris Cherny("나는 루프가 Claude에게 프롬프트하게 한다, 내 일은 루프를 작성하는 것")의 선언을 실전 패턴으로 구체화한 첫 번째 체계적 레퍼런스다.
개별 프롬프트를 잘 다듬는 것은 세션이 끝나면 초기화된다. 에이전트는 이전 대화를 모른다. 매번 컨텍스트를 다시 설명하고, 오늘 작업을 다시 찾아야 하고, 검증도 손으로 해야 한다. 프롬프트가 아무리 좋아도 "내가 직접 매번 해야 한다"는 구조적 한계는 사라지지 않는다.
이것이 인텐트 부채(Intent Debt)다 — 세션마다 에이전트가 컨텍스트를 추측으로 채운다. 루프 엔지니어링은 이 빚을 스킬(SKILL.md)로 갚는다.
루프는 스케줄에 따라 작업을 스스로 발견하고(CI 실패, 이슈, PR), 스킬 파일에서 판단 기준을 읽고, 구현 에이전트를 실행하고, 검증 에이전트로 결과를 확인하고, 상태 파일에 기록하고, 사람이 결정해야 할 항목만 에스컬레이션한다. 사람은 루프가 만든 STATE.md를 읽고 승인하거나 방향을 조정하는 역할로 올라선다.
코드가 아닌 '지식·패턴 레퍼런스' — 다루는 개념과 도구 전체 지도.
이 레포는 실행 파일이 아니라 체계화된 설계 지식이다. 크게 네 층위로 구성된다.
| 개념 | 정의 | 실전 의미 |
|---|---|---|
| 루프(Loop) | 재귀적 목표 실행 체계 | 스케줄+트리아지+상태+검증의 연결고리 |
| 에이전트 하니스 | 단일 에이전트의 실행 환경 | 도구·권한·컨텍스트 설정 = 하니스, 반복 오케스트레이션 = 루프 |
| 팩토리 모델 | 소프트웨어를 만드는 시스템 | 파이프라인·에이전트·핸드오프의 공장 라인 |
| 인텐트 부채 | 세션마다 쌓이는 컨텍스트 추측 | 스킬 파일로 해결 — 한 번 작성, 매 실행 읽기 |
| 이해 부채 | 루프가 만든 코드를 이해 못 하는 상태 | 루프 속도 올릴수록 빠르게 쌓임 |
| 인지 항복 | 루프에 판단을 전부 넘긴 상태 | 루프 설계에 의견이 없어지는 문화적 위험 |
| 오케스트레이션 세금 | 병렬 에이전트 조율에 드는 인간 비용 | 워크트리가 기계적 충돌을 제거, 인간은 여전히 병목 |
| 프리미티브 | 역할 | 없으면? |
|---|---|---|
| 스케줄링·자동화 | 루프의 심장박동 — 주기적 실행 | 일회성 에이전트 실행에 그침 |
| 워크트리(Worktrees) | 에이전트별 격리된 작업 디렉토리 | 병렬 에이전트가 같은 파일 수정 → 충돌 |
| 스킬(Skills) | 프로젝트 컨벤션·판단 기준의 영구 메모리 | 에이전트가 매번 처음부터 추측 |
| 플러그인·커넥터(MCP) | 외부 도구(Linear, GitHub, Slack) 연결 | 파일시스템 밖으로 영향 못 미침 |
| 하위 에이전트 | 구현자(Maker) / 검증자(Checker) 분리 | 자기 작업을 자기가 평가 — 신뢰 불가 |
| 메모리·상태(STATE.md) | 세션 밖에서 살아남는 영구 기억 | 루프가 매번 기억상실 상태에서 시작 |
| 패턴 | 주기 | 시작 단계 | 토큰 비용 |
|---|---|---|---|
| Daily Triage | 1일/2시간 | L1 리포트 전용 | 낮음 (~50k/회) |
| PR Babysitter | 5~15분 | L1 모니터 | 높음 |
| CI Sweeper | 5~15분 | L2 신중하게 | 매우 높음 |
| Dependency Sweeper | 6시간/1일 | L2 패치 전용 | 중간 |
| Changelog Drafter | 1일/태그 | L1 초안 | 낮음 |
| Post-Merge Cleanup | 1일/6시간 | L1 오프피크 | 낮음 |
| Issue Triage | 2시간/1일 | L1 제안 전용 | 낮음 |
| 도구 | 설치 | 역할 |
|---|---|---|
| loop-audit | npx @cobusgreyling/loop-audit | 루프 준비도 점수(L0~L3) 자동 측정 |
| loop-init | npx @cobusgreyling/loop-init | 패턴별 스타터 키트 자동 생성 |
| loop-cost | npx @cobusgreyling/loop-cost | 토큰 비용 사전 추정 |
루프의 구조도 + 핵심 설계 패턴.
루프 엔지니어링의 핵심 설계 원칙은 "절대 L1을 건너뛰지 마라"다. 3단계를 단계별로 신뢰를 쌓아야 한다.
구현 에이전트는 절대 자기 작업을 '완료'로 표시할 수 없다. 동일한 에이전트(혹은 동일 세션)가 구현하고 검증하면 확증 편향이 생기고 약한 테스트를 통과시킨다.
검증자는 별도 에이전트·별도 모델·별도 지시를 가지며, 기본 자세는 "REJECT"다. 강한 모델을 검증자에 쓰는 것이 무인 루프에서 특히 중요하다.
# STATE.md — 루프의 영구 기억, 세션 경계를 넘나든다
# Loop State — Project X
Last run: 2026-06-27 08:15 UTC
## High Priority (루프 행동 중 or 인간 대기)
- [ ] #1241 — auth 플로우 플레이키 테스트 (main CI 레드)
Loop action: 워크트리 열림. 수정 제안됨. 인간 PR 리뷰 대기.
## Watch List
- PR #1238 활동 없이 4일째 오픈.
## Recent Noise (이번 회 무시)
- Dependabot PRs (별도 자동화로 처리)
이 레포 자체가 루프 엔지니어링으로 운영된다 — "개밥 먹기(dogfood)".
이 레포에서 무엇을 배울 수 있는가.
모든 반복 작업은 루프로 표현할 수 있다. 핵심은 다음 4가지 질문에 답하는 것이다.
| 질문 | 루프 설계 요소 | 예시 |
|---|---|---|
| 무엇을 발견하나? | 트리아지 스킬 | CI 실패, 오픈 이슈, 오래된 PR |
| 무엇을 기억하나? | STATE.md 스키마 | 지난 실행 결과, 대기 항목 |
| 누가 만들고 누가 검증하나? | Maker/Checker 분리 | 구현 에이전트 → 검증 에이전트 |
| 사람이 언제 개입하나? | 인간 게이트 정의 | 보안·결제·인프라 변경, 3회 실패 |
docs/anti-patterns.md의 10개 안티패턴은 루프 설계 교과서다. 각 안티패턴은 "왜 실패하는가"와 "대신 무엇을 하라"가 쌍으로 제시된다.
같은 세션이 자기 작업을 "완료"로 표시하면 확증 편향이 생기고 약한 테스트가 통과된다. 구현자와 검증자는 반드시 분리되어야 하고, 검증자의 기본 태도는 "거부"여야 한다.
무한 수정 루프가 생기고 토큰이 폭발한다. 항목당 최대 3회 시도 후 반드시 에스컬레이션해야 한다.
루프는 에이전트를 자동 실행하므로 비용이 눈에 보이지 않는다. docs/operating-loops.md는 실용적인 비용 계획 프레임워크를 제공한다.
| 루프 유형 | 주기 | 일 실행 횟수 | 대략적 토큰/일 |
|---|---|---|---|
| 일간 트리아지 (L1) | 1일 | 1회 | ~50k |
| CI 스위퍼 (풀 실행) | 15분 | 96회 | ~5M (위험!) |
| 보조 수정 포함 (L2) | 1일 | 1회 | ~200k |
핵심 원칙: 트리아지 패스는 저렴하게. 행동 항목이 없으면 5k 토큰 이내에 종료. 하위 에이전트는 "행동 가능한 항목이 있을 때만" 소환해야 한다.
코드 레포가 아니므로 "어떻게 읽고 적용하는가"가 핵심이다.
무작정 읽으면 정보가 많아서 길을 잃는다. 다음 순서를 권장한다.
| 순서 | 파일 | 이유 |
|---|---|---|
| 1 | README.md | 전체 지도와 핵심 인용문 |
| 2 | docs/concepts.md | 루프 엔지니어링 용어 정립 |
| 3 | docs/pattern-picker.md | 어느 패턴부터 시작할지 결정 |
| 4 | patterns/{선택}.md | 선택한 패턴 상세 설계 이해 |
| 5 | starters/{선택}/ | 스타터 키트 복사해서 실전 투입 |
| 6 | docs/anti-patterns.md | 설계 실수 미리 피하기 |
| 7 | docs/failure-modes.md | 문제 발생 시 진단표로 활용 |
# 1. 스타터 자동 생성 (npm 설치 불필요, npx 직접 실행)
npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude-code
# 2. 토큰 비용 사전 추정
npx @cobusgreyling/loop-cost --pattern daily-triage --level L1
# 3. 루프 준비도 점수 측정
npx @cobusgreyling/loop-audit . --suggest
# 4. 수동 클론 후 원하는 스타터만 복사
git clone --depth 1 https://github.com/cobusgreyling/loop-engineering.git
cp -r loop-engineering/starters/daily-triage/. my-project/# Claude Code 터미널에서 직접 실행
/loop 1d Run $loop-triage skill. Update STATE.md.
No auto-fix in week one — report only.이 레포는 실행 가능한 소프트웨어 제품이 아니다. 개념을 정리한 설계 가이드다. npm CLI 3개(loop-audit, loop-init, loop-cost)는 실제 도구이지만, 핵심 가치는 어떻게 루프를 설계하느냐는 사고 프레임워크에 있다. 이 레포를 "클론해서 실행"하는 것보다 "읽고 자신의 프로젝트에 적용"하는 것이 올바른 사용법이다.
루프 엔지니어링 패턴을 실제로 손에 익히는 난이도별 과제.
자신의 프로젝트 폴더에서 npx @cobusgreyling/loop-audit . --suggest를 실행하고, 점수와 개선 제안을 읽어보자. 점수가 낮으면 어떤 파일이 빠진 것인지 확인하고, 레포의 templates/에서 STATE.md나 LOOP.md 템플릿을 가져다 추가한다.
npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude-code로 스타터를 생성하고, 생성된 LOOP.md와 STATE.md, .claude/ 스킬 파일을 읽어본다. Claude Code에서 /loop 1d Run $loop-triage를 실행하고 STATE.md에 어떤 내용이 쌓이는지 확인한다. 1주일 동안 리포트 전용(L1)으로 운영해 트리아지 품질을 측정한다.
starters/ci-sweeper/의 .claude/agents/loop-verifier.md를 열어 검증 에이전트의 지시문을 분석한다. 자신의 프로젝트에서 "구현 에이전트 → 검증 에이전트" 체인을 직접 작성해본다. 검증자 프롬프트에 "기본 태도는 REJECT, 실제 테스트 실행 후 합격 여부 판정"을 명시적으로 넣어야 한다.
npx @cobusgreyling/loop-cost --pattern ci-sweeper --cadence 15m를 실행해 이론적 비용을 계산한다. 실제 자신이 쓰는 AI API 요금제 한도와 비교해 하루 최대 토큰 예산을 정하고, templates/loop-budget.md.template을 기반으로 자신의 loop-budget.md를 작성한다. "예산 초과 시 → 스케줄러 중지 → 인간 알림" 킬 스위치를 스킬에 인코딩한다.
docs/anti-patterns.md의 10개 패턴을 자신의 루프 설계에 대조해 "이 안티패턴이 현재 내 설계에 있는가?"를 점검하는 리뷰 체크리스트로 변환한다. 각 항목마다 "지금 내 설계 상태"와 "수정 방향"을 적는다. 완성된 체크리스트를 AGENTS.md나 스킬 파일에 추가해 에이전트가 루프 설계 시 자동으로 참조하게 만든다.
루프 엔지니어링을 중심으로 연결되는 기술 영역 주차별 학습.
| 주차 | 주제 | 학습 목표 | 자료 |
|---|---|---|---|
| 1주 | 루프 철학 · 개념 이해 | 루프 엔지니어링 6개 프리미티브 암기, 인텐트 부채·이해 부채 구분 | 이 레포 docs/concepts.md + README |
| 2주 | Claude Code 기초 | 터미널 에이전트 설치·실행, SKILL.md 파일 작성법, /loop 명령 사용 | Claude Code 공식 문서 |
| 3주 | 첫 루프 실전 | Daily Triage L1 세팅, STATE.md 스키마 설계, 1주일 운영 후 트리아지 품질 측정 | 이 레포 starters/daily-triage |
| 4주 | Git Worktree 격리 | git worktree 사용법, 에이전트 격리 실험, 병렬 실행 충돌 재현 후 해결 | git 공식 문서 + 이 레포 primitives.md |
| 5주 | MCP 커넥터 연동 | GitHub MCP 읽기 전용 연결, Linear 이슈 자동 조회, 쓰기 권한 단계적 확장 | 이 레포 examples/mcp/ |
| 6주 | Maker/Checker 구현 | CI Sweeper L2 세팅, 검증 에이전트 분리 구현, 자동화 3회 실패 시 에스컬레이션 | 이 레포 starters/ci-sweeper/ |
| 7주 | 비용·관측성 | loop-cost 추정, loop-budget.md 작성, run-log 자동 기록, 메트릭 대시보드 설계 | 이 레포 operating-loops.md + loop-cost 도구 |
| 8주 | 고장 모드 대응 | failure-modes.md 10개 시나리오 시뮬레이션, 킬 스위치 구현, 사후 분석 stories/ 작성 | 이 레포 failure-modes.md + safety.md |
이 레포의 핵심 용어 한국어 해설.
| 용어 | 한국어 해설 |
|---|---|
| Loop Engineering | 에이전트에게 직접 프롬프트하는 역할을 대체하는 시스템(루프)을 설계하는 엔지니어링 분야 |
| Loop (루프) | 목표를 정의하면 AI 에이전트가 반복적으로(스케줄+상태+검증) 완료하거나 인간에게 넘기는 재귀적 실행 체계 |
| Agent Harness | 단일 에이전트 세션의 실행 환경(도구·권한·컨텍스트). 루프 = 하니스 + 스케줄 + 상태 + 검증 체인 |
| Maker / Checker | 구현 에이전트와 검증 에이전트를 분리하는 설계 패턴. 구현자는 절대 자기 작업을 완료로 표시할 수 없다 |
| Intent Debt | 에이전트가 매 세션 컨텍스트를 추측으로 채우는 누적 비용. SKILL.md 작성으로 해결 |
| Comprehension Debt | 루프가 만든 코드를 인간이 이해하지 못하게 되는 상태. 루프 속도가 빠를수록 빠르게 쌓임 |
| Cognitive Surrender | 루프에 판단을 전부 넘기고 인간이 의견을 갖지 않게 되는 문화적 위험 |
| STATE.md | 루프의 영구 기억 파일. 세션 경계를 넘어 "무엇을 하고 있나, 지난번 결과는 무엇인가"를 기록 |
| SKILL.md | 프로젝트 컨벤션·판단 기준을 에이전트가 매 실행 읽는 영구 지식 파일. 인텐트 부채 해결 도구 |
| L1 / L2 / L3 | 루프 성숙도 단계. L1=리포트 전용, L2=소규모 자동 수정+검증자, L3=무인 자동화(모든 체크리스트 충족) |
| Worktree | 각 에이전트가 독립적으로 파일을 편집할 수 있는 격리된 git 작업 디렉토리 |
| MCP | Model Context Protocol. 에이전트와 외부 도구(GitHub, Linear, Slack) 연결 표준 프로토콜 |
| loop-audit | 프로젝트의 루프 준비도 점수를 자동 측정하는 CLI. npx @cobusgreyling/loop-audit |
| loop-init | 패턴·도구 선택 시 스타터 키트(STATE.md, LOOP.md, 스킬 등)를 자동 생성하는 CLI |
| loop-cost | 선택한 패턴과 주기로 발생할 토큰 비용을 사전 추정하는 CLI |
| Denylist | 루프가 절대 자동 수정하면 안 되는 경로 목록. .env, auth/**, payments/** 등 |
| Factory Model | 소프트웨어를 만드는 시스템 자체 — 파이프라인·에이전트·체크·핸드오프의 공장 라인 비유 |
| Orchestration Tax | 병렬 에이전트 조율에 드는 인간 비용. 워크트리로 기계적 충돌을 제거해도 리뷰 bandwidth는 여전히 병목 |
출처·관련 자료.