안드로이드 앱 바이브 코딩 3단계: AI 에이전트로 로드맵 실제 구현하기

안드로이드 앱 바이브 코딩의 3단계는 준비한 계획을 AI에게 보여 주고 실제 앱 만들기를 시작하는 과정입니다. 앞 단계에서 만든 mvp.txt와 ROADMAP.md를 AI가 읽게 한 뒤, 작은 기능부터 하나씩 만들고 직접 실행해 확인합니다. 이 글에서는 /goal로 긴 작업을 맡기는 방법, 작업을 작은 단계로 나누는 방법, AI가 “완료했다”고 보고했을 때 우리가 꼭 확인할 내용을 초보자 눈높이에서 설명합니다.

이 글은 이제 막 바이브 코딩을 시작한 분을 대상으로 합니다. Kotlin이나 Jetpack Compose를 자세히 몰라도 괜찮습니다. Android Studio에서 프로젝트가 열리고 AI 개발 도구가 프로젝트 파일을 읽을 수 있으면 시작할 수 있습니다. 어려운 내부 구조를 모두 이해하는 것보다 “무엇을 만들기로 했는지”, “앱이 실제로 실행되는지”, “버튼을 눌렀을 때 약속한 일이 되는지”를 확인하는 습관이 더 중요합니다.

계획과 현재 프로젝트가 얼마나 다른지 먼저 확인한다

ROADMAP.md에는 앞으로 만들 기능이 적혀 있고, 프로젝트 폴더에는 지금까지 만들어진 파일이 들어 있습니다. 두 내용이 정확히 같다고 가정하면 안 됩니다. 계획에는 로그인 화면이 있다고 적혀 있지만 실제 버튼은 동작하지 않을 수 있고, 반대로 AI가 앞 작업에서 미리 만든 파일이 있을 수도 있습니다. 그래서 새 코드를 만들기 전에 AI에게 계획 문서와 현재 프로젝트를 함께 비교하게 합니다.

여기서 중요한 것은 파일 이름이 아니라 실제 동작입니다. 설정 화면 파일이 있어도 저장 버튼을 눌렀을 때 값이 남지 않으면 완료가 아닙니다. 목록 화면이 보여도 새 항목을 추가하거나 삭제할 수 없다면 일부만 만들어진 상태입니다. AI에게 각 기능을 “완료”, “일부만 구현”, “아직 없음”, “직접 실행해야 확인 가능”으로 나누게 하면 지금 어디서 시작해야 하는지 쉽게 알 수 있습니다.

/goal
프로젝트 루트의 mvp.txt와 ROADMAP.md를 처음부터 끝까지 읽고,
현재 저장소 구현과 로드맵의 차이를 정밀 분석해 주세요.

각 요구사항을 완료, 부분 구현, 미구현, 확인 불가로 분류하고
근거 파일과 테스트, 실제 실행 경로를 함께 제시하세요.
화면 파일이나 인터페이스의 존재만으로 완료라고 판단하지 마세요.

마일스톤 의존 관계, 컴파일 위험, 데이터 마이그레이션,
권한·보안·개인정보 위험, UI·UX 누락, 테스트 공백을 식별하세요.
분석 중에는 코드를 변경하지 말고 먼저 구현 순서와 검증 명령을 보고하세요.

분석 결과는 요구사항별 표로 받는 것이 좋습니다. 열에는 로드맵 항목, 현재 상태, 코드 근거, 빠진 동작, 선행 작업, 위험도, 완료 조건, 검증 명령을 둡니다. 확인 불가는 미구현과 분리합니다. 에뮬레이터나 API 키가 없어 검증하지 못한 기능을 실패로 단정할 필요는 없지만 완료로 올려서도 안 됩니다. 이렇게 만든 표가 에이전트와 개발자가 공유하는 실제 작업 대장이 됩니다.

여러 전문 도구는 확인할 일을 나눠 맡긴다

