반쯤 완성된 아이디어에서 테스트를 거쳐 배포된 코드까지 — 우리가 한 시간 이내에 기능을 출시하는 방법.

48분

우리의 전형적인 기능 구축 과정은 다음과 같습니다:

10:02  /specify "크레딧 상태 대시보드에 시간 범위 필터 추가"
10:03  → 8개의 수락 기준 (acceptance criteria)을 포함한 REQ-287 생성

...

48분. 아이디어에서 테스트를 거쳐 병합된 기능까지. 명세 (spec) 작성에는 60초가 걸렸습니다. 사람은 차이점 (diffs)을 검토하고, PR (Pull Request)을 승인하며, 컴포넌트의 패딩 (padding)을 한 번 조정했습니다. 테스트는 모의 객체 (mock)나 스텁 (stub)이 아닌, 데이터베이스 수준에서 실제 데이터가 검증된 라이브 개발 배포 환경 (live dev deployment)에서 실행되었습니다.

BrainGrid의 모든 기능은 이런 방식으로 구축됩니다. 마케팅용 수사가 아니라, 이것이 우리가 발견한 가장 빠른 워크플로우 (workflow)이기 때문입니다. 이 포스트에서는 이것이 어떻게 작동하는지 설명합니다.

문제점

Vibe-coding은 코드를 병합하고 배포한 뒤, 에러 상태 (error state)를 잊었다는 것을 깨닫기 전까지는 잘 작동합니다. 혹은 로딩 상태 (loading state)를 잊었거나, 사용자의 크레딧이 0인데 버튼을 클릭했을 때 어떤 일이 발생하는지를 잊었을 때 말이죠.

당신은 빠르게 움직이고 있기 때문에 그런 케이스들을 생각하지 못했을 것이며, 이는 프로토타입 (prototype) 단계에서는 괜찮습니다. 하지만 AI 역시 그런 것들을 생각하지 못했습니다. 당신이 말해주지 않았기 때문입니다. AI는 당신이 설명한 그대로, 즉 해피 패스 (happy path)만을 구축했습니다. 그 외의 모든 것은 누락되었습니다.

해결책은 속도를 늦추거나 AI 사용을 중단하는 것이 아닙니다. AI에게 에지 케이스 (edge cases), 에러 처리 (error handling), 로딩 상태 (loading states)가 이미 고려된 요구사항 (requirement)을 제공하는 것입니다. 그러면 당신이 직접 고민할 필요가 없습니다. 당신의 명세 (spec)를 작성하는 AI는 제품 엔지니어 (product engineer)처럼 생각합니다. 당신이 건너뛸 법한 질문들을 던집니다. 명세를 구현하는 AI는 프로덕션 소프트웨어 엔지니어 (production software engineer)처럼 실행합니다. 전문적인 요구사항이 그것을 요구하기 때문입니다.

이것이 전체 철학입니다: 코드가 아닌 요구사항에서 시작하라 (start with requirements, not code).

워크플로우 (Workflow): 네 가지 명령어

1. /specify — 아이디어를 요구사항으로 전환

/specify "Trial users should see upgrade prompt instead of buy credits when out of credits"

AI는 당신의 한 줄짜리 아이디어를 구조화된 요구사항 (Requirement)으로 정교화합니다. /specify를 거친 후의 REQ-375는 다음과 같은 모습이었습니다:

REQ-375: Trial users should see upgrade prompt instead of buy credits

Problem:
...

이것은 요약된 형태입니다. 전체 요구사항에는 데이터 페칭 전략 (5분간의 stale time을 가진 React Query), Props 인터페이스, 에러/로딩 상태 명세, 그리고 모든 조건에 배너 변형, 메시지 문구, CTA 버튼을 매핑하는 메시지 변형 테이블도 포함되어 있었습니다.

잘 구조화된 요구사항은 다음과 같은 구성 요소를 가집니다:

• 문제 정의 (Problem statement) — 사용자 관점에서 무엇이 잘못되었거나 누락되었는지
• 솔루션 요약 (Solution summary) — 구현 방법이 아닌 접근 방식
• 범위 (Scope) — 어떤 파일/컴포넌트가 영향을 받는지 (AI가 엉뚱한 곳을 헤매지 않도록 함)
• 수락 기준 (Acceptance criteria) — "완료"를 정의하는 테스트 가능한 Given/When/Then 조건
• 예외 케이스 및 에러 처리 (Edge cases and error handling) — 로딩 상태, 실패, 경계 조건
• 범위 외 (Out of scope) — 이 요구사항에서 의도적으로 다루지 않는 것

