SELFISH AAA
arrow_back 주간 미션으로 돌아가기

week 06 흐민 submit

하네스와 오케스트레이션 — 개념 정리와 Selforge 적용

1. 하네스(Harness)란

쉽게 풀어내면

“LLM을 일하게 만드는 바깥쪽 껍데기” 다.

: LLM 자체는 텍스트를 받으면 텍스트를 뱉는 함수일 뿐이다. 파일을 읽지도, 명령을 실행하지도, 기억을 유지하지도, 스케줄에 맞춰 깨어나지도 않는다. 이 모델을 실제 일꾼처럼 굴리려면 모델 주변에 다음과 같은 장치들이 필요하다.

  • 입력을 모으는 장치 — 사용자 메시지, 파일 내용, 시스템 지시사항을 한 덩어리의 컨텍스트로 조립한다.

  • 도구를 집행하는 장치 — 모델이 “이 명령을 써라”라고 말하면 실제로 셸에서 실행하고 결과를 돌려준다.

  • 루프를 유지하는 장치 — 모델이 끝났다고 말할 때까지 도구 호출 → 결과 주입 → 다음 판단을 반복한다.

  • 죽어도 다시 살리는 장치 — 프로세스가 터지거나 교착되면 재시작한다.

  • 외부 세계와 잇는 장치 — 크론, 메신저, 파일시스템, API를 컨텍스트 조각으로 변환해 모델에 주입한다.

이 껍데기 전체가 하네스다. 말이 끄는 마차에서 말과 마차를 연결하는 가죽 장구(harness)에서 온 비유 그대로, 모델의 힘을 실제 일로 전환시키는 전달 구조물이다.

핵심은 두 가지다.

  1. 하네스는 모델의 추론 능력을 업그레이드하지 않는다. 똑같은 모델이라도 하네스가 얼마나 좋은 맥락을 얼마나 싼값에 얹어주느냐에 따라 결과물 질이 갈린다.

  2. 하네스는 캐시 친화적이어야 한다. 매 턴 컨텍스트가 조금씩 바뀌면 프롬프트 캐시가 깨져 돈과 레이턴시를 다 잃는다. 그래서 “안정된 상단 + 가변 하단” 구조가 선이다.

Selforge에 어떻게 적용했는가

Selforge의 하네스는 Claude Code CLI + OMC 플러그인 + tmux 러너 + 워치독 + 훅이 겹친 다층 구조다.

(1) Claude Code 자체가 1차 하네스

CLI가 도구(Read/Write/Bash/Grep…), 서브에이전트 호출, MCP 서버 연결, 슬래시 커맨드, 스킬 로딩을 전부 관리해준다. 우리가 직접 만든 것이 아니라 “딛고 선 바닥”이다.

(2) OMC 플러그인으로 상단을 교체했다

~/.claude/CLAUDE.md에 OMC가 주입한 operating_principles / delegation_rules / model_routing / skills 블록이 상단에 고정된다. 이게 캐시 상단으로 자리잡아 매 세션 비용을 낮추면서, “Opus는 아키텍처·Haiku는 조회·Sonnet은 표준”처럼 모델 라우팅 규칙을 하네스에 박아 넣는다.

(3) 프로젝트 CLAUDE.md로 도메인 하네스를 얹었다

/Users/hminn/claude_projects/selforge/CLAUDE.md는 Selforge 고유 규칙(자동 발행 금지, Brand Voice 필수, Obsidian 볼트 보호, 흐민 언어 보존, Sullivan 톤 5원칙)을 프로젝트 컨텍스트로 주입한다. 즉 같은 Claude Code라도 Selforge 폴더에 진입하는 순간 행동 제약이 달라진다.

(4) 스크립트 레이어로 수명과 외부 연결을 붙였다

  • scripts/sullivan-runner.sh — while true; do claude …; sleep 5; done 무한 루프. Claude 프로세스가 죽어도 5초 뒤 되살아난다. 모델이 죽어도 하네스는 안 죽는다는 원칙.

  • scripts/start.sh — tmux 세션(sullivan-channel)을 띄우고 TUI가 준비되면 스케줄러 등록 프롬프트를 자동 입력한다. 세션 부팅의 자동화.

  • scripts/watchdog.sh — Telegram Bot API의 pending_update_count를 주기적으로 조회한다. 메시지가 두 번 연속 소비되지 않으면 “모델이 살아있지만 일을 안 한다”고 판정하고 세션을 강제 재시작한다. 교착 감지 + 자가 복구 장치

