아이디어에서 빌드플랜까지 — AI로 앱 설계 문서 8종 자동화한 방법

마이위키 설계에서 검증된 product-pipeline 파이프라인 공개

마이위키 설계를 시작하던 날, 저는 하루 종일 AI와 씨름했습니다. 저장소 어디에 둘지, LLM 컨텍스트를 어떻게 전달할지, 공간 격리는 어떻게 구현할지 — 결정 항목 하나하나를 맨바닥에서 발견하면서요. 세션이 끝날 때 돌아보니 “요구사항 → 설계 4종 → 스택 결정(AD-1~11) → 코딩 규칙 → 자동화 시나리오”까지 한 바퀴를 돌긴 했는데, 시간이 너무 많이 걸렸습니다.

그때 깨달았어요. 느렸던 이유는 결정 항목 자체를 그때그때 발견했기 때문이라는 걸.

문제 정의: 설계가 느린 진짜 이유

앱을 설계할 때 AI가 도와주기는 해도, 보통 이런 흐름이 됩니다. “어떤 DB를 쓸까요?” 물어보면 옵션을 나열해주고, 그걸 고르면 또 다음 질문이 나오고. 결정 항목을 탐색하는 데 대부분의 시간이 쓰입니다. 같은 종류의 앱을 두 번 만들어도 같은 결정을 다시 처음부터 하게 됩니다.

반면 이 파이프라인의 아이디어는 단순합니다. 오늘 발견한 결정 항목 + 각 항목의 추천 기본값을 스킬에 박아두면, 다음 앱은 “추천대로 수락 + 앱 고유 부분만 수정”이 됩니다. 결정 발견 비용이 0이 되는 거죠.

접근법: product-pipeline 스킬

[[docs-init-스킬-문서-골격-최소화|/docs-init]]으로 문서 골격을 깔고, /product-pipeline으로 내용을 채웁니다. 이 둘은 다른 층입니다.

• docs-init: 아무 프로젝트나 — 문서 골격(index/todo/log + 타입폴더) 깔기
• product-pipeline: 제품 앱만 — 그 안에 설계 문서 내용 채우기

파이프라인의 입력은 두 가지입니다. 요구사항 문서 + 프로토타입(없으면 아이디어 메모). 산출물은 8종입니다.

1. 기능 명세
2. 아키텍처 결정(ADR)
3. 시스템 다이어그램
4. 도메인 모델
5. API 계약
6. 앱 아키텍처
7. CLAUDE.md 코딩 규칙
8. Build-plan (줄기→가지→통합→검증)

각 단계: 어떻게 작동하나

0~2단계: 입력 준비

docs-init으로 골격을 먼저 깔고, 요구사항 문서를 임포트합니다. 프로토타입이 있으면 함께 넣습니다. 엔티티 초안은 requirement에서, 화면 구조는 프로토타입에서 자동 추출됩니다.

3~6단계: 결정 라운드

사람이 개입하는 핵심 구간입니다. 에이전트가 각 결정 항목을 객관식 + 추천 프리필로 제시하면, 대부분은 “수락”으로 넘어갑니다. 결정 카탈로그(AD-1~11)는 마이위키 설계에서 만들어진 표준 의사결정 항목들입니다.

실제 마이위키 설계에서 인상적인 순간이 있었는데요. AD-6 결정 라운드였습니다. 처음엔 “공간 격리” — 공간마다 맥락을 완전히 분리한다는 아이디어로 시작했는데, AI가 설계를 도와주다가 더 나은 방향을 제안했습니다. “공간이 아니라 관련도 기반으로 맥락을 스코프하면 어떨까요? 관련 있으면 공간을 넘어 가져오고, 관련 없으면 같은 공간이어도 안 가져오는 거죠.” 저는 그 자리에서 방향을 바꿨습니다. 설계 중반에 AI가 저보다 더 나은 아이디어를 꺼낸 순간이었어요.

이처럼 결정 라운드는 단순히 선택하는 자리가 아니라, AI와 실제로 설계를 함께 만드는 구간입니다.

무거운 단계(명세 추출·엔티티/엔드포인트 설계)는 워크플로우 팬아웃으로 병렬 처리합니다.

7~9단계: 산출물 확인 + 빌드플랜

결정이 끝나면 설계 문서 8종이 생성됩니다. 빌드플랜은 구현 직전까지의 작업을 “한 세션에 독립 실행 가능한 단위”로 쪼개줍니다. 이후 코딩은 플랜 항목 하나씩, 단일 세션으로 진행하면 됩니다.

왜 작동하는가

핵심은 결정 카탈로그입니다. AD-1~11은 저장 방식·LLM 분리·맥락 스코프·ORM·인증·결제 등 웹 앱 설계에서 반복되는 의사결정 항목들입니다. 추천값은 Slowloop 기본 스택(자가호스팅·Next.js·Postgres+pgvector)으로 내장돼 있습니다.

다음 앱을 만들 때 이 결정들을 처음부터 다시 발견할 필요가 없습니다. 추천대로 수락하거나 앱 고유 부분만 갈아끼우면 됩니다. 마이위키 설계에서 6패치 + docs-init 3패치를 거치며 실전 검증된 카탈로그입니다.

결정은 항상 ADR로 남습니다. “기록 안 하면 증발한다”는 걸 컨텍스트 컴팩션을 겪으면서 직접 배웠거든요. 다음 단계도, 다음 앱도 이 결정 위에서 시작합니다.

실전 적용 방법

다음에 앱을 만들 때 요구사항이 정리됐으면, 결정 라운드를 AD-1부터 하나씩 통과해보세요. 대부분은 “추천대로 수락”으로 빠르게 넘어갑니다. 설계 문서가 없는 채로 코딩을 시작하는 것보다 훨씬 빠릅니다 — 코딩 중간에 구조를 바꾸는 비용이 훨씬 크니까요.

빌드플랜-스킬로-개발시간-단축에서 이 파이프라인의 산출물인 빌드플랜을 어떻게 실제 개발에 연결했는지 이어서 볼 수 있습니다.

배경: 마이위키가 왜 만들어졌나 · 세컨드브레인 설계 결정 심화: 빌드플랜 스킬 실전 적용 · product-pipeline 스킬 상세 함께 보기: Claude Code 4레버 방법론