AI 도구에 Material 3, Compose Expert, Adaptive, Android Ninja 같은 전문 기능이 설치되어 있다면 활용할 수 있습니다. 다만 이름을 많이 나열하는 것보다 무엇을 확인할지 쉽게 나누는 편이 좋습니다. 한 도구에는 화면이 보기 쉽고 누르기 편한지, 다른 도구에는 휴대폰과 태블릿에서 화면이 잘 보이는지, 또 다른 도구에는 오류가 났을 때 다시 시도할 수 있는지를 확인하게 합니다. 설치되지 않은 기능을 사용했다고 가정하지 말고 먼저 사용 가능한 도구 목록을 확인합니다.

모든 도구에게 앱 전체를 다시 설계하라고 하면 서로 다른 제안이 쌓여 오히려 복잡해집니다. 먼저 계획에서 빠진 기능을 찾고, 그다음 화면 사용성을 살피고, 마지막으로 빌드와 실행을 확인하는 순서가 이해하기 쉽습니다. 발견한 문제는 긴 보고서로만 남기지 말고 ROADMAP.md의 해당 단계에 “무엇을 고칠지”와 “어떻게 확인할지”로 적습니다.

사용 가능한 Android 관련 스킬과 도구를 먼저 확인하세요.
설치되지 않은 스킬을 사용했다고 가정하지 마세요.

1. 로드맵 감사: 요구사항과 현재 구현의 갭, 의존 관계, 완료 조건
2. Compose 검토: 상태 호이스팅, 단방향 데이터 흐름, 재구성, 부수 효과
3. Material 3 검토: 표준 컴포넌트, 테마, 오류·로딩·빈 상태, 접근성
4. Adaptive 검토: 창 크기 클래스, 목록·상세, 회전, 폴더블, 멀티 윈도우
5. Android 품질 검토: 수명주기, 프로세스 재생성, 성능, 보안, 테스트

각 검토 결과를 중복 제거한 뒤 ROADMAP.md의 해당 마일스톤에
구현 작업, 완료 조건, 테스트로 반영하세요.
새 아키텍처나 라이브러리는 필요성과 비용을 설명한 경우에만 제안하세요.Code language: CSS (css)

예쁜 화면보다 실제로 사용할 수 있는지 확인한다

AI는 데이터가 가득 찬 예쁜 화면을 빠르게 만들 수 있습니다. 하지만 사용자가 처음 앱을 열었을 때 목록이 비어 있거나, 인터넷이 끊기거나, 권한을 거절하거나, 잘못된 값을 입력하는 상황도 확인해야 합니다. 빈 화면에는 다음에 할 일을 안내하고, 오류 화면에는 다시 시도할 방법을 보여 줍니다. 저장에 실패했는데 성공 메시지를 보여 주거나 입력한 내용을 모두 지우면 안 됩니다.

Material 3는 Android 앱에서 자주 쓰는 버튼, 입력창, 메뉴와 화면 모양을 모아 둔 기본 디자인 기준입니다. 특별한 이유가 없다면 AI에게 이 기본 부품을 우선 사용하게 합니다. 글자가 커져도 잘리지 않는지, 버튼이 너무 작지 않은지, 밝은 화면과 어두운 화면에서 글자가 잘 보이는지 확인합니다. 처음부터 독특한 버튼을 직접 만들게 하는 것보다 기본 부품을 사용하는 편이 실수도 적고 수정도 쉽습니다.

Adaptive UI는 화면 크기에 맞춰 배치를 바꾸는 방식입니다. 휴대폰에서는 목록과 상세 화면을 차례로 보여 주고, 태블릿처럼 넓은 화면에서는 두 화면을 나란히 보여 줄 수 있습니다. 초보자가 내부 원리를 모두 알 필요는 없습니다. AI에게 휴대폰 세로·가로, 태블릿, 화면 분할 상태에서 중요한 버튼과 글자가 잘리지 않는지 확인하게 하고 결과 화면을 직접 보면 됩니다.

