안드로이드 앱 바이브 코딩 2단계: 프로젝트·원격 저장소·ROADMAP 준비하기

아이디어와 첫 버전 계획이 정리됐다면 다음 단계는 AI가 작업할 프로젝트 폴더를 준비하는 일입니다. 계획 문서를 파일로 저장하고, 작업 내용을 잃지 않도록 비공개 원격 저장소에 연결한 뒤, AI가 따라갈 쉬운 작업 목록을 만듭니다. 이 글에서는 폴더를 어떻게 나누고, 어떤 문서를 준비하며, 코딩을 시작하기 전에 무엇을 확인해야 하는지 차례대로 설명합니다.

앞 단계에서 만든 MVP 문서만 있으면 시작할 수 있습니다. 여기서 MVP는 사용자가 가장 중요한 기능을 써 볼 수 있는 첫 버전 계획입니다. 이번 단계가 끝나면 프로젝트 폴더, 작업 기록을 보관할 비공개 저장소, AI가 읽을 mvp.txt, 순서대로 할 일을 적은 ROADMAP.md가 준비됩니다. 아직 모든 기능을 만들 필요는 없습니다.

어려운 도구 이름보다 네 가지 결과만 기억한다

프로젝트 폴더는 앱과 관련된 파일을 모아 두는 작업 공간입니다. Git은 파일이 언제 어떻게 바뀌었는지 기록해 실수했을 때 이전 상태로 돌아가게 돕습니다. 원격 저장소는 Git 기록을 다른 서버에도 보관하는 비공개 공간입니다. ROADMAP.md는 AI가 앞으로 할 일을 순서대로 적은 체크리스트입니다. 이 네 가지를 준비하는 것이 이번 단계의 핵심입니다.

SSH, 브랜치, Compose BOM처럼 처음 보는 말이 나오더라도 모두 외울 필요는 없습니다. AI에게 명령을 실행하게 하고 우리는 저장소 연결이 되는지, 비밀 파일이 올라가지 않았는지, 작업 목록이 너무 크지 않은지만 확인하면 됩니다. 세부 기술은 실제로 문제가 생겼을 때 필요한 만큼 배워도 늦지 않습니다.

프로젝트 폴더와 원격 저장소 준비하기

AI 개발 도구는 현재 열어 둔 폴더 안에서 파일을 읽고 수정합니다. 따라서 다운로드 폴더처럼 여러 파일이 섞인 곳에서 시작하지 말고 앱마다 전용 폴더를 하나 만듭니다. 앱 코드와 계획 문서는 프로젝트 폴더에 두고, 키스토어처럼 공개되면 안 되는 파일은 프로젝트 밖의 별도 폴더에 둡니다. 이렇게 나누면 AI가 관련 없는 파일을 건드리거나 중요한 파일을 실수로 저장소에 올릴 가능성이 줄어듭니다.

workspace/
├── app-project/
│   └── mvp.txt
└── keystores/
    └── app-project-release.jks

app-project가 Git 저장소가 될 프로젝트 루트이고 mvp.txt에는 앞 단계에서 확정한 최종 요구사항을 저장합니다. keystores는 프로젝트 형제 디렉터리로 두어 단순한 git add .에도 포함되지 않도록 합니다. 실제 경로와 파일명은 운영 환경에 맞게 바꿀 수 있지만 “코드와 서명 키를 물리적으로 분리한다”는 원칙은 유지하는 편이 좋습니다. 키스토어 암호와 키 별칭도 소스 파일에 직접 적지 않고 별도 비밀 저장소나 안전한 환경 변수 주입 방식을 사용합니다.

MVP 문서와 로드맵, 키스토어를 분리한 Android 프로젝트 작업 공간 — 여러 코딩 에이전트는 같은 요구사항 문서를 읽고, 키스토어는 프로젝트와 분리된 안전한 위치에서 관리합니다.

긴 MVP를 프롬프트가 아니라 파일로 관리하는 이유

긴 계획을 매번 채팅창에 붙여 넣으면 일부가 빠지거나 대화가 길어지면서 처음 조건을 잊기 쉽습니다. 계획을 mvp.txt 파일로 저장하면 어떤 AI 도구를 사용하더라도 같은 내용을 다시 읽을 수 있습니다. 개발 중 새 대화를 시작해도 “프로젝트의 mvp.txt를 처음부터 끝까지 읽어 주세요”라고 요청하면 기준을 다시 맞출 수 있습니다.

