4. 아키텍처 설계

이 단계에서 하는 것: 솔루션 아키텍트 서브에이전트를 설정하고, 데이터·API·기능 구현의 기준이 될 기술 구조를 docs/아키텍처.md에 정리한다. 사용할 기술, 코드의 계층 구조, 인증·접근 제어 전략, 역할별 책임을 정한다. 다음 단계로 넘길 것: 아키텍처 설계서와 설계에 맞춰 구성해 실행할 수 있는 기본 앱. DBA는 이를 바탕으로 데이터 모델을 설계하고, 아키텍트는 이후 API 명세서를 작성한다.

PRD와 화면기획서로 무엇을 만들고 화면에 어떻게 보여줄지 정했다. 코드를 작성하기 전에는 어떤 기술을 사용하고 코드를 어떻게 구성할지도 정해야 한다. 이 기준이 없으면 데이터·API·화면을 담당하는 역할이 서로 다른 구조를 가정할 수 있다. 이번 단계에서는 솔루션 아키텍트 서브에이전트에게 기술 구조 설계를 맡긴다.

기술 스택은 회사 표준을 기본으로 한다(Next.js·Supabase·Vercel 등). 기존 기술을 쓰면 담당자가 바뀌어도 유지보수하기 쉽고, 회사의 배포·모니터링 환경도 활용할 수 있다. 다른 기술이 필요하다면 이유를 기록하고 승인을 받는다. 기술 선택과 근거를 남긴 기록을 ADR이라고 한다.

아키텍트는 회사 표준 중 이 프로젝트에 사용할 기술을 정하고, 선택 이유와 계층별 책임을 문서에 기록한다. DBA는 그 결정을 바탕으로 DB를 구축한다. 담당 역할을 구분하면 이후 작업에서 기술 선택을 반복해서 논의하지 않아도 된다.

[상황이 다르면] SI·외주 프로젝트에서는 발주처가 기술 스택을 지정할 수 있다. 스타트업의 첫 제품이라면 아키텍트가 처음부터 선택해야 할 수도 있다. 어느 경우든 기술 선택과 그 근거, 팀이 따라야 할 구현 원칙을 기록하는 일은 필요하다.

회사 표준은 사용할 수 있는 기술의 범위를 정한다. 예를 들어 AWS를 표준으로 삼는 조직은 사용을 승인한 서비스 목록도 정할 수 있다. 그 안에서 캐시(ElastiCache)가 필요한지, DB로 Aurora와 DynamoDB 중 무엇이 적합한지는 아키텍트가 응답 속도·처리량·비용 등의 요구사항을 바탕으로 판단한다. 노드 유형·샤드 수·TTL 같은 세부 설정은 인프라와 백엔드 담당자가 정한다. 처음에는 필요한 최소 구성으로 시작하고, 캐시나 큐가 필요해지면 근거를 기록한 뒤 추가한다.

준비 확인

앞에서 docs/PRD.md와 docs/화면기획서.md가 만들어져 있다.
docs/가이드/에 회사 표준 문서(프로젝트구조·코딩컨벤션·디자인시스템·깃커밋컨벤션)가 있다.

따라하기

단계 1 — [정의] 솔루션 아키텍트 서브에이전트 만들기

먼저 서브에이전트의 책임과 작업 범위만 정의한다. 실제 설계 작업은 다음 단계에서 요청한다.

'솔루션 아키텍트' 서브에이전트를 만들어줘. 기술 아키텍처를 결정하고 문서화하며, 그 문서에 따라 기본 프로젝트 구조(스캐폴딩)까지 만든다. 회사 표준에 따른 기술 선택, 계층 구조, 인증·접근 제어 전략, 폴더 구조, 계층별 책임과 비기능 요건(NFR)을 맡는다. 이후 API 명세서(경로·요청·응답·상태 코드)도 관리한다. API 명세서는 docs/templates/API-Spec-템플릿.md 양식을 따르고, 템플릿의 절과 열을 더하거나 빼지 않는다. docs/PRD.md와 docs/가이드/프로젝트구조.pdf를 기준으로 삼는다. 라이브러리는 최신 공식 문서를 확인하고 필요한 의존성을 추가한다. 기능 코드·DB 스키마·API는 구현하지 않는다.

이렇게 나오면 성공: .claude/agents/에 아키텍트 서브에이전트가 생기고, "결정·문서화와 빈 뼈대까지 맡되, 기능 코드·스키마·API 구현은 하지 않는다"는 범위가 잡힌다. 파일을 열어 API 명세 템플릿 경로가 들어 있는지 본다 — 뒤 단계에서 명세 모양을 같게 만드는 한 줄이다.