• 최초 실행과 온보딩 완료 여부
• 빈 데이터와 첫 항목 생성 동선
• 전체 로딩, 부분 로딩, 새로고침 중 기존 데이터 유지
• 네트워크 단절, 인증 만료, 서버 오류와 재시도
• 권한 거부, 다시 묻지 않음, 시스템 설정 이동
• 화면 회전, 창 크기 변경, 폴더블 자세 변화
• 큰 글꼴, 고대비, TalkBack, 키보드와 스위치 접근
• IME가 입력 필드와 주요 버튼을 가리는지 여부
• 프로세스 재생성 후 선택·입력·작업 상태 복원

/goal로 긴 개발 작업을 맡기는 방법

/goal은 한두 번의 답변으로 끝나지 않는 긴 작업을 AI가 계속 이어 가게 할 때 사용합니다. 그렇다고 한 번 맡긴 뒤 결과를 전혀 확인하지 않아도 된다는 뜻은 아닙니다. AI가 계획을 작은 단계로 나누고, 한 단계가 끝날 때마다 앱을 만들고 시험하게 해야 합니다. 오류가 나오면 다음 기능으로 넘어가지 말고 먼저 고치도록 적습니다. 계정이나 API 키처럼 사용자가 제공해야 하는 정보가 없으면 가짜 값을 넣지 말고 멈춰서 알려 달라고 합니다.

전체 개발 착수 프롬프트

/goal
프로젝트 루트의 mvp.txt와 ROADMAP.md를 처음부터 끝까지 확인하고,
현재 로드맵에 정의된 기능을 구현해 주세요.

먼저 저장소의 현재 구현과 로드맵 사이의 갭을 분석하고,
기능별 상태와 근거 파일, 의존 관계, 완료 조건을 정리하세요.
마일스톤과 의존 관계를 준수하여 작업하고,
각 단계가 완료될 때마다 빌드, 테스트, 정적 분석을 실행해 주세요.
컴파일 오류나 테스트 실패를 다음 단계로 넘기지 마세요.

임시 구현, 빈 화면, 가짜 성공 처리, 하드코딩된 샘플 값,
미완성 TODO를 완료된 기능으로 간주하지 마세요.
오류·로딩·빈 상태와 복구 동작을 구현하고,
화면 회전, 창 크기 변경, 프로세스 재생성 후 상태를 검증하세요.

민감정보를 소스와 로그에 기록하지 말고 Deprecated API를 피하세요.
새 의존성이나 복잡한 구조는 도입 이유와 대안을 먼저 검토하세요.
구현이 완료된 항목은 증거와 함께 ROADMAP.md와 CHANGELOG.md에 반영하세요.
마지막에는 변경 파일, 실행한 명령, 테스트 결과, 남은 위험과 미완료 항목을 보고하세요.

이 프롬프트의 중요한 부분은 “완료”의 정의입니다. 에이전트가 체크박스를 바꾼 사실이 아니라 사용자 흐름이 연결되고 자동화된 검증이 통과했다는 증거가 필요합니다. CHANGELOG에는 파일을 만들었다는 내부 작업보다 사용자가 관찰할 수 있는 변경을 기록합니다. ROADMAP의 체크 표시는 관련 테스트와 확인 방법을 함께 남깁니다. 검증할 수 없는 항목은 “완료” 대신 “구현됨·기기 검증 필요”처럼 상태를 분리하면 다음 세션에서 놓치지 않습니다.

큰 프로젝트는 마일스톤 단위가 더 안정적이다

한 번의 명령으로 모든 기능이 완벽하게 구현될 것이라고 기대해서는 안 됩니다. 작업 범위가 커질수록 에이전트는 앞에서 내린 판단을 잊거나, 테스트 시간이 길다는 이유로 일부 검증을 생략하거나, 뒤 마일스톤을 위해 필요 이상의 추상화를 도입하기 쉽습니다. 특히 데이터 계층과 인증, 동기화, 결제처럼 실패 비용이 큰 기능은 작은 경계로 나누는 편이 좋습니다. 한 마일스톤을 구현하고 사람이 앱을 직접 조작해 본 뒤 다음 목표를 여는 방식이 수정 비용을 낮춥니다.

마일스톤 단위 개발 프롬프트

/goal
ROADMAP.md의 M1 범위만 구현해 주세요.
먼저 M1의 현재 구현 상태와 누락을 근거 파일 단위로 확인하세요.