mvp.txt는 원본 요구사항 문서로 유지합니다. 작업 완료 표시, 임시 메모, 오늘 할 일을 계속 덧붙이면 어느 문장이 제품 요구사항이고 어느 문장이 진행 기록인지 구분하기 어려워집니다. 구현 중 요구사항이 정말 바뀌었다면 변경 이유와 날짜를 먼저 결정 기록에 남기고 MVP를 의도적으로 수정합니다. 단순 진행 상황과 구현 순서는 별도의 ROADMAP.md에서 관리합니다. 이렇게 나누면 요구사항의 기준선과 현재 작업 상태를 동시에 보존할 수 있습니다.

mvp.txt: 앱의 목적, 사용자, 기능과 제약을 담은 원본 요구사항
ROADMAP.md: 마일스톤, 작업 순서, 완료 조건과 현재 진행 상태
README.md: 프로젝트 소개, 개발환경 준비와 빌드·실행 방법
DECISIONS.md: 중요한 기술 선택과 변경 이유를 날짜와 함께 기록
AGENTS.md: 코딩 에이전트가 지켜야 할 프로젝트 규칙과 검증 명령

문서가 많아지는 것이 부담이라면 처음에는 MVP와 ROADMAP 두 개만 시작해도 됩니다. 중요한 것은 동일한 사실을 여러 파일에 복사하지 않는 것입니다. 예를 들어 지원 Android 버전과 패키지명은 한 곳을 기준으로 정하고 다른 문서에서는 링크로 참조합니다. 문서끼리 값이 다르면 코딩 에이전트는 어느 쪽이 최신인지 판단하지 못하고, 실행할 때마다 다른 선택을 할 수 있습니다.

키스토어는 Git 밖에 두고 복구 가능하게 백업한다

키스토어를 저장소에서 제외하는 것만으로 관리가 끝나지는 않습니다. 출시 서명 키를 잃어버리면 업데이트 경로가 복잡해지거나 배포에 문제가 생길 수 있으므로 암호화된 백업을 최소 두 위치에 보관하고 실제 복원 절차를 시험해야 합니다. 키스토어 파일, 키 별칭, 저장소 암호와 키 암호를 한 장소에 평문으로 모으지 않습니다. Google Play App Signing을 사용하더라도 업로드 키의 관리와 교체 절차를 확인해야 합니다.

.gitignore는 아직 추적하지 않은 파일이 새로 커밋되는 일을 막지만 이미 커밋한 비밀을 기록에서 지워 주지는 않습니다. 실수로 키나 서비스 계정 파일을 커밋했다면 단순 삭제 커밋으로 끝내지 말고 해당 자격 증명을 폐기하거나 교체하고, 필요하면 저장소 기록 정리와 모든 복제본 동기화를 진행해야 합니다. 따라서 첫 커밋 전에 ignore 규칙과 git status를 확인하는 것이 가장 저렴한 예방책입니다.

# Signing files and local secrets
*.jks
*.keystore
keystore.properties
local.properties
.env
.env.*
google-services.json

# Android and IDE outputs
.gradle/
.idea/
**/build/
local.properties
captures/
*.apk
*.aabCode language: PHP (php)

google-services.json을 무조건 제외할지는 프로젝트 운영 방식과 포함된 식별 정보의 성격을 검토해 결정합니다. 여기서는 처음부터 민감 설정을 자동 커밋하지 않는 보수적인 예시로 제시했습니다. 파일을 제외하면 CI와 새 개발환경에서 안전하게 주입할 방법도 함께 마련해야 합니다. ignore 규칙만 있고 복원 방법이 없으면 다른 환경에서 빌드가 재현되지 않습니다.

GitHub 또는 Self-hosted Gitea에 비공개 저장소 만들기

