영상 자막·공개 저장소 코드 기반 정리 · 2026년 7월 27일

그래프 엔지니어링은 AI 작업을 나누고 검증하는 실행 설계다

가장 쉬운 예: 아침 보고서 만들기

AI가 매일 아침 뉴스와 커뮤니티 반응을 모아 보고서를 만든다고 해보자. AI 하나가 검색부터 글쓰기까지 전부 처리할 수도 있고, 일을 나눠 맡길 수도 있다.

아래쪽처럼 작업을 나누고 연결한 전체 모양이 그래프다. 한 가지 일을 맡는 칸을 작업 노드(task node), 결과가 다음 작업으로 넘어가는 길을 연결선(edge)이라고 부른다. 그래프 엔지니어링(graph engineering)은 노드와 연결선을 배치해 AI의 작업 흐름을 설계하는 일이다. 이후부터는 쉬운 설명 뒤에 영상에서 쓰는 영어 용어를 함께 적는다.

어려운 용어는 이렇게 읽으면 된다

대화가 너무 길어져 AI가 앞의 조건을 놓치거나 판단이 흐려지는 현상을 컨텍스트 로트(context rot)라고 한다. 조건에 따라 다음 작업을 고르는 갈림길은 라우터(router), 결과를 따로 검사하는 작업은 검증자(verifier), 검사에 실패한 부분을 다시 돌리는 구조는 재시도 루프(retry loop)다. 영어 이름보다 각 요소가 실제로 무슨 일을 하는지 이해하는 것이 먼저다.

언제 쓰면 좋은가

• 서로 기다릴 필요 없는 조사를 동시에 할 수 있을 때
• 만든 사람과 검사하는 사람을 분리해야 할 때
• 전체를 다시 하지 않고 실패한 부분만 고치고 싶을 때

요약 한 번, 이메일 초안 한 번처럼 짧은 일은 AI 하나로 끝내는 편이 낫다. 작업 칸이 늘어나면 실행 비용과 관리할 것도 같이 늘어난다.

AI를 많이 붙이는 것이 목적이 아니다. 일을 나누면 더 빠르고 정확해지는 구간만 나눠야 한다.

Claude Code와 Codex는 어디가 다른가

Claude Code 영상의 방식은 Claude가 JavaScript workflow를 만들고 그 코드가 병렬 실행, 조건 분기, 결과 합류, 재시도를 통제하는 구조다. Codex도 내부에서 하위 에이전트를 만드는 spawn_agent와 결과를 기다리는 wait_agent를 제공한다. 다만 공개 구현을 확인해 보니, Codex 사용자는 하나의 고정된 workflow 기능만 쓰지 않았다.

Codex 안에서 가장 가볍게 시작하려면 skill과 custom agent 설정에 작업 노드, depends_on, 병렬 실행 wave, 검증 조건을 적는다. 반대로 실행 순서와 재시도 횟수를 반드시 지켜야 한다면 Python·JavaScript·shell 같은 host code가 여러 codex exec를 호출하게 만든다.

· · ·

Claude Code와 Graph Engineering을 설명한 영상 3편

이번 영상 조사에서 Graph Engineering을 직접 다룬 핵심 자료는 아래 세 편이다. 첫 영상은 과장과 위험을 구분하고, 두 번째는 작업 분할과 병렬화를 설명하며, 세 번째는 Claude Code의 dynamic workflow로 graph를 설계하는 방법을 다룬다.

1. 과장을 걷어내고 개념 잡기

이 영상은 “그래프 엔지니어링이 정말 새로운 기술인가?”라는 질문에서 시작한다. 결론부터 말하면 완전히 새로운 원리는 아니다. AI 하나가 목표를 향해 반복해서 일하는 구조를 에이전트 루프(agent loop)라고 하는데, 일이 복잡해지면 루프 하나로는 부족하다. 그때 여러 루프와 검사 단계를 연결한 구조가 그래프다. 따라서 그래프는 루프를 없애는 것이 아니라 안에 포함한다.

영상은 코드 변경 요청을 예로 든다. 첫 번째 AI가 코드를 고쳐 풀 리퀘스트(pull request)를 만든다. 두 번째 AI는 보안이나 품질 문제를 찾는다. 문제가 발견되면 수정 담당 AI가 고치고, 마지막으로 자동 테스트가 실행된다. 검사 결과에 따라 수정 단계로 돌아가거나 끝내는 이 흐름이 하나의 그래프다.