서브에이전트를 만들었으니 Claude Code를 한 번 다시 띄운다(/exit 뒤 claude). 다시 띄우지 않으면 다음 단계에서 범용 에이전트가 조용히 대신 일한다.

단계 2 — [실행] 아키텍처 설계서 쓰기

설정한 서브에이전트에게 기술 구조를 문서로 정리하도록 요청한다.

솔루션 아키텍트 서브에이전트로, 이 프로젝트의 기술 아키텍처를 docs/아키텍처.md로 정리해줘. 스택은 회의록과 docs/가이드 문서가 정한 대로 쓰고, 이 프로젝트에 실제로 필요한 것만 채택해 각 결정에 이유를 한 줄씩 남겨줘.AI 모델은 gemini-3.8-flash를 쓴다.인증 흐름·화면 주소·폴더 구조 같은 나머지 기술 결정은 네가 정하고 이유를 적어. PRD와 CLAUDE.md에 있는 것은 다시 묻지 마. 요금·리전·계약 같은 운영 질문은 적지 않는다. 질문 목록은 비워줘.

이 줄들이 있는 이유: 스택은 회의록(Supabase·토스페이먼츠)과 가이드 문서(Next.js·TypeScript·Tailwind·Vercel)가 이미 정했으니 다시 적지 않고 가리킨다. 사람이 새로 주는 것은 AI 모델 이름 하나다 — 회사 계정으로 쓸 수 있는 모델은 어느 문서에도 없다. 인증 흐름·화면 주소·폴더 구조는 아키텍트가 정하고 이유를 남긴다. 사람은 다음 단계에서 그 결정을 읽고 틀린 것만 고친다. "질문 목록은 비워줘"가 없으면 설계서 끝에 질문이 열 개 넘게 남는다. PRD와 CLAUDE.md에 이미 있는 것(AI 10초 제한, 가격, 집계와 판정은 서버가)은 여기 다시 적지 않는다 — 같은 말을 두 곳에 두면 한쪽이 틀어진다. 아키텍트가 그걸 물어 오면 "PRD에 있다, 그대로"라고 문서를 가리킨다.

서브에이전트가 공식 문서를 읽으러 가면 웹 조회 승인 창이 여러 번 뜬다. 라이브러리 버전을 확인하는 정상 동작이니 승인한다.

기술 스택은 어디에 있나: 조직에 따라 기술 표준을 기술 레이더나 개발 템플릿으로 관리하기도 하고, 팀에서 합의해 쓰기도 한다. 이 실습에서는 회의록(Supabase·토스페이먼츠)과 docs/가이드/의 문서(Next.js·TypeScript·Tailwind·Vercel)에 흩어져 있다. 그래서 프롬프트는 스택을 다시 적지 않고 "회의록과 가이드 문서가 정한 대로"라고 가리킨다.

이렇게 나오면 성공: docs/아키텍처.md에 기술 선택과 이유, 계층 구조, 인증·접근 제어 전략, 계층별 책임이 정리된다. 인증 절에 가입·로그인을 어디서 처리하고 세션을 어떻게 유지하는지, 데이터 접근은 어느 경로로만 하는지가 이유와 함께 적혀 있다. 화면 주소도 화면마다 정해져 있다. 질문 목록은 비어 있다. 이 단계에서는 아직 코드나 SQL을 작성하지 않는다.

단계 3 — [사람 검증] 설계서를 눈으로 확인

AI가 작성을 마치면 문서를 직접 열어 다음 역할들이 이 문서를 기준으로 작업할 수 있을 만큼 구체적인지 확인한다.

docs/아키텍처.md를 열어, 스택마다 "왜 쓰는지" 한 줄이 붙어 있는지 본다(그냥 나열이 아니라 채택 근거).
계층 구조(api→service→repository→supabase)와 각 계층 책임이 적혀 있는지, "판정은 서버" 원칙이 드러나는지 본다.
접근 제어 전략이 구체적인지 본다 — "남의 데이터는 못 본다"를 무엇으로, 어느 계층에서 강제하는지. 다음 단계의 DBA가 이걸 그대로 구현한다.
아키텍트가 스스로 정한 것(인증 흐름, 화면 주소, 폴더 구조)을 읽는다. 동의하지 않는 것만 고유명사로 고친다 — 예: "로그인 엔드포인트를 우리 API에 두지 말고 Supabase Auth를 화면이 직접 부르게 바꿔줘". 전부 뜯어고치면 설계를 사람이 하는 셈이다.