원격 저장소는 작업의 백업이자 에이전트가 만든 변경을 검토하고 되돌리는 기준점입니다. GitHub와 Gitea 모두 사용할 수 있습니다. 개인 프로젝트와 아직 공개하지 않은 상용 앱에서는 자체 호스팅 Gitea의 비공개 저장소가 코드 위치와 접근 정책을 직접 통제하기 좋습니다. 다만 자체 호스팅은 서버 업데이트, 백업, 장애 복구, 인증서와 계정 보안을 운영자가 책임져야 합니다. 운영 부담을 감당하기 어렵다면 관리형 비공개 저장소가 오히려 안전할 수 있습니다.

개발 서버와 비공개 Git 저장소를 SSH 키로 안전하게 연결한 구조 — 개발 서버와 비공개 저장소 사이의 SSH 연결, 키 권한과 보호 브랜치를 첫 커밋 전에 검증합니다.

저장소를 만들 때 공개 범위를 비공개로 설정하고 기본 브랜치를 정합니다. 개발 서버에서 사용할 SSH 키 쌍은 해당 서버에서 만들고 공개 키만 Gitea나 GitHub 계정에 등록합니다. 개인 키는 서버 밖으로 복사하지 않으며 파일 권한을 제한합니다. 여러 개발 서버가 있다면 같은 개인 키를 복제하기보다 서버마다 키를 발급해 어느 접근을 폐기해야 하는지 구분하는 편이 좋습니다.

ssh-keygen -t ed25519 -C "android-dev-server"
ssh -T git@gitea.example.com

git init
git branch -M main
git remote add origin git@gitea.example.com:siamakerlab/app-project.git
git status
git add mvp.txt .gitignore
git commit -m "Initialize Android app requirements"
git push -u origin mainCode language: CSS (css)

ssh -T의 정확한 성공 메시지는 서버 구현과 설정에 따라 다를 수 있습니다. 중요한 것은 올바른 호스트 키를 확인하고 비밀번호 입력 없이 의도한 계정으로 인증되는지, 실제 저장소에 clone·pull·push가 가능한지 시험하는 것입니다. 처음 연결할 때 표시되는 호스트 지문을 무심코 승인하지 말고 서버 관리 화면이나 신뢰할 수 있는 경로에서 확인합니다. 자동화 환경에서는 개인 키에 무제한 권한을 주지 말고 가능하면 저장소별 배포 키나 제한된 서비스 계정을 사용합니다.

기본 브랜치 보호도 초기에 정합니다. 혼자 개발하더라도 main 강제 푸시와 삭제를 막고, 테스트가 생긴 뒤에는 통과한 변경만 병합하도록 설정할 수 있습니다. 에이전트에게 main 직접 작업을 허용하기보다 작업 브랜치를 만들고 diff를 검토한 뒤 병합하는 흐름이 안전합니다. 다만 첫 커밋도 없는 빈 저장소에서는 보호 규칙 설정이 제한될 수 있으므로 초기 커밋 후 적용합니다. GitHub의 비공개 저장소 브랜치 보호 기능은 요금제에 따라 제공 범위가 달라질 수 있으므로 현재 플랜을 확인합니다.

MVP를 실행 가능한 ROADMAP.md로 변환하기

원격 저장소가 준비되면 코딩 에이전트에게 먼저 코드를 쓰게 하지 않고 mvp.txt 전체를 읽어 ROADMAP을 만들게 합니다. 로드맵은 화면 목록을 다시 적는 문서가 아니라 작업의 의존 관계를 드러내는 실행 계획입니다. 예를 들어 데이터 모델과 저장소 인터페이스가 필요한 화면은 그 기반 작업 뒤에 와야 하며, 인증이 필요한 네트워크 기능은 보안 저장과 세션 만료 처리까지 같은 마일스톤에서 검증해야 합니다.

프로젝트 루트의 mvp.txt를 처음부터 끝까지 읽고,
실제 구현을 위한 ROADMAP.md를 작성해 주세요.

기능을 구현 가능한 작업 단위와 마일스톤으로 분리하고,
선행 작업과 의존 관계를 고려해 구현 순서를 정해 주세요.
각 작업에 상세 스펙, 완료 조건, 테스트 조건,
예외 처리와 보안 요구사항을 포함해 주세요.

ROADMAP을 작성하기 전 모순되거나 결정되지 않은 요구사항을 질문 목록으로 분리하세요.
확인 없이 임의로 제품 요구사항을 확장하지 마세요.Code language: CSS (css)