범위를 벗어나는 기능은 구현하지 말고,
필요한 인터페이스와 확장 지점만 준비해 주세요.
미래 기능을 예상한 과도한 추상화와 사용하지 않는 의존성은 추가하지 마세요.

각 작업을 완료 조건과 연결하고 구현 후 빌드, 단위 테스트,
UI 테스트, 정적 분석을 실행해 결과를 보고해 주세요.
실패가 있으면 원인을 해결한 뒤 같은 검증을 다시 실행하세요.

실제 기기나 외부 서비스가 필요해 자동 검증할 수 없는 항목은
완료로 표시하지 말고 수동 검증 절차와 기대 결과를 남기세요.
완료된 M1 항목만 ROADMAP.md와 CHANGELOG.md에 반영하세요.

마일스톤 경계는 기능 수보다 사용자에게 보여 줄 수 있는 수직 흐름을 기준으로 잡습니다. 데이터베이스 테이블만 만드는 M1보다 “항목을 생성하고 앱을 다시 열어도 남아 있는 최소 흐름”이 검증하기 좋습니다. 다만 다음 마일스톤의 동기화 서버까지 미리 구현하지는 않습니다. 로컬 저장소 인터페이스처럼 확장에 필요한 경계는 만들되 아직 쓰지 않는 범용 프레임워크와 플러그인 시스템은 미룹니다. 지금의 요구를 단순하게 해결하는 코드가 다음 요구가 실제로 나타났을 때 바꾸기도 쉽습니다.

AI의 완료 보고는 앱을 직접 열어 확인한다

AI가 “모든 작업이 완료되었습니다”라고 말해도 앱을 직접 열어 봐야 합니다. 빌드가 성공했는지, 앱이 설치되는지, 만들기로 한 기능을 처음부터 끝까지 사용할 수 있는지 확인합니다. 테스트에 익숙하지 않다면 먼저 AI에게 실행한 명령과 성공·실패 결과를 짧은 표로 보여 달라고 하세요. 그다음 에뮬레이터나 실제 휴대폰에서 가장 중요한 기능을 직접 눌러 봅니다.

./gradlew assembleDebug
./gradlew testDebugUnitTest
./gradlew lintDebug
./gradlew connectedDebugAndroidTest

위 명령은 일반적인 예시이며 실제 멀티 모듈 프로젝트의 모듈명과 빌드 변형에 맞춰 조정해야 합니다. connectedDebugAndroidTest는 실행 가능한 에뮬레이터나 기기가 필요합니다. CI와 로컬 환경의 JDK, SDK, 환경변수가 다르면 한쪽의 성공만으로 충분하지 않습니다. 프로젝트 README나 기여 문서에 기준 JDK와 재현 명령을 기록하고, 가능하면 같은 명령을 CI에서도 실행합니다.

• 실제 빌드가 성공하고 설치 가능한 APK 또는 App Bundle이 생성되는가
• 앱이 시작되고 핵심 사용자 흐름을 끝까지 수행할 수 있는가
• 로드맵의 완료 조건을 테스트나 재현 절차로 증명했는가
• 화면만 존재하고 내부 저장·조회·동기화 기능은 비어 있지 않은가
• 하드코딩된 샘플 값, 임시 성공 응답, 테스트 전용 분기가 남아 있지 않은가
• 입력 오류, 네트워크 오류, 저장 실패와 복구 동작이 구현되어 있는가
• 화면 회전, 창 크기 변경, 백그라운드 복귀와 프로세스 재생성을 견디는가
• API 키, 토큰, 개인정보가 소스·로그·스크린샷에 노출되지 않는가
• Deprecated API와 경고를 무시한 억제 코드가 새로 늘지 않았는가
• 요구사항보다 불필요하게 복잡한 계층과 의존성이 도입되지 않았는가

화면만 있고 기능은 비어 있지 않은지 확인한다

