그래프 엔지니어링은 다운로드가 아니라 청사진이었다 — 내 하네스에 그래프를 그려 넣은 이야기

"요즘 그래프 엔지니어링이 나왔다던데?" 라는 말을 듣고 조사부터 시작했습니다. 기대는 새로운 라이브러리나 플러그인이었는데, 파 보니 설치할 물건이 하나도 없었습니다. 오히려 제가 하네스를 만지면서 이미 반쯤 하고 있던 일에 이름이 붙은 것에 가까웠습니다. 이 글은 그 조사와, 조사 끝에 제 하네스(~/.claude/)에 그래프를 실제로 그려 넣은 과정을 정리한 것입니다. 정답이 아니라, 한 사람이 개념 하나를 자기 환경에 앉혀 본 사례로 읽어 주시면 됩니다.

1. "그래프 엔지니어링이 나왔다" 는 말의 정체

먼저 실체부터. 2026년 중반에 개발자들 사이에서 "loop engineering 은 끝났고 이제 graph engineering 이다" 라는 프레이밍이 돌았습니다. 계기는 한 개발자의 짧은 트윗 — "아직도 loop 얘기하냐, graph 로 넘어갔냐?" — 정도였고요.

내용 자체는 이렇습니다. 여러 에이전트·스텝을 방향 그래프로 엮는 것.

• 노드 = 일하는 단위 하나 (코드 한 조각, LLM 한 번 호출, 툴 호출, 에이전트 한 실행)
• 엣지 = "이 일 끝나면 다음 어디로" — 그냥 if 문
• state = 그래프를 관통해 흐르는 공유 메모장 (모든 노드가 같은 걸 읽고 씀)

에이전트 하나가 루프 한 번 도는 걸로 안 될 때 쓰는 "다음 계층" 이라는 겁니다. 계층으로 늘어놓으면 이렇게 됩니다.

prompt engineering    → 모델 한 번의 응답 제어
context engineering   → 검색·메모리·컨텍스트 예산 관리
loop engineering      → 에이전트 1개의 관찰-추론-행동 루프
graph engineering     → 여러 노드에 걸친 흐름·토폴로지 제어   ← 지금 이거

중요한 건, 이게 서로 교체가 아니라 적층이라는 점입니다. 루프도 결국 "사이클 하나짜리 그래프" 라서 대립 개념이 아닙니다. 그리고 정직하게 말하면, 방향 그래프·상태머신이라는 메커니즘 자체는 수십 년 된 것이고 LangGraph 같은 도구가 몇 년째 하던 일입니다. 새로 생긴 건 기술이 아니라 "이걸 하나의 설계 기술로 부르자"는 공용 이름 쪽에 가깝습니다.

2. 첫 번째 함정 — "그래프" 가 두 가지 뜻으로 쓰인다

조사하다 가장 먼저 헷갈린 지점입니다. 같은 "그래프 엔지니어링" 이라는 말이 전혀 다른 두 가지를 가리킵니다.

"나왔다" 는 거의 확실히 (A) 입니다. (B) 는 데이터 검색 얘기라 결이 다릅니다. 이 글도 (A) 기준으로 씁니다. 이 구분을 안 하면, 에이전트 흐름 얘기를 하다가 갑자기 벡터 DB·지식그래프 튜토리얼로 새 버립니다.

3. 두 번째 함정 — 이건 다운로드가 아니다

여기서 제가 제일 오래 헷갈렸습니다. LangGraph, AutoGen, CrewAI, Spring AI... 이름이 자꾸 나오니까 "결국 뭐 하나 깔라는 거 아냐?" 싶었거든요. 아닙니다.

정확히 이 비유입니다.

즉 개념(설계) 은 공짜고, 저 프레임워크들은 그 개념을 코드로 옮길 때 쓰는 삽입니다. 저 이름들이 나오는 이유는 "이 개념을 실제 제품 코드로 만들 거면 이 삽 중 하나를 써라" 를 알려주려는 것이지, "그래프 엔지니어링 = 저 패키지" 라는 뜻이 아닙니다.

제 경우처럼 백엔드가 Spring 이라면, AI 에이전트 서버를 만들 때 쓰는 삽은 Spring AI(Java 판)가 됩니다. LangGraph 를 따로 깔 필요가 없습니다 — 그건 파이썬 쪽 삽이고, Java 면 같은 그래프를 Spring AI 위에서 표현하면 됩니다. 어느 쪽이든 그래프 엔지니어링은 그 삽으로 "무엇을 어떻게 팔지" 설계하는 행위 지, 삽 자체가 아닙니다.