여기서 중요한 위험도 설명한다. 각 작업 노드 안의 AI는 정답을 계산하는 프로그램이 아니라 확률적으로 답을 만든다. 같은 모델과 같은 자료를 본 AI 여러 개가 서로 검토하면 모두 같은 오해에 빠질 수 있다. 영상은 이를 “질서 있게 정리된 헛소리(organized nonsense)”라고 표현한다.

그래서 검증자(verifier)는 초안을 만든 AI와 다른 근거를 써야 한다. 다른 모델이나 새로운 대화를 사용하거나, 코드 테스트처럼 답이 명확한 검사, 수치 기준, 사람의 최종 확인을 넣는 방식이다. 각 작업이 남긴 상태(state), 중단시킬 권한(veto), 최대 반복 횟수, 비용 한도, 종료 조건(hard stop)도 미리 정해야 한다.

구현 코드를 자세히 보여주는 영상은 아니다. 대신 그래프를 그리는 이유와, 여러 AI가 서로 동의한다고 해서 결과가 맞는 것은 아니라는 점을 이해하기 좋다.

루프 하나로 부족해지는 시점 02:24 · AI가 작업을 오해할 수 있는 이유 04:34 · 같은 모델끼리 검토할 때의 문제 06:22 · 작게 시작하는 방법 07:44 · 자동 영어 자막

2. 어떤 일을 나누면 좋은지 보기

이 영상은 그래프가 필요한 상황을 아침 보고서 예시로 설명한다. 먼저 단순한 에이전트 루프(agent loop)를 “시작 조건(trigger), 맡은 일(task), 성공 기준(success criteria)” 세 부분으로 나눈다. 예를 들어 매일 오전 7시에 시작하고, 전날 뉴스를 조사하며, 출처가 포함된 보고서를 만들면 끝나는 식이다.

문제는 AI 하나가 YouTube, X, Reddit, 이메일을 모두 조사하고 글까지 쓸 때 생긴다. 대화가 길어지고, 어느 출처에서 문제가 생겼는지 찾기 어렵다. 그래프 방식에서는 출처마다 조사 담당을 따로 둔다. 각 담당은 동시에 조사한 뒤 결과를 보고서 작성 담당에게 넘긴다. 여러 작업을 동시에 나누는 것을 팬아웃(fan-out), 결과를 한곳에 모으는 것을 팬인(fan-in)이라고 한다.

작업이 작아지면 성공 기준도 구체적으로 적을 수 있다. YouTube 조사 담당에는 “서로 다른 영상 세 편 이상”, Reddit 담당에는 “반응이 많은 글과 반대 의견 포함”, 최종 작성 담당에는 “각 항목에 왜 중요한지 한 문장 추가”처럼 요구할 수 있다. 이렇게 범위가 명확한 작은 일을 원자적 작업(atomic task)이라고 부른다.

영상이 말하는 장점은 세 가지다. 첫째, 담당 범위가 좁아져 결과 품질을 확인하기 쉽다. 둘째, 독립적인 조사를 동시에 실행하므로 시간이 줄어든다. 셋째, 실패한 작업이 드러나므로 전체를 처음부터 다시 하지 않아도 된다.

그래프를 고려할 조건도 분명히 제시한다. 한 대화가 지나치게 길어지는 컨텍스트 로트(context rot)가 생길 때, 결과를 만든 AI와 별도의 독립 검토(independent review)가 필요할 때, 여러 일을 동시에 끝내야 하는 시간 조건이 있을 때다. 반대로 짧고 단순한 일은 루프 하나가 더 싸고 관리하기 쉽다.

루프의 확장으로 정의 00:36 · 출처별 동시 조사 02:53 · 작은 작업이 품질을 높이는 이유 05:29 · 그래프가 필요한 세 조건 07:19 · 자동 영어 자막

3. 실제 설계 규칙 익히기

앞의 두 영상이 “왜 나누는가”를 설명했다면, 이 영상은 “어떻게 나누는가”에 집중한다. 출발점은 긴 작업이 느리고 불안정한 이유가 프롬프트보다 일의 모양(work shape)에 있을 수 있다는 주장이다. 모든 일을 직선으로 잇는 대신, 실제 자료 의존 관계에 맞게 모양을 바꿔야 한다는 뜻이다.