작업 단위는 “설정 화면 구현”처럼 넓지도, “파일 한 줄 수정”처럼 잘게 쪼개지도 않습니다. 하나의 목적과 검증 결과를 가진 크기가 좋습니다. 예를 들어 “설정 화면에서 테마를 변경하고 프로세스를 재시작해도 선택이 유지된다”는 작업은 UI, DataStore 저장, 복원과 테스트가 연결됩니다. 완료 조건에는 빌드 성공만 쓰지 않고 사용자가 볼 결과, 자동 테스트, 접근성 확인과 오류 조건을 포함합니다.

앱에 필요한 도구 버전은 AI가 공식 문서에서 확인하게 한다

Android 프로젝트에는 여러 도구와 라이브러리 버전이 함께 들어갑니다. 초보자가 각 버전 관계를 외울 필요는 없습니다. AI에게 기억에 의존하지 말고 Android 공식 문서에서 현재 안정 버전을 확인하게 하세요. 그리고 선택한 버전과 확인한 날짜를 ROADMAP.md에 짧게 남기면 다음 작업에서 같은 질문을 반복하지 않아도 됩니다.

처음 만드는 앱이라면 이름에 Alpha, Beta, RC, Canary, Preview가 붙은 시험 버전보다 안정 버전을 선택하는 편이 쉽습니다. 숫자가 가장 큰 버전이 반드시 초보자에게 좋은 버전은 아닙니다. AI에게 “시험 버전은 제외하고 서로 함께 사용할 수 있는 안정 버전을 선택해 달라”고 요청하면 충분합니다. 실제 프로젝트를 만드는 날에는 Compose 공식 문서도 다시 확인하게 합니다.

사용할 Android SDK, Gradle, Android Gradle Plugin, Kotlin,
Jetpack Compose, AndroidX 및 기타 라이브러리는
공식 문서와 공식 저장소에서 직접 확인해 주세요.

현재 사용 가능한 최신 안정화 버전을 기준으로 호환성 표를 작성하고,
확인한 URL과 날짜를 함께 기록해 주세요.
Alpha, Beta, RC, Canary, Preview, Snapshot 버전은 사용하지 마세요.
모델의 기억만으로 버전을 선택하지 마세요.

경쟁 앱과 기능 격차를 분석하되 범위를 다시 키우지 않는다

초기 로드맵을 만든 뒤 현재 Google Play에 등록된 주요 경쟁 앱과 공식 앱을 다시 조사합니다. 첫 단계의 시장 조사가 “만들 가치가 있는가”를 판단했다면 이번 조사는 “핵심 사용 흐름에 빠진 것이 있는가”를 확인합니다. 조사 결과를 mvp.txt와 ROADMAP.md에 나란히 놓고 반드시 필요한 기능, 경쟁력을 높이는 기능, 구현 비용에 비해 가치가 낮은 기능으로 구분합니다.

현재 Google Play Store에 등록된 주요 경쟁 앱과 공식 앱을 조사해 주세요.
조사 날짜, 지역, 실제 스토어 링크를 함께 기록해 주세요.

조사 결과와 현재 mvp.txt, ROADMAP.md를 비교해 기능 격차를 분석하세요.
반드시 필요한 기능, 경쟁력을 높일 수 있는 기능,
구현 비용에 비해 가치가 낮은 기능으로 구분해 주세요.

추가할 가치가 검증된 기능만 기존 로드맵의 적절한 마일스톤에 반영하고,
앱의 핵심 목적과 맞지 않는 기능은 추가하지 마세요.
변경한 항목마다 근거와 범위 증가 비용을 기록해 주세요.Code language: CSS (css)

경쟁 앱의 모든 기능을 따라가는 것은 목표가 아닙니다. 오래 운영된 앱은 다양한 사용자층의 요구를 누적해 기능이 많을 수 있고, 그 복잡함 자체가 새 앱이 해결할 문제일 수도 있습니다. 격차 분석으로 기능을 추가했다면 같은 양의 다른 기능을 미루거나 출시 일정을 다시 계산합니다. 로드맵은 희망 목록이 아니라 제한된 시간과 운영 능력 안에서 무엇을 하지 않을지 결정하는 문서입니다.

화면 계획은 사용자가 누르는 순서대로 적는다

