Search
청약 서비스 기획부터 디자인 시스템까지 - 집보다 개발기 1편
개요
회사에서 AI 활용법을 공부하고 실무에 적용해 온 경험을 바탕으로, 웹과 앱(iOS·Android) 서비스를 혼자 만들고 있습니다. 청약 공고를 한곳에서 찾고, 공고 속 도면을 3D로 둘러볼 수 있는 주거 서비스 "집보다"입니다.
집보다 개발기는 총 3편으로 연재합니다. 기획부터 디자인, 개발까지의 과정과 시행착오를 그대로 정리해, 자신의 서비스를 만들고 싶은 분들이 참고할 수 있도록 작성했습니다. 1편에서는 서비스를 기획한 과정과, 디자이너 없이 AI로 디자인과 디자인 시스템을 만든 방법을 다룹니다.
이 글을 읽고 나면 다음을 할 수 있습니다. - 서비스 주제를 고를 때 도메인 지식을 기준으로 삼는다. - 디자이너 없이 AI로 와이어프레임과 디자인 시안을 만든다. - 웹과 앱이 함께 쓰는 디자인 시스템을 패키지로 구성한다.
왜 도메인 지식에서 시작했나
AI 덕분에 이제는 누구나 서비스를 만들 수 있습니다. 그만큼 "어떻게 만들까"보다 "무엇을 만들까"가 더 중요해졌습니다. 그래서 서비스를 구상할 때 가장 먼저 고려한 것은 기술이 아니라 도메인 지식이었습니다.
도메인 지식이 중요한 이유 AI는 코드를 빠르게 작성하지만, 사용자가 어디서 불편을 느끼는지는 알려 주지 않습니다. 무엇을 만들지 정하는 기준은 결국 그 분야를 직접 겪어 본 사람의 경험에서 나옵니다.
제가 가장 관심이 많고 잘 아는 분야는 "집"이었습니다. 본가가 재개발을 겪는 과정을 가까이에서 지켜봤고, 지금은 전세금을 돌려받지 못하고 있는 상황이라 자연스럽게 청약에 관심을 갖게 되었습니다. 평소 부동산 시장을 꾸준히 지켜봐 온 것도 도움이 되었습니다. 세 가지 경험이 모두 주거로 이어졌기 때문에, 서비스의 주제도 주거로 정했습니다.
문제 정의: 청약 정보는 왜 찾기 어려울까
공공 청약 공고는 LH(한국토지주택공사), SH(서울주택도시공사), IH(인천도시공사), GH(경기주택도시공사)처럼 기관마다 각자의 사이트에서 제공됩니다. 부동산 앱에서는 지도에서 매물을 찾고 사진과 평면도로 집을 비교하는 경험이 익숙하지만, 청약 공고를 그렇게 편리하게 볼 수 있는 서비스는 찾기 어려웠습니다.
- 공고가 기관별 사이트에 흩어져 있어 한곳에서 비교하기 어렵다. - 공고문과 도면이 PDF 중심이라 필요한 정보를 찾으려면 문서를 직접 읽어야 한다. - 도면만으로는 실제 집의 크기와 구조를 떠올리기 어렵다.
아이디어: 도면을 읽는 대신 걸어 보게
여기에 회사 경험이 더해졌습니다. 회사에서 R&D로 진행한 프로젝트 중에 모델러분들의 작업을 바탕으로 구축한 WebGL 서비스가 있었습니다. 그 경험을 떠올리며 이런 생각을 했습니다. "공고만 보여 주는 대신, 공고의 도면을 AI의 도움을 받아 3D 모델로 만들고, 그 집 안을 1인칭으로 걸어 다닐 수 있게 하면 어떨까?"
워크스루(Walkthrough)란? 사용자가 1인칭 시점으로 3D 공간 안을 직접 걸어 다니며 둘러보는 기능입니다. 도면에서 본 집을 실제로 걷는 것처럼 경험할 수 있어, 평면도를 읽는 데 익숙하지 않은 사람도 집의 구조를 쉽게 이해할 수 있습니다.
실제로 구현한 1인칭 집구경 화면은 아래 "지금까지 만든 웹"에서 확인할 수 있고, 이 아이디어를 기능으로 만든 과정은 2편에서 자세히 다룹니다.
서비스 구성 정하기
코드를 작성하기 전에 요구사항정의서, 화면설계서, API 및 인터페이스 정의서를 먼저 만들었습니다. 이 문서들은 이후 AI에게 작업을 맡길 때 기준이 되는 자료가 되었습니다. 그다음 서비스를 저장소 단위로 나눴습니다.
- zipboda-web: 사용자용 웹 (Next.js) - zipboda-admin: 청약 공고와 콘텐츠를 관리하는 관리자 웹 (Next.js) - zipboda-app: iOS·Android 앱 (Expo, React Native) - zipboda-api: 백엔드 API (설계 단계) - zipboda-design-system: 세 서비스가 함께 쓰는 디자인 시스템
기획한 주요 기능은 청약 공고 통합 검색과 마감 알림, 청약 가점 계산, 3D 평면도와 1인칭 집구경, 가구 쇼핑, 커뮤니티입니다. 현재는 웹을 중심으로 개발하고 있고, 관리자와 앱은 기본 구성만 갖춘 상태입니다.
가장 부족했던 것, 디자인
기획, 백엔드, 프론트엔드는 실무에서 경험해 본 영역이었지만, 저에게 가장 부족한 것은 디자인이었습니다. 처음에는 Claude나 Codex에게 화면 디자인을 바로 요청해 봤습니다. 결과는 기능은 갖췄지만 투박하고, 한눈에 "AI가 만든 것 같은" UI였습니다.
돌아보면 화면의 구조와 시각적인 스타일을 한 번에 맡긴 것이 원인이었습니다. 그래서 디자인을 단계별로 나누고, 각 단계에 맞는 도구를 사용했습니다.
1. Claude와 Figma MCP로 와이어프레임 잡기
먼저 화면설계서를 바탕으로 Claude가 Figma MCP를 통해 Figma에 와이어프레임을 직접 그리게 했습니다. 프로젝트에는 Figma 데이터를 읽는 MCP와 Figma에 직접 그리는 MCP를 함께 연결해 두었습니다. 이 단계에서는 화면에 무엇이 어디에 들어가는지만 정합니다.
1// 와이어프레임 요청 예시 2 3"화면설계서의 '청약 목록' 화면을 Figma에 와이어프레임으로 그려 줘. 4- 1280px 데스크톱 기준 5- 구성: 상단 내비게이션, 검색과 필터, 공고 카드 목록, 지도 영역 6- 회색 박스와 기본 텍스트만 사용하고 색상, 아이콘, 그림자는 넣지 마."
와이어프레임 단계에서는 색과 스타일을 넣지 않습니다. 구조와 스타일을 함께 다루면 다시 "AI가 만든 것 같은" 화면으로 돌아갑니다.
2. Figma Make에 톤앤매너만 전달하기
와이어프레임으로 구조가 정해지면 Figma의 AI 디자인 도구인 Figma Make로 시각 디자인을 만들었습니다. 이때 구조는 다시 설명하지 않고, 서비스가 주어야 할 분위기인 톤앤매너만 전달했습니다.
AI 시대 프론트엔드 개발자의 일과 전망 - 검증, 토큰, 프로덕트 엔지니어
개요
올해 1월 새로운 회사에 합류한 이후, 업무에서 Claude와 Codex를 매일 사용하고 있습니다. 지난 글에서 두 서비스의 모델별 차이를 정리했다면, 이번 글에서는 모델이 아니라 그 모델과 함께 일하는 개발자의 이야기를 다룹니다.
AI 모델의 성능이 빠르게 올라가면서 프론트엔드 개발자의 업무도 크게 달라졌습니다. 코드를 직접 작성하는 시간은 줄었고, AI에게 무엇을 어떻게 맡길지, 그 결과물을 어떻게 신뢰할 수 있을지 고민하는 시간이 늘었습니다. 이 글에서는 그 과정에서 계속 붙잡고 있던 세 가지 질문을 정리합니다.
이 글에서 다루는 질문은 다음과 같습니다. - 바이브 코딩으로 만든 결과물은 어떻게 검증해야 할까? - 토큰 사용량을 줄이는 것이 왜 개발자의 역량이 되었을까? - 개발자가 아니어도 개발할 수 있는 시대에 개발자는 어디로 가야 할까?
이제 코드는 AI와 함께 작성한다
현재 업무에서 작성하는 코드의 상당 부분은 AI와 함께 만들고 있습니다. 그러다 보니 코드를 얼마나 빠르게 작성하느냐보다, AI가 프로젝트의 기준을 지키며 일하도록 만드는 것이 훨씬 중요해졌습니다.
규칙과 스킬이란? 규칙은 CLAUDE.md, AGENTS.md 같은 파일에 프로젝트가 지켜야 할 코드 컨벤션과 원칙을 정리해 두고, AI가 작업할 때마다 읽고 따르게 하는 방식입니다. 스킬은 커밋 작성, 코드 리뷰처럼 반복되는 작업의 절차를 문서로 묶어 두고 필요할 때만 불러 쓰는 방식입니다.
저는 가독성, 예측 가능성, 응집도, 결합도 네 가지 기준으로 정리한 프론트엔드 코드 규칙을 전역 규칙 파일에 두고 사용합니다. 토스의 Frontend Fundamentals에서 제시하는 좋은 코드의 네 가지 기준이기도 합니다. 매직 넘버 대신 이름 있는 상수를 쓰고, 중첩 삼항 연산자를 쓰지 않으며, 함수 이름에 드러나지 않는 부수효과를 숨기지 않는 식입니다. 커밋 메시지와 브랜치 이름 규칙도 정해 두고 AI가 그대로 따르게 합니다.
규칙을 세우고, 스킬을 활용하고, 프롬프트를 다듬어 토큰 사용량을 줄이는 일. 예전에는 요령 정도로 여겼던 이 일들이 이제는 개발자의 분명한 강점이 될 것이라고 생각합니다.
가장 큰 고민, 바이브 코딩의 결과물은 어떻게 검증할까
AI로 개발하면서 가장 오래 붙잡고 있던 질문은 "검증은 어떻게 할 것인가?"였습니다.
올해 초에 작성한 바이브 코딩 글에서 저는 "생성된 코드를 반드시 읽어요"라고 적었습니다. 그런데 AI가 만들어 내는 코드의 양이 사람이 읽을 수 있는 속도를 넘어서면서, 이 원칙 하나만으로는 감당하기 어려워졌습니다. 모든 줄을 읽으면 AI를 쓰는 의미가 줄어들고, 읽지 않으면 불안했습니다.
토스 모닥불에서 얻은 힌트
이 고민에 방향을 잡아 준 것은 토스 프론트엔드 챕터의 기술 토크인 "모닥불"이었습니다. 이를 통해 토스 프론트엔드 개발자들이 AI를 실제로 어떻게 활용하는지 알 수 있었습니다.
가장 크게 와닿은 것은 목표를 바라보는 관점이었습니다. 프로젝트를 진행하고 서비스를 만들 때 무엇보다 우선되는 것은 기간 안에 개발을 완료하고, 고객이 아무 문제 없이 서비스를 사용하는 것입니다.
검증의 기준이 바뀌었다 주어진 규칙 안에서라면 코드를 어떻게 작성했는지보다 서비스가 완전히 잘 작동하는지가 더 중요합니다. 코드 한 줄 한 줄이 아니라, 고객이 경험하는 "서비스의 동작"을 검증하는 방향입니다.
토스에서는 구현이 끝나면 테스트도 AI를 통해 진행한다고 합니다. 코드 리뷰, QA, E2E 테스트를 AI에게 맡기고, 특히 단순한 기능 테스트도 E2E 방식으로 진행한다는 점이 인상적이었습니다. 또한 E2E 문서를 별도로 만들어 테스트를 진행하고, AI가 수행하는 테스트와 사람이 직접 수행하는 테스트를 병합해 검증합니다.
단순한 기능도 E2E로 테스트하는 이유
단위 테스트는 함수의 입력과 출력을 확인하지만, 고객은 함수가 아니라 화면을 사용합니다. E2E 테스트는 실제 사용자처럼 화면을 열고, 클릭하고, 결과를 확인하기 때문에 "고객이 문제없이 사용한다"는 목표를 가장 직접적으로 검증합니다.
AI와 함께 개발할 때는 장점이 하나 더 있습니다. AI는 같은 기능이라도 요청할 때마다 내부 구현을 조금씩 다르게 작성합니다. 구현 방식에 의존하는 테스트는 그때마다 깨지지만, 동작을 확인하는 E2E 테스트는 내부 구현이 바뀌어도 그대로 유효합니다.
E2E 문서 작성 예시
E2E 문서에는 사전 조건, 사용자 시나리오, 그리고 각 시나리오를 누가 검증할지를 정리합니다. 최근 작업한 앱 간 테마 공유 기능을 예로 들면 다음과 같습니다.
1// E2E 시나리오 문서 예시 - 앱 간 테마 공유 2 3[사전 조건] 4- 테마 쿠키 없음, OS 설정은 다크 모드 5 6[시나리오] 71. 홈에 처음 접속하면 화면이 그려지기 전에 다크 테마가 적용된다 82. 포트폴리오에서 라이트로 바꾸면 블로그와 이력서에서도 라이트로 보인다 93. 새로고침해도 라이트 테마가 유지된다 10 11[검증 담당] 12- AI: 1~3번을 Playwright로 자동 실행하고 결과를 보고 13- 사람: 실제 휴대폰 브라우저에서 2~3번을 직접 확인
AI는 정해진 시나리오를 빠르고 반복적으로 확인하는 데 강하고, 사람은 실제 기기에서의 체감이나 문서에 없던 어색한 동작을 찾아내는 데 강합니다. 두 테스트를 병합하는 이유가 여기에 있습니다.
AI가 작성한 테스트를 같은 AI가 통과시키는 구조만으로는 부족합니다. 무엇을 검증할지 정하는 E2E 문서는 사람이 작성하거나 반드시 검토하고, AI는 그 시나리오를 실행하고 보고하는 역할로 나누는 것이 안전합니다.
Claude와 Codex 모델별 차이 정리 - Opus 5.5부터 GPT-6 Astra까지
개요
Claude Code와 Codex로 개발하다 보면 매일 같은 질문을 마주합니다. "이 작업은 어떤 모델로 돌려야 하지?" 두 서비스 모두 최상위 모델부터 가볍고 빠른 모델까지 여러 등급을 제공하고, 같은 모델 안에서도 추론 강도를 조절할 수 있어서 선택지가 생각보다 많습니다. 이 글에서는 2026년 10월 공식 문서를 기준으로 두 서비스의 모델 라인업을 정리하고, 작업 종류별로 모델을 고르는 기준을 세워봅니다.
이 글을 읽고 나면 다음을 할 수 있습니다. - Claude와 Codex의 모델 등급과 각 모델의 용도를 구분한다. - 성능·비용·속도를 기준으로 작업에 맞는 모델을 고른다. - 추론 강도(effort)를 조절해 같은 모델로 비용과 품질의 균형을 맞춘다.
이름만 보고 고르면 생기는 일
모델을 고를 때 흔히 쓰는 방법은 세 가지입니다.
- 무조건 최상위 모델: 가장 똑똑한 모델을 쓰면 결과도 가장 좋을 것이라고 생각하는 방식입니다.
- 무조건 기본값: 도구가 정해준 모델을 그대로 쓰는 방식입니다.
- 가장 싼 모델: 비용을 줄이려고 경량 모델부터 쓰는 방식입니다.
세 방법 모두 절반만 맞습니다. 최상위 모델은 단순 작업에서 느리고 비싸며, 경량 모델은 어려운 작업에서 재시도가 늘어 오히려 총비용이 커질 수 있습니다. 또 같은 모델이라도 추론 강도에 따라 결과와 비용이 크게 달라집니다. 모델 이름보다 "작업에 맞는 등급과 추론 강도"를 고르는 것이 핵심입니다.
모델을 고르는 세 가지 기준
1. 성능 등급
성능 등급이란? 두 서비스 모두 모델을 "최상위 / 주력 / 경량" 단계로 나눠 제공합니다. 최상위 모델은 가장 어려운 추론과 오래 걸리는 에이전트 작업을, 주력 모델은 일상 개발을, 경량 모델은 요약·분류처럼 빠르고 많이 처리해야 하는 작업을 맡습니다.
2. 추론 강도(effort)
추론 강도(effort)란? 같은 모델이라도 답하기 전에 얼마나 깊이 생각할지를 정하는 설정입니다. 두 서비스 모두 low부터 max까지 단계를 제공하며, 높일수록 정확도는 올라가지만 응답 시간과 토큰 사용량도 늘어납니다.
추론 강도는 모델마다 기본값이 다르다는 점을 꼭 기억해야 합니다. 예를 들어 Claude Opus 5.5의 기본값은 medium이라, 어려운 작업에서는 high 이상으로 직접 올려 주는 것이 좋습니다.
3. 비용과 속도
가격을 읽는 법 가격은 "100만 토큰당 입력 / 출력" 단위로 표기합니다. 이번에 비교하는 일곱 모델은 모두 출력 가격이 입력 가격의 5배입니다. 응답이 긴 작업일수록 출력 가격이 총비용을 좌우합니다.
Claude 모델 라인업
Anthropic은 공식 문서에서 "어떤 모델을 써야 할지 모르겠다면 Claude Opus 5.5부터 시작하고, 더 높은 추론 강도에서도 부족하면 Claude Fable 5.1을 쓰라"고 안내합니다. 네 모델 모두 컨텍스트 1M 토큰, 최대 출력 128K 토큰을 지원합니다.
Claude Fable 5.1
가장 어려운 추론과 장시간 에이전트 작업용 최상위 모델 사고(thinking)가 항상 켜져 있고 기본 추론 강도는 high입니다. 가격은 입력 $10 / 출력 $50으로 가장 비싸고, 응답도 가장 느린 편입니다.
여러 단계를 스스로 판단해야 하는 긴 에이전트 작업이나, Opus 5.5로 추론 강도를 올려도 풀리지 않는 문제에 꺼내 쓰는 모델입니다. 모든 작업의 기본값으로 두기보다는 "마지막 카드"로 쓰는 편이 비용 면에서 유리합니다.
Claude Opus 5.5
장시간 에이전트 코딩과 지식 작업을 위한 기본 추천 모델 입력 $4 / 출력 $20으로 Fable 5.1보다 훨씬 저렴하면서 사고가 항상 켜져 있습니다. 기본 추론 강도는 medium입니다.
Fast 모드를 켜면 같은 Opus 5.5 모델로 출력 속도를 최대 2.5배까지 높일 수 있습니다. 더 작은 모델로 바꾸는 것이 아니라 같은 모델을 빠르게 돌리는 방식이라 품질은 그대로이고, 가격은 입력 $8 / 출력 $40으로 두 배가 됩니다.
Claude Sonnet 5.5
속도와 지능의 균형을 맞춘 주력 모델 입력 $2 / 출력 $10에 기본 추론 강도는 high입니다. 일상적인 코딩, 에이전트 작업, 업무 자동화를 빠르게 처리합니다.
기능 구현, 테스트 작성, 코드 수정처럼 하루에 수십 번 반복하는 작업에 잘 맞습니다.
Claude Haiku 5.5
대량·저지연 작업을 위한 경량 모델 입력 $0.10 / 출력 $0.50부터 시작하는 가장 저렴한 모델로, 응답도 가장 빠릅니다. 기본 추론 강도는 medium입니다.
분류, 추출, 라우팅처럼 짧고 많은 요청을 처리할 때 씁니다. 표시 가격은 프롬프트 10만 토큰 이하 기준이며, 이를 넘으면 입력 $0.50 / 출력 $2.50이 적용됩니다.
Codex 모델 라인업
OpenAI는 2026년 9월 GPT-6 Astra를 공개하며 Codex의 모델 구성을 GPT-6 계열로 바꿨습니다. 세 모델 모두 컨텍스트 1.05M 토큰, 최대 출력 128K 토큰을 지원합니다.
GPT-6 Astra
코드·앱·리서치 전반의 가장 까다로운 작업용 최상위 모델 입력 $10 / 출력 $50으로 Claude Fable 5.1과 같은 가격대입니다. 추론 강도는 low부터 max까지 고를 수 있습니다.
Codex의 가장 강력한 모델입니다. 다만 공식 문서가 GPT-6.1 Sol을 "Astra에 가까운 성능을 더 낮은 비용으로" 내는 모델로 소개하고 있어, 반복되는 복잡한 작업은 Sol로 처리하고 Astra는 Sol로 부족할 때 꺼내는 편이 경제적입니다.
최신 AI 프롬프트 기법 5가지와 실전 프로젝트 적용법
개요
AI 모델은 빠르게 진화하고 있지만, 기존 프롬프트 방식만으로는 최신 모델의 잠재력을 충분히 끌어내기 어렵습니다. 이 글에서는 최신 AI 프롬프트 기법 5가지를 소개하고, 각 기법을 실제 프로젝트의 설계부터 구현 단계까지 적용하는 방법을 다룹니다.
이 글을 읽고 나면 다음을 할 수 있습니다. - 5가지 프롬프트 기법의 원리와 효과를 이해한다. - 프로젝트 단계별로 적합한 기법을 선택하여 적용한다. - AI를 단순 질의응답 도구가 아닌 협업 파트너로 활용하는 프로세스를 구축한다.
GPT-4 시절의 기본기, 이제는 부족하다
최신 모델을 사용하기 전에, 기존 방식이 왜 부족한지 짚어보겠습니다. 다음 세 가지는 GPT-4 시절에 효과적이었던 기법입니다.
- 역할 부여: "10년 차 마케터"처럼 특정 역할을 부여하여 답변의 톤과 전문성을 잡는 방식입니다.
- 예시 주기: 원하는 결과물의 샘플을 제공하여 AI가 패턴을 파악하고 일관된 출력을 생성하도록 유도합니다.
- 생각의 사슬(Chain of Thought): 단계별로 사고하도록 유도하여 논리적 정확도를 높이는 기법입니다. 과거 연구에서 논리 정확도가 6점에서 9점으로 상승했습니다.
최신 AI 모델은 이러한 기본 능력을 이미 내장하고 있습니다. 역할을 부여하지 않아도 맥락에 맞는 전문적 답변을 생성하고, 별도 지시 없이도 단계별 추론을 수행합니다. 이 방법들만으로는 AI의 잠재력을 완전히 끌어낼 수 없습니다.
5가지 최신 프롬프트 기법
1. 생각의 트리(Tree of Thought)
생각의 트리(Tree of Thought)란? 기존 생각의 사슬이 하나의 경로를 따라 순차적으로 사고했다면, 생각의 트리는 여러 전략을 동시에 탐색하고 스스로 평가하여 최적의 판단을 내리게 하는 기법입니다. AI가 단순 계산을 넘어 전략적 선택을 수행합니다.
AI에게 여러 옵션을 제시하고, 각 옵션의 장단점과 예상 비용을 평가하게 합니다. 비합리적인 옵션은 가지치기하고, 최종적으로 하나의 안과 그 선택 이유를 보고하도록 구성합니다.
프롬프트 예시:
1// 생각의 트리 프롬프트 구조 2 3"우리 서비스의 인증 시스템을 개선하려고 해. 4다음 세 가지 전략을 각각 분석해 줘. 5 6전략 A: JWT 기반 토큰 인증 7전략 B: 세션 기반 인증 + Redis 8전략 C: OAuth 2.0 위임 인증 9 10각 전략에 대해 다음을 평가해 줘. 111. 구현 복잡도 122. 보안 수준 133. 확장성 144. 예상 개발 기간 15 16가장 비합리적인 전략 하나를 제거하고, 17남은 두 전략을 비교한 뒤 18최종 추천안과 선택 이유를 보고해 줘."
프린스턴 대학교 연구에서 복잡한 수학 퍼즐 "Game of 24"의 해결률이 기존 방식 4%에서 생각의 트리 적용 시 74%로 상승했습니다.
2. 자기 성찰(Self-Reflection)
자기 성찰(Self-Reflection)이란? AI가 생성한 결과물을 스스로 검토하고 비판하며 개선하도록 만드는 기법입니다. AI는 기본적으로 비판적 사고 능력을 가지고 있지만, 명시적으로 요청해야 이 능력을 발휘합니다.
프롬프트 예시:
1// 자기 성찰 프롬프트 구조 2 3"네가 방금 작성한 API 설계를 검토해 줘. 4 51단계: 비평가의 시선으로 다시 읽어봐. 62단계: 다음 관점에서 약점을 지적해 줘. 7 - 논리적으로 부족한 부분 2가지 8 - 실제 운영에서 문제가 될 부분 2가지 9 - 보안상 취약한 부분이 있다면 지적 103단계: 지적한 내용을 반영하여 11 개선된 최종 버전을 새로 작성해 줘."
MIT 연구에 따르면, 복잡한 코딩 문제에서 초기 정확도 80%였던 AI가 자기 성찰 루프를 적용하자 최종 정확도 91%까지 향상되었습니다.
3. 메타 프롬프트(Meta-Prompting)
Markdown 설계서와 AI 코딩으로 풀스택 기능을 하루 만에 구현한 방법
들어가며
최근 회사 프로젝트에서 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};