가장 흔한 문제는 화면은 보이지만 실제 기능은 없는 경우입니다. 저장 버튼을 눌렀는데 성공 문구만 뜨고 앱을 다시 열면 내용이 사라질 수 있습니다. 목록에 보이는 값이 항상 같은 예시 데이터일 수도 있습니다. AI에게 TODO, 임시 데이터, 가짜 성공 응답, 고정된 사용자 정보가 남아 있는지 검색하게 하고, 저장한 뒤 앱을 완전히 닫았다가 다시 열어 내용이 남는지 직접 확인합니다.

오류 처리도 예외를 잡는 것만으로 완료되지 않습니다. 오류를 어떤 계층에서 어떤 의미로 변환하는지, 재시도해도 안전한지, 사용자의 작성 중 입력이 보존되는지 확인합니다. 취소 예외를 일반 오류처럼 삼키면 코루틴 취소가 깨질 수 있고, 모든 오류를 “인터넷을 확인하세요”로 바꾸면 인증 만료나 서버 검증 실패를 해결할 수 없습니다. 로그에는 원인 추적에 필요한 범주와 요청 식별자를 남기되 토큰, 이메일, 위치, 입력 본문 같은 민감정보를 기록하지 않습니다.

화면을 돌리거나 앱을 다시 열어도 작업이 남는지 본다

폼을 작성하다가 휴대폰을 가로로 돌렸을 때 입력 내용이 모두 사라지면 사용하기 불편합니다. 다른 앱을 잠시 사용하고 돌아왔을 때도 진행 중인 작업이 가능한 한 유지되어야 합니다. 초보자가 Android의 상태 저장 기술을 모두 이해할 필요는 없습니다. AI에게 “화면 회전, 화면 크기 변경, 앱을 백그라운드에 보낸 뒤 돌아오기, 앱을 완전히 다시 열기”를 각각 확인하게 하고 어떤 내용이 유지되어야 하는지 알려 주면 됩니다.

검증할 때는 개발자 옵션의 “활동 유지 안 함”만 의존하지 않습니다. 화면 회전과 다크 모드 전환, 백그라운드 이동, 프로세스 종료 후 복귀를 각각 재현합니다. 목록에서 항목을 선택한 상태, 폼을 절반 작성한 상태, 네트워크 요청 중인 상태처럼 경계가 드러나는 순간을 선택합니다. 복원할 수 없는 일회성 작업은 중복 실행되지 않아야 하며, 영속 데이터는 단일 진실 공급원에서 다시 읽어야 합니다. 이 검증을 ROADMAP의 완료 조건에 포함하면 기능을 만든 뒤 별도 안정화 기간에 몰아서 고치는 일을 줄일 수 있습니다.

로드맵과 변경 이력은 증거를 반영하되 과장하지 않는다

구현 후 ROADMAP.md를 고칠 때는 체크 표시만 추가하지 않습니다. 완료한 범위와 제외한 범위, 검증한 환경, 관련 테스트를 간단히 남깁니다. 자동 테스트는 통과했지만 실제 Google 로그인이나 결제 샌드박스를 확인하지 못했다면 그 사실을 기록합니다. CHANGELOG에는 아직 기본 브랜치나 릴리스에 들어가지 않은 내용을 출시된 기능처럼 쓰지 않습니다. 개발 브랜치에서 구현한 내용은 “개발 중” 또는 “다음 릴리스 예정”으로 구분합니다.

에이전트에게 문서를 자동 갱신하게 하면 코드와 문서의 일치도를 높일 수 있지만, 실패한 테스트를 삭제하거나 완료 조건을 낮춰 체크하도록 허용해서는 안 됩니다. 요구사항 변경이 필요하면 기존 조건을 몰래 바꾸지 말고 결정 기록을 남깁니다. 무엇을 포기했고 왜 포기했는지, 사용자 영향과 후속 계획은 무엇인지 기록해야 다음 작업자가 같은 논쟁을 반복하지 않습니다.

막혔을 때는 범위를 숨기지 말고 목표를 다시 자른다