(5) 훅과 system-reminder로 런타임 컨텍스트를 주입한다

SessionStart / PreToolUse / PostToolUse 훅이 hot paths, 프로젝트 메모리, 병렬 실행 가이드 같은 조각을 <system-reminder> 태그로 매 턴 끼워 넣는다. 모델이 “기억”하는 게 아니라 하네스가 매번 재주입한다. <remember> / <remember priority> 태그는 영속 메모리를 이 주입 파이프라인에 연결한 것.

(6) 채널과 스케줄이 외부 세계와의 접점이다

텔레그램 플러그인은 메시지를 <channel source="telegram" …> 태그로 감싸 컨텍스트에 투입한다. CronCreate로 등록된 6개 스케줄은 아침 브리핑·점심 체크인·자기 전 회고·주간 리포트를 시간 이벤트 → 프롬프트로 변환해 주입한다. 즉 Selforge의 하네스는 “채널 입력 + 크론 입력 + 파일시스템 입력”을 하나의 컨텍스트로 합쳐 모델에 넘기는 파이프라인이다.

정리하면, Selforge의 하네스 엔지니어링 결정은 세 가지다.

  • 상단은 고정, 하단만 가변 (CLAUDE.md + OMC 블록을 캐시 상단으로).

  • 죽으면 되살린다, 교착되면 흔들어 깨운다 (runner + watchdog).

  • 모델은 해석하지 않는다 (흐민 언어 보존, Obsidian 읽기 전용 등 제약을 하네스가 강제).

2. 오케스트레이션(Orchestration)이란

쉽게 풀어내면

“여러 전문가를 지휘해서 한 편의 결과물로 합치는 설계” 다.

단일 모델/단일 호출로 끝나는 작업은 오케스트레이션이 필요 없다. 하지만 다음과 같은 순간이 오면 지휘자가 필요해진다.

  • 한 번에 다 넣으면 컨텍스트가 터진다 (큰 자료 읽기 + 전략 수립 + 작성 + 검수).

  • 각 단계가 요구하는 전문성과 제약이 다르다 (리서치는 넓게, 작성은 보이스 고정, 검수는 의심병).

  • 한 곳의 실수가 다음 단계에 그대로 복사되면 안 된다 (격리된 역할이 필요).

이때 전문가(에이전트) 각자가 좁은 책임을 지고, 지휘자(오케스트레이터)가 누구를 언제 호출할지·무엇을 넘길지·결과를 어떻게 합칠지를 결정한다. 이게 오케스트레이션이다.

세 가지 전형적 패턴이 있다.

  • 파이프라인 — A → B → C 순차, 각 단계의 출력이 다음 단계 입력.

  • 팬아웃/팬인 — 독립적인 K개 작업을 병렬로 돌리고 결과를 합친다.

  • 휴먼 인더 루프 — 중간에 사람이 한 번 승인/수정한다. 자동화와 통제의 균형점.

오케스트레이션이 잘되려면 두 가지가 같이 가야 한다.

  1. 역할 경계가 선명해야 한다. “이 에이전트는 해석하지 않는다”, “저 에이전트는 저장만 한다” 같은 단일 책임. 경계가 흐리면 지휘가 무의미해진다.

  2. 오케스트레이터는 메인 세션이어야 한다. 서브에이전트가 또 서브에이전트를 호출하게 만들면 격리와 캐시가 무너진다. (Claude Code는 이 제약을 명시한다 — “서브에이전트는 서브에이전트를 호출할 수 없다”.)

Selforge에 어떻게 적용했는가

Selforge의 오케스트레이션은 “3-Layer × 에이전트 파이프라인 × 메인 세션 지휘” 세 축으로 구성된다.

(1) 인지 모드를 레이어로 쪼갰다

| 레이어 | 모드 | 에이전트 |

|---|---|---|

| 사고(Sullivan) | 발산 — 더 넓게 | morning / capture / reflection / insight |

| 지식(Wiki) | 수렴 — 더 깊게 | wiki-agent-a / wiki-agent-b / graphify |

| 자산화 | 변환 — 더 날카롭게 | LinkedIn·Naver 파이프라인 |

