본문으로 건너뛰기
SpecifyDocs

활용 가이드

페르소나로 따라 하는 아키텍처 설계

기술 리드 지민의 맘마(육아 앱) 사례로 현재 구조 파악, 대안 비교, 목표 설계, 결정 문서와 MCP 구현까지 따라 합니다.

코딩 에이전트와 개발하는 기술 리드가 현재 구조를 파악하고, 다음 기능의 목표 구조를 설계해 구현으로 연결하는 예제입니다. 맘마(육아 앱)의 기록 저장 흐름을 출발점으로 따라 해 보세요.

페르소나와 목표

지민은 개발자 3명으로 구성된 팀의 기술 리드입니다. 팀은 코딩 에이전트와 함께 육아 기록 서비스를 개발합니다. 지민은 연결 상태가 달라져도 사용자가 기록 작성과 저장 결과 확인을 이어갈 수 있도록 다음 구조를 설계하려고 합니다.

항목이번 설계에서 정할 것
사용자 경험작성 중인 기록, 저장 진행, 완료 상태를 어떻게 보여 줄지
구조기존 화면·저장 경로에서 재사용할 부분과 추가할 책임
품질 기준재시도, 중복 저장, 앱을 다시 열었을 때의 확인 방법
결과물현재 구조 캔버스, 목표 구조 캔버스, 설계 결정 문서, 구현·테스트 체크리스트
지민과 추가 요구사항은 활용 흐름을 설명하는 가상 시나리오입니다. 이 가이드의 화면은 실제 맘마 코드를 읽어 생성한 문서·캔버스입니다. 목표 설계는 현재 구현과 구분해 관리합니다.

준비할 자료

  • GitHub 연결에서 접근 가능한 저장소와 기준 브랜치
  • 현재 기능 설명과 사용자가 겪는 상황을 적은 요구사항
  • 유지할 API, 데이터 구조, 권한, 배포·운영 조건
  • 완료를 판단할 사용자 시나리오와 테스트 기준

지민은 “기록 작성 → 저장 요청 → 결과 확인”이라는 한 흐름부터 시작합니다. 이 범위를 정하면 AI가 읽을 코드와 사람이 판단할 질문을 함께 좁힐 수 있습니다.

현재 구조를 한 장으로 정리하기

채팅에서 저장소와 관련 문서를 지정하고, 현재 호출 흐름과 책임을 설명하는 문서·캔버스를 요청합니다.

맘마 저장소의 기록 작성과 저장 흐름을 읽어 줘.
화면, 상태 관리, 저장 명령, 데이터 접근 계층의 호출 관계를
현재 구조 캔버스로 만들고 주요 설명에 소스 경로를 남겨 줘.
코드로 확인한 내용과 추가 확인할 질문을 구분해 줘.
현재 구현 설명을 별도 문서로 저장해 줘.
맘마 코드에서 생성한 현재 아키텍처 캔버스
기존 구조를 먼저 공유하면 새 책임을 어느 계층에 둘지 함께 판단하기 쉽습니다.

지민은 각 화살표를 코드 근거와 대조합니다. 특히 저장을 시작하는 곳, 결과를 화면에 전달하는 곳, 사용자와 데이터의 접근 범위를 확인합니다.

캔버스 하단에서 에이전트와 설계 다듬기

현재 구조 캔버스를 열고 하단의 **캔버스에 명령하기…**에 변경을 입력합니다. 지민은 구성요소를 계층별로 배치하고, 도형이나 연결선을 선택해 해당 부분의 역할과 개선안을 질문합니다. AI 패널을 닫아 설계도를 넓게 보면서 같은 대화를 이어갈 수 있습니다.

캔버스 하단에서 맘마 구조의 개선을 요청하는 화면
그림을 보면서 변경 대상과 유지할 조건을 함께 전달합니다.
선택한 부분의 책임과 연결 방향을 설명해 줘.
현재 구조는 유지하고, 저장 재시도 책임을 둘 위치를 대안으로 제안해 줘.
목표 구조는 별도 캔버스로 만들어 줘.