4. 그런데 — 나는 이미 하고 있었다

여기서부터가 진짜였습니다. (A) 오케스트레이션 그래프의 메커니즘을 뜯어보니, 제가 하네스에 이미 만들어 둔 부품들과 정확히 대응됐습니다.

제 커밋 흐름 — 코드 변경 → 테스트 → 커버리지 → 리뷰 게이트 → 승인 → git add — 이건 이미 노드 + 엣지 + 게이트로 된 그래프였습니다. 이름만 안 붙였을 뿐이죠.

그래서 하네스 엔지니어링 시리즈에서 다뤘던 그 작업이, 사실은 그래프 엔지니어링의 특수한 경우였다는 걸 뒤늦게 알았습니다. 흔히 그래프 엔지니어링이라고 하면 "출시할 AI 제품의 런타임 흐름" 을 떠올리는데, 똑같은 메커니즘을 내 개발 하네스에 적용하면 "표준화된 작업 흐름을 명시적으로 고정하는 일" 이 됩니다. 대상이 다를 뿐 삽질은 같습니다.

5. 진짜 값어치는 토큰이 아니라 "판단을 안 하는 것"

그럼 하네스에 그래프를 명시적으로 그리면 뭐가 좋은가. 처음엔 "컨텍스트 토큰 절약" 이라고 생각했는데, 파 보니 그건 절반이었습니다.

흐름이 여러 파일에 산문으로 흩어져 있으면, 모델은 매번 그 조각들을 읽고 파이프라인을 머릿속에서 재조립합니다. 이게 추론입니다. 압축된 그래프 한 장을 두면 그 재조립이 사라집니다 — 이게 첫 번째 이득(재유도 비용 감소).

그런데 더 큰 건 두 번째입니다. 결정 지점에서 즉흥 판단 자체를 없애는 것. "지금 커버리지 검수를 스킵해도 되나? 리뷰를 돌려야 하나?" 를 매번 판단하면, 그게 곧 오차와 변동입니다(같은 상황인데 답이 그때그때 달라짐). 흐름을 그래프로 못박으면, 이미 정해진 걸 다시 정하지 않습니다. LangChain 팀의 표현을 빌리면 "시스템이 어떻게 동작해야 하는지에 대한 네 지식을 코드로 인코딩" 하는 것 — 모델이 이미 결정된 걸 재결정하지 않게.

정리하면 이렇습니다.

토큰 절약은 부산물이고, 본질은 "고정돼야 할 판단을 그래프로 박아 즉흥 추론과 그 변동을 없애는 것" 이다.

단, 청사진도 공짜는 아니다

여기서 한 번 브레이크를 밟아야 했습니다. 청사진 자체도 토큰을 먹습니다. 특히 CLAUDE.md 는 매 세션 상주하므로, 거기에 상세를 다 때려 넣으면 절약분을 상주 비용이 도로 잡아먹습니다. 그래서 원칙을 하나 세웠습니다.

• 마스터 흐름만 컴팩트하게 CLAUDE.md 에 (상주할 가치가 있는 뼈대).
• 각 게이트의 상세 상태기계는 필요할 때만 로드되는 스킬 파일에 (on-demand).

"재유도 절약 > 상주 비용" 이 성립해야 이득이라는 얘깁니다. 이건 제가 하네스를 정리할 때 쓰는 지연 로딩 원칙과 같은 결입니다.

6. 그래서 내 하네스에 그래프 두 장을 그려 넣었다

말만 하고 끝내면 그래프 엔지니어링이 아니라 그래프 감상입니다. 그래서 실제로 두 곳에 그려 넣었습니다.

(1) CLAUDE.md — 작업 생애주기 (상주, 컴팩트)

네 개 파일에 흩어져 있던 게이트·스킵 조건·사람 허들을 한 장으로 모았습니다.

  비자명 작업 → 계획 수립
      │
      ▼
  ① 사전 구현 리뷰 게이트 ─(3R 미합의)─▶ 사람 에스컬레이션
      │ 합의
      ▼
  ② 계획 승인 ·············································· 사람 게이트
      │   ├─ ③ 티켓 필요? → 티켓 작성 (키 명시면 생략)
      │   └─ ④ 설계문서 필요? → 설계문서 작성
      ▼
  [구현] ── 파일 수정 전 변경안 승인 ······················ 사람 게이트
      ▼
  회귀 테스트 ─(빌드불가)─▶ 스킵 + 패치 이관 ─▶ 사람 직접 테스트
      │ 통과
      ▼
  커버리지 검수(4항목 게이트) ─(미달)─▶ 보완 루프
      │ 통과
      ▼
  커밋 직전 리뷰 게이트 ─(미합의)─▶ git add 보류
      │ 합의
      ▼
  git add(재확인 없이 즉시) ─▶ STOP: git commit 은 사람 몫
      ▼
  (선택) 개발 완료 문서

