이 레포가 무엇을 하는 물건인가.
보통 우리는 AI 코딩 에이전트 하나에게 "이거 만들어 줘"라고 통째로 맡긴다. 그러면 그 한 명이 계획·구현·검증·커밋을 다 하는데, 자기가 짠 코드를 자기가 채점하니 객관성이 무너진다. architect-loop는 이걸 "판단하는 자(architect)"와 "만드는 자(builder)"로 분리한다.
핵심 통찰은 두 가지다. 첫째 "약한 설계자가 약한 시공자보다 더 해롭다" — 그래서 더 똑똑한 모델에게 설계를 맡긴다. 둘째 "에이전트는 자기가 보이는 테스트를 게임(gaming)한다" — 그래서 합격 기준을 시작 전에 얼려 두고(frozen gate), 설계자가 빌더의 말이 아니라 diff를 직접 읽는다.
architect-loop는 /architect(빌드 루프)와 /architect-research(리서치 루프) 단 두 개의 Claude Code 슬래시 명령을 제공한다. /architect는 "지난 실행을 판정 → 다음 한 조각(slice)을 스펙으로 작성 → 빌더 디스패치"라는 한 번의 작업 블록(work block)을 돌린다. /architect-research는 "무엇을 만들지" 아직 정하지 못했을 때, 인용이 달린 리서치 보고서를 만들어 빌드 루프의 PRD로 먹인다.
SKILL.md라는 마크다운 파일에 "이 역할을 맡을 때 따라야 할 규칙·절차"를 적어두면, 슬래시 명령(/architect)으로 그 페르소나를 불러올 수 있다. architect-loop는 실행 코드가 거의 없고, 잘 설계된 SKILL.md 텍스트가 본체인 "프롬프트 패키지"다.트렌딩 이유 · "AI 하나에게 다 맡기기" 대비 장점.
2026년의 코딩 에이전트들은 충분히 똑똑해졌지만, 장시간 무인 작업(unattended)에서 신뢰성이 무너진다는 공통의 약점이 있다. architect-loop가 트렌딩하는 이유는, 이 신뢰성 붕괴를 새 모델이 아니라 "운영 규율"로 막는다는 데 있다. 그리고 그 규율 하나하나에 출처가 달려 있다(DESIGN.md). 즉 "감으로 만든 프롬프트"가 아니라 근거 기반 설계라는 점이 개발자들에게 신뢰를 준다.
| 비교 항목 | AI 하나에게 통째로 맡기기 | architect-loop |
|---|---|---|
| 역할 분리 | 한 모델이 설계·구현·검증·커밋 전부 | 설계/심사 = Claude, 구현 = Codex로 분리 |
| 채점 주체 | 자기가 짠 코드를 자기가 채점(편향) | 아무도 자기 일을 채점하지 않음 — 빌더 주장은 전언, 설계자가 직접 게이트 실행 |
| 합격 기준 | 작업 중 즉흥적으로 조정 가능 | 시작 전 얼리고 커밋(frozen gate) — 빌더가 게이트 파일 수정 시 자동 실패 |
| 병렬화 | 대개 단일 스레드 | 1~4개 격리 worktree에서 빌더 병렬, 파일셋 겹침 사전 검사 |
| 메모리 | 긴 대화 컨텍스트(점점 썩음) | 레포 자체가 메모리 — 짧은 HANDOFF.md + 게이트/레인 파일 + git 히스토리 |
| 비용 모델 | API 키 종량제 | API 키 불필요 — Claude 구독 + ChatGPT 구독 quota 사용 |
| 설치 무게 | 프레임워크·런타임 설치 | 마크다운 파일 복사가 전부(install.sh 30초) |
① 자가 채점 편향. 에이전트가 직접 짠 코드를 직접 "통과했습니다"라고 보고하면, 통과한 테스트가 실제로 병합 가능한지(mergeable)는 별개다. 연구상 에이전트가 통과시킨 PR은 자주 병합 불가다. ② 테스트 게이밍. 보이는 테스트를 향해 반복 수정하면, 에이전트는 의도가 아니라 테스트를 만족시키는 꼼수를 학습한다. ③ 메모리 부패. 모든 맥락을 한 메모리 파일/긴 대화에 쌓으면, 그 파일이 비대해지며 정작 중요한 작업을 밀어낸다.
합격 기준을 시작 전에 docs/gates/에 커밋해 동결(① 게이밍 차단)하고, 설계자가 빌더와 다른 세션에서 게이트를 직접 돌리고 diff를 읽어(② 자가채점 차단) 판정한다. 메모리는 짧은 목차(HANDOFF.md ~150줄)로 유지하고 상세는 게이트/레인 파일로 분산(③ 부패 차단). 빌더는 각자 git worktree에 격리돼 충돌이 구조적으로 불가능하다. "레포에 없으면 일어나지 않은 일"이 원칙이다.
놀랍게도 "런타임"은 거의 없다 — 본체는 마크다운 프롬프트다.
architect-loop의 가장 충격적인 사실은 실행되는 애플리케이션 코드가 거의 없다는 점이다. 레포의 핵심 자산은 잘 설계된 마크다운 문서 7개다. 이들은 Claude Code와 Codex CLI라는 이미 존재하는 두 에이전트를 지휘하는 "운영 매뉴얼"이다. 즉 architect-loop는 "엔진"이 아니라 "두 엔진을 협업시키는 악보(score)"다.
| 요소 | 역할 |
|---|---|
skills/architect/SKILL.md | 설계자 페르소나의 본체 — 8개 하드 룰 + 절차(Ground→Arbitrate→Judge→Spec→Dispatch). effort: high 프론트매터. |
dispatch.md | 검증된 codex exec 명령·빌더 블록 템플릿·worktree 팬아웃·스톨 분류. 실제 CLI 동작에 맞춘 "현장 매뉴얼". |
research.md | 슬라이스 규모의 인라인 팩트체크 팬아웃(빌드 루프 안의 작은 리서치). |
HANDOFF.template.md | 레포-메모리 파일 골격. 매 세션 짧게 유지(목차+포인터). |
architect-research/SKILL.md | 리서치 오케스트레이션: scout→design→fan out→verify→write. |
lanes.md | scout 블록 + 소스 클래스별 전술 라이브러리(검증된 엔드포인트 포함). |
DESIGN.md | 34KB짜리 설계 문서 — 12개 강제 규칙·실패 모드 표·인용 출처. 이 레포의 진짜 본체. |
| 요소 | 역할 |
|---|---|
| Claude Code | 앤트로픽 터미널 코딩 에이전트. 여기서 설계자(Claude Fable 5) 역할로 동작. SKILL.md를 로드해 페르소나가 됨. |
| Codex CLI (≥0.133) | OpenAI의 코딩 CLI. 빌더(시공자) 역할. codex exec 헤드리스 모드로 비대화식 실행. |
모델: gpt-5.5 | 빌더가 쓰는 모델 슬러그. -codex 접미사 라인은 deprecated(흔한 오해). model_reasoning_effort="xhigh" 기본. |
| git worktree | 레인별 격리 작업 디렉토리. 빌더는 자기 worktree에서만 파일 수정, .git은 sandbox 보호로 read-only. |
| 웹 검색 (Codex) | 리서치 루프의 scout/researcher가 사용. codex exec는 --search 플래그를 거부(TUI 전용)하므로 설정으로 제어. |
| 요소 | 역할 |
|---|---|
install.sh / install.ps1 | 스킬 디렉토리를 ~/.claude/skills/(전역) 또는 ./.claude/skills/(--project)로 복사. Codex 버전도 체크. |
tests/validate_skills.py | stdlib만 쓰는 레포 무결성 검사 — 프론트매터 길이(≤1024자)·깨진 링크·불균형 코드펜스 등 실제로 겪은 실패 모드를 잡음. |
샌드박스: --sandbox workspace-write | 빌더의 유일한 권한 통제. .git을 read-only로 강제 → 빌더는 커밋 불가(설계자만 커밋). |
| quota | API 키 대신 ChatGPT 플랜의 5시간/주간 quota를 소모. 멀티시간 런은 주간 윈도우의 의미 있는 비중. |
.gitignore | /docs/ /.architect/ /research/ 무시 — 런타임 산출물은 레포에서 분리. |
-)으로 넘긴다 — 큰 프롬프트의 따옴표를 셸(특히 PowerShell)이 망가뜨려 무한 대기에 빠지는 사고를 막기 위해서다..git은 포인터 파일이고 그 실제 git 디렉토리도 샌드박스 보호를 받아 빌더는 공유 히스토리를 건드릴 수 없다.설계자-빌더 분업 + 얼린 게이트 + worktree 격리, 그리고 두 개의 루프.
한 번의 호출 = 한 번의 작업 블록(work block)이다. 설계자(Claude)는 판단만 하고 구현 코드는 한 줄도 쓰지 않는다. 지난 실행을 판정 → 다음 한 PR 분량의 슬라이스(slice)를 스펙으로 작성 → 1~4개 레인(lane)으로 쪼개 파일셋 겹침 검사 → 합격 기준(gate)을 먼저 커밋해 얼림 → 각 레인을 격리 worktree에서 Codex 빌더로 병렬 발사. 빌더가 끝나면 다른(fresh) 세션에서 설계자가 게이트를 직접 돌리고 diff를 읽어 통과 레인만 병합한다.
같은 시험을 출제한 선생님이 답안도 채점하면, 무의식적으로 "내가 의도한 답"에 후하게 점수를 준다. architect-loop는 발사한 그 세션에서는 절대 판정하지 않는다. 판정은 "이 코드가 어떻게 만들어졌는지 모르는" 새 세션이 맡는다. 출제와 채점을 다른 사람이 하는 셈 — 인용된 연구가 "fresh-context 리뷰가 더 정확하다"고 뒷받침하기 때문이다.
| 패턴 | architect-loop에서의 구현 |
|---|---|
| 설계/구현 분리 | 설계자는 구현 코드 작성 금지(하드룰 1). "약한 설계자가 약한 시공자보다 해롭다"는 근거. |
| 얼린 외부 게이트 | 합격 기준을 결과가 생기기 전에 커밋. 빌더가 게이트 파일을 만지면 git diff로 잡혀 자동 FAIL(하드룰 3). |
| 아무도 자기 채점 안 함 | 빌더 보고는 전언(hearsay). 설계자가 게이트를 직접 실행하고, 발사한 세션과 다른 세션에서 판정(하드룰 4). |
| 강제된 이견 | 빌더는 PHASE 0에서 실제 파일을 인용해 스펙에 반론해야 함. 침묵 순응 = 결함(하드룰 5). |
| 매니저+격리 워커 | 설계자=매니저, 빌더=worktree 격리 워커. 공유 파일 직접 조율은 throughput을 붕괴시킨다는 근거. |
| 레포가 메모리 | HANDOFF.md(짧은 목차)+gates/+lanes/+git history. 대화·빌더 출력에만 있는 결과는 판정 거부(하드룰 2). |
| 스톨 감지·구제 | liveness 체크, 자식 프로세스 트리 진단, "가장 좁은 것"만 kill, 모든 긴 명령에 명시적 타임아웃. |
| 스케일 매칭 | 사소한 수정은 루프 쓰지 말 것 — 루프는 슬라이스 규모 작업용. 도구를 작업에 맞춤. |
docs/gates/에 커밋해 "동결"한다. 레인 간 파일이 겹쳐 merge 충돌이 나면, 그것은 "레인 계획이 disjoint하지 않았다 = 스펙 결함"으로 보고 충돌 레인을 죽이고 재스펙한다(손으로 충돌 해결 안 함)."무엇을 만들지" 아직 결정 못 했을 때 쓰는 리서치 루프다. 고정된 레인 분류(taxonomy)를 쓰지 않고, 프로덕션 딥리서치 시스템처럼 scout가 먼저 지형을 그린 뒤 설계자가 토픽별 레인을 즉석 설계한다.
리서치 루프는 의도적으로 분리됐다. 깊은 병렬 리서치는 토큰을 엄청 먹기 때문에, 빌드 루프의 부작용으로 슬쩍 일어나면 안 되고 "의도적 행위"여야 한다는 것이 저자의 설명이다. 그래서 무엇을 만들지 정하는 단계(/architect-research)와 만드는 단계(/architect)를 명령부터 갈라 놓았다.
코드가 아니라 마크다운이 본체 — 그래서 구조가 곧 "역할 명세서".
① README.md로 "두 명령이 뭘 하나" 큰 그림 → ② skills/architect/SKILL.md의 Hard rules 8개로 "절대 규칙" 파악 → ③ dispatch.md로 빌더를 실제로 어떻게 발사하는지(codex exec·worktree) → ④ DESIGN.md로 각 규칙의 근거(인용)까지. 코드 한 줄 없이도 "멀티 에이전트 운영 규율"의 정수가 이 네 파일에 다 들어 있다.
"프레임워크 없이 프롬프트·규율만으로 멀티에이전트를 운영하는 법".
가장 큰 교훈은 "한 에이전트에게 다 시키지 말라"는 것이다. 계획·구현·검증·커밋을 한 모델이 다 하면 자가 채점 편향이 생긴다. architect-loop는 설계와 구현을 분리하고, 설계에 더 강한 모델을 배치한다 — 약한 부분을 시공이 아니라 설계에 두면 더 크게 망가진다는 근거에 따른 것이다. 모델·도구가 무엇이든 옮길 수 있는 원칙이다.
에이전트는 보이는 테스트를 향해 반복 수정하며 의도가 아니라 테스트를 만족시키는 꼼수를 배운다. architect-loop의 답은 ① 합격 기준을 작업 전에 커밋해 동결하고, ② 빌더가 그 게이트 파일을 만지면 git diff로 잡아 자동 실패시키며, ③ 게이트 통과는 필요조건일 뿐 — 설계자가 diff를 의도와 직접 대조한다는 것. "테스트 통과 ≠ 병합 가능"을 코드/절차로 강제한다.
긴 대화나 비대한 메모리 파일에 모든 맥락을 쌓으면 점점 부패해 정작 중요한 일을 밀어낸다. architect-loop는 HANDOFF.md를 짧은 "목차"로만 유지하고(매 세션 가지치기), 상세는 게이트·레인 파일로 분산시킨다. "레포에 없으면 일어나지 않은 일"이라는 규칙은 대화에만 있는 진행상황을 신뢰하지 말라는 강력한 규율이다. 이는 모든 장기 에이전트 작업에 적용된다.
무인 멀티시간 런에서 진짜 적은 "버그"가 아니라 조용히 멈춘 프로세스다. architect-loop는 ① --json 출력 파일이 15분+ 안 자라고 마지막 이벤트가 in_progress면 스톨로 판정, ② 자식 프로세스 트리를 진단(hot-spin vs blocked), ③ 전체가 아니라 "가장 좁은 멈춘 자식"만 kill해 빌더의 컨텍스트를 살린다. 모든 긴 명령엔 명시적 타임아웃을 건다. 운영(ops) 사고방식을 코드로 옮긴 좋은 예다.
asyncio.wait_for나 셸 timeout으로 개별 단계에 타임아웃을 거는 패턴을 익혀라.architect-loop가 신뢰받는 또 다른 이유는 모든 설계 결정에 출처를 붙였다는 점이다(DESIGN.md). "이렇게 하면 좋더라"가 아니라 "이 연구·이 시스템이 이렇게 한다"로 정당화한다. validate_skills.py도 추상적 베스트프랙티스가 아니라 "우리가 실제로 겪은 실패 모드"(프론트매터 1024자 초과로 Codex가 스킬 로드 거부 등)를 잡는다. "근거와 실제 실패에서 출발하라"가 핵심.
설치는 30초 — 진짜 요구사항은 "두 구독"이다.
| 항목 | 요구사항 |
|---|---|
| 설계자 | Claude Code — 유료 Claude 플랜 아무거나. SKILL.md를 ~/.claude/skills/에 설치. |
| 빌더 | Codex CLI ≥ 0.133(npm i -g @openai/codex@latest). ChatGPT 플랜에 로그인. |
| API 키 | 불필요(기본). Claude는 Claude 플랜, Codex는 ChatGPT 플랜 quota로 동작. |
| OS | bash(install.sh) 또는 Windows PowerShell(install.ps1). git 필요(worktree). |
| 비용 체감 | 빌더/연구원 런은 ChatGPT의 5시간/주간 quota를 소모 — 멀티시간 런 1회 = 주간 윈도우의 의미 있는 비중. 설계자 세션은 "시간"이 아니라 "분" 단위. |
| 검증(선택) | python tests/validate_skills.py — stdlib만 필요(추가 의존성 없음). |
| 적용 범위 | 슬라이스 규모 작업에 맞는 도구. 사소한 1줄 수정엔 루프를 쓰지 말 것(SKILL.md가 명시). |
난이도별 5단계 — 두 구독이 있으면 실제로, 없으면 "패턴 이식"으로.
레포를 클론하고 ./install.sh --project로 현재 테스트 레포에만 설치한 뒤, Claude Code에서 /architect와 /architect-research가 슬래시 명령으로 뜨는지 확인한다. codex --version이 0.133+ 인지도 체크. 아직 발사하지 말고 페르소나가 로드되는 것만 확인.
skills/architect/SKILL.md의 Hard rules를 읽고, 각 규칙이 "어떤 실패를 막는가"를 한 줄씩 적는다(예: 룰 4 = 자가 채점 편향 방지). 그다음 DESIGN.md에서 그 규칙의 인용 출처를 찾아 짝지어 본다. "규칙 ↔ 근거" 매핑 표를 직접 완성.
architect-loop가 없어도 패턴은 쓸 수 있다. 작은 기능 하나에 대해 ① 합격 기준을 텍스트 파일로 먼저 작성·git commit(동결) → ② AI에게 구현 시킴 → ③ 기준 파일을 수정하지 않고 그대로 채점 → ④ git diff로 기준 파일이 안 바뀌었는지 확인. 게이트가 변경되면 "FAIL"로 간주.
git worktree add로 같은 레포에 디렉토리 2개를 따로 체크아웃하고, 서로 겹치지 않는 파일셋을 각각 수정해 본다. 그다음 merge --no-ff로 합쳐 충돌이 없는지 확인. 일부러 같은 파일을 양쪽에서 고쳐 충돌을 내 본 뒤, "충돌 = 레인 분할 실패"라는 architect-loop의 판단을 체감하라.
두 구독이 있다면, 작은 실험 레포에서 /architect로 한 슬라이스를 실제로 발사한다. .architect/last-run.md(--json 출력)가 자라는 것을 지켜보고, 의도적으로 느린 작업을 시켜 15분+ 무성장 = 스톨 판정 로직을 관찰한다. 끝나면 설계자를 새 세션으로 띄워 게이트를 직접 돌리고 diff를 읽어 판정해 보라.
6주 코스 — 코딩 에이전트 기초부터 멀티에이전트 오케스트레이션 설계까지.
| 주차 | 주제 | 실습 · 참고 |
|---|---|---|
| 1주차 | 코딩 에이전트 CLI 기초 — Claude Code / Codex CLI 사용법, 헤드리스 실행 | 두 CLI 설치·기본 명령 · codex exec의 stdin 패턴 이해 |
| 2주차 | 에이전트 스킬 작성 — SKILL.md 프론트매터·페르소나·절차 설계 | skills/architect/SKILL.md 정독 · 내 도메인의 미니 스킬 작성 |
| 3주차 | 역할 분리 토폴로지 — 매니저+워커, 설계/구현 분리 | DESIGN.md의 토폴로지 근거 · 한 작업을 스펙/구현 두 세션으로 분리 실험 |
| 4주차 | 검증 게이팅 — 얼린 게이트·반증·"테스트 통과 ≠ 병합 가능" | 게이트 동결 워크플로 직접 구축 · diff 리뷰 습관화 |
| 5주차 | 병렬 격리 — git worktree·파일셋 disjoint 검사·통합 전략 | dispatch.md의 worktree 팬아웃 · merge --no-ff 실습(과제 4) |
| 6주차 | 운영 견고성 + 딥리서치 오케스트레이션 — 스톨/타임아웃, scout-first 리서치 | dispatch.md 스톨 분류 · architect-research/lanes.md 전술 라이브러리 |
본문·소스에 나온 용어 빠른 참조.
| 용어 | 의미 |
|---|---|
| architect / builder | 설계자(판단·심사만, Claude) / 시공자(구현, Codex). 핵심 역할 분리. |
| Fable | Claude를 설계자 역할로 운용할 때의 별칭(원 아이디어 출처에서 유래). |
| SKILL.md | Claude Code 스킬 정의 파일. 프론트매터(name·description·effort)+절차. 슬래시 명령으로 로드. |
| slice (슬라이스) | 한 PR 분량의 작업 단위. 한 작업 블록이 한 슬라이스를 다룸. |
| lane (레인) | 슬라이스를 병렬로 나눈 갈래(1~4). 파일셋이 서로 겹치지 않게 분할. |
| gate (게이트) | 합격 판정 기준(테스트/린트/빌드). 작업 전 docs/gates/에 커밋해 동결. |
| frozen / freeze | 게이트를 결과 생성 전에 커밋해 잠금. 이후 수정(빌더든 누구든) = 자동 FAIL. |
| HANDOFF.md | 레포-메모리 파일. 짧은 목차(~150줄)로 유지, 매 세션 가지치기. |
| 레포가 메모리 | 대화·빌더 출력이 아니라 레포(파일·git)에 있는 것만 진실로 취급. |
| codex exec | Codex CLI 비대화식 헤드리스 실행. 프롬프트는 stdin(-)으로 전달. |
| gpt-5.5 | 빌더 모델 슬러그. -codex 접미사 라인은 deprecated. |
| xhigh | model_reasoning_effort 값. 무인 작업 기본값(리뷰 생존 데이터 근거). |
| git worktree | 한 레포의 다중 작업 디렉토리. 레인 격리에 사용. .git은 sandbox로 read-only. |
| sandbox workspace-write | 빌더 권한 통제. .git read-only → 빌더는 커밋 불가(설계자만 커밋). |
| PHASE 0 (이견) | 빌더가 빌드 전 실제 파일을 인용해 스펙에 반론하는 단계. 침묵 순응=결함. |
| stall (스톨) | --json 출력이 15분+ 무성장 + 마지막이 in_progress인 멈춤 상태. |
| scout | 리서치 루프에서 값싸게 토픽 지형을 먼저 그리는 1차 패스(~10검색). |
| saturation stop | 새 정보가 더 안 나오면 검색을 멈추는 리서치 종료 조건. |