장시간 목표가 멈추는 원인은 대개 코드 난이도 하나가 아닙니다. 제품 결정이 비어 있거나, 외부 API 계정과 테스트 자격증명이 없거나, 에뮬레이터에서 재현할 수 없는 기기 기능이 필요할 수 있습니다. 이때 에이전트가 임의의 키와 가짜 응답으로 작업을 끝내면 나중에 더 큰 비용이 생깁니다. 차단 원인, 이미 확인한 내용, 필요한 사용자 결정, 안전하게 계속할 수 있는 범위를 구분해 보고하게 합니다. 예를 들어 실제 결제 승인만 막혔다면 결제 공급자 인터페이스, 실패 상태 UI, 테스트 더블과 단위 테스트까지 진행하고 실제 연동은 미완료로 남길 수 있습니다.

반대로 하나의 마일스톤이 너무 크다면 목표를 데이터 계층, 핵심 사용자 흐름, 오류·복원, 접근성·Adaptive 검증으로 나눕니다. 분할할 때도 각 조각은 빌드 가능한 상태를 유지해야 합니다. 여러 세션이 같은 파일을 동시에 크게 바꾸지 않도록 작업 경계를 나누고, 각 세션 시작 시 저장소 상태와 이전 검증 결과를 다시 확인합니다. 오래 걸리는 작업에서 속도보다 중요한 것은 언제든 정상 상태로 돌아갈 수 있는 작은 체크포인트입니다.

실전 인수 절차: 보고서를 앱 동작으로 바꾸기

마일스톤이 끝났다는 보고를 받으면 깨끗한 환경에서 의존성을 받아 빌드하고 에뮬레이터 또는 실제 기기에 설치합니다. 첫 실행부터 핵심 작업 완료까지 화면을 따라가고, 네트워크를 끊거나 잘못된 값을 입력해 실패 흐름을 확인합니다. 화면을 회전하고 창 크기를 바꾸며 앱을 백그라운드로 보낸 뒤 돌아옵니다. Android Studio Logcat에서 크래시와 민감정보를 살피고, 테스트 보고서와 Lint 결과를 엽니다. 마지막으로 ROADMAP의 완료 조건을 한 줄씩 읽으며 각 조건에 대응하는 증거가 있는지 표시합니다.

1. 기준 브랜치와 작업 트리, 변경 파일 범위를 확인합니다.
2. 에이전트가 보고한 빌드·테스트·정적 분석 명령을 다시 실행합니다.
3. 앱을 설치해 핵심 사용자 흐름과 실패·복구 흐름을 직접 수행합니다.
4. 회전, 프로세스 재생성, 다양한 창 크기와 접근성 설정을 확인합니다.
5. 임시 코드, 샘플 데이터, 미완성 TODO, 민감정보와 경고를 검색합니다.
6. ROADMAP과 CHANGELOG가 실제 구현과 같은 상태를 말하는지 비교합니다.
7. 미완료와 확인 불가 항목을 다음 마일스톤 입력으로 남깁니다.

마무리: AI 개발의 단위는 프롬프트가 아니라 검증된 마일스톤이다

바이브 코딩 3단계에서 AI 에이전트는 많은 코드를 빠르게 작성하는 도구를 넘어 조사자, 구현자, 리뷰어, 테스트 실행자의 역할을 맡습니다. 그러나 제품 책임까지 넘길 수는 없습니다. 좋은 결과는 긴 프롬프트 한 번보다 정확한 로드맵, 현재 구현과의 갭 분석, 역할이 분명한 전문 검토, 작은 마일스톤, 반복 가능한 검증 명령에서 나옵니다. /goal은 이 긴 흐름을 유지하는 수단이며 완료 조건을 대신하지 않습니다.

실제 착수에서는 전체 개발 프롬프트로 저장소를 한 번에 이해시키되, 프로젝트가 크거나 위험한 기능이 포함되어 있다면 M1부터 범위를 잘라 진행해 보세요. 빌드가 깨진 상태를 넘기지 않고, 화면만 있는 기능을 완료로 세지 않고, 검증하지 못한 항목을 솔직하게 남기는 습관이 중요합니다. 다음 단계에서는 구현된 앱을 실제 사용자 관점에서 테스트하고, 출시 빌드와 서명, 개인정보 처리, Play Console 배포 준비로 연결할 수 있습니다.