기능 순서가 정리되면 UI·UX 계획을 ROADMAP에 연결합니다. “깔끔하고 현대적인 화면” 같은 표현은 구현 기준이 아닙니다. 화면 목록, 내비게이션 구조, 핵심 사용자 흐름, 화면별 컴포넌트와 상태, 다이얼로그, 바텀시트, 권한 요청 시점, 키보드와 시스템 바 대응을 구체적으로 적습니다. Material 3 컴포넌트를 우선 사용하고 커스텀 컴포넌트가 필요한 이유도 기록합니다.

MVP를 구현 로드맵으로 나누고 스마트폰과 태블릿, 폴더블 UI를 설계하는 과정 — 요구사항에서 마일스톤과 테스트를 거쳐 다양한 창 크기에 적응하는 UI까지 하나의 계획으로 연결합니다.

Adaptive UI는 “스마트폰 레이아웃 하나, 태블릿 레이아웃 하나”를 고정해서 만드는 일이 아닙니다. Android 공식 지침은 현재 앱 창의 크기와 구성 변화에 맞춰 레이아웃과 내비게이션을 조정하도록 안내합니다. 같은 태블릿도 분할 화면에서는 좁은 창이 될 수 있고, 데스크톱 창 모드에서는 사용자가 실행 중 크기를 바꿀 수 있습니다. 창 크기 클래스를 기준으로 내비게이션 바와 레일을 바꾸고, 목록·상세나 보조 패널처럼 제품에 맞는 canonical layout을 선택합니다.

2026년 7월 기준 Compose Material 3 Adaptive의 최신 안정 릴리스는 1.2.0이며 1.3.0-rc01은 이름 그대로 RC이므로 이 프로젝트 원칙에서는 선택하지 않습니다. 다만 이 숫자 역시 개발 시작일에 공식 Material 3 Adaptive 릴리스 페이지에서 재확인합니다. 필요한 기능이 안정 버전에 없다고 곧바로 프리릴리스를 채택하지 말고, 안정 API로 구현할 대안과 위험을 비교합니다.

mvp.txt와 ROADMAP.md를 분석해 이 앱의 기능과 대상 사용자에게
가장 적합한 UI·UX 구조를 설계해 주세요.

Material 3, Jetpack Compose, Adaptive Layout 공식 지침을 사용하세요.
화면 목록, 내비게이션 구조, 주요 사용자 흐름, 화면별 컴포넌트,
상태 처리, 다이얼로그, 바텀시트와 권한 요청 흐름을 구체화하세요.

스마트폰, 태블릿, 폴더블, 가로 모드, 창 크기 변경,
라이트·다크 테마, 접근성, 시스템 바, IME 대응을 포함하세요.
실제 Jetpack Compose로 구현 가능한 컴포넌트와 상태 모델로 작성하고
작업 및 테스트 항목을 ROADMAP.md의 관련 마일스톤에 반영하세요.Code language: CSS (css)

정상 화면뿐 아니라 빈 화면과 오류 화면도 준비한다

디자인 시안은 보통 데이터가 완벽히 채워진 정상 화면을 보여주지만 실제 사용자는 빈 화면과 로딩, 오류를 더 먼저 만납니다. 최초 실행에는 제품의 가치를 설명하고 꼭 필요한 시점에 권한을 요청해야 합니다. 데이터가 없을 때는 빈 공간이 아니라 다음 행동을 안내합니다. 부분 로딩에서는 이미 받은 데이터를 유지할지, 실패한 영역만 재시도할지 정합니다. 네트워크 단절과 인증 만료는 서로 다른 회복 흐름을 가져야 합니다.

최초 실행과 온보딩 완료 여부
데이터 없음과 첫 항목 생성 유도
전체 로딩 및 부분 로딩
복구 가능한 오류와 복구 불가능한 오류
네트워크 연결 끊김과 재연결
권한 거부, 다시 묻지 않음과 설정 이동
인증 만료와 작성 중 데이터 보존
잘못된 입력과 필드별 오류 안내
백그라운드 복귀와 오래된 데이터 갱신
프로세스 재생성 후 상태 복원
화면 크기 변경과 폴더블 자세 변화