AI는 단 한 문장으로부터 이 모든 것을 생성합니다. 당신이 한 줄을 입력하면, AI가 문제 정의, 수락 기준, 예외 케이스, 범위를 포함한 전체 명세 (Spec)를 작성하고 당신은 이를 검토합니다. 대부분의 경우 80%는 정확합니다. 당신은 나머지 20%를 수정하고 다음으로 넘어갑니다. 우리는 약 20%의 확률로 잘못된 명세를 발견합니다. 예를 들어 AI가 인라인 편집 (Inline editing) 대신 모달 (Modal)을 가정했거나, 인증 체크 (Auth check)를 놓쳤거나, 범위를 너무 넓게 잡는 경우입니다. 명세를 수정하는 데는 몇 초가 걸리지만, 잘못된 구현을 디버깅하는 데는 한 시간이 걸립니다.

2. /breakdown — 명세를 작업(Task)으로 전환

/breakdown REQ-375

이것은 단순히 "작업을 덩어리로 나누는 것" 이상의 의미를 갖습니다. AI는 세 가지 소스(전체 요구사항(수락 기준, 엣지 케이스, 기술적 결정), 코드베이스 구조(리포지토리 분석, 파일 트리, 기존 패턴), 관련 문서)로부터 컨텍스트(Context)를 수집합니다. 그런 다음 각 작업이 단일 관심사(Single concern)에 집중되도록 범위를 지정하고, 작업 간의 명시적인 의존성을 포함하는 원자적 구현 작업(Atomic implementation tasks)을 생성합니다. AI는 어떤 파일이 존재하는지, 어떤 훅(Hook)과 컴포넌트(Component)가 이미 코드베이스에 있는지, 그리고 그것들이 어떻게 구조화되어 있는지를 알고 있습니다.

REQ-375에 대해 생성된 실제 작업들은 다음과 같습니다:

TASK-1: useSubscriptionStatus 훅 생성
  → 새 훅: src/hooks/use-subscription-status.ts
  → /api/organizations/[orgId]/subscription 에서 페치(Fetch)
...

이것들은 모호한 티켓이 아닙니다. 이것들은 프롬프트(Prompt)입니다. 각 프롬프트는 에이전트(Agent)에게 정확히 어떤 파일을 수정해야 하는지, 어떤 패턴을 따라야 하는지, 어떤 프롭(Prop)을 추가해야 하는지, 그리고 기대되는 동작이 무엇인지를 알려줍니다. 명세(Spec)에서 이미 설계 결정(캐시 키, stale time, 폴백 동작)을 내렸기 때문에, 작업들은 순수한 실행(Execution) 단계가 됩니다.

3. /build — 구현 시작

/build REQ-375

이 명령은 다음의 4단계 흐름을 실행합니다:

1. 빌드 계획(Build plan) 가져오기: BrainGrid로부터 요구사항 상세 정보와 전체 작업 배열을 가져옵니다.
2. 기능 브랜치(Feature branch) 생성: feature/REQ-375-trial-upgrade-prompt 브랜치를 생성하고 이를 BrainGrid에 연결하여 모든 것이 연동되도록 합니다.
3. 작업 생성 및 연결: Claude Code에서 작업을 생성하고 연결하며, 각 작업을 BrainGrid와 연결하여 상태가 자동으로 동기화되도록 합니다.
4. 첫 번째 작업 즉시 구현 시작: "진행할까요?"와 같은 확인 프롬프트 없이 바로 시작합니다.

에이전트는 작업을 순차적으로 수행합니다. 코드를 구현하고, yarn validate:fix를 실행하며, 검증(Validation)이 통과되면 작업을 완료로 표시하고 다음 작업으로 넘어갑니다. 검증에 실패하면 에러를 읽고 문제를 수정한 뒤, 다음으로 넘어가기 전에 다시 실행합니다. 사용자는 이를 실시간으로 지켜보며 필요할 때 방향을 수정할 수 있습니다.

지침을 추가하여 집중 분야를 조절할 수도 있습니다: /build REQ-375 start with the data fetching hook — 그러면 Claude가 그에 따라 작업 우선순위를 조정합니다.

4. braingrid requirement review — PR에 대한 수락 기준 (Acceptance Criteria) 검증

braingrid requirement review

이 단계야말로 명세 (Spec)가 제 역할을 하는 지점입니다. 이 명령은 git에서 브랜치 이름과 PR 번호를 통해 요구사항을 자동으로 감지한 다음, AI를 사용하여 리뷰를 수행합니다. GitHub에서 PR diff를 가져오고 BrainGrid에서 수락 기준 (Acceptance Criteria)이 포함된 전체 요구사항을 가져온 뒤, AI는 실제 코드 변경 사항이 각 기준을 충족하는지 추론합니다. 이때 기준을 diff의 특정 라인과 연결하여 추적합니다:

Reviewing PR #1288 against REQ-375...