직접 그리기, 선택 영역 명령과 저장 확인은 아키텍처 다이어그램과 캔버스에서 따라 할 수 있습니다.

대안을 비교하고 목표 구조 그리기

현재 구조와 목표 구조를 별도 캔버스로 관리합니다. 예를 들어 지민은 기존 저장 경로를 활용하는 재시도 방식과 별도 저장 대기열을 두는 방식을 비교하도록 요청합니다. 두 방식은 이번 요구사항을 위한 설계 후보입니다.

현재 구조와 기록 저장 요구사항을 바탕으로 두 설계 대안을 비교해 줘.
A는 기존 저장 경로를 활용하고, B는 별도 저장 대기열을 둡니다.
변경할 모듈, 기록 식별자, 저장 순서, 중복 처리, 권한,
사용자에게 보여 줄 상태와 테스트 범위를 표로 정리해 줘.
각 대안의 전제와 검증할 질문을 남기고 목표 구조 초안을 그려 줘.
현재 구조 캔버스는 유지하고 새 목표 구조 캔버스로 저장해 줘.
비교 기준리뷰할 질문
책임의 위치저장 상태와 재시도를 어느 계층이 관리하는가?
데이터 일관성같은 기록이 다시 전송될 때 어떤 식별자와 처리 규칙을 쓰는가?
사용자 경험저장 진행과 완료를 어떤 근거로 구분하는가?
접근 권한사용자·가족 등 기존 접근 범위를 어떻게 유지하는가?
구현과 운영추가 저장소, 배포, 관찰 지표와 테스트가 얼마나 필요한가?

리뷰 결과를 설계 결정 문서로 남기기

지민이 대안을 선택하면 채팅에서 결정 이유와 변경 범위를 문서로 정리합니다. 문서에는 선택한 안, 비교한 대안, 유지할 인터페이스, 데이터 흐름, 수락 조건, 검증할 질문을 담습니다.

맘마 문서를 읽고 기록 흐름과 리뷰 항목을 정리한 채팅
사람이 검토할 질문을 좁히고 합의한 내용을 설계 문서로 이어갑니다.

예를 들어 “같은 기록을 다시 저장해도 하나의 기록으로 확인된다”, “앱을 다시 열면 저장 상태를 확인할 수 있다”를 수락 조건으로 적습니다. 팀이 합의한 조건에 맞춰 성공·재시도·권한·재접속 시나리오를 테스트 목록으로 만듭니다.

코딩 에이전트가 설계를 읽고 구현하기

Specify MCP를 연결한 코딩 에이전트에 설계 결정 문서와 목표 캔버스를 읽도록 요청합니다. 사용 중인 MCP 도구가 제공하는 문서·캔버스 읽기 기능으로 같은 맥락을 확인할 수 있습니다.

Specify MCP에서 맘마 기록 저장 설계 결정 문서와 목표 캔버스를 읽어 줘.
현재 코드와 대조해 변경할 모듈과 구현 순서를 정리해 줘.
수락 조건에 맞춰 구현하고 성공, 재시도, 권한, 재접속을 테스트해 줘.
추가 결정이 필요한 정책은 질문으로 모아 줘.

다음 변경에서 설계와 구현 맞추기

구현 뒤 현재 상태를 나타내는 문서·캔버스에 저장소를 각각 연결합니다. 해당 브랜치의 push를 계기로 갱신된 결과와 편집 기록을 확인하세요. 목표 설계 문서는 합의 기준으로 유지하고, 현재 상태 자료와 비교하며 수락 조건을 점검합니다.

자세한 설정은 저장소 연결 관리, 결과 검토는 자동 갱신 결과 확인을 참고하세요.

완료 체크리스트

  • 현재 구조와 목표 구조의 역할이 구분되어 있습니다.
  • 새 책임, 기존 인터페이스와 데이터 흐름을 설명할 수 있습니다.
  • 선택 이유와 수락 조건이 설계 결정 문서에 남아 있습니다.
  • 코딩 에이전트가 같은 문서를 읽고 구현·테스트 결과를 남겼습니다.
  • 변경 뒤 현재 구조와 실제 코드가 맞는지 사람이 확인했습니다.