각 상태에는 진입 조건, 표시 컴포넌트, 가능한 사용자 행동, 다음 상태, 테스트 조건을 붙입니다. 접근성은 마지막 점검 항목이 아니라 컴포넌트 선택 기준입니다. 글자 크기 확대, 충분한 색상 대비, 의미 있는 contentDescription, 터치 영역, 스크린리더 탐색 순서, 키보드와 스위치 접근을 계획합니다. 가로 모드와 큰 화면에서는 단순히 요소를 가로로 늘리지 않고 읽기 폭과 주요 작업의 위치를 조정합니다.

릴리즈와 디버그 앱을 한 기기에 동시에 설치하기

개발 중 가장 불편한 실수 가운데 하나는 디버그 앱을 설치할 때 실제 사용 중인 릴리즈 앱과 충돌하거나 덮어쓰려는 상황입니다. Android에서 기기와 Google Play가 앱을 식별하는 핵심 값은 applicationId입니다. 릴리즈와 디버그의 applicationId를 다르게 만들면 한 기기에 두 앱을 함께 설치해 실제 데이터와 테스트 데이터를 분리할 수 있습니다.

하나의 소스에서 디버그와 릴리즈 앱을 서로 다른 식별자로 빌드해 동시에 설치하는 구조 — 소스 namespace는 공유하면서 applicationIdSuffix로 디버그 앱의 설치 식별자를 분리합니다.

android {
    namespace = "com.siamakerlab.app_name"

    defaultConfig {
        applicationId = "com.siamakerlab.app_name"
    }

    buildTypes {
        debug {
            applicationIdSuffix = ".debug"
            versionNameSuffix = "-debug"
            resValue("string", "app_name", "App Name DEV")
        }
        release {
            isMinifyEnabled = true
        }
    }
}Code language: JavaScript (javascript)

위 구성에서 릴리즈 applicationId는 com.siamakerlab.app_name, 디버그는 com.siamakerlab.app_name.debug가 됩니다. 실제 제품 식별자의 app_name에는 Android applicationId 규칙을 만족하는 고유 이름을 사용합니다. 디버그 빌드의 앱 이름에는 DEV 같은 표시를 붙이고 src/debug/res에 색상이 다른 아이콘을 두면 런처와 최근 앱 화면에서 실수할 가능성이 줄어듭니다. 앱 내부 상단이나 정보 화면에도 빌드 유형을 표시하면 테스트 캡처를 구분하기 쉽습니다.

앱의 고유 이름과 개발용 표시를 구분한다

namespace는 소스 코드와 생성되는 R, BuildConfig 클래스의 패키지 기준입니다. applicationId는 빌드된 앱이 기기와 Play 스토어에서 갖는 고유 식별자입니다. applicationIdSuffix는 특정 빌드 타입이나 변형의 식별자 뒤에 접미사를 붙입니다. 동시 설치를 위해 주로 변경할 값은 applicationId이며, 디버그마다 소스 namespace까지 바꿀 필요는 없습니다.

Android 공식 문서도 namespace와 applicationId를 독립적으로 설명하며, 출시 후 applicationId를 변경하면 Play 스토어에서 다른 앱으로 취급되므로 바꾸지 말라고 강조합니다. 첫 출시 전에 명시적으로 applicationId를 정하고 유지해야 합니다. 단순히 코드 패키지 폴더 이름을 리팩터링하는 작업과 배포 앱의 정체성을 바꾸는 작업을 혼동해서는 안 됩니다. 자세한 기준은 앱 모듈 구성 공식 문서에서 확인할 수 있습니다.

개발용 앱을 따로 만들면 외부 서비스에도 등록한다

applicationIdSuffix만 추가하면 설치 분리는 되지만 외부 서비스가 자동으로 따라오는 것은 아닙니다. OAuth 리디렉션, Firebase 앱 등록, App Links와 딥링크, API 키 제한, 푸시 알림, ContentProvider authority가 applicationId에 묶여 있다면 디버그 식별자를 별도로 등록하거나 매니페스트 자리표시자를 사용해야 합니다. 서버가 패키지명이나 서명 인증서 지문을 검증한다면 디버그 인증서도 테스트 환경에 등록해야 합니다.

