블로그 목록으로

 · 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에서 나옵니다.

만들면서 풀려고 한 문제는 네 가지였습니다.

화면은 요구사항(칸반·백로그·스프린트·변경 추적), 개발관리(개발리스트·현황판·주간 실적), 테스트관리, 위험·이슈, 결재함, 시스템관리로 나뉩니다. 프런트는 Next.js, 백엔드는 NestJS, DB는 Oracle이고 pnpm + Turborepo 모노레포입니다.

요구사항이 지나가는 길

요구사항 한 건은 아래 상태를 차례로 지납니다.

상태뜻옮기는 사람
DRAFT초안등록자
REVIEW요구사항 검토컨설턴트
APPROVED요구사항 승인 (스프린트에 넣을 수 있음)컨설턴트
IN_PROGRESS개발 중개발자
IN_REVIEW개발 검토 (현업 확인 대기)개발자
DONE완료현업 프로세스 담당(PI)의 확인으로만

요구사항은 개발항목 여러 건으로 나뉘고, 개발항목은 DESIGN → BUILD → TEST → DEPLOY 공정을 밟습니다. 공정마다 WAIT → DOING → APPROVE 세 상태가 있습니다. 구현이 끝나면 컨설턴트 컨펌과 현업 리뷰라는 확인 축을 따로 거칩니다.

중요한 규칙은 화면이 아니라 서버가 강제합니다.

계정 역할은 관리자·PM·컨설턴트·개발자·PI·요청자 여섯 가지이고, 리소스마다 읽기·쓰기·승인·관리·계획 다섯 액션을 정적인 표로 매핑합니다. 「본인이 관련된 건만」 같은 범위 판정은 서비스 로직이 합니다.

이 규칙들이 서버에 있다는 점이 뒤에 나올 에이전트 연결의 전제입니다.


연결 구조: 세 층

사람
웹 화면
에이전트
Skills절차 문서
CLIbash 래퍼
REST API권한 표 · 상태 규칙
DB
사람은 웹 화면으로, 에이전트는 Skills와 CLI로 같은 REST API를 탑니다.
층맡는 일형태
API무엇이 허용되는가NestJS 컨트롤러 약 30개, 역할 × 리소스 권한 표
CLI어떻게 부르는가bash 스크립트 1개, 하위 명령 43개
Skills언제, 어떤 순서로, 어디서 멈추는가절차 문서 16개

이 글의 개수와 줄 수는 2026년 11월 20일 저장소 기준입니다.

사람과 에이전트는 같은 API를 탑니다. 에이전트 전용 뒷문이 없으므로 에이전트가 할 수 있는 일은 그 토큰 주인의 역할이 할 수 있는 일과 같습니다.


CLI: 얇은 연동 수단 하나

에이전트용 연결이라고 하면 MCP 서버를 먼저 떠올리지만, VIBE OPS에는 MCP 서버가 없습니다. 연동 수단은 ops라는 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 [사유]
sprint11개sprint active, sprint assign <sprintId> <REQ…>
그 밖backlog, approvals pending, processes, whoami

인증과 비밀값

자동화는 API 토큰으로 합니다. 대화식 로그인도 있지만 TTY가 필요해서 에이전트가 실행하면 아무 출력 없이 끝납니다.

종료 코드도 에이전트가 읽기 쉽게 나눴습니다. 0은 정상, 1은 오류, 3은 인증 없음 또는 만료, 4는 권한 없음(403)입니다. 4를 받으면 재시도하지 않고 그 일을 누가 해야 하는지 안내하도록 절차에 적어 두었습니다.

에이전트의 컨텍스트를 아끼는 출력

사람에게는 사소하지만 에이전트에게는 비용인 것들이 있습니다.

일부러 넣지 않은 명령

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 문서 한 장입니다.

스킬은 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
② PRDPRD가 없을 때만 초안 작성 → 사용자 검토 → 저장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-opsops req list --mine목록을 요약해 보고합니다. 쓰기는 없습니다.
「REQ-101 진행해줘」work-reqops req get REQ-101 → ops req artifact list <id> → ops req dev-items <id>어디까지 돼 있는지와 규모를 먼저 보고합니다. PRD 초안은 사용자가 검토한 뒤에만 ops req artifact save <id> prd <파일>로 올립니다.
「DEV-201 설계 끝났어, 기록해줘」work-devops 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)재시도 금지, 누가 해야 하는지 안내
기획 문서 저장—초안은 사용자 검토 뒤에만 올림
운영 반영—배포 버튼과 운영 브랜치 머지는 사람

문서만으로 막으면 에이전트가 절차를 잘못 읽는 순간 뚫립니다. 코드만으로 막으면 에이전트가 거절당한 뒤 우회로를 찾느라 시간을 씁니다. 서버가 막고, 문서가 「여기서는 시도하지 말고 이렇게 보고한다」를 알려 주는 조합이 가장 안정적이었습니다.


운영하며 배운 것


마치며

정리하면 세 가지입니다.

  1. 규칙은 서버에 둡니다. 사람과 에이전트가 같은 API, 같은 권한 표를 탑니다.
  2. 연동 수단은 얇게 둡니다. CLI는 API를 그대로 옮기고, API와 같은 저장소에서 같이 바뀝니다.
  3. 순서와 멈출 자리는 문서로 둡니다. 에이전트가 어디까지 하고 어디서 사람에게 넘기는지를 절차에 적습니다.

한 줄 정리

에이전트에게 더 많은 일을 맡기려면 더 똑똑한 프롬프트보다, 에이전트가 읽고 쓸 운영 시스템과 그 시스템이 지키는 규칙이 먼저 필요했습니다.

우리 업무도 될까요? 2주 무료 현장 진단으로 확인하세요

업무 하나를 골라 2주 동안 현장에서 진단하고, 진단 보고서와 구축 제안을 드립니다. 다음 단계로 갈 의무는 없습니다.

컨설팅 알아보기