한 가지 범위가 분명한 일을 작업 노드(node), 이전 작업의 결과가 다음 작업에 꼭 필요하다는 관계를 연결선(edge)이라고 정의한다. “그리고 다음에”라는 문장만으로 두 작업을 잇지 말고, 다음 작업이 이전 결과를 실제로 읽는지 확인하라고 한다. 읽지 않는다면 가짜 연결선이므로 두 작업을 동시에 실행할 수 있다.

각 노드는 작은 계약처럼 설계한다. 어떤 자료를 입력으로 받고, 한 가지 일만 처리하며, 어떤 형식으로 결과를 내놓을지 정한다. 결과는 자유로운 문장보다 JSON처럼 검사할 수 있는 구조화된 출력(structured output)이 좋다. 필드가 빠지거나 형식이 틀리면 다음 단계로 보내지 않고 그 자리에서 다시 실행한다.

결과를 합치거나 정렬하고, 중복을 제거하고, 조건에 맞지 않는 항목을 버리는 일은 AI에게 맡길 이유가 없다. 같은 입력이면 항상 같은 결과가 나오는 일반 코드, 즉 결정적 처리(deterministic processing)를 쓰는 편이 싸고 안전하다.

독립적인 작업은 팬아웃(fan-out)으로 동시에 보낸다. 모든 결과가 꼭 필요한 지점에서는 잠시 기다렸다가 팬인(fan-in)으로 합친다. 이 대기 지점을 배리어(barrier)라고 한다. 영상은 모든 작업이 끝나기를 습관적으로 기다리지 말고, 결과 하나가 준비되는 즉시 다음 단계로 넘기는 파이프라인(pipeline)을 기본으로 삼으라고 권한다.

후반부에는 조건에 따라 경로를 고르는 라우터(router), 의심스러운 결과를 반박하는 검증자(verifier), 한 작업의 실패가 전체로 번지지 않게 막는 실패 격리(failure isolation)를 설명한다. 반복 탐색에서는 확정된 결과만이 아니라 이미 한 번 본 항목 전체를 기준으로 중복을 제거해야 무한 반복을 막을 수 있다.

모델도 작업에 맞춰 배치한다. 반복 분류는 저렴한 모델, 여러 결과를 합쳐 판단하는 단계는 강한 모델을 쓰는 모델 등급 나누기(model tiering)다. 다만 Claude Code 중심 설명이라 다른 도구에서는 동시 실행 수, 파일 충돌, 격리 환경을 별도로 설계해야 한다.

노드와 연결선 01:23 · 출력 형식 검사 05:27 · 동시 실행 07:22 · 검증자 배치 12:16 · 배리어보다 파이프라인 18:09 · 자동 영어 자막

Claude Code에서 실제로 구현하는 방식

세 번째 영상의 설명에 따르면 사용자는 Claude Code에 작업을 설명하고, Claude가 일반 JavaScript orchestration script를 작성한다. 모델은 각 node 안에서 판단하지만 node 실행 순서, fan-out, 결과 전달, schema 검사, retry는 대화가 아니라 workflow code가 맡는다. 그래서 영상은 “The model thinks inside the nodes. The script runs the graph.”라고 구분한다.

여기서 핵심은 subagent를 많이 만드는 것이 아니다. 각 node가 한 가지 bounded job만 맡고, 다음 node가 추측하지 않도록 JSON schema를 통과한 결과를 내놓는 것이 먼저다. 단순 정렬·중복 제거·filter는 JavaScript가 처리하고, verifier는 의심스러운 결과만 반박한다. 전체 결과가 꼭 필요한 지점에서만 barrier를 두고 나머지는 준비되는 즉시 다음 node로 보내는 pipeline을 기본으로 한다.

증거 수준: 위 구조는 영상의 Claude Code workflow 설명 01:45과 다운로드한 자동 영어 자막을 기준으로 재구성했다. Codex 사례처럼 공개 저장소 구현을 독립적으로 clone해 검증한 항목은 아니다.

· · ·

Codex에서 실제로 구현한 공개 사례

공개 저장소 17개와 자막이 있는 데모 영상 1개를 검토했다. 그중 노드, 의존성, 병렬 실행, 검증, 재시도, worktree 같은 구조가 실제 코드나 재사용 설정에 확인되는 사례는 10개였다. 아래 다섯 개는 구현 방식이 서로 달라 대표로 선정했다.

