코딩 전에 결정부터 — product-pipeline 스킬이 명세화를 강제하는 방법

혼자 개발할 때도 “뜯어야 해”를 막을 수 있다

혼자 개발할 때 가장 많이 하는 실수가 있습니다. 아이디어가 생기면 바로 코딩을 시작하는 거예요. 처음엔 잘 됩니다. 화면이 올라오고, 데이터가 들어오고. 그러다 어느 순간 막히죠. “근데 이 DB 어떻게 할 거지?” “공간 격리를 이렇게 하면 나중에 검색이 안 되는데.” 잠깐 결정을 내리고 다시 코딩하면, 조금 뒤에 또 뭔가 막힙니다. 코딩 흐름과 설계 흐름이 계속 충돌합니다.

“명세부터 써야 한다”는 말은 모두가 압니다. 문제는 팀이 없을 때 그걸 강제할 장치도 없다는 거예요. 슬랙에서 누가 물어봐 주는 것도 아니고, 기획서를 검토해 주는 사람도 없습니다. 결국 다시 코딩부터 시작하게 됩니다.

결정을 전부 앞으로 꺼내는 것

product-pipeline 스킬이 하는 일은 단순합니다. 코딩 중간에 끼어드는 결정들을 전부 앞으로 꺼내는 거예요.

스킬을 실행하면 결정 카탈로그(AD-1~13)가 순서대로 나옵니다. 저장 위치(AD-1), 인증 방식(AD-4), 결제(AD-5)처럼 앱 설계의 핵심 의사결정 항목들을 객관식으로 물어봅니다. 각 항목에는 추천값이 이미 붙어있어서, 동의하면 넘어가고 다른 선택을 하면 근거를 기록하는 방식입니다. 답변이 끝나면 설계 문서 7종(기능 명세, 아키텍처 결정 기록, 시스템 다이어그램, 도메인 모델, API 계약, 앱 아키텍처, 코딩 규칙)과 빌드 플랜이 자동으로 만들어집니다.

사람이 개입하는 지점은 오직 결정 라운드뿐입니다. 생성은 AI가 합니다.

AD-6: 설계 중간에 방향이 바뀌었을 때

마이위키 설계를 하면서 가장 드라마틱했던 순간이 AD-6였습니다.

처음 설계는 “공간 격리” 방식이었습니다. 공간(스페이스)마다 맥락을 완전히 분리하는 것이었죠. 그런데 설계 중반에 결정 라운드를 거치면서 문제가 보였습니다. “오염”은 공간을 넘어서 생기는 게 아니라 관련 없는 내용이 끼어들어서 생기는 거였어요. 그러면 공간을 벽으로 나누는 게 아니라 관련도로 걸러내는 게 맞습니다.

그래서 AD-6는 “공간 격리 → 관련도 기반 컨텍스트”로 전환됐습니다.

여기서 중요한 건 이 전환이 코딩 중에 발견된 게 아니라는 점입니다. 만약 명세 없이 코딩부터 시작했다면 공간 격리 가정이 코드 여러 곳에 박혔을 거예요. 서비스 레이어, 쿼리 로직, API 설계 전반에. ADR에 결정이 기록되어 있었기 때문에 방향 전환이 문서 한 곳에서 반영되고 깔끔하게 처리됐습니다.

AD-12: 구현 중 발견된 브레이킹 체인지

두 번째 사례는 구현 단계에서 나왔습니다.

B2(영속성 베이스) 작업을 시작했을 때 설치된 MikroORM이 v7이었습니다. 그런데 v7은 기존 데코레이터 API(@Entity, @PrimaryKey, @Property)를 완전히 제거하고 defineEntity 빌더 방식으로 일원화한 버전이었어요. AD-10(영속성 결정)에서 데코레이터 기반 Data Mapper를 전제했으니 충돌이었습니다.

이때 ADR이 있었기 때문에 처리가 달랐습니다. AD-12를 신설하고 “이후 모든 엔티티 슬라이스는 defineEntity 패턴을 따른다”고 기록했습니다. 한 줄의 결정이 이후 모든 작업의 기준이 됐습니다.

ADR이 없었으면 B3, B6 등 각 슬라이스에서 하나씩 발견하면서 수정했을 거예요. 발견할 때마다 “어, 이거 왜 이렇게 됐지?” 하며 처음부터 다시 파악하는 시간이 반복됐을 겁니다.

왜 “결정이 앞에 있으면 생성은 직진”인가

빌드플랜 @docs/guide/build-plan.md B2 진행하자 — 이게 실제로 쓰는 패턴입니다. 결정이 문서에 담겨있으면 줄 하나로 맥락 전달이 끝납니다. AI 에이전트가 설계 의도를 이미 알고 있으니 자의 판단 없이 일관되게 생성합니다.

반대로 결정이 없으면 에이전트는 그때그때 자기 판단으로 채웁니다. 슬라이스마다 다른 판단이 들어가면서 일관성이 깨지고, 나중에 하나씩 뜯어야 합니다.

스킬 자체도 명세→검증→개선 사이클을 거쳤다

product-pipeline 스킬이 처음부터 완성형이었던 건 아닙니다. 마이위키 설계 실전에서 직접 쓰면서 6패치가 나왔습니다. “이 결정 항목은 필요하다”, “잠정 결정을 처리하는 방법이 없다”, “미결 항목은 별도 섹션으로 분리해야 한다” 같은 것들이 부딪히면서 나왔어요.

스킬 자체가 명세→검증→개선 사이클을 거쳤다는 게 포인트입니다. 결정 카탈로그가 한 프로젝트씩 쌓이면 다음 프로젝트는 “수락 위주”로 빠르게 통과할 수 있습니다. 처음부터 발견하는 비용이 점점 줄어드는 거예요.

다음 앱을 시작할 때 코딩을 열기 전에 AD-1부터 물어보세요. “이 앱 데이터 어디 저장할 거야?” 10분이면 설계 방향이 잡힙니다. 그 10분이 나중에 “다 뜯어야 해”를 막습니다.

<- 이전 편: 빌드플랜 스킬로 개발 시간 단축하기 · 다음 편 ->: 스킬의 비밀: 자연어가 로직이 되는 순간 배경: 마이위키 탄생 스토리 · 함께 보기: Claude Code 4레버 방법론