Acceptance Criteria:
...

구현 과정에서 엣지 케이스 (Edge case)를 놓쳤을까요? 코드 변경 사항과 일치하는 기준이 없나요? 사용자가 버그를 보고하기 전, PR이 머지 (Merge)되기 전에 이를 확인할 수 있습니다.

기준을 충족하지 못했을 때의 모습은 다음과 같습니다. 예를 들어, 에이전트가 상단 배너는 구현했지만 에이전트 오버레이 (Agent overlay) 업데이트를 잊은 경우입니다:

Reviewing PR #1288 against REQ-375...

Acceptance Criteria:
...

AI는 각 기준을 diff의 특정 라인으로 추적합니다. 단순히 키워드를 검색 (Grepping)하는 것이 아니라, 코드 변경 사항이 실제로 기준을 충족하는지 추론합니다. 이는 컴파일 (Compile)과 린트 (Lint)가 통과되더라도 발생하는 의미론적 간극 (Semantic gaps)을 잡아냅니다. 예를 들어, 테스트 상태 (Trial state)를 처리하지만 잘못된 CTA 텍스트를 렌더링하는 컴포넌트나, 올바르게 작동하지만 기준에 명시된 동작과 일치하지 않는 에러 폴백 (Error fallback) 등이 이에 해당합니다. 다만, 코드는 올바르게 읽히지만 동작이 잘못된 런타임 로직 에러(예:

테스트: Stripe을 이용한 크레딧 충전
──────────────────────────────────────────────────
설정: 초기 잔액 조회 → 1,998 크레딧
...

agent-browser가 버튼 클릭, 양식 작성, 페이지 탐색과 같은 실제 사용자 흐름 (user flow)을 주도합니다. MCP 서버는 에이전트에게 설정 및 검증을 위한 직접적인 데이터베이스 접근 권한을 부여합니다. 에이전트는 명세 (spec)를 읽고, 실행 중인 앱을 대상으로 각 단계를 수행하며, 관찰된 이벤트 페이로드 (event payloads) 및 데이터베이스 상태 변경을 포함한 실제 결과를 추가합니다.

방어 체계는 계층화 (layered)되어 있습니다. 명세 검토 (spec review)는 누락된 구현을 잡아내고, 요구사항 검토 (requirement review)는 기준과 코드 사이의 간극을 잡아내며, 브라우저 테스트 (browser tests)는 라이브 앱에서의 동작 버그를 잡아냅니다. 진짜 간극, 즉 잘못된 명세와 잘못된 테스트가 동시에 존재하는 상황은 인간 엔지니어링에서도 발생하는 것과 동일한 간극입니다. 차이점은 모든 계층이 자동으로 실행된다는 점입니다.

작동이 실패할 때

해피 패스 (happy path)는 보기 좋습니다. 상황이 잘못될 때는 다음과 같은 일이 발생합니다.

명세 자체가 틀린 경우. 이것은 어떤 자동화로도 잡아낼 수 없는 유일한 실패 모드 (failure mode)입니다. 왜냐하면 모든 하위 계층이 명세를 충실히 실행하기 때문입니다. 만약 명세에 "모달 (modal)을 표시하라"고 되어 있는데 실제 의도가 인라인 편집 (inline editing)이었다면, 구현은 "잘못된 명세에 따라" 올바르게 이루어질 것입니다. 이것이 바로 /specify가 요구사항을 생성하기 전에 명확화 질문 (clarifying questions)을 통해 단계를 안내하는 이유이며, /breakdown을 하기 전에 명세를 검토해야 하는 이유입니다. 인간이 체크포인트 (checkpoint)입니다. 만약 잘못된 명세를 그대로 승인 (rubber-stamp)한다면, 그 이후의 모든 단계에 대한 책임은 당신에게 있습니다.

AI가 명세를 오해하는 경우. 위 상황과는 다릅니다. 이는 /specify가 당신의 의도와 일치하지 않는 수락 기준 (acceptance criteria)을 생성했을 때, 당신이 이를 잡아내는 경우를 말합니다. 우리는 잘못된 명세를 약 20%의 확률로 잡아냅니다. 예를 들어, 인라인 편집을 원했는데 AI가 모달을 가정했거나, 인증 (auth) 요구사항을 놓쳤거나, 범위를 너무 넓게 설정한 경우 등입니다. 명세를 수정하는 데는 몇 초가 걸리지만, 잘못된 구현을 디버깅하는 데는 한 시간이 걸립니다.

작업 검증 실패 (A task fails validation). 에이전트는 모든 작업 후에 yarn validate:fix를 실행합니다. 만약 타입 (types)이 깨지거나 테스트가 실패하면, 에이전트는 에러를 읽고 코드를 수정한 뒤, 작업을 완료로 표시하기 전에 다시 검증합니다. 여러분은 이 과정이 실시간으로 일어나는 것을 볼 수 있습니다. 만약 에이전트가 루프에 빠지면 사용자가 개입해야 하지만, 작업 설명(task description)에 이미 따라야 할 패턴이 명시되어 있기 때문에 그런 일은 드뭅니다.

requirement review가 공백을 발견함. 특정 기준 (criterion)에 대응하는 코드 변경 사항이 나타나지 않습니다. 에이전트가 이를 놓쳤거나 범위 외 (out of scope)라고 판단한 것입니다. 여러분은 정확히 어떤 기준이 실패했는지 확인할 수 있으며, 이를 구현하거나 의도적으로 보류 (deferred)된 것으로 표시할 수 있습니다.

테스트 실패. 에이전트 브라우저 (agent-browser)가 DOM을 스냅샷 (snapshot)하고 에이전트가 실제 상태를 읽습니다. "'Upgrade plan' 버튼을 예상했으나, 'Top-up credits' 버튼이 발견되었습니다." 스냅샷을 통해 에러는 대개 명확하게 드러납니다. 에이전트는 코드를 수정하고 다시 실행할 수 있으며, 사용자가 직접 조사할 수도 있습니다. 요소 참조 (Element refs, @e1, @e2)는 페이지 상호작용이 일어날 때마다 변경되므로, 에이전트는 각 단계 이후에 다시 스냅샷을 찍습니다. 오래된 참조 (stale refs)는 가장 흔한 실패 모드이지만, 툴링 (tooling)이 이를 처리합니다.

훔칠 만한 가치가 있는 패턴들

이 패턴들은 BrainGrid 사용 여부와 상관없이 모든 AI 보조 개발 워크플로우 (AI-assisted development workflow)에 적용 가능합니다:

1. 구축하기 전에 명세(Specify)하세요. 초기에 몇 분간 명확하게 정의하는 것이 한 시간의 재작업을 줄여줍니다. 이것은 당신이 할 수 있는 가장 영향력 있는 단 한 가지 일입니다.
2. 태스크(Tasks)는 프롬프트입니다. 마치 AI에게 프롬프트를 작성하듯 태스크 설명을 작성하세요. 실제로 그렇게 하는 것이니까요. 파일 경로, 패턴, API를 포함하세요.
3. 사람이 잊어버리는 것들을 자동화하세요. 태스크 상태 동기화(Task status sync), 검증(validation), 브랜치 명명 규칙(branch naming conventions) 등이 해당됩니다. 개발자가 직접 기억해서 해야 한다면, 결국 하지 않게 될 것입니다.
4. 코드뿐만 아니라 명세(spec)를 기준으로 검증하세요. 코드 리뷰는 버그를 잡아냅니다. 명세 리뷰는 누락된 요구사항을 잡아냅니다. 브라우저 테스트는 동작 회귀(behavioral regressions)를 잡아냅니다. 이 세 가지가 모두 필요합니다.
5. 에이전트는 즉시 시작해야 합니다. 명시적인 빌드 명령이 내려진 후에는 "진행할까요?"라고 묻지 마세요. 사용자는 이미 의도를 표현했습니다.
6. 실제 인프라를 대상으로 테스트하세요. 데이터베이스 쿼리, 브라우저 상호작용, 배포된 엔드포인트(endpoints) 등이 해당됩니다. 모크(Mocks)는 버그를 숨깁니다.
7. 메모리는 복리로 쌓입니다. 학습한 내용을 지속적으로 저장하세요. 미래의 당신(그리고 당신의 에이전트들)이 고마워할 것입니다.
8. 오류를 반응적으로 처리하세요. 모든 도구가 설치되어 있는지 미리 확인하지 마세요. 일단 실행하고, 실패가 발생하면 그때 처리하세요.

5분 안에 시도해보기

시작하기 위해 전체 설정을 갖출 필요는 없습니다. 핵심 루프인 명세(specify), 분해(break down), 구축(build)은 다음 세 가지만 있으면 작동합니다:

## 1. CLI 설치
npm install -g @braingrid/cli

...

그게 전부입니다. MCP 서버도, 훅(hooks)도, 브라우저 자동화도 필요 없습니다. 데이터베이스 검증, 자동화된 태스크 동기화, 또는 AI 기반 테스트가 필요할 때 나중에 추가하세요. 명세(spec)부터 시작하세요.

내부 동작 원리 (Under the Hood)

이 워크플로우는 몇 가지 확장 기능을 갖춘 Claude Code 위에서 실행됩니다. 위의 모든 사항은 즉시 사용 가능합니다. 아래의 모든 사항은 전체 경험을 구동하지만 선택 사항입니다.