디버그와 릴리즈가 서로 다른 앱이므로 내부 저장소, 데이터베이스, 권한 승인과 알림 채널도 기본적으로 분리됩니다. 이것은 안전한 테스트에 유리하지만 릴리즈 데이터를 디버그에서 그대로 볼 수 없다는 뜻이기도 합니다. 데이터 이전 기능을 시험해야 한다면 익명화한 테스트 데이터 내보내기나 전용 개발 서버를 준비합니다. 실제 사용자 데이터와 운영 API를 디버그 앱에서 사용하는 흐름은 최대한 피합니다.

릴리즈 빌드의 applicationId는 com.siamakerlab.app_name으로 설정해 주세요.
디버그 빌드는 applicationIdSuffix = ".debug"를 사용해
com.siamakerlab.app_name.debug가 되도록 설정해 주세요.

두 앱을 동일한 기기에 동시에 설치할 수 있어야 합니다.
앱 이름과 아이콘도 빌드 타입별로 구분해 사용자가 혼동하지 않게 해 주세요.
namespace는 공통 소스 패키지 기준으로 유지하세요.

OAuth, Firebase, App Links, 딥링크, Provider authority,
API 키 제한과 푸시 알림에서 디버그 applicationId 및 서명 지문을
별도로 설정해야 하는지 점검하고 ROADMAP에 테스트를 추가해 주세요.Code language: JavaScript (javascript)

코딩을 시작하기 전 최종 점검표

프로젝트 루트에 최종 mvp.txt가 있고 진행 기록과 분리됐는가
키스토어와 비밀정보가 프로젝트 밖에 있으며 암호화된 복구 가능 백업이 있는가
.gitignore 적용 후 첫 커밋 대상을 git status로 검토했는가
비공개 원격 저장소와 SSH 호스트 지문, clone·pull·push를 확인했는가
main 강제 푸시와 삭제를 막을 보호 규칙을 설정했는가
ROADMAP에 의존 관계, 완료 조건, 테스트, 예외와 보안 요구사항이 있는가
SDK와 라이브러리를 공식 자료의 최신 안정판으로 확인했는가
경쟁 앱 분석이 핵심 목적을 흐리는 기능 추가로 변하지 않았는가
최초·빈·로딩·오류·오프라인·권한 거부·복원 상태를 UI 계획에 포함했는가
창 크기 변화, 태블릿, 폴더블, 가로 모드와 접근성 테스트가 있는가
릴리즈와 디버그 applicationId, 이름과 아이콘이 구분되는가
외부 서비스가 디버그 식별자와 서명을 지원하도록 계획했는가

마무리: 에이전트가 빠르게 움직일수록 기준점이 중요하다

코딩 에이전트는 파일을 만들고 빌드를 고치고 기능을 확장하는 속도가 빠릅니다. 하지만 요구사항 원본, 작업 경계, 버전 선택 기준과 완료 조건이 없으면 그 속도가 곧 변경 비용이 됩니다. 프로젝트 폴더와 비공개 저장소, MVP와 ROADMAP의 분리, 안정 버전 원칙, 상태 중심 UI 계획, 디버그·릴리즈 식별자 분리는 화려한 기능이 아니지만 이후 모든 개발 단계의 안전망이 됩니다.

이 준비가 끝난 뒤에야 코딩 에이전트에게 프로젝트 초기화와 첫 마일스톤 구현을 맡깁니다. 첫 요청에서는 전체 앱 완성을 지시하기보다 MVP와 ROADMAP을 읽고 현재 환경을 검사한 다음, 첫 마일스톤의 변경 파일과 검증 명령을 제안하게 하는 편이 좋습니다. 구현 후에는 빌드 성공만 확인하지 않고 테스트 결과, 실제 기기 동작, 접근성, Git diff와 비밀정보 포함 여부를 함께 검토합니다. 다음 글에서는 이 기준 문서를 바탕으로 Android 프로젝트를 초기화하고 에이전트와 첫 구현 사이클을 운영하는 방법을 이어서 정리하겠습니다.

작성 기준: 2026년 7월 26일. Android 및 라이브러리 릴리스는 계속 변경됩니다. 프로젝트 초기화 시 앱 모듈 구성, Compose BOM, Adaptive 앱 구축, Material 3 Adaptive 릴리스 공식 문서를 다시 확인하세요.