대부분의 작성자는 “Graph Engineering”이라는 이름을 직접 쓰지 않는다. 대신 orchestration, swarm, workflow, coordinator라고 부르면서 내용상 같은 작업 그래프를 구현한다.

1. Codex 안에서 skill로 만드는 방식

am-will/codex-skills는 사용자가 생각한 “Codex 안의 workflow”에 가장 가깝다. parallel-task skill이 계획 파일에서 depends_on을 읽고, 선행 작업이 끝난 unblocked task를 여러 subagent로 동시에 실행한다. 각 worker는 정해진 파일 범위와 acceptance criteria를 받고, 테스트가 실패하는 RED 상태에서 구현 후 GREEN으로 바뀐 증거를 남겨야 한다.

한 wave가 끝나면 결과와 commit을 검사한다. 실패한 작업은 다시 실행하거나 상위 판단으로 넘기고, 새로 풀린 작업을 다음 wave에서 실행한다. node·edge·fan-out·verifier·retry가 모두 있지만, 이를 강제하는 scheduler는 별도 프로그램이 아니라 Codex가 읽는 SKILL.md와 TOML 지시다.

실제 근거: 의존성 파싱과 병렬 실행 · 검증·재시도·다음 wave

2. Python이 Codex 실행 순서를 강제하는 방식

acogood/diffmode_free는 Graph Engineering의 코드 구현에 가장 가깝다. Python의 orchestrate.py가 intake, 경쟁사 조사, audience·acquisition 병렬 분석, 세 개의 think-tank, constraints, synthesis, reviewer 순서를 고정한다. 각 작업은 worker TOML과 입력·출력 파일을 받고 codex exec로 실행된다.

독립 작업은 sliding pool로 동시에 실행하고, mining branch가 끝나는 지점에서 join한다. 구조 검사가 실패하면 다음 단계로 가지 않으며, worker 종료·출력 오류·rate limit에는 제한 횟수와 exponential backoff를 둔다. 이 방식에서는 모델이 아니라 Python이 edge, barrier, retry를 강제한다.

실제 근거: 전체 stage graph · 병렬 pool과 rate-limit retry

3. tmux와 Git worktree로 병렬 구현하는 방식

codex-yolo/codex-yolo는 task마다 tmux window와 Git worktree를 만든다. 여러 Codex가 서로 다른 branch에서 동시에 코드를 수정하고, 각 작업이 완료 marker를 만들면 merge resolver가 순서대로 결과를 합친다.

별도의 conflict daemon은 branch 사이 충돌을 git merge-tree로 검사한다. 충돌이 생기면 resolver Codex를 새 window에서 실행하고, 남은 conflict marker를 다시 검사한다. 병렬화와 파일 충돌 방지는 강하지만, 기능 품질을 판단하는 테스트·review gate는 상대적으로 약하다.

실제 근거: Codex window fan-out · 완료 대기와 sequential merge

4. GitHub Issue를 공유 state로 쓰는 방식

troykelly/codex-skills는 GitHub Issue와 Project Board를 작업 그래프의 durable state로 사용한다. issue마다 branch와 worktree를 만들고 background codex exec worker를 실행한다. PID와 로그는 로컬에, 진행·handover·결과는 issue comment와 project status에 남긴다.

PR을 만들기 전에는 hook이 comprehensive review artifact를 찾는다. review가 없거나 미해결 finding이 남아 있으면 PR 생성 자체를 막는다. worker가 실패하거나 handover를 남기면 replacement worker가 이어받을 수 있어 재시작에도 비교적 강하다.

실제 근거: worktree worker 실행 · PR review gate

5. Codex를 제품형 orchestrator에 넣는 방식

ComposioHQ/agent-orchestrator는 여러 coding-agent session을 관리하는 제품형 runner다. session마다 branch와 worktree를 만들고 Codex를 worker 또는 읽기 전용 reviewer로 선택할 수 있다. backend DB가 session·worktree·PR·review run 상태를 저장한다.

CI failure, review changes requested, unresolved comment, merge conflict가 관측되면 lifecycle code가 해당 내용을 worker prompt로 다시 보낸다. 즉 GitHub PR lifecycle 자체가 router와 retry edge 역할을 한다. 다만 Codex 전용 프로그램이 아니라 Claude와 다른 agent도 연결할 수 있는 multi-backend orchestrator다.

