그래프 엔지니어링 세팅, 그래서 어떻게 하는데? 5분만에 딸깍 실행하기
본문 로딩 중...
화장실이 급하다면
- 5분 동안
graph-run과 검증 스킬 네 개를~/.claude/skills/에 넣는다.graph-run은 작업 분할, 계약, 파일 소유권, 사용자 승인 지점을 관리한다.- 개발이 끝나면
verification-orchestrator가 요구사항·코드·테스트 검증을 묶어서 실행한다.- 자동 테스트를 먼저 실행하고, 코드로 판정하지 못한 화면만 브라우저 스킬로 확인한다.
- Claude Code에서
/graph-run을 호출해 시작한다. 나머지 검증 스킬은 검증 단계에서Skill도구로 호출된다.
무언가를 만들면서 보완해야하는 스킬들이다. 환벽하지 않다.
이전 글에서는 그래프 엔지니어링의 결함과 검증 방법을 다룬 영상을 번역했다.
번역한 이유는 그래프를 실제 작업에 적용하는 방법을 찾기 위해서였다.
그래서 한 번 스킬이 있나 검색해봤는데...
없다...
그래서 지금 시점에서, 내가 가장 찾고 싶은 문장을 제목으로 써봤다...
이번에는 Claude Code에 graph-run과 검증 스킬 네 개를 설치한다.
여기서 5분은 공개 저장소의 스킬 파일을 전역 폴더에 배치하고 /graph-run 호출을 확인하는 시간이다.
요구사항 작성, 구현, 테스트, 브라우저 확인 시간은 포함하지 않는다.
다섯 스킬은 하나의 실행 흐름으로 묶었다. graph-run이 개발 전후의 순서를 관리하고, 검증 단계에서 나머지 네 스킬을 연결한다.
세팅 실측 시간:
[처음부터 다시 설치한 뒤 기입]
그래프 엔지니어링에서는 작업을 노드로 나누고 실행 순서와 결과 전달 관계를 정한다.
작업 요청
↓
완료 조건·그래프·계약 확정
↓
여러 에이전트 실행
↓
검증
↓
결과 분류와 재검증
세팅 전에 지식 인터뷰를 진행했다. 내가 막힌 부분은 작업을 나누는 기준, 병렬 작업자가 공유할 계약, 파일 소유권, 여러 검증 결과의 통합 방법이었다.
영상에서 사용한 검증 스킬은 공개 배포된 스킬이 아니었다. 같은 구성을 그대로 설치할 수 있는 공개 스킬도 찾지 못했다.
검증에 필요한 책임을 네 개로 나눠 커스텀 스킬을 만들고, 개발 전후의 실행 순서를 관리하는 graph-run을 추가했다.
| 스킬 | 맡은 일 |
|---|---|
graph-run | 완료 조건, 작업 그래프, 계약, 파일 소유권, 사용자 승인 지점을 관리한다. |
verification-orchestrator | 세 검증 결과를 모아 실제 결함, 중복, 오탐, 보류로 분류한다. |
requirements-review | 구현 결과를 최초 요구사항과 완료 조건에 대조한다. |
code-review | 동작 오류, 권한, 보안, 데이터 흐름, 회귀 위험을 코드 증거로 확인한다. |
test-runner | 타입 검사, 린트, 단위 테스트, 설정된 E2E 테스트를 낮은 비용 순서로 실행한다. |
다섯 스킬의 관계는 다음과 같다.
graph-run
└─ 개발 완료 후 verification-orchestrator
├─ requirements-review
├─ code-review
└─ test-runner
Claude Code에서 사용자가 직접 입력하는 명령은 /graph-run이다. graph-run은 검증 단계에서 Skill 도구로 verification-orchestrator를 호출하고, 오케스트레이터가 세 검증 스킬을 각각 호출한다.
터미널에서 Claude Code 버전을 확인한다.
claude --version
이번 세팅에서 확인한 버전은 2.1.220이다.
스킬은 프로젝트 폴더가 아닌 사용자 전역 폴더에 둔다.
~/.claude/
└─ skills/
├─ graph-run/
│ └─ SKILL.md
├─ verification-orchestrator/
│ └─ SKILL.md
├─ requirements-review/
│ └─ SKILL.md
├─ code-review/
│ └─ SKILL.md
└─ test-runner/
└─ SKILL.md
이 위치에 두면 다른 프로젝트에서도 같은 스킬을 불러올 수 있다. 검사 명령과 금지 범위는 각 프로젝트의 문서를 읽고 다시 결정한다.
다섯 스킬을 하나씩 작성하지 않고, 공개 저장소의 skills/ 디렉터리를 사용한다.
git clone https://github.com/imbhj/graph-run.git graph-run
cd graph-run
저장소에는 다음 다섯 스킬이 함께 들어 있다.
skills/
├─ graph-run/
├─ verification-orchestrator/
├─ requirements-review/
├─ code-review/
└─ test-runner/
각 디렉터리의 SKILL.md에는 다음 내용이 들어 있다.
name
description
입력
검사할 항목
출력 형식
수정 금지 범위
검증 스킬은 코드를 수정하지 않는다. 수정은 검증 결과를 분류하고 사용자가 범위를 확인한 뒤 별도 노드가 맡는다.
공개 저장소의 다섯 스킬을 Claude Code 전역 스킬 폴더에 복사한다.
mkdir -p ~/.claude/skills
cp -R skills/graph-run ~/.claude/skills/
cp -R skills/verification-orchestrator ~/.claude/skills/
cp -R skills/requirements-review ~/.claude/skills/
cp -R skills/code-review ~/.claude/skills/
cp -R skills/test-runner ~/.claude/skills/
verification-orchestrator에는 다음 순서가 들어 있다.
1. 원래 요구사항과 완료 조건을 읽는다.
2. requirements-review를 실행한다.
3. code-review를 실행한다.
4. test-runner를 실행한다.
5. 같은 원인의 지적을 합친다.
6. 실제 결함, 중복, 오탐, 보류로 분류한다.
7. 수정할 항목과 증거를 보고한다.
세 검증이 서로의 결과를 필요로 하지 않으면 병렬로 실행한다. 구현 에이전트의 자기평가는 검증 에이전트에 전달하지 않는다.
검사 명령은 package.json과 프로젝트 문서에 존재하는 것만 사용한다. 명령이 없으면 임의로 만들거나 라이브러리를 설치하지 않고 NOT_CONFIGURED로 기록한다.
타입 검사:
린트:
단위 테스트:
E2E 테스트:
빌드:
작은 변경을 대상으로 verification-orchestrator 호출을 확인한다.
/verification-orchestrator
현재 변경 사항을 원래 요구사항과 완료 조건에 맞게 검증해줘.
다음을 확인한다.
여기까지가 4분 세팅 범위다.
개발이 끝난 결과를 검증하는 부분은 여기서 동작한다.
graph-run을 쓴다네 검증 스킬은 개발이 끝난 결과를 검증한다.
작업을 어떤 노드로 나눌지, 병렬 노드가 무엇을 공유할지, 각 에이전트가 어느 파일을 수정할지는 graph-run이 관리한다.
나처럼 다음 항목에서 자주 멈춘다면 graph-run까지 쓰는 편이 낫다.
graph-run에는 다음 순서를 고정했다.
완료 조건 확정
→ 그래프 승인
→ 계약과 파일 소유권 승인
→ 구현
→ verification-orchestrator 실행
→ 실제 결함 수정
→ 관련 검증만 재실행
네 개의 정지 지점도 넣는다.
| 게이트 | 멈추는 조건 |
|---|---|
| 게이트 0 | 완료 조건과 금지 범위를 승인하지 않았다. |
| 게이트 1 | 노드와 실행 순서를 승인하지 않았다. |
| 게이트 2 | 계약과 파일 소유권을 승인하지 않았다. |
| 게이트 5 | REVIEW와 범위 밖 항목의 처리 방향이 정해지지 않았다. |
graph-run은 네 검증 스킬을 대체하지 않는다. 개발 전 순서와 승인 지점을 관리하고, 개발이 끝나면 verification-orchestrator를 호출한다.
graph-run
└─ 개발 완료 후 verification-orchestrator
├─ requirements-review
├─ code-review
└─ test-runner
작은 변경을 대상으로 graph-run 호출을 확인한다.
/graph-run
현재 변경 사항을 완료 조건에 맞게 작업 그래프로 나누고 검증해줘.
다음을 확인한다.
graph-run이 완료 조건과 범위를 먼저 확인하는가verification-orchestrator를 호출하는가한 파일의 짧은 수정, 완료 조건을 쓸 수 없는 작업, 모든 작업이 같은 파일에 몰리는 경우에는 graph-run을 사용하지 않는다. 운영 DB 변경, 배포, 삭제가 필요한 작업도 이번 실행 대상에서 뺐다.
Nn, N1, N2는 무엇인가N은 Node의 약자다. Nn은 “n번째 노드”를 나타내는 일반 표기다. N1, N2, N3는 그래프에서 구분한 첫 번째, 두 번째, 세 번째 작업 단위다. 에이전트 모델이나 세션 번호가 아니다.
N1: 첫 번째 작업 노드
N2: 두 번째 작업 노드
N3: 세 번째 작업 노드
번호는 실행 순서와 같을 수도 있고 다를 수도 있다. N1과 N2가 서로의 결과를 필요로 하지 않으면 병렬로 실행한다. N3가 두 결과를 모두 입력받아야 한다면 합류점 뒤에 둔다.
테스트 노드는 계약 파일과 완료 조건만 읽고 테스트를 작성한다. 구현 파일을 읽지 못하도록 소유권 표에서 제한할 수 있다. 구현 노드와 테스트 노드는 계약만 공유하고 병렬로 실행한다.
계약
├─ N1: 구현 코드 작성
└─ N2: 테스트 코드 작성
이렇게 하면 테스트 노드가 현재 구현에 맞춰 기대값을 바꾸는 일을 줄일 수 있다.
구현과 테스트가 계약을 다르게 해석하면 자동 검사에서 차이가 드러난다.
브라우저 스킬을 기본 다섯 스킬에 넣지 않았다.
상태 변화, 입력 검증, 계산 결과처럼 코드로 판정할 수 있는 동작은 테스트로 작성한다. 실제 레이아웃, 포커스 이동, 클릭 경로, 브라우저에서만 발생하는 문제는 자동 테스트가 통과한 뒤 브라우저로 확인한다.
완료 조건 작성
→ 계약만 읽고 테스트 작성
→ 구현
→ 자동 테스트
→ 필요한 화면 항목만 브라우저 확인
브라우저 스킬은 모든 화면을 처음부터 돌아다니는 용도로 쓰지 않는다. 자동 테스트로 판정하지 못한 완료 조건만 전달한다.
여기까지 세팅을 마치면 Claude Code에서 /graph-run을 호출해 개발 전 단계부터 시작한다.
실제 주제 선정, 노드 구성, 테스트 결과, 브라우저 확인, 검증 결과는 다음 글에서 다룬다.
- 하네스·루프·그래프는 서로를 대체하는 게 아니라 겹쳐 있는 층이다. - 나누기만 하고 공유할 기준을 못 박지 않으면 합칠 때 어긋난다 (직접 겪은 사례). - Bun의 Rust 재작성은 가능성을 보여줬지만 사람의 검토를 대신하지 못했다. - 한계는 사라진 게 아니라 토큰 비용과 검토 책임으로 옮겨갔다.
![[AI] AI 여러개를 동시에 돌리는 Orca](https://data.develog.develrocket.com/upload/develog/user_1777093328305/1787402072812-3sglwy/_____2026-08-22_213348.png)
Orca 설명 및 테스트
![[AI] AI 여러 개를 쓸 때의 깃 워크플로우](https://data.develog.develrocket.com/upload/develog/user_1777093328305/1787227537851-94buqs/ChatGPT_Image_2026__8__20_____08_53_52.png)
깃 워크플로우
- 하네스·루프·그래프는 서로를 대체하는 게 아니라 겹쳐 있는 층이다. - 나누기만 하고 공유할 기준을 못 박지 않으면 합칠 때 어긋난다 (직접 겪은 사례). - Bun의 Rust 재작성은 가능성을 보여줬지만 사람의 검토를 대신하지 못했다. - 한계는 사라진 게 아니라 토큰 비용과 검토 책임으로 옮겨갔다.
딸깍
딸깍
딸각..