들어가며

최근 회사 프로젝트에서 IoT 데이터 시각화 기능을 개발했어요. Docker 인프라 설정부터 백엔드 API, 프론트엔드 UI까지 풀스택으로 진행해야 하는 작업이었죠. Markdown 설계서를 먼저 작성하고 AI를 활용해 구현했더니 하루 만에 기능 전체를 완성할 수 있었어요.

Markdown 설계서가 곧 프롬프트

AI에게 "시각화 페이지 만들어줘"라고 말하면 결과물이 들쭉날쭉해요. AI가 프로젝트의 맥락을 모르기 때문이죠. 하지만 구조화된 Markdown 설계서를 작성해두면 결과가 안정돼요.

- 설계서 기반 AI 개발이란?
AI에게 막연한 요청을 하는 대신 Markdown으로 작성한 설계서를 전달하여 구현을 요청하는 방식이에요. 설계서가 곧 AI에 대한 상세한 지시서 역할을 하죠.

두 방식의 차이를 보면 명확해요.

- 일반적인 프롬프트: "데이터 시각화 페이지 만들어줘" → AI가 임의로 해석, 의도와 다른 결과
- 설계서 기반 프롬프트: "설계서의 Phase 4를 구현해줘" → 정의된 컴포넌트, API, 데이터 구조 그대로 구현

같은 AI라도 입력의 품질에 따라 출력이 달라져요.

설계서에는 무엇을 담아야 할까

저는 아래 항목들을 기준으로 설계서를 작성했어요.

1. 용어 정의: 프로젝트에서 사용하는 도메인 용어를 명확히 정의
2. 현재 상태 분석: 기존 코드 구조, 아직 구현되지 않은 항목 정리
3. 목표 아키텍처: 시스템 전체 구조를 ASCII 다이어그램으로 표현
4. UI 와이어프레임: ASCII 기반 화면 레이아웃
5. API 명세: 엔드포인트, 요청/응답 형식 정의
6. 컴포넌트 설계: 필요한 컴포넌트 목록과 각각의 props 구조
7. 수정/생성 파일 목록: Phase별로 건드려야 할 파일 경로
8. 검증 계획: 구현 후 확인해야 할 항목

각 항목이 AI에게 주는 효과가 달라요. 용어 정의가 있으면 변수명과 주석을 일관되게 작성해요. 현재 상태 분석이 있으면 기존 코드와 충돌 없이 작업하고, 파일 목록이 있으면 어떤 파일을 건드려야 하는지 명확히 인지하죠.

ASCII 와이어프레임이 핵심

Figma나 이미지 기반 와이어프레임은 AI가 직접 읽을 수 없어요. 반면 ASCII로 그린 레이아웃은 AI가 그대로 해석할 수 있죠.

예를 들어 서비스 간 연결 구조를 이렇게 표현했어요.

이 다이어그램 하나로 AI는 노드 간 연결 관계를 정확히 파악하고, 컴포넌트 구조와 데이터 바인딩까지 설계 의도대로 구현해요.

설계서 기반 AI 개발 워크플로우

Step 1. Markdown 설계서 작성

프로젝트 저장소 안에 파일로 설계서를 작성해요. 이번 프로젝트에서는 약 800줄 분량의 설계서를 작성했죠. 핵심은 구현 로드맵을 Phase 단위로 나누는 거예요.

- Phase 1: 인프라 — Docker 서비스 설정, 환경 구성
- Phase 2: 백엔드 — API 엔드포인트, 모델, URL 라우팅
- Phase 3: 프론트엔드 훅 — 데이터 페칭, 상태 관리 훅
- Phase 4: 프론트엔드 UI — 메인 페이지 컴포넌트
- Phase 5: 프론트엔드 UI — 상세 뷰 컴포넌트

전체를 한 번에 요청하면 AI의 컨텍스트 한계에 부딪혀요. Phase를 나누면 한 번에 4~6개 파일씩 집중해서 작업할 수 있고 이전 Phase의 결과물을 다음 Phase에서 참조할 수 있어요.

Step 2. Phase 단위로 AI에게 구현 요청