실제 근거: Codex session adapter · 읽기 전용 reviewer · CI·review·conflict feedback

공개 구현에서 반복된 공통 구조

1. 큰 요청을 task node로 나누고 입력·수정 범위·성공 조건을 적는다.
2. depends_on 또는 stage 순서로 실제 dependency edge를 표시한다.
3. 서로 독립적인 작업은 subagent, process, tmux window로 동시에 실행한다.
4. 파일을 수정하는 worker는 branch와 Git worktree로 격리한다.
5. 결과는 파일, JSON, GitHub Issue, DB 같은 공유 state에 기록한다.
6. 테스트·schema·reviewer·CI를 통과해야 다음 단계나 PR로 보낸다.
7. 실패하면 해당 worker만 다시 실행하고 최대 횟수나 중단 조건을 둔다.
8. 마지막에는 merge 또는 synthesis node가 결과를 합친다.

Codex 안에서 시작한다면

처음부터 별도 플랫폼을 만들 필요는 없다. 가장 작은 구성은 프로젝트 skill과 custom agent 설정이다. planner가 dependency가 있는 계획을 만들고, worker가 unblocked task를 병렬로 처리하고, verifier가 테스트와 diff를 검사하도록 한다.

사용자 요청
  → planner: task와 depends_on 작성
  → Codex subagent fan-out
  → worker별 파일 소유권 또는 worktree
  → test · schema · verifier
  → 실패 task만 retry
  → 통합 commit 또는 PR

이 구조로 실제 불안정성이 확인된 뒤에만 Python runner를 추가하는 편이 낫다. 반복 횟수, timeout, artifact schema, merge 순서를 코드로 반드시 강제해야 할 때가 외부 runner를 붙일 시점이다.

강한 비교 사례 10개 전체 보기

구현	주요 방식	대표 여부
am-will/codex-skills	native skill·custom agent·TOML	대표
acogood/diffmode_free	Python DAG + codex exec	대표
codex-yolo	tmux·worktree·merge resolver	대표
troykelly/codex-skills	GitHub state·worker dispatch·PR gate	대표
ComposioHQ/agent-orchestrator	제품형 session·review·CI loop	대표
obra/external-subagents	manifest fan-out·wait fan-in	비교
junhoyeo/contrabass	dependency·phase·fix loop·worktree	비교
umputun/ralphex	Codex executor·review loop	혼합 구조
Sneakoscope-Codex	loop schema·scheduler·maker/checker	비교
raine/workmux	tmux·worktree substrate	비교

영상과 코드에 나오는 영어 표현 보기

영어 표현	쉬운 뜻
node	작업 칸, 하나의 작은 일
edge / depends_on	선행 결과가 필요한 의존 관계
fan-out / fan-in	여러 작업을 동시에 실행하고 결과를 한곳에 모음
router	조건에 따라 다음 작업을 고르는 갈림길
verifier / gate	다음 단계로 보내기 전 결과를 검사하는 장치
barrier / join	필요한 작업이 끝날 때까지 기다렸다가 합치는 지점
retry / feedback loop	실패한 작업이나 수정 요청을 다시 worker에게 보내는 연결
worktree isolation	worker별 작업 폴더와 branch를 분리해 파일 충돌을 막는 방식
structured output	JSON처럼 프로그램이 검사할 수 있는 출력 형식

조사 범위와 한계

영상 부분은 내려받은 전체 자막을 기준으로 정리했다. Codex 구현 조사는 공개 저장소 17개를 shallow clone해 README뿐 아니라 실제 runner, skill, hook, adapter, worktree, review 코드를 확인했다. 대표 사례의 line link는 조사 당시 commit에 고정했다.

공개 구현이 있다는 사실과 해당 방식이 모든 프로젝트에 적합하다는 판단은 다르다. skill 기반 방식은 가볍지만 모델의 지시 이행에 의존하고, 외부 runner는 실행을 강제할 수 있지만 운영 코드와 장애 지점이 늘어난다. 또한 Agent Orchestrator와 Ralphex처럼 Codex를 지원하되 여러 agent를 함께 쓰는 프로젝트는 Codex 전용 구현과 구분했다.