· AXOps · 읽는 시간 약 14분
AI 에이전트가 직접 쓰는 프로젝트 운영 시스템: VIBE OPS를 CLI와 Skills로 연결하기
요구사항부터 배포 확인까지를 관리하는 운영 시스템(VIBE OPS)을 만들고, AI 코딩 에이전트가 그 시스템을 사람과 같은 규칙으로 읽고 쓰게 연결한 과정을 정리했습니다. 연동 수단은 MCP 서버가 아니라 bash CLI 하나와 절차 문서(Skills)입니다.
이 글에서 다루는 것
엔터프라이즈 시스템 구축 프로젝트에서 개발의 상당 부분을 AI 코딩 에이전트(Claude Code)가 수행하고 있습니다. 에이전트가 코드를 잘 쓰는 것만으로는 프로젝트가 굴러가지 않습니다. 무엇을 만들지 읽어야 하고, 만든 결과를 기록해야 하고, 사람의 승인이 필요한 자리에서는 멈춰야 합니다.
이 글은 그 일을 맡는 VIBE OPS 시스템이 무엇인지, 그리고 에이전트를 VIBE OPS에 어떻게 연결했는지를 세 층으로 나눠 설명합니다. 규칙을 가진 API, 얇은 연동 수단인 CLI, 순서와 멈출 자리를 적은 Skills입니다.
VIBE OPS란 무엇인가
VIBE OPS는 개발 대상 시스템의 요구사항이 들어와서 완료로 확인될 때까지를 한 곳에서 관리하는 프로젝트 운영 플랫폼입니다. 요구사항 → PRD → 개발항목 → 공정 확정 → 테스트로 이어지는 흐름을 담고, 진행·지연·결재를 집계로 보여 줍니다. 본 시스템 개발의 입력이 VIBE OPS에서 나옵니다.
만들면서 풀려고 한 문제는 네 가지였습니다.
- 손으로 적는 진척은 실제와 어긋납니다. 8월 초에 확인해 보니 개발항목 185건의 진척률 칸이 전부 0이었습니다. 그래서 진척률을 입력받지 않고 공정 확정에서 계산합니다. 구현에 착수하면 50, 완료하면 100입니다.
- 승인 없이 늘어난 범위가 숫자에 보이지 않습니다. 추가 요건은 승인 전까지 진척 계산의 분모에 넣지 않습니다.
- 결재가 화면마다 흩어집니다. 요구사항·목업·추가 요건·개발 컨펌의 결재를 「내 결재함」 한 곳으로 모았습니다.
- 요구사항과 업무 프로세스, 화면 사이의 추적이 끊깁니다. 업무 프로세스(L1~L3)를 유일한 축으로 두고 요구사항과 화면을 여기에 잇습니다.
화면은 요구사항(칸반·백로그·스프린트·변경 추적), 개발관리(개발리스트·현황판·주간 실적), 테스트관리, 위험·이슈, 결재함, 시스템관리로 나뉩니다. 프런트는 Next.js, 백엔드는 NestJS, DB는 Oracle이고 pnpm + Turborepo 모노레포입니다.
요구사항이 지나가는 길
요구사항 한 건은 아래 상태를 차례로 지납니다.
| 상태 | 뜻 | 옮기는 사람 |
|---|---|---|
DRAFT | 초안 | 등록자 |
REVIEW | 요구사항 검토 | 컨설턴트 |
APPROVED | 요구사항 승인 (스프린트에 넣을 수 있음) | 컨설턴트 |
IN_PROGRESS | 개발 중 | 개발자 |
IN_REVIEW | 개발 검토 (현업 확인 대기) | 개발자 |
DONE | 완료 | 현업 프로세스 담당(PI)의 확인으로만 |
요구사항은 개발항목 여러 건으로 나뉘고, 개발항목은 DESIGN → BUILD → TEST → DEPLOY 공정을 밟습니다. 공정마다 WAIT → DOING → APPROVE 세 상태가 있습니다. 구현이 끝나면 컨설턴트 컨펌과 현업 리뷰라는 확인 축을 따로 거칩니다.
중요한 규칙은 화면이 아니라 서버가 강제합니다.
- PRD가 있어야 개발 중 이상으로 넘어갑니다.
- 진행 중인 스프린트에 들어 있는 요구사항만 개발 중이 됩니다.
- 완료는 확인 절차로만 됩니다. 스프린트를 쓰는 프로젝트에서 상태를 직접
DONE으로 바꾸는 요청은 관리자 계정이어도 400으로 거절되고, 관리자는 대리 확인 절차를 써야 합니다. (상위 요구사항에서 갈라진 하위 요구사항은 이 절차 밖입니다.) - 개발 상태는 개발항목에서 파생되는 값이라 직접 쓸 수 없습니다.
계정 역할은 관리자·PM·컨설턴트·개발자·PI·요청자 여섯 가지이고, 리소스마다 읽기·쓰기·승인·관리·계획 다섯 액션을 정적인 표로 매핑합니다. 「본인이 관련된 건만」 같은 범위 판정은 서비스 로직이 합니다.
이 규칙들이 서버에 있다는 점이 뒤에 나올 에이전트 연결의 전제입니다.
연결 구조: 세 층
| 층 | 맡는 일 | 형태 |
|---|---|---|
| API | 무엇이 허용되는가 | NestJS 컨트롤러 약 30개, 역할 × 리소스 권한 표 |
| CLI | 어떻게 부르는가 | bash 스크립트 1개, 하위 명령 43개 |
| Skills | 언제, 어떤 순서로, 어디서 멈추는가 | 절차 문서 16개 |
이 글의 개수와 줄 수는 2026년 11월 20일 저장소 기준입니다.
사람과 에이전트는 같은 API를 탑니다. 에이전트 전용 뒷문이 없으므로 에이전트가 할 수 있는 일은 그 토큰 주인의 역할이 할 수 있는 일과 같습니다.
CLI: 얇은 연동 수단 하나
에이전트용 연결이라고 하면 MCP 서버를 먼저 떠올리지만, VIBE OPS에는 MCP 서버가 없습니다. 연동 수단은 ops라는 CLI 하나입니다.
- bash 스크립트 한 파일입니다. 약 1,560줄이고 의존하는 도구는
curl과jq뿐입니다. 빌드도 설치 과정도 없습니다. - REST API의 얇은 래퍼입니다. 판단 로직을 넣지 않고 엔드포인트를 명령으로 옮겼습니다.
- API와 같은 저장소에서 버전을 관리합니다. 엔드포인트를 바꾸면 같은 PR에서 CLI도 함께 고친다는 규칙을 두었습니다. 서버와 클라이언트의 계약이 따로 낡을 틈이 없습니다.
- 사람도 같은 명령을 씁니다. 에이전트가 한 일을 터미널에서 그대로 재현할 수 있어서 문제를 추적하기 쉽습니다.
등록은 홈 디렉터리의 실행 경로에 한 줄짜리 래퍼 스크립트를 두는 방식입니다. 저장소의 스크립트를 exec으로 넘겨 부르기만 하므로 git pull만 하면 CLI도 최신이 됩니다.
명령 구성
| 명령군 | 하위 명령 | 예 |
|---|---|---|
req (요구사항) | 21개 | req list --status APPROVED --mine, req get <id>, req status <id> <STATUS> [코멘트], req artifact save <id> prd <파일> |
dev (개발항목) | 8개 | dev list --mine, dev doc save <id> DEV_SPEC <파일>, dev stage step <id> BUILD APPROVE [사유] |
sprint | 11개 | sprint active, sprint assign <sprintId> <REQ…> |
| 그 밖 | backlog, approvals pending, processes, whoami |
인증과 비밀값
자동화는 API 토큰으로 합니다. 대화식 로그인도 있지만 TTY가 필요해서 에이전트가 실행하면 아무 출력 없이 끝납니다.
- 토큰은 사람이 웹 설정 화면에서 발급합니다. 만료는 30일에서 365일 사이에서 고르고 기본은 90일입니다.
- 서버는 토큰 원문을 저장하지 않고 SHA-256 해시만 둡니다.
- CLI는 환경변수나 권한 600인 파일에서 토큰을 읽습니다. 인증 헤더는 명령 인자가 아니라 표준 입력으로
curl에 넘겨서 프로세스 목록에 토큰이 보이지 않습니다. - 에이전트는 비밀번호나 토큰 값을 어떤 경로로도 입력받지 않습니다. 설치 런북에서도 환경 판별·설치·검증은 에이전트가 끝까지 하고, 토큰 발급과 관리자 권한 입력만 사람에게 넘깁니다.
종료 코드도 에이전트가 읽기 쉽게 나눴습니다. 0은 정상, 1은 오류, 3은 인증 없음 또는 만료, 4는 권한 없음(403)입니다. 4를 받으면 재시도하지 않고 그 일을 누가 해야 하는지 안내하도록 절차에 적어 두었습니다.
에이전트의 컨텍스트를 아끼는 출력
사람에게는 사소하지만 에이전트에게는 비용인 것들이 있습니다.
- 요구사항 한 건을 그대로 조회하면 응답이 약 3만 3,800자였습니다(2026년 9월 4일 실측). 그중 92%가 생성 문서 원문이었습니다. 그래서
req get은 문서 원문을 글자 수 표기로 접어서 내보내고, 필요할 때만 옵션으로 펼칩니다. 같은 조회가 약 2,700자가 됩니다. REQ-101같은 번호를 내부 ID로 바꾸려면 목록을 훑어야 합니다. 절차 문서에 「첫 조회에서 ID를 잡아 두고 이후에는 ID로 부른다」를 넣었더니 조회 한 번이 3.3초에서 0.75초로 줄었습니다(같은 날 실측).- 목록은 사람용 표와
--json출력을 함께 지원합니다.
일부러 넣지 않은 명령
CLI에는 삭제와 완료 되돌리기가 없습니다. 파괴적이거나 되돌리기 어려운 작업은 웹 화면에서 사람이 직접 합니다. 에이전트의 권한을 프롬프트로 타이르는 대신, 연동 수단 자체에 그 명령을 두지 않았습니다.
AI 코딩 에이전트에 연결하기
연결은 처음 한 번, 여섯 단계입니다. 비밀값이 오가는 두 단계는 사람이 하고, 설치와 확인은 에이전트가 합니다. 절차 문서 연결은 팀이 저장소에 한 번 해 둡니다.
| 단계 | 누가 | 하는 일 |
|---|---|---|
| 1. 환경 확인 | 에이전트 | 운영체제와 셸을 판별하고 curl·jq가 있는지 봅니다. |
| 2. CLI 등록 | 에이전트 | 실행 경로에 한 줄짜리 래퍼 스크립트를 둡니다. alias는 에이전트가 쓰는 비대화형 셸에서 잡히지 않아 쓰지 않습니다. |
| 3. 토큰 발급 | 사람 | VIBE OPS 웹 설정 화면에서 API 토큰을 만듭니다. 원문은 발급 직후 한 번만 보입니다. |
| 4. 토큰 저장 | 사람 | 자기 터미널에서, 화면에 표시되지 않는 입력으로 파일에 넣고 본인만 읽게 합니다. 채팅에 붙여넣지 않습니다. |
| 5. 확인 | 에이전트 | ops whoami 한 번으로 서버 접속과 인증을 함께 봅니다. 이름과 역할이 나오면 끝입니다. 인증이 없으면 3·4단계를 안내하고 멈춥니다. |
| 6. 절차 문서 연결 | 팀 | 저장소의 에이전트 지침 파일에 「이런 요청이면 이 절차 문서」 표를 두고, 절차 문서(Skills)를 같은 저장소에 둡니다. 에이전트는 작업을 시작할 때 이 표를 읽습니다. |
# (에이전트) 저장소 루트에서 — 실행 경로에 래퍼 등록
mkdir -p ~/bin
printf '#!/usr/bin/env bash\nexec "%s/scripts/ops-cli.sh" "$@"\n' "$(pwd)" > ~/bin/ops
chmod +x ~/bin/ops
# (사람) 자기 터미널에서 — 토큰은 화면에 보이지 않게 입력
mkdir -p ~/.ops
read -rs -p 'API 토큰 붙여넣기: ' T && printf %s "$T" > ~/.ops/token && unset T; echo
chmod 600 ~/.ops/token
# (에이전트) 확인
ops whoami # 예시 출력: { "name": "홍길동", "role": "developer", … }토큰의 권한은 발급한 사람의 역할을 그대로 따릅니다. 그래서 연결이 끝난 에이전트가 할 수 있는 일은 그 사람이 웹 화면에서 할 수 있는 일과 같습니다.
Skills: 순서와 멈출 자리를 적은 문서
CLI가 「어떻게 부르는가」라면 Skills는 「언제 무엇을 부르고 어디서 멈추는가」입니다. 스킬 하나는 SKILL.md 문서 한 장입니다.
- 머리말에 이름과 설명을 적습니다. 설명에는 「스킬 이름을 말하지 않고 ○○라고 해도 적용한다」 같은 자연어 조건이 들어 있어서, 사용자가 명령을 외우지 않아도 에이전트가 의도를 읽고 해당 절차를 꺼냅니다.
- 본문은 번호 단계입니다. 단계마다 실제로 실행할 명령 블록이 있습니다.
- 끝에 「함정」 표와 「금지」 목록을 둡니다. 실제 사고에서 나온 항목들입니다.
- 여러 스킬이 같이 쓰는 규칙(DB 계층, 전달 규칙, 조회 비용 규칙)은 공통 참고 문서로 빼서 링크합니다.
스킬은 16개이고 네 묶음입니다.
| 묶음 | 스킬 |
|---|---|
| Git 흐름 | 작업 시작, 사전 점검, MR 생성, 머지, 정리, 현황, 릴리스 |
| 환경 | 서버 기동·중지, 작업 이어받기, 스키마 변경, 배포 큐 |
| 기획 문서 | PRD 초안, 개발 스펙 초안 |
| VIBE OPS 연동 | CLI 레퍼런스(work-ops), 요구사항 한 건 끝까지(work-req), 개발항목 한 건 끝까지(work-dev) |
요구사항 한 건을 끝까지: work-req
「REQ-101 진행해줘」라는 한마디가 아래 절차로 풀립니다. 이 글에 나오는 요구사항 번호와 코멘트 문구는 예시입니다.
| 단계 | 하는 일 | CLI |
|---|---|---|
| ① 파악 | 요구사항·산출물·개발항목·코멘트·이력을 읽고 진입 지점과 규모를 보고 | req get, req artifact list, req dev-items, req timeline |
| ② PRD | PRD가 없을 때만 초안 작성 → 사용자 검토 → 저장 | req artifact save <id> prd |
| ③ 스펙·시나리오 | 각각 없을 때만 작성 | req artifact save <id> devSpec |
| ④ 분해 | 개발항목 분해안을 표로 제시 → 확인 뒤 등록 | req dev-add |
| ⑤ 개발 | 스프린트 소속을 확인하고 항목마다 work-dev 실행 | sprint active, req status <id> IN_PROGRESS |
| ⑥ 마무리 | 전 항목이 끝나면 개발 검토로 올리고 멈춤 | req status <id> IN_REVIEW |
①~②를 명령으로 보면 이렇습니다.
RID=$(ops req get REQ-101 | jq -r .id) # 번호 → ID, 한 번만
ops req get "$RID" | jq 'del(.generatedDocs)' # 본문만 (약 33,800자 → 2,700자)
ops req artifact list "$RID" # 산출물이 이미 있는가
ops req dev-items "$RID"
# PRD 없음 → 초안 작성 → 사용자 검토 → 저장과 코멘트를 한 번에
ops req artifact save "$RID" prd ./prd.md \
&& ops req comment "$RID" "PRD 등록 — 기능 요구 4건"이 절차는 멱등입니다. 산출물이 이미 있는지를 보고 진입 지점을 정하므로, 중간에 끊긴 작업을 다른 세션이 이어받아도 같은 일을 두 번 하지 않습니다.
개발항목 한 건: work-dev
개발항목은 공정 도장으로 진행을 남깁니다.
ops dev doc save "$DID" PRD ./prd.md \
&& ops dev stage step "$DID" DESIGN DOING "설계 착수"
# … 구현, 로컬 검증 …
ops dev comment "$DID" "로컬 E2E 4/4 · 사전 점검 통과"
ops dev stage step "$DID" BUILD APPROVE "구현 완료 — MR 머지·배포 반영"앞에서 말한 「진척률은 입력받지 않는다」가 여기서 닫힙니다. 에이전트가 찍은 공정 도장이 곧 현황판의 숫자가 됩니다. 검증 결과는 「통과했다」가 아니라 「4/4」처럼 숫자로 적게 했습니다.
좌석 나누기
절차 안에서 일의 성격에 따라 에이전트 좌석도 나눕니다. 설계·계획은 읽기 전용인 상위 모델 좌석이, 코드 위치 찾기는 가벼운 모델의 탐색 좌석이 결론과 경로:줄만 돌려주고, 구현은 격리된 작업 폴더(워크트리)에서 구현 좌석이 맡습니다.
자연어로 실행하기
연결이 끝나면 명령을 외울 필요가 없습니다. 절차 문서의 머리말에 자연어 조건이 적혀 있기 때문입니다. 개발항목 절차의 머리말은 요청 예시를 나열한 뒤 이렇게 끝납니다.
…처럼 스킬 이름 없이 개발리스트 항목의 진행을 요청할 때도 이 스킬을 적용한다.
한마디가 명령이 되기까지를 네 가지 경우로 보면 이렇습니다(번호는 예시).
| 사용자의 한마디 | 에이전트가 고르는 절차 | 실행하는 명령 | 결과 또는 멈추는 자리 |
|---|---|---|---|
| 「내 요구사항 뭐 있어?」 | work-ops | ops req list --mine | 목록을 요약해 보고합니다. 쓰기는 없습니다. |
| 「REQ-101 진행해줘」 | work-req | ops req get REQ-101 → ops req artifact list <id> → ops req dev-items <id> | 어디까지 돼 있는지와 규모를 먼저 보고합니다. PRD 초안은 사용자가 검토한 뒤에만 ops req artifact save <id> prd <파일>로 올립니다. |
| 「DEV-201 설계 끝났어, 기록해줘」 | work-dev | ops dev stage list <id> → ops dev stage step <id> DESIGN APPROVE "설계 완료" | 그 단계를 밟을 수 없으면(담당이 아니거나 앞 단계가 안 끝남) 기록하지 않고 이유를 알립니다. |
| 「REQ-101 완료 처리해줘」 | work-ops | 실행하지 않음 | 완료는 현업 확인으로만 처리된다고 안내하고 멈춥니다. |
대화로 보면 다음과 같습니다(응답 문구는 예시).
- 사용자
- 내 요구사항 뭐 있어?
- 에이전트
- 담당하거나 요청하신 요구사항은 3건입니다. 개발 중 1건(REQ-101), 요구사항 검토 2건(REQ-102, REQ-103)입니다.
- 사용자
- REQ-101 완료 처리해줘.
- 에이전트
- REQ-101은 제가 완료로 바꿀 수 없습니다. 완료는 현업 프로세스 담당의 확인으로만 처리되고, 상태를 직접 바꾸는 요청은 서버가 거절합니다. 개발항목 2건이 모두 끝났으니, 원하시면 「개발 검토」로 올려 확인을 기다리게 하겠습니다.
두 번째 대화에서 에이전트는 명령을 시도해 보고 실패하는 대신, 절차 문서에 적힌 규칙을 먼저 읽고 멈춥니다. 서버도 같은 규칙을 강제하므로, 에이전트가 문서를 잘못 읽더라도 완료 처리는 되지 않습니다.
에이전트가 멈추는 자리
연결에서 가장 공을 들인 부분은 에이전트가 하지 않는 일입니다. 멈출 자리를 코드와 문서 양쪽에 두었습니다.
| 멈추는 자리 | 서버(코드) | 절차(문서) |
|---|---|---|
| 완료 처리 | DONE은 확인 절차로만, 직접 변경은 400 | 개발 검토까지 올리고 멈춤 |
| 스프린트·요구사항 승인 | 역할 권한 표 | 사용자가 명시적으로 요청할 때만 |
| 스프린트에 없는 요구사항 | 개발 중 전환 거절 | 스스로 스프린트에 넣지 않고 담당자에게 요청하라고 보고 |
| 삭제·되돌리기 | CLI에 명령 없음 | 웹 화면에서 사람이 |
| 권한 오류 | 403 (종료 코드 4) | 재시도 금지, 누가 해야 하는지 안내 |
| 기획 문서 저장 | — | 초안은 사용자 검토 뒤에만 올림 |
| 운영 반영 | — | 배포 버튼과 운영 브랜치 머지는 사람 |
문서만으로 막으면 에이전트가 절차를 잘못 읽는 순간 뚫립니다. 코드만으로 막으면 에이전트가 거절당한 뒤 우회로를 찾느라 시간을 씁니다. 서버가 막고, 문서가 「여기서는 시도하지 말고 이렇게 보고한다」를 알려 주는 조합이 가장 안정적이었습니다.
운영하며 배운 것
alias는 에이전트 셸에서 잡히지 않습니다. 비대화형 셸은 alias를 읽지 않습니다. 실행 경로에 래퍼 스크립트를 두어야 합니다.- Windows Git Bash의
ln -s는 링크가 아니라 복사본을 만듭니다. 저장소를 갱신해도 옛 CLI가 남습니다. 래퍼가 저장소의 스크립트를 직접 부르게 하면 생기지 않는 문제입니다. - 한글 본문은 인자로 넘기지 않습니다. 일부 환경에서 인코딩이 깨져서 본문은 임시 파일로 전달합니다.
- 문서는 코드보다 먼저 낡습니다. 역할이 다섯에서 여섯으로 늘어난 뒤에도 설계 문서 두 곳에는 다섯으로 적혀 있습니다. 에이전트가 따르는 정본은 코드, CLI 도움말, 절차 문서로 좁히고, 규칙을 바꾸면 그 셋을 같은 변경에서 고칩니다.
- 스킬의 본체는 포장이 아니라 문서입니다. 처음에는 스킬을 플러그인으로 묶어 슬래시 명령으로 호출했습니다. 지금은 묶음을 풀고 에이전트가 절차 문서를 직접 읽어 따릅니다. 호출 방식이 바뀌어도 절차는 그대로 쓸 수 있었습니다.
마치며
정리하면 세 가지입니다.
- 규칙은 서버에 둡니다. 사람과 에이전트가 같은 API, 같은 권한 표를 탑니다.
- 연동 수단은 얇게 둡니다. CLI는 API를 그대로 옮기고, API와 같은 저장소에서 같이 바뀝니다.
- 순서와 멈출 자리는 문서로 둡니다. 에이전트가 어디까지 하고 어디서 사람에게 넘기는지를 절차에 적습니다.
한 줄 정리
에이전트에게 더 많은 일을 맡기려면 더 똑똑한 프롬프트보다, 에이전트가 읽고 쓸 운영 시스템과 그 시스템이 지키는 규칙이 먼저 필요했습니다.