모든 사람들이 루프에 대해 이야기하고 있습니다. 하지만 루프가 무엇 위에서 실행되는지에 대해 이야기하는 사람은 거의 없습니다. 10 명 중 9 명의 빌더가 기본 하네스에서 Claude Code 를 실행합니다. 규칙도, 서브 에이전트도, 훅도, 메모리도 없이 말이죠.
그러면서 왜 루프가 형편없는 결과물을 만들어내는지 의아해합니다. 진실은 간단합니다. 루프는 그 아래에 있는 하네스만큼만 좋습니다. 이것이 하네스로 가는 14 단계 로드맵입니다. 하나의 에이전트에서 스스로 개선되는 시스템으로.
제 Substack 을 팔로우하여 최신 AI 알파를 받아보세요:
루프 엔지니어링(일정에 따라 에이전트를 프롬프트하는 시스템 구축)이 이번 달 모든 주목을 받았습니다. 하지만 루프에 대한 장문의 글을 쓴 Addy Osmani 는 그 아래에 무엇이 있는지 조심스럽게 지적했습니다.
“루프 엔지니어링은 하네스 한 층 위에 위치합니다. 하네스는 하나의 에이전트가 내부에서 실행되는 환경입니다. 루프는 하네스와 같지만, 타이머로 실행되고, 도우미를 생성하며, 스스로에게 피드백을 제공합니다.”
하네스 엔지니어링은 해당 환경을 설계하는 것입니다: 모델, 도구, 권한, 컨텍스트, 메모리.
화려하지 않은 레이어입니다. 그리고 그 위에 있는 모든 것이 제대로 작동하는지 결정하는 레이어이기도 합니다. 나쁜 하네스 위의 훌륭한 루프는 대규모로 쓰레기를 생산하는 빠른 방법입니다.
14 단계. 3 개 계층. 다른 모든 것이 서 있는 기초.
파트 1 · 하네스란 무엇인가
01. 하네스는 하나의 에이전트가 내부에서 실행되는 환경입니다.
전문 용어를 빼고 생각하면 하네스는 네 가지 요소입니다: 사고를 수행하는 모델, 도달할 수 있는 도구, 해당 도구에 대한 권한, 그리고 매 실행 시작 시 읽는 컨텍스트.
이것이 전체 표면입니다. 그 외의 모든 것(서브 에이전트, 훅, 메모리)은 이 네 가지 중 하나를 형성하는 방법입니다.
하네스가 사람들이 생각하는 것보다 더 중요한 이유는 에이전트가 도구를 선택하고, 실행하고, 결과를 확인하고, 다음 동작을 결정하는 while True 루프이기 때문입니다.
하네스는 어떤 도구가 존재하는지, 에이전트가 무엇을 할 수 있는지, 그리고 시작할 때 무엇을 알고 있는지를 정의합니다. 같은 모델, 다른 하네스, 완전히 다른 에이전트.
02. 전체 하네스는 하나의 폴더에 있습니다. .claude/
에이전트를 구성하는 모든 것은 프로젝트 루트의 단일 디렉토리에 있습니다. 이 레이아웃을 익히면 누구의 하네스든 한눈에 읽을 수 있습니다:
1.claude/2├─ CLAUDE.md # 고정된 사실 — 모든 세션에서 읽음3├─ settings.json # 권한, 모델, 훅4├─ .mcp.json # 외부 도구 연결5├─ rules/ # 경로별 동작6│ ├─ tests.md7│ └─ python-types.md8├─ agents/ # 서브 에이전트 정의 (각 ~30 줄)9│ ├─ reviewer.md10│ └─ eval-runner.md11├─ skills/ # 재사용 가능한 워크플로우12│ └─ pr-checklist/13│ └─ SKILL.md14└─ agent-memory/ # 실행 간 유지되는 정보15 └─ STATE.md
깔끔한 하네스와 엉망인 하네스를 구분 짓는 한 가지 규칙: 모든 파일이 존재하는 이유를 설명할 수 있을 정도로 작게 유지하세요. 규칙, 훅, 또는 서브 에이전트의 용도를 말할 수 없다면 삭제하세요.
03. 하네스 vs 루프 vs 시스템. 세 가지 층, 혼동하지 마세요.
대부분의 "내 에이전트 설정은 엉망이야"라는 문제는 세 가지 층을 혼동하는 데서 비롯됩니다. 명확히 구분하세요:
- 하네스는 하나의 에이전트가 살아있는 런타임입니다. 정적 구성: 모델, 도구, 권한, 컨텍스트. 이번 호.
- 루프는 타이머로 에이전트를 프롬프트하고, 도우미를 생성하며, 스스로에게 피드백을 제공합니다. 하네스 위에서 실행됩니다.
- 자기 개선 시스템은 루프와 복리 효과를 내는 메모리를 더한 것입니다. 매 실행마다 다음 실행이 더 예리해집니다.
실용적인 버전: 고정된 사실은 컨텍스트에, 강제 규칙은 훅에, 절차는 스킬에, 격리는 서브 에이전트에 배치하세요.
이것들을 혼동하는 것(CLAUDE.md 에 강제 규칙을 넣거나, 절차가 컨텍스트를 비대하게 만드는 것)은 일관성 없고 비용이 많이 드는 에이전트의 근본 원인입니다.
04. 기본 하네스. 기본 제공되는 것.
Claude Code 를 설치하고 폴더를 열면 이미 하네스가 있습니다. 단지 빈 하네스일 뿐입니다. 기본값은 강력한 모델, 내장 도구(읽기, 쓰기, bash, 검색), 그리고 모든 위험한 작업에 대한 승인 프롬프트를 제공합니다. 프로젝트 컨텍스트, 커스텀 서브 에이전트, 메모리는 없습니다.
한 번만 수행할 작업이라면 기본값으로 충분합니다. 두 번 이상 수행하는 작업이라면 기본값은 에이전트가 매 세션마다 프로젝트를 처음부터 다시 파악하게 하고, 안전한 작업에 대해 허가를 요청하게 하며, 터미널을 닫으면 모든 것을 잊어버리게 합니다.
다음 10 단계는 이 격차를 해소하는 방법입니다.
05. CLAUDE.md: 짧게 유지된 고정 사실.
CLAUDE.md 는 모든 세션 시작 시 읽힙니다. 에이전트의 프로젝트에 대한 고정된 지식입니다. 규칙, 아키텍처, "그 사건 때문에 우리는 이렇게 하지 않는다."
가장 흔한 단일 실수: 방대한 절차 문서로 성장하여 모든 세션을 비대하게 만드는 것입니다.
매일 이것을 실행하는 실무자들의 규칙: 기본 메모리 파일을 약 500 토큰 미만으로 유지하세요. 고정된 사실은 여기에 넣습니다.
다단계 절차는 스킬(8 단계)에 넣습니다. 경로별 동작은 해당 경로로 범위가 지정된 rules/ 파일에 넣습니다. CLAUDE.md 의 한 섹션이 사실이 아닌 절차가 되었다면, 다른 곳에 속합니다.
CLAUDE.md 를 소리 내어 읽어보세요. 모든 줄은
사실(fact)
이어야 하며, 에이전트가 모든 세션에서 필요로 하는 내용입니다 (“우리는 npm이 아닌 pnpm을 사용합니다”). 만약 줄이
절차(procedure)
(“기능을 추가하려면, 먼저…”), 스킬로 이동하세요.
만약 하나의 폴더에 대한 규칙이라면 rules/ 로 이동하세요.
06. settings.json: 권한과 모델, 한 번 설정.
기본 하네스는 모든 위험한 작업 전에 묻습니다. 지켜보고 있을 때는 옳지만, 그렇지 않을 때는 틀립니다. settings.json 은 안전한 작업을 사전 승인하고, 위험한 작업을 거부하며, 어떤 모델을 실행할지 선택하는 곳입니다.
1{2 "model": "claude-sonnet-4-6",3 "permissions": {4 "autoApprove": [5 "Read(*)", "Grep(*)",6 "Bash(npm test)", "Bash(git status)"7 ],8 "deny": [9 "Bash(rm -rf*)", "Bash(git push*)",10 "Edit(.env*)", "Edit(secrets/*)"11 ]12 }13}
자동 승인 여부를 결정하는 테스트: 이것이 잘못되었을 때 되돌리기가 얼마나 어려운가? 되돌리기 쉬움 → 자동 승인. 되돌리기 어려움(force-push, 파일 삭제, 시크릿 접근) → 항상 거부 또는 확인. 중간 지점은 로그를 기록한다면 자동 승인해도 괜찮습니다.
07. 서브 에이전트: 더러운 작업을 위한 격리된 컨텍스트.
서브 에이전트는 메인 에이전트에서 실행되는 독립적인 Claude 세션입니다. 자체 컨텍스트 윈도우, 자체 도구 목록을 가집니다. 목적은 병렬 처리 자체가 아닙니다. 메인 컨텍스트에서 노이즈를 제거하는 것입니다.
40 개의 파일을 읽는 연구 작업, 새로운 관점이 필요한 검토 패스, 로그 벽을 만들어내는 평가 실행은 서브 에이전트에 속하므로 메인 스레드를 오염시키지 않습니다.
GIF
모든 하네스에서 가장 가치 있는 서브 에이전트는 메인 에이전트가 수행한 작업을 확인하는 서브 에이전트입니다. 모델이 자신의 출력을 검토하는 것은 스스로에게 너그럽습니다. 새로운 컨텍스트 윈도우를 가진 별도의 리뷰어는 작성자가 스스로 납득시킨 내용을 잡아냅니다. 이것이 바로 하네스 위의 모든 루프를 신뢰할 수 있게 만드는 작성자 대 검증자 분할입니다.
08. 스킬: 에이전트가 재사용하는 절차.
스킬은 에이전트가 실행하는 SKILL.md 파일입니다. /skill-name으로 호출하거나 작업이 설명과 일치할 때 자동으로 실행됩니다.
서브 에이전트와 달리 동일한 컨텍스트 윈도우에서 실행됩니다. 세션의 일부가 되는 재사용 가능한 명령어일 뿐입니다.
스킬을 생성하는 트리거: 매번 새로운 대화에 동일한 지침을 붙여넣고 있다는 것을 깨닫는 순간입니다. 그것이 바로 스킬이 되어야 할 것입니다. PR 체크리스트, 평가 절차, 릴리스 프로세스 — 한 번 작성하고 영원히 호출합니다.
그리고 스킬은 재사용 가능한 단위이기 때문에 시간이 지남에 따라 하네스를 개선하게 만드는 요소입니다. 절차가 새로운 방식으로 실패할 때마다 그 교훈을 스킬에 추가하면 다음 실행이 이를 상속받습니다.
09. 훅: 모델이 환각을 일으킬 수 없는 결정론적 규칙.
지금까지의 모든 것은 모델이 지침을 이해하는 것에 달려 있습니다. 훅은 그렇지 않습니다.
훅은 에이전트 라이프사이클의 고정된 지점(도구 실행 전, 파일 변경 후, 세션 종료 시)에서 실행되는 셸 명령이며, 종료 코드는 작업을 차단할 수 있습니다. 훅은 강제이고, CLAUDE.md 는 제안입니다.
거의 모든 하네스에서 제자리를 찾는 두 가지 훅:
- PreToolUse 게이트: rm -rf, .env 읽기, main 으로의 푸시와 같은 위험한 명령을 결정론적으로 차단합니다. 종료 코드 2 는 호출이 실행되기 전에 중단시킵니다. 모델이 이를 우회하도록 설득할 수 없습니다.
- PostToolUse 포매터: 모든 편집 후 린터 또는 포매터를 실행합니다. 하네스가 자동으로 포맷하기 때문에 에이전트가 포맷되지 않은 코드를 출시하지 않습니다.
1"hooks": {2 "PreToolUse": [{3 "matcher": "Bash",4 "command": "./.claude/hooks/block-dangerous.sh"5 // exit 2 = 호출이 실행되기 전에 차단6 }],7 "PostToolUse": [{8 "matcher": "Edit|Write",9 "command": "prettier --write \"$CLAUDE_FILE_PATH\""10 }]11}
반드시 발생해야 하거나 절대 발생해서는 안 되는 작업(안전, 포매팅, 감사 로깅)에는 훅을 사용하세요.
판단이 필요한 작업에는 사용하지 마세요. 그것은 모델의 역할입니다. 좋은 하네스는 하나 또는 두 개의 예리한 훅을 가지고 있으며, 스무 개가 아닙니다.
파트 3 · 복리 효과 만들기
10. 루프 추가하기. 이제 하네스가 타이머로 실행됩니다.
구성된 하네스는 여전히 당신이 입력하기를 기다립니다. 루프는 자체적으로 실행되게 만듭니다. 가장 간단한 버전은 Claude Code 의 /loop 입니다. 주기적인 프롬프트입니다.
/goal 과 함께 사용하면 독립적인 평가자가 에이전트가 스스로 평가하는 대신 확인할 때까지 루프가 계속됩니다.
1> /loop 30m /goal 모든 테스트가 통과하고 린트가 깨끗합니다.2 새로운 실패를 분류하고, claude/ 브랜치에서 수정안을 작성합니다.34▲ Claude 는 당신이 구축한 하네스를 사용합니다:5 - rules/ 규칙 적용6 - reviewer 서브 에이전트가 각 수정사항 확인7 - PreToolUse 훅이 main 으로의 푸시를 차단8✓ 루핑 중. 독립적인 평가자가 "완료"를 결정합니다.
방금 무슨 일이 일어났는지 주목하세요. 루프는 지능을 추가하지 않았습니다. 하네스의 모든 것을 재사용했습니다 — 규칙, 리뷰어 서브 에이전트, 안전 훅. 좋은 하네스는 루프를 사소하게 만듭니다. 그것이 기초를 먼저 구축하는 이유의 전부입니다.
11. 동적 워크플로우 추가하기. 하네스가 자체 오케스트레이션을 작성합니다.
단일 루프에 비해 너무 복잡한 작업(대규모 병렬, 고도로 구조화된, 적대적)의 경우 Claude 는 즉석에서 자체 JavaScript 하네스를 작성할 수 있습니다.
이것이 동적 워크플로우입니다: 생성을 위한 agent(), 확장을 위한 parallel(), 스트리밍을 위한 pipeline(). 하네스가 정의하는 서브 에이전트를 확장 및 합성 또는 적대적 검증과 같은 패턴으로 구성합니다.
하네스 엔지니어링과의 연결 고리: 동적 워크플로우는 호출할 수 있는 서브 에이전트와 스킬만큼만 좋습니다.
하네스에 예리한 리뷰어 서브 에이전트와 잘 작성된 평가 스킬이 있다면 워크플로우는 오케스트레이션할 좋은 조각을 가집니다. 하네스가 비어 있다면 워크플로우는 함께 작업할 것이 없습니다.
워크플로우는 지휘자이고, 당신의 하네스는 오케스트라입니다.
12. 메모리 추가하기. 에이전트가 잊는 것을 하네스가 기억합니다.
이 단계는 구성된 하네스를 실제로 개선되는 시스템으로 바꿉니다. 에이전트는 실행 간에 모든 것을 잊어버립니다. 하네스는 그럴 필요가 없습니다.
상태 파일(agent-memory/ 의 마크다운 파일, 또는 Linear 보드)은 시도한 것, 효과가 있었던 것, 실패한 것, 살아남은 규칙을 기록합니다.
가장 강력한 에이전트가 사용하는 방식에서 가져온, 메모리가 복리 효과를 내는 패턴:
- 떠나기 전에 기록하세요. 모든 실행은 상태 파일을 업데이트하며 종료됩니다 — 얻은 교훈, 확인된 사실, 다음 단계.
- 시작할 때 읽으세요. 모든 실행은 상태 파일과 관련 스킬을 읽으며 시작하므로 다시 시작하는 대신 재개합니다.
- 스킬로 정제하세요. 교훈이 일반적일 때(“Windows 러너는 PowerShell이 아닌 bash 가 필요합니다”), 상태 파일에서 스킬로 졸업하여 모든 미래 프로젝트에 적용됩니다.
1# 프로젝트 메모리23## 확인된 사실 # 이에 대해 추측하지 마세요4- prc는 센트가 아니라 달러 단위입니다 (SELECT MIN/MAX로 확인됨)5- auth 미들웨어 순서: rate_limit -> jwt -> rbac67## 얻은 교훈 # 일반적인 것은 스킬로 정제하세요8- Windows CI 러너는 PowerShell에서 TLS 1.2에 실패합니다 — bash를 사용하세요9- 100만 행이 넘는 테이블의 마이그레이션은 1만 개 청크로 배치 처리해야 합니다1011## 마지막 세션 # 재시작하지 말고 재개하세요122026-06-11 · 3개 수정 병합, 2개 에스컬레이션. 다음: rate-limit 수정 확인.
13. 루프 닫기. 출력 → 교훈 → 스킬 → 더 나은 출력.
여기서 세 가지 층이 서로 맞물려 스스로 개선되는 무언가가 됩니다. 각 실행은 출력을 생성합니다. 리뷰어 서브 에이전트(7 단계)가 이를 확인합니다. 결과(통과한 것, 실패한 것, 배운 것)는 메모리(12 단계)에 기록됩니다. 일반적인 교훈은 스킬(8 단계)로 정제됩니다.
다음 실행은 더 예리한 스킬과 더 풍부한 메모리를 상속받습니다.
이것이 바로 자기 개선 루프의 전부이며, 이 모든 것이 하네스 부품으로 완전히 구축되었음을 주목하세요:
- 서브 에이전트가 작업을 평가합니다 — 객관적인 확인, 새로운 컨텍스트.
- 메모리가 평결을 기록합니다 — 실행 간에 유지됩니다.
- 스킬을 정제합니다.
- 루프가 다시 실행합니다 — 이제 마지막 실행에서 배운 모든 것을 가지고.
모델은 결코 변하지 않았습니다. 주변의 하네스가 더 예리해졌습니다. 이것이 '자기 개선'이 진정 의미하는 바입니다. 학습하는 모델이 아니라, 축적되는 하네스 말입니다.
14. 하네스 출시하기. 패키징하고. 공유하고. 재사용하세요.
하나의 프로젝트에서 작동하는 하네스는 자산입니다.
스킬, 서브 에이전트 및 규칙을 플러그인으로 묶으면 전체 팀이 동일한 설정을 한 단계로 설치합니다(동일한 규칙, 동일한 안전 훅, 동일한 리뷰어).
하네스는 더 이상 당신의 개인 설정이 아니라 공유 인프라가 됩니다.
마지막으로 한 번 더, 순서가 곧 교훈이므로 구축 순서를 말씀드립니다: 깔끔한 하네스에서 하나의 수동 실행을 안정적으로 만드세요. 컨텍스트와 권한을 추가하세요. 리뷰어 서브 에이전트를 추가하세요. 메모리를 추가하세요. 그런 다음, 오직 그런 다음에 루프로 감싸세요. 좋은 하네스 위의 루프는 복리 효과를 냅니다. 나쁜 하네스 위의 루프는 더 빨리 피를 흘릴 뿐입니다.
§ 모든 루프를 더 나쁘게 만드는 하네스 실수
- 기본값으로 실행. 컨텍스트, 규칙, 메모리 없음 — 에이전트가 매 세션마다 프로젝트를 다시 파악합니다.
- 비대한 CLAUDE.md. 절차가 고정된 컨텍스트에 채워져 모든 실행을 비대하게 만듭니다. 스킬로 이동하세요.
- 훅 대신 CLAUDE.md 에서 강제 규칙을 사용. 모델은 제안을 무시할 수 있습니다. exit 2 로 종료되는 훅은 무시할 수 없습니다.
- 하나의 에이전트가 자신의 작업을 작성하고 평가. 새로운 컨텍스트 윈도우를 가진 리뷰어 서브 에이전트를 추가하세요.
- 메모리 없음. 모든 실행이 0에서 다시 시작됩니다. 상태 파일이 내일의 재개를 가능하게 합니다.
- 나쁜 하네스에 루프를 감싸기. 루프는 더 빠르게 쓰레기를 생산할 뿐입니다. 기초를 먼저 구축하세요.
- 스무 개의 훅. 하나 또는 두 개의 예리한 훅이 아무도 이해하지 못하는 더미를 이깁니다.
- 스캔하지 않고 하네스 출시. 유출된 시크릿과 과도하게 광범위한 권한이 설치하는 모든 사람에게 퍼집니다.
결론:
루프가 영광을 얻습니다. 하네스가 일을 합니다.
루프 엔지니어링은 흥미로운 부분입니다. 에이전트가 스스로 프롬프트하고, 당신이 자는 동안 실행되는 것 말이죠. 하지만 루프는 타이머가 있는 하네스일 뿐입니다.
출력이 좋은지 형편없는지를 결정하는 모든 것은 한 층 아래에 있습니다, 당신이 선택한 모델, 허용한 도구, 작성한 컨텍스트, 추가한 리뷰어, 유지한 메모리에 달려 있습니다.
그 층을 잘 구축하면 그 위에 있는 모든 것이 복리 효과를 냅니다. 루프는 당신의 서브 에이전트를 재사용하고, 워크플로우는 당신의 스킬을 오케스트레이션하며, 메모리는 각 실행을 이전보다 더 예리하게 만듭니다.
자기 개선은 결코 모델의 속성이 아닙니다. 그것은 모델 주변에 구축하는 하네스의 속성입니다.
지금 하고 있지 않은 한 가지를 선택하세요(아마도 리뷰어 서브 에이전트, 안전 훅, 또는 상태 파일일 것입니다) — 그리고 오늘 추가하세요. 하네스를 설명할 수 있을 정도로 작게 유지하세요. 그런 다음 그 위에 루프를 올려놓고 기초가 작업을 수행하는 것을 지켜보세요.