설계서가 완성되면 AI에게 "설계서의 Phase N을 구현해줘"라고 요청해요. AI가 설계서에서 해당 Phase의 파일 목록, 컴포넌트 구조, API 스펙을 참조하여 구현하죠.

인프라 → 백엔드 → 프론트엔드 순서를 지키는 게 중요해요. 백엔드 API가 없는 상태에서 프론트엔드 훅을 만들면 엔드포인트가 어긋나거든요. 설계서에 순서를 정해두면 이런 실수를 방지할 수 있어요.

Step 3. 빌드 검증 및 보정

각 Phase 구현 후 빌드 오류가 없는지 확인하고 브라우저에서 동작을 검증해요.

AI가 생성한 코드가 문법적으로 정확하더라도 실제 빌드 환경에서 타입 에러나 import 경로 문제가 발생할 수 있어요. 매 Phase마다 빌드 검증은 필수예요.

이번 프로젝트에서도 다이어그램의 연결선이 flex 레이아웃 특성상 한쪽으로 몰려 보이는 문제가 있었어요. 브라우저에서 확인하고 AI에게 상황을 전달하니 원인을 파악하고 SVG 기반 구조로 수정안을 제시했죠.

코드상으로는 올바르더라도 UI 렌더링 결과가 의도와 다를 수 있어요. 시각적 결과는 반드시 눈으로 확인해야 해요.

설계서를 잘 쓰기 위한 실전 팁

모호한 설계서는 모호한 결과물을 만들어요. 실전에서 특히 중요했던 세 가지를 공유할게요.

첫 번째, API 엔드포인트와 응답 형식을 반드시 명시해요. 프론트엔드와 백엔드 간의 계약이 모호하면 양쪽 코드가 어긋나요.

1// 설계서에 이렇게 API 명세를 작성해두면
2// GET /api/v1/services/status
3// Response: { services: [{ name: string, status: "running" | "stopped", metrics: {...} }] }
4
5// AI가 프론트엔드 훅과 백엔드 뷰를 동시에 일관되게 생성해요
6const useServiceStatus = () => {
7  return useQuery({
8    queryKey: ['serviceStatus'],
9    queryFn: () => fetch('/api/v1/services/status').then(res => res.json()),
10  });
11};

두 번째, 기존 코드와의 연결점을 명시해요. "어떤 훅을 재사용하고 어떤 모델을 확장하는지"를 적어두면 AI가 기존 코드와 충돌 없이 작업해요.

세 번째, 파일 경로를 정확히 적어요. 경로를 명시하면 AI가 정확한 위치에 파일을 생성하고 수정해요. 구현 완료 후 "설계서 대비 누락된 파일이 있는지" 검토를 요청할 수도 있죠.

Markdown 설계서가 효과적인 이유

1. 사람과 AI 모두 읽을 수 있어요: Figma나 Notion 설계서는 AI가 직접 읽을 수 없지만 Markdown 파일은 프로젝트 레포지토리 안에 함께 존재하고 AI가 그대로 해석할 수 있어요.
2. ASCII 와이어프레임은 구현 지시서가 돼요: 단순해 보이지만 컴포넌트 구조와 데이터 바인딩을 명확히 전달하죠.
3. Phase 분리가 컨텍스트 관리를 해결해요: 한 번에 전체를 맡기지 않고 단계별로 나누면 AI가 집중해서 작업할 수 있어요.
4. 파일 목록 테이블이 누락을 방지해요: 전체 파일 목록을 작성해두면 AI가 구현 후 누락 여부를 스스로 검증해요.

마지막으로

이 방식의 핵심은 "설계에 시간을 투자할수록 구현 시간이 줄어든다"는 거예요. 잘 작성된 Markdown 설계서 한 장이 수십 번의 프롬프트 수정을 대체해요.

AI가 코드를 생성해주는 시대에 개발자의 가치는 "코드를 얼마나 빠르게 치느냐"가 아니라 "얼마나 명확하게 설계하느냐"에 있어요. 설계서를 작성하는 시간이 아깝게 느껴질 수 있지만, 그 시간이 전체 개발 시간을 줄여주고 결과물의 품질도 높여줘요.

AI와 협업할 때 가장 강력한 도구는 화려한 프롬프트 기법이 아니라 잘 정리된 설계서 한 장이에요.