이렇게 나오면 성공: 한 문서에서 기술 선택, 계층별 책임, 인증·접근 제어 방법을 확인할 수 있다.

단계 4 — [실행] 설계서대로 프로젝트 초기 셋업

설계 문서에 적은 구조가 실제로 구성 가능한지도 확인한다. 문서에 따라 기본 프로젝트를 만들고 실행해 본다.

솔루션 아키텍트 서브에이전트로, docs/아키텍처.md에 정한 대로 이 프로젝트 초기 셋업을 해줘.디자인시스템의 색·간격 토큰도 프로젝트 설정에 등록해줘.docs/아키텍처.md는 개발 리더가 승인했다. 기능 코드는 아직 만들지 말고 빈 뼈대까지만. 빌드가 통과하는지까지 확인해줘.라이브러리 버전이 서로 맞지 않으면 한 단계 낮은 안정 버전으로 내리고, 그 이유를 docs/아키텍처.md에 적어줘.Supabase 접속 정보는 뒤 단계에서 넣는다. 환경변수가 아직 없어도 뼈대 화면은 오류 없이 떠야 한다.

뼈대가 만들어지면 서버를 띄우게 하고 브라우저로 확인한다.

서버 실행해서 url 알려줘. 내가 확인해볼게

개발 서버란? 내 컴퓨터에서 앱을 실행해 브라우저로 확인할 수 있게 하는 서버다. 끄기 전까지 계속 돌아간다. AI가 백그라운드로 띄우고 주소(보통 http://localhost:3000)를 알려 준다. 포트가 이미 쓰이고 있으면 다른 포트로 띄우거나 무엇이 쓰고 있는지 알려 온다 — 다른 프로그램을 끄겠다고 하면 거절하고 다른 포트를 쓰게 한다.

AI가 알려 준 주소를 브라우저에서 연다.

이렇게 나오면 성공: 브라우저에 뼈대 화면이 뜬다 — Next.js 기본 환영 화면일 수도 있고, AI가 자리 표시로 만든 로그인 화면으로 바로 넘어갈 수도 있다. 어느 쪽이든 오류 없이 화면이 나오면 된다. 폴더 구조가 docs/아키텍처.md의 계층 구조와 일치한다. 디자인 시스템 토큰은 Tailwind 설정에 등록되어 있다 — Tailwind 4는 설정 파일 대신 app/globals.css의 @theme 블록에 등록되므로 거기서 primary-600, income-600, space-4를 찾는다. 서버를 끌 때는 "개발 서버 꺼줘"라고 한다.

단계 5 — [실행] 커밋

1장에서 저장소를 만든 뒤 작성한 PRD·화면기획서·프로토타입·아키텍처 문서와 기본 앱을 커밋한다.

지금까지 만든 문서들과 앱 뼈대를 깃커밋컨벤션에 맞춰 main 브랜치에 커밋하고 푸시해줘.

이렇게 나오면 성공: GitHub 저장소에 docs/PRD.md·docs/화면기획서.md·docs/아키텍처.md와 앱 뼈대가 모두 올라간다. .env*와 node_modules는 빠진 채로다(앞에서 .gitignore로 막아 뒀다).

이 단계 마무리

솔루션 아키텍트 서브에이전트가 docs/아키텍처.md에 기술 선택·계층 구조·인증과 접근 제어 전략을 정리했다. 이 문서를 바탕으로 기본 앱을 만들고 http://localhost:3000에서 실행했다.
아키텍트는 기술을 결정하고 DBA는 DB를 구축한다. 다음 단계에서 DBA는 아키텍처 문서를 기준으로 데이터 모델과 스키마를 설계한다.
막히면: 설치 중 "버전이 맞지 않는다"(예: TypeScript 최신판을 ESLint 플러그인이 아직 지원하지 않는다)가 나오면, 한 단계 낮은 안정 버전으로 내리고 이유를 설계서에 적게 한다 — 프롬프트에 이미 그 허락이 있다. 문서가 스택을 나열만 하고 이유가 없으면 "각 선택에 채택 이유를 한 줄씩(ADR) 붙여줘"라고 다시 요청한다. 접근 제어 전략이 두루뭉술하면 "남의 데이터 접근을 무엇으로 어느 계층에서 막는지, 동작별로 구체적으로 적어줘"라고 한다.

다음 단계에서는 DBA 서브에이전트에게 데이터 모델(ERD) 설계와 실제 DB 구축을 맡긴다.