여기서 두 가지가 처음으로 한눈에 들어왔습니다. 교차 스킵(① 통과 + 구현 diff 가 계획 범위 안이면 뒤쪽 게이트들이 통째로 스킵된다)과, 사람 허들이 정확히 몇 개인가(계획 승인 · 구현 전 변경 승인 · 커밋, 딱 셋). 이전엔 이걸 매번 여러 스킬을 넘나들며 재구성했습니다.

(2) 리뷰 게이트 스킬 — 상태기계 (on-demand)

가장 복잡한(사이클 + 게이트 + 분기 + 사람 개입이 다 있는) 리뷰 핑퐁은, 7개 섹션에 흩어져 있던 종료·스킵·에스컬레이션 조건을 스킬 상단에 상태기계 한 장으로 요약했습니다.

  진입: (a) 커밋 직전  /  (b) 사전 구현
     │
     ▼
  스킵 게이트 ──충족──▶ 한 줄 보고 후 게이트 OPEN (핑퐁 없음)
     │ 미충족
     ▼
  ┌─▶ Round N/3 ── 외부 모델 검토  ∥  자체 평가  (병렬)
  │      │
  │      ▼  합의 판정: 양쪽 [위험] 0?
  │      ├─ 아니오 ─▶ [위험] 자동수정 ─▶ 카운터 +1 ─┐
  │      └─ 예 ─▶ 게이트 OPEN ─▶ [경고] 1회 보고 ─▶ 사람 승인 ─▶ 다음 흐름
  └───────────────────(N<3)──────────────────────────┘
         │ N=3 미해소 / 포맷 실패 / 호출 실패
         ▼
  사람 에스컬레이션 ── 항목별 결정
         ├─ 1건이라도 "적용" ─▶ +1 라운드
         └─ 전부 "무시" ─▶ 합의 간주 ─▶ 사람 최종 승인 ─▶ 다음 흐름

두 다이어그램 다 mermaid 가 아니라 텍스트 화살표로 그렸습니다. 이 파일들은 사람이 읽기도 하지만 모델의 컨텍스트로도 들어가는데, 텍스트 화살표가 어디서든(터미널·컨텍스트) 그대로 읽히고 토큰도 더 쌉니다.

7. 언제 그리고, 언제 안 그리나

그리면서 세운 판정 기준은 하나였습니다. 분기·사이클·게이트·팬아웃 중 하나라도 실재하는 흐름만 그린다.

• 그린다: 커밋 파이프라인(게이트+사이클+분기), 리뷰 핑퐁(4요소 전부).
• 안 그린다: 순수 직선 절차, 이미 표로 구조화된 것, 이미 코드로 구현된 병렬 워크플로. 여기에 다이어그램을 얹으면 상주 컨텍스트만 불립니다.

실제로 후보를 쭉 훑고도 리팩터 루프·계획 게이트·커버리지 검수는 안 그렸습니다 — 앞의 둘은 이미 결정 표로 반쯤 구조화돼 있었고, 커버리지는 본체가 직선 체크리스트라 게이트 하나 그리자고 페이지를 늘릴 값어치가 없었습니다. 그래프 엔지니어링의 절반은 "어디에 그릴까" 가 아니라 "어디에 안 그릴까" 였습니다.

마무리

조사부터 적용까지 하고 나서 남은 한 줄은 이것이었습니다.

그래프 엔지니어링은 새로 깔 도구가 아니라, 이미 흩어져 있던 내 판단을 한 장에 못박는 일이었다.

스킬은 부품이고, 그래프는 그 부품들의 배치 청사진입니다. 부품을 아무리 잘 만들어도 배치도가 머릿속에만 있으면 매 세션 다시 그려야 하고, 다시 그릴 때마다 조금씩 달라집니다. 청사진을 파일에 박아 두는 것 — 거창한 새 개념인 줄 알았던 게, 결국 제 하네스를 한 뼘 더 결정론적으로 만드는 작은 정리 작업이었습니다.