발산·수렴·변환을 한 프롬프트 안에 섞지 않는다. 이 분리 자체가 오케스트레이션 설계의 1차 결정이다.

(2) LinkedIn 자산화는 6단 파이프라인이다


source-reader → [소스 브리프 확인: 사람] → content-strategy

→ linkedin-writer → content-reviewer → brand-voice → qa-validator

각 에이전트는 좁은 책임만 진다. source-reader는 Obsidian에서 재료만 모으고, content-strategy는 각도를 잡고, linkedin-writer는 쓰고, content-reviewer는 소스 충실도·할루시네이션을 잡고, brand-voice는 보이스 체크리스트로 정제하고, qa-validator는 최종 저장만 한다. “Brand Voice를 통과하지 않은 결과물은 나가지 못한다” 는 프로젝트 원칙이 이 파이프라인의 6단계 중 한 자리로 고정되어 있다.

(3) 휴먼 인더 루프를 강제 단계로 박았다

source-reader 다음에 “소스 브리프 확인” 이라는 사람 승인 단계가 의무로 들어간다. 핵심 소재·보조 소재·제안 각도를 사람에게 먼저 보여주고 방향을 확정한 뒤에야 하류 에이전트로 내려간다. 그리고 그 브리프의 “핵심 소재”는 보존 제약이라는 이름으로 하류에 전달되어, 작성·검수 단계가 이걸 누락하지 못하게 한다. 즉 사람 승인이 단순 관문이 아니라 하류 제약 생성기다.

(4) 네이버 파이프라인은 도메인이 달라 조립을 다시 했다


photo-analyzer → research-agent(조건부) → content-strategy

→ naver-writer → brand-voice → qa-validator

사진 분석이 먼저 들어오고, 리서치는 조건부다. 같은 오케스트레이터가 도메인마다 다른 악보를 연주한다.

(5) 메인 세션이 지휘자이고, OMC가 악단이다

Selforge에서 오케스트레이터는 항상 메인 Claude Code 세션이다. 서브에이전트에 서브에이전트 호출 권한을 주지 않는다. OMC가 제공하는 explore·planner·architect·executor·verifier·document-specialist 같은 역할별 에이전트는 메인 세션이 “이 일은 누구에게”를 결정할 때 고르는 옵션이다. OMC의 강점이 바로 여기다 — 모델 라우팅(haiku/sonnet/opus)과 역할 라우팅(탐색/계획/실행/검증)을 동시에 제공하는 오케스트레이션 레이어라서, 우리는 각 레이어 위에서 “누가·어떤 모델로·어떤 스킬과 함께” 일할지를 선택만 하면 된다.

(6) 검증은 별도 레인으로 분리했다

executor가 쓴 결과를 같은 컨텍스트 안에서 자기검증하지 않는다. content-reviewer · brand-voice · qa-validator로 별도 패스를 돌린다. OMC의 <execution_protocols> 에 명시된 “authoring과 review를 분리” 원칙을 그대로 도메인 파이프라인에 박아 넣은 것이다.

3. 하네스와 오케스트레이션의 관계 — Selforge 관점

둘은 층위가 다르다.

  • 하네스는 “모델이 어떻게 일하게 할 것인가” — 프로세스·컨텍스트·복구·채널.

  • 오케스트레이션은 “여러 일꾼을 어떻게 합칠 것인가” — 역할·순서·경계·승인.

Selforge에서는 이 둘을 하네스가 오케스트레이션을 가능하게 하는 토대로 겹쳐 놓았다.

  • 하네스(Claude Code + OMC + CLAUDE.md)가 상단을 고정해 캐시·규칙·모델 라우팅을 먼저 세팅한다.

  • 그 위에서 메인 세션이 파이프라인을 지휘하고, 각 단계는 적절한 모델·스킬·서브에이전트로 위임된다.

  • runner + watchdog이 이 전체 지휘가 끊기지 않고 반복되도록 감싼다.

결국 Selforge의 설계 철학 세 줄 — “AI는 해석하지 않고 드러낸다 / 레이어 분리는 인지 모드 분리 / 검증은 사용의 일부” — 는 하네스로 제약을 강제하고, 오케스트레이션으로 역할을 분리해 구현된다. 개념이 추상이 아니라 파일 경로와 스크립트로 내려와 있다는 점이 이 프로젝트의 특징이다.