만들고, 써 보게 하고, 고치게 한다 — vspec MVP로 세팅한 에이전트 루프 강의노트

2026-05-28 라이브 · 6시간 19분 · 다시보기

Vooster의 스펙 도구 vspec을 서버 없는 CLI로 다시 만들고, 형제 제품에 붙여 에이전트가 쓴 기록으로 고칠 곳을 찾게 한 6시간 실습이에요.

이 노트를 읽고 나면 할 수 있는 것

1. 계획은 Claude로 세우고, 구현은 목표 문서 하나와 게이트를 걸어 Codex /goal에 맡기기
2. 에이전트가 내 CLI를 써 본 세션 로그를 분석시켜 사용성 테스트와 QA를 대신하기
3. 자리를 비우기 전에, 맥락이 압축돼도 흐름을 잃지 않는 리팩터링 목표 문서 걸어 두기

목차

• 서버 없는 MVP를 새 레포에 다시 짜요 ▶ 0:03:45
• Codex /goal에는 파일 경로만 넘겨요 ▶ 0:39:27
• 형제 제품에 붙여 개밥먹기 ▶ 1:03:37
• 생산성의 주어는 사람이에요 ▶ 1:43:56
• 에이전트가 남긴 세션이 곧 QA예요 ▶ 2:01:22
• 쓰면서 고치고, 브레이크를 달아요 ▶ 3:38:16
• 자러 가기 전에 리팩터링 목표를 걸어 둬요 ▶ 5:55:38
• Q&A ▶ 3:39:51
• 오늘 해볼 것 ▶ 6:17:50

서버 없는 MVP를 새 레포에 다시 짜요 ▶ 0:03:45

이날 목표는 에이전트 루프 세팅이었어요. 컨설팅에서 세팅해 드리는 것과 같은 구조인데, 에이전트에게 준 피드백이 인사이트로 남아서 하네스(에이전트가 일하는 규칙·도구·검사의 묶음)를 계속 키우는 루프예요 ▶ 0:04:15.

에이전트랑 대화하면서 작업하지 않고, 프로세스를 정규화하는 게 목적이에요. ▶ 0:04:24 프로세스가 정해져 있어야 성과를 재기 좋고, 반복해서 고치기도 좋거든요.

재료는 만들던 스펙 관리 제품 Vooster의 스펙 도구 vspec이었어요. 문제는 개밥먹기(만든 사람이 자기 제품을 먼저 써 보는 단계)를 시작하기에 스펙이 너무 컸다는 거예요 ▶ 0:06:11. 서버 DB를 띄우고, 배포하고, 마이그레이션까지 챙기다 보니 개밥먹기 단계만 두 달이 걸릴 판이었어요.

그래서 스펙을 줄이는 대신 경량 버전을 새 프로젝트로 만들기로 했어요 ▶ 0:06:36. 스펙을 줄이면 지금까지 짠 코드가 아깝기 때문이에요.

빈 폴더를 만들고 git init만 해 둔 뒤, 기존 레포의 Claude Code에게 음성으로 요청했어요. 서버 없이 로컬 파일 시스템만으로 도는 MVP를 새 경로에 만들 거라고요.

그리고 구현은 Codex의 goal 기능으로 할 테니 구현에 필요한 문서와 페이즈별 계획이 담긴 goal 문서를 써 달라고요. 모호한 점은 먼저 논의점으로 올려 달라고 덧붙였어요.

이어서 범위도 정해 줬어요. 기존 레포의 goal 시스템만큼 복잡하게 만들지 말고, goal 문서와 진행 상황을 추적할 JSON 파일 하나면 된다고요 ▶ 0:12:24.

Claude는 먼저 서버가 있어야 성립하던 기능을 골라냈어요. 브랜치·리비전은 Git이 이미 하는 일이고, 동기화나 인증은 아예 사라져요. Claude와 논의를 마치고 나온 첫 커밋은 코드 없이 문서뿐이었어요.

vooster-spec-mvp/        # 첫 커밋 "initial setting"
├── GOAL.md              # 페이즈 0~7, 페이즈마다 게이트
├── progress.json        # task 상태 todo → doing → done
└── docs/
    ├── 00-overview.md
    ├── 01-cockburn.md
    ├── 02-file-format.md
    ├── 03-cli-spec.md
    └── 04-agent-envelope.md

vspec이 다루는 건 코번식 유스케이스(Alistair Cockburn이 정리한, 주 행위자·주 성공 시나리오·확장 흐름으로 쓰는 요구사항 문서)예요. 이 형식을 마크다운으로 쓰고, 검증하고, 내보내는 CLI를 만드는 게 MVP의 범위였어요.