00. 목표와 개발자 계정 정하기
첫 버전의 동작을 정하고, 앱을 올릴 계정을 준비해요.
이 단계에서는 무엇을 하나요?
첫 버전에서 꼭 동작할 기능 한 가지를 정하고, Google Play에 올릴 계정을 준비해요. 예를 들어 기분 기록 앱이라면 “선택 → 저장 → 다시 보기”가 첫 목표예요. 계정 확인은 기다리는 시간이 생길 수 있으니 개발과 함께 시작해요.
첫 목표를 정하는 순서
- 만든 디자인에서 가장 중요한 화면 하나를 고르고, 그 화면에서 사람이 할 행동을 적어요.
- 버튼을 눌렀을 때 보여야 할 결과를 적어요. 예: 기분을 저장하면 목록에 오늘 기록이 보여요.
- 잘못 눌렀을 때도 정해요. 예: 기분을 고르지 않았다면 저장하지 않고 이유를 알려줘요.
이렇게 적은 “행동 → 결과”가 02단계 구현과 07단계 폰 시험의 기준이 돼요.
먼저, 이 두 가지는 달라요
| 이름 | 하는 일 |
|---|---|
| Google 계정 | Gmail이나 유튜브에 로그인할 때 쓰는 계정이에요. |
| Play Console 개발자 계정 | Google Play에 앱 파일을 제출하고, 테스트와 출시를 관리하는 계정이에요. Google 계정으로 가입해요. |
따라 할 순서
- Play Console 가입 페이지를 열어요. 가입자는 만 18세 이상이어야 해요.
- 앱을 계속 관리할 계정 소유자를 정해요. 출시한 뒤 누가 업데이트할지도 함께 정하세요.
- 개인 또는 조직 계정 중 실제 상황에 맞는 유형을 골라요. 혼자 만드는 사람은 보통 개인 계정, 회사·기관은 조직 계정을 검토해요. 테스트를 피하려고 조직으로 선택하지 마세요.
- 등록비 25달러를 한 번 결제하고, 화면에 나오는 본인 확인을 진행해요. 필요한 서류는 계정 유형에 따라 달라요.
- 새 개인 계정은 실제 안드로이드 기기에 접근할 수 있는지도 확인해요. 콘솔이 안내하는 Play Console 모바일 앱 절차를 따라요.
- 팀으로 만든다면 각자의 Google 계정을 사용자로 초대해 필요한 권한을 줘요. 계정 비밀번호를 돌려 쓰는 방식보다 관리하기 쉬워요.
지금 함께 준비할 것
안드로이드 폰, 연결 가능한 USB 케이블, 앱을 만드는 컴퓨터를 준비해요. 아주 오래된 폰은 앱의 지원 버전이나 기기 인증 조건에 맞지 않을 수 있으니 먼저 확인하세요. 테스터 모집도 지금 시작하면 좋아요.
여기까지 되면 다음 단계로
이미 만든 디자인과 기획을 바탕으로 첫 출시 목표를 정하려고 해. 핵심 기능 한 가지와 실제로 눌러 확인할 동작을 짧게 정리해줘. 지금은 새 화면을 만들지 말고 필요한 자료와 계정 준비 항목만 알려줘.
01. 작업 공간과 자료 준비하기
Codex가 실제로 읽을 수 있는 기획·디자인 자료를 모아요.
완성한 디자인이 있다고 가정하고 시작해요
기획·디자인 전달 → 컴퓨터에서 화면과 기능 구현 → 폰 앱으로 실행 → 실제 폰에서 확인 → 테스트 배포 → 정식 공개.
개발자 계정과 스토어 자료는 개발과 함께 준비해요. 첫 화면이 동작하면 폰에서도 일찍 열어 보세요.
이 단계에서는 무엇을 하나요?
이미 만든 기획과 디자인을 AI가 읽을 수 있게 모아요. 앱을 새로 기획하는 단계가 아니에요. 먼저 컴퓨터에 앱 작업용 폴더 하나를 정하고, Codex에서 그 폴더를 열어요.
도구마다 맡은 일이 달라요
| 도구·자료 | 쓰는 이유 |
|---|---|
| 기획 문서(PRD) | 어떤 화면과 기능을 만들지 알려줘요. 예: 저장 버튼을 누르면 오늘 기록이 남아요. |
| Figma·화면 이미지·디자인 토큰 | 어떻게 보여야 하는지 알려줘요. 토큰은 색·글자 크기·간격 같은 공통 값이에요. |
| Codex | 자료를 읽고 실제로 작동하는 코드를 만들고 고쳐요. 이 가이드는 Codex를 예로 들어요. |
| 프로젝트 폴더 | 앱 코드와 관련 자료가 들어 있는 내 컴퓨터의 폴더예요. |
| GitHub 저장소(repository) | 코드와 변경 기록을 온라인에 보관하는 프로젝트 공간이에요. Figma 파일과는 별개예요. |
따라 할 순서
- 작업 폴더를 만들거나, 팀의 기존 GitHub 저장소를 내 컴퓨터로 복사해요. 이 복사를 clone이라고 불러요. GitHub의 초대를 먼저 수락해야 할 수 있어요.
- Codex에서 이 폴더를 열어요. 이미 코드가 있다면 새 프로젝트를 또 만들지 말고 그 폴더를 사용해요.
- 폴더 안에 docs 폴더를 만들고 기획 문서를 넣어요. 화면 이름과 화면별 기능이 드러나게 정리하세요.
- 디자인을 전달해요. Figma를 Codex에서 읽을 수 있도록 연결했다면 화면 링크를 주고, 실제로 읽을 수 있는지 먼저 확인해요. 연결되지 않았다면 화면 이미지·토큰 파일·레이아웃 설명을 함께 줘요. 링크만 적는다고 자동으로 읽는 것은 아니에요.
- 프로젝트 맨 위에 AGENTS.md 파일을 만들어요. AI에게 반복해서 알려줄 작업 규칙을 적는 텍스트 파일이에요.
- 팀원이 같은 자료를 볼 수 있도록 GitHub에 올려요. AI에게 변경 파일 목록을 먼저 보여 달라고 하고, 비밀번호나 비밀 파일이 섞이지 않았는지 확인하세요.
토큰만 주면 화면까지 정해지나요?
토큰은 “색은 이 값, 간격은 이 값”을 정해요. 하지만 “제목 아래에 카드가 몇 개 있고, 버튼은 어디에 있는지”까지 정해 주지는 않아요. 화면 이미지 또는 Figma + 토큰 + 화면 구성 설명을 같이 주면 의도를 더 정확히 전달할 수 있어요.
이 폴더에서 안드로이드용 하이브리드 앱을 만들 거야. 먼저 기존 파일을 읽고, 기획 문서와 디자인 자료가 어디에 있는지 정리해줘. 디자인을 실제로 읽을 수 있는지도 확인해줘. 읽지 못하면 추측해서 구현하지 말고 알려줘. AGENTS.md를 만들어 아래 규칙을 적어줘. - docs의 기획과 제공한 디자인·토큰을 따른다. - 한 번에 화면 하나, 기능 하나씩 작업한다. - 완료하면 실행 방법과 직접 확인할 항목을 알려준다. - 비밀번호·비밀 키·서명 파일은 GitHub에 올리지 않는다. 아직 기능 구현은 시작하지 말고, 빠진 자료부터 알려줘.
AGENTS.md는 왜 필요한가요?
대화에만 규칙을 남겨 두면 새 작업에서 빠질 수 있어요. 파일로 남겨 두면 프로젝트의 공통 기준으로 사용할 수 있어요. 단, 파일에 썼다고 AI가 반드시 지키는 것은 아니니 결과는 직접 확인해야 해요.
여기까지 되면 다음 단계로
02. 화면과 기능 구현하기
디자인한 화면에 실제 동작을 하나씩 붙여요.
이 단계에서는 무엇을 하나요?
먼저 컴퓨터의 웹 브라우저에서 앱 화면을 실행해요. 그다음 버튼을 눌렀을 때 화면이 바뀌고, 입력한 내용이 저장되도록 하나씩 연결해요. 예시는 “오늘의 기분을 고르고 기록하는 앱”으로 이어갈게요.
만든 화면은 앱에서 어떻게 보이나요?
이 가이드는 웹 기술로 화면을 만들고, 그 화면을 Android 앱 안의 웹뷰에서 보여줘요. 아래 그림은 첫 버전의 기본 구조예요. 06단계에서 실제 앱으로 포장해요.
상단 제목 · 내용 · 버튼 · 하단 탭
이 영역을 웹 기술로 만들어요.앱 안에서 웹 화면을 표시하는 영역을 웹뷰(WebView)라고 해요. 처음에는 제목과 하단 탭까지 웹에서 만들면 화면 이동을 한곳에서 관리하기 쉬워요. 시간·배터리 표시 영역은 안드로이드가 맡아요.
처음 만나는 용어 세 가지
| 용어 | 뜻과 확인 방법 |
|---|---|
| Node.js | 이런 웹 프로젝트의 개발 도구를 실행하는 데 필요한 프로그램이에요. 프로젝트에 맞는 버전을 AI가 먼저 확인하게 하세요. |
| 개발 서버 / localhost | 내 컴퓨터에서 앱 화면을 시험할 수 있게 실행한 상태와 그 주소예요. 예: http://localhost:5173. 다른 사람에게 보내는 공개 주소는 아니에요. |
| 데이터 저장 | 입력값을 나중에도 다시 읽을 수 있게 남기는 일이에요. 내 폰에만 저장할지, 서버에도 저장할지에 따라 구현이 달라요. |
따라 할 순서
- AI에게 기존 프로젝트를 확인하고 실행해 달라고 해요. 필요한 프로그램이 없다면 이름과 설치 방법부터 안내받아요.
- AI가 알려준 localhost 주소를 브라우저에서 열어요. 하얀 화면이거나 오류가 뜨면 먼저 해결해요.
- 화면 하나를 디자인과 비교해요. 글자, 간격, 버튼 위치를 확인해요. 390px 같은 디자인 기준 너비에서 보고, 더 작은 너비에서도 잘리는지 살펴봐요.
- 핵심 기능 하나만 연결해요. 예: 기분 선택 → 저장 → 기록 목록에 표시.
- 정상적인 경우와 실패하는 경우를 둘 다 눌러 봐요. 예: 기분을 고르지 않고 저장하면 어떻게 되나요?
- 완료된 기능을 저장하고 다음 기능으로 넘어가요. 첫 화면이 동작하면 06단계로 가서 폰에서도 한 번 열어 보세요.
오늘 기록 화면의 저장 기능을 만들어줘. 1. 기분 하나를 선택하고 저장을 누르면 날짜와 기분을 저장한다. 2. 저장하면 기록 목록으로 이동해서 방금 저장한 기록을 보여준다. 3. 선택하지 않고 저장하면 “기분을 하나 골라 주세요”를 보여준다. 4. 앱을 닫았다가 다시 열어도 기록이 남아야 한다. 이번 실습은 이 기기에만 저장하고, 로그인과 서버 저장은 추가하지 않는다. 제공한 디자인과 토큰을 유지하고 다른 기능은 수정하지 마. 완료 후 내가 직접 눌러 볼 순서와 저장 위치를 알려줘.
AI가 “완료”라고 했을 때 확인할 것
| 눌러 볼 행동 | 기대하는 결과 |
|---|---|
| 기분 선택 후 저장 | 목록에 오늘 날짜와 선택한 기분이 보여요. |
| 아무것도 선택하지 않고 저장 | 이유를 알려 주고 저장하지 않아요. |
| 새로고침 또는 앱 재실행 | 저장한 기록이 다시 보여요. |
| 저장 버튼을 빠르게 두 번 누르기 | 원하지 않는 중복 기록이 생기지 않아요. |
막히면 이렇게 전달하세요
“안 돼요” 대신 어느 화면에서 → 무엇을 했는데 → 무엇이 나왔는지 → 원한 결과는 무엇인지를 말해요. 오류 메시지는 요약하지 말고 그대로 전달하되, 비밀 값은 가려요. 예: “오늘 기록 화면에서 기분 선택 후 저장했는데 목록이 비어 있어. 목록에 방금 기록이 보여야 해.”
여기까지 되면 다음 단계로
03. 기능별 브랜치에서 반복 개발하기
기능 하나를 만들고 검토한 다음, 다음 기능을 시작해요.
이 단계에서는 무엇을 하나요?
한 기능마다 작업용 브랜치를 만들어 다른 변경과 섞이지 않게 해요. main은 합쳐진 기준 코드이고, 브랜치는 그 기준에서 나온 작업 가지예요. Codex의 채팅이나 프로젝트 이름만으로 코드가 분리되는 것은 아니니 실제 브랜치를 확인해요.
팀 작업과 코드 저장은 이렇게 해요
브랜치는 같은 프로젝트에서 작업을 나눠 진행하는 공간이에요. 커밋은 변경 내용을 기록으로 남기는 일, push는 그 기록을 GitHub에 올리는 일이에요. PR은 변경 내용을 검토해 합치자고 요청하는 것이고, 병합(merge)은 실제로 합치는 일이에요.
- 작업 전에 최신 코드를 받고 내 브랜치를 만들어요.
- 기능 하나를 만들고 직접 확인한 뒤 커밋해요.
- GitHub에 push하고 PR을 만들어요.
- 팀원이 확인한 뒤 main에 병합해요. main은 팀이 기준으로 삼는 코드예요.
- 다음 작업 전 다시 최신 main을 받아요. 같은 파일을 동시에 크게 고치지 않도록 역할을 나누세요.
기능 하나를 반복해서 만드는 순서
- 최신 main을 받고 이번 기능을 정해요. 예: 기록 목록.
feature/record-list처럼 이름을 붙여 새 브랜치를 만들어요.- Codex와 기능을 만들고 정상·실패 상황을 직접 시험해요.
- 04단계에서 commit·push하고 05단계에서 PR로 검토받아 합쳐요.
- 다음 기능을 시작할 때 다시 최신 main에서 새 브랜치를 만들어요.
다른 사람이 만든 코드도 그 사람의 브랜치나 포크에서 PR을 열어 같은 방식으로 검토할 수 있어요.
현재 프로젝트의 저장소와 브랜치를 확인해줘. 최신 main을 기준으로 기록 목록 기능용 브랜치를 만들고, 다른 기능은 건드리지 마. 작업 전에는 이번 브랜치에서 바꿀 파일과 확인할 동작을 먼저 알려줘.
여기까지 되면 다음 단계로
04. commit과 push로 변경 기록 남기기
내 컴퓨터에 기록하고 GitHub의 작업 브랜치에 올려요.
이 단계에서는 무엇을 하나요?
잘 작동하는 작은 변경을 commit으로 기록하고, push로 GitHub의 내 브랜치에 올려요. commit은 내 컴퓨터의 Git 기록에 먼저 남아요. push 전에는 다른 사람이 GitHub에서 그 기록을 볼 수 없어요.
기록은 어디에 있나요?
| 장소 | 무엇을 볼 수 있나요? |
|---|---|
내 폴더의 .git | 내 컴퓨터의 Git 기록이에요. git log --oneline으로 볼 수 있어요. |
| GitHub의 내 브랜치 | push한 뒤 저장소의 Commits에서 기록을 볼 수 있어요. |
| PR 화면 | Commits에서는 기록을, Files changed에서는 실제 바뀐 줄을 볼 수 있어요. |
Codex가 Git 기록을 따로 보관하는 것은 아니에요. Codex가 commit을 도와줘도 기록은 Git에 남고, push한 기록은 GitHub에서도 보여요.
따라 할 순서
- Codex에 바뀐 파일 목록을 보여 달라고 해요. 비밀번호·키 파일·임시 파일이 없는지 확인해요.
- 설명할 수 있는 작은 작업이 끝나면 “기록 목록 표시”처럼 결과를 담은 한 줄로 commit해요.
- 현재 작업 브랜치를 GitHub에 push해요. main에 바로 올리는 것과 구분해요.
- GitHub에서 내 브랜치를 열어 방금 올린 commit과 바뀐 파일을 확인해요.
매시간 기록할 필요는 없어요. 기능의 작은 부분이 끝나고 다시 돌아올 지점이 생겼을 때 commit하면 돼요.
지금 브랜치에서 바뀐 파일과 변경 내용을 먼저 보여줘. 비밀 값이나 서명 파일이 포함되지 않았는지 확인한 뒤, 완료한 기능만 commit해줘. commit 메시지는 한 줄로 무엇을 했는지 쓰고, 내 브랜치에 push해줘. 마지막에 로컬 기록과 GitHub에서 각각 어디서 확인하는지 알려줘.
여기까지 되면 다음 단계로
05. PR을 검토하고 main에 합치기
누가 승인하고 누가 합치는지 정한 뒤 안전하게 병합해요.
이 단계에서는 무엇을 하나요?
PR(Pull Request)은 “내 브랜치의 변경을 main에 합쳐도 될까요?”라고 제안하는 화면이에요. 누군가 내용을 보고 의견을 주거나 승인할 수 있고, 조건을 채운 뒤 권한 있는 사람이 실제로 합쳐요.
누가 검토하고, 승인하고, 합치나요?
| 역할 | 쉽게 말하면 |
|---|---|
| 리뷰어 | 저장소 소유자만 가능한 역할은 아니에요. 권한과 저장소 설정에 맞는 사람이나 팀을 지정해 의견을 받을 수 있어요. |
| 필수 승인 | main 보호 규칙에 필수 승인을 켰다면, 규칙에서 인정하는 권한을 가진 사람의 승인이 필요해요. PR 작성자는 자기 PR을 승인할 수 없어요. |
| merge 담당 | 보통 저장소에 쓰기 권한이 있는 사람이 승인·테스트·보호 규칙을 확인하고 합쳐요. 관리자 예외는 설정에 따라 달라요. |
따라 할 순서
- 04단계의 push가 끝났다면 GitHub에서 Pull requests → New pull request를 열어요.
- 합칠 곳은 main, 가져올 곳은 내 작업 브랜치인지 확인해요.
- 무엇을 바꿨는지, 직접 눌러 본 결과, 남은 문제를 적고 리뷰어를 지정해요.
- 리뷰어가 고칠 점을 남기면 같은 브랜치에서 수정·commit·push해요. PR에도 반영돼요.
- 필요한 승인과 자동 테스트가 통과하면 권한 있는 사람이 merge해요. 다음 기능은 최신 main에서 시작해요.
main을 보호하는 설정
저장소 관리 권한이 있는 사람은 GitHub의 브랜치 보호 규칙에서 “PR을 거치기”, “몇 명의 승인 받기”, “테스트 통과하기”를 정할 수 있어요. 혼자 작업하면서 필수 승인을 켜면 자기 PR을 승인하지 못해 합치기 막힐 수 있어요. 협업자를 정하거나 규칙을 상황에 맞게 설정하세요.
PR 승인은 앱 출시 승인이 아니에요. PR은 코드를 합치는 단계이고, Google Play 공개는 08단계에서 별도 제출과 검토를 거쳐요.
현재 PR을 만들기 전에 바뀐 파일, commit, 직접 시험한 결과를 요약해줘. PR 설명에는 무엇을 왜 고쳤는지와 확인 방법을 적어줘. 리뷰어를 지정할 수 있는 권한과 main 보호 규칙을 확인하고, merge를 막는 조건이 있으면 알려줘.
여기까지 되면 다음 단계로
06. Android 앱으로 만들기
웹 화면을 앱 안의 웹뷰에 담고 폰에서 실행해요.
이 단계에서는 무엇을 하나요?
컴퓨터 브라우저에서 동작하는 화면을 안드로이드 앱 안에 넣어요. 이 가이드는 Capacitor라는 도구를 쓰는 방법을 예로 들어요. 이미 다른 방식으로 만든 프로젝트라면 AI에게 현재 구조부터 확인하게 하세요.
하이브리드 앱의 구조
상단 제목 · 내용 · 버튼 · 하단 탭
이 영역을 웹 기술로 만들어요.앱 안에서 웹 화면을 표시하는 영역을 웹뷰(WebView)라고 해요. 처음에는 제목과 하단 탭까지 웹에서 만들면 화면 이동을 한곳에서 관리하기 쉬워요. 시간·배터리 표시 영역은 안드로이드가 맡아요.
파일이 만들어지는 과정을 이해해요
| 순서 | 실제로 하는 일 |
|---|---|
| 웹 코드 수정 | 화면과 기능을 고쳐요. |
| 빌드(build) | 코드를 앱에 넣어 실행할 수 있는 웹 파일 묶음으로 만들어요. 보통 dist 같은 폴더에 생겨요. |
| 동기화(sync) | 빌드한 웹 파일과 필요한 설정을 안드로이드 프로젝트에 반영해요. |
| Android Studio 실행 | 안드로이드 앱을 빌드하고 폰이나 가상 기기에 실행하는 프로그램을 열어요. |
| 폰에서 실행 | 방금 바꾼 내용이 실제 앱에도 보이는지 확인해요. |
따라 할 순서
- Android Studio를 설치하고 첫 실행 안내를 마쳐요. 가상 안드로이드 기기를 에뮬레이터라고 해요. 실제 폰이 없어도 기본 동작을 확인할 수 있어요.
- AI에게 프로젝트와 호환되는 Capacitor 설정을 요청해요. 설치 도구 버전은 기존 프로젝트에 맞춰야 해요.
- 앱 이름과 앱 ID를 정해요. 앱 ID는 com.example.moodnote처럼 앱을 구분하는 고유 이름이에요. 실제 배포용 값은 팀에서 정하고 출시 뒤에는 함부로 바꾸지 않아요.
- AI에게 웹 빌드와 안드로이드 동기화를 실행하게 해요. Android Studio에서 프로젝트가 열리는지 확인해요.
- 에뮬레이터 또는 USB로 연결한 폰을 선택하고 실행 버튼(▶)을 눌러요. 실제 폰 연결은 07단계에서 설명해요.
현재 웹 프로젝트를 Capacitor 기반 안드로이드 앱으로 실행할 수 있게 해줘. 기존 설정과 프로젝트의 도구 버전을 먼저 확인하고 중복 생성하지 마. 앱 이름: [우리 앱 이름] 앱 ID: [팀에서 정한 고유 ID] 제목·내용·하단 탭은 웹에서 만들고 화면 이동도 웹에서 관리해줘. 상태바와 하단 시스템 영역에 버튼이 가려지지 않게 해줘. 안드로이드 뒤로가기는 이전 화면으로 돌아가게 하고, 첫 화면에서는 정한 종료 방식으로 처리해줘. 필요한 프로그램·버전, 실제 실행한 명령, Android Studio에서 내가 할 일을 따로 알려줘.
고쳤는데 폰에서는 예전 화면이 보이나요?
코드를 고친 것만으로 폰 앱에 자동 반영되지는 않을 수 있어요. 이 가이드의 기본 흐름은 수정 → 웹 빌드 → 동기화 → 앱 다시 실행이에요. AI에게 “최신 웹 코드를 빌드해서 안드로이드에 동기화했는지 확인해줘”라고 요청하세요.
여기까지 되면 다음 단계로
뒤로가기와 화면 가장자리를 확인해요
제목과 하단 탭을 웹에서 그린다면 화면 이동의 기준도 웹에 두어요. Android 뒤로가기 신호가 왔을 때 웹의 이전 화면으로 이동하고, 첫 화면에서는 종료 방법을 정해요. 상태바와 아래 시스템 영역에 버튼이 가려지지 않는지도 실제 폰에서 봐요.
07. 실제 폰에서 시험하고 AAB 만들기
폰에서 실패 상황까지 확인한 뒤 제출할 파일을 만들어요.
이 단계에서는 무엇을 하나요?
브라우저에서 잘 되는 앱도 폰에서는 키보드에 버튼이 가려지거나 뒤로가기가 다르게 작동할 수 있어요. 먼저 실제 사용 상황을 확인하고, Google Play에 올릴 AAB 파일을 만들어요.
폰으로 실행하는 순서
- 폰의 설정에서 개발자 옵션을 켜요. 보통 휴대전화 정보 안의 빌드 번호를 여러 번 누르면 켤 수 있어요. 메뉴 위치는 제조사마다 달라요.
- 개발자 옵션에서 USB 디버깅을 켜요. 컴퓨터에서 폰에 개발 중인 앱을 실행할 수 있게 하는 설정이에요.
- 데이터 전송이 되는 USB 케이블로 연결하고, 폰에 뜨는 이 컴퓨터 허용 안내를 확인해요.
- Android Studio의 기기 목록에서 내 폰을 선택하고 실행해요. 기기가 안 보이면 폰 모델·안드로이드 버전·오류 메시지를 AI에게 전달해요.
실제 폰에서 꼭 눌러 볼 것
| 상황 | 살펴볼 점 |
|---|---|
| 안드로이드 뒤로가기 | 이전 화면으로 가나요? 저장하지 않은 입력은 어떻게 되나요? |
| 키보드 열기 | 입력칸과 저장 버튼이 가려지지 않나요? |
| 긴 문장·작은 화면·큰 글자 | 내용이 잘리거나 버튼이 겹치지 않나요? |
| 상태바·하단 시스템 영역 | 제목과 하단 버튼을 정상적으로 누를 수 있나요? |
| 앱 종료 후 다시 열기 | 남아야 할 기록은 남고, 민감한 정보가 뜻밖에 보이지 않나요? |
| 인터넷 끄기 | 통신이 필요한 기능에 안내가 나오나요? 무한히 기다리지 않나요? |
| 권한 거부 | 카메라·알림 권한을 거절해도 앱이 멈추지 않나요? |
AAB·APK·서명은 무엇인가요?
| 이름 | 의미 |
|---|---|
| APK (.apk) | 안드로이드 기기에 설치하는 앱 파일 형식이에요. 개발 중 직접 설치할 때도 써요. |
| AAB (.aab) | Google Play에 제출하는 앱 묶음이에요. 이것을 폰에서 눌러 직접 설치하는 방식은 아니에요. 구글이 기기에 맞는 설치 파일을 만들어 배포해요. |
| 서명 / 업로드 키 | 업로드할 파일이 우리 쪽에서 만든 것임을 확인하는 데 쓰여요. 키는 keystore라는 파일에 보관할 수 있어요. |
| versionCode | 제출하는 앱 파일을 구분하는 내부 번호예요. 새 파일을 올릴 때 이전보다 큰 값이 필요해요. |
| target SDK / min SDK | target은 어떤 안드로이드 기준에 맞춰 만들었는지, min은 설치를 지원하는 가장 낮은 버전이에요. 서로 다른 값이에요. |
제출 파일을 만드는 순서
- 팀의 기준 코드(main)에 필요한 변경이 모두 합쳐졌는지 확인해요. 최신 웹 빌드와 동기화를 다시 실행해요.
- 2026년 10월 확인 기준, 일반 휴대전화용 신규 앱과 업데이트는 Android 16(API 36) 이상을 대상으로 해야 해요. 제출 직전 공식 기준도 다시 확인하세요. 이것이 Android 16 폰에만 설치된다는 뜻은 아니에요. 설치 범위는 min SDK도 함께 봐요. [공식 자료]
- Android Studio의 Build 메뉴에서 Generate Signed Bundle / APK를 찾아 Android App Bundle을 선택해요. 메뉴 이름은 버전에 따라 조금 다를 수 있어요.
- 첫 제출이라면 업로드용 키 파일을 만들고 파일 위치·비밀번호·키 이름(alias)을 안전하게 보관해요. AI 대화나 GitHub에 비밀번호를 붙여 넣지 마세요.
- release용 AAB를 만들고, 만들어진 파일의 정확한 경로와 versionCode를 기록해요. Play App Signing 설정도 콘솔 안내에 따라 진행해요.
Play Console에 제출할 release AAB를 만들 준비를 확인해줘. 최신 코드인지, 웹 빌드·동기화가 끝났는지, target SDK와 versionCode가 맞는지 확인해줘. 서명용 키·비밀번호가 GitHub에 올라가지 않도록 제외 설정을 확인해줘. 비밀번호는 대화에 요구하거나 출력하지 마. 내가 Android Studio에서 입력해야 할 항목과 완성될 파일 위치를 알려줘.
키 파일을 잃어버리면요?
안전한 별도 장소에 백업하세요. 다만 “잃어버리면 무조건 업데이트가 영원히 불가능”한 것은 아니에요. Play App Signing을 이용하고 업로드 키를 잃은 경우에는 재설정을 요청할 수 있어요. 앱 서명 키와 업로드 키는 역할이 달라요. 공식 설명을 참고하세요.
여기까지 되면 다음 단계로
검사한 코드와 제출 파일이 같은지 확인해요
PR로 main에 합친 최신 코드로 웹 빌드·동기화를 다시 한 다음 release AAB를 만들어요. 그 AAB의 파일 위치와 versionCode를 적어 두고, 실제로 시험한 버전과 일치하는지 확인해요.
08. Google Play 테스트와 출시
스토어 정보 준비 → 비공개 테스트 → 정식 공개 권한 → 앱 검토 순서로 진행해요.
이 단계에서는 무엇을 하나요?
스토어 소개와 앱 콘텐츠를 먼저 채우고, 필요한 계정이라면 비공개 테스트를 시작해요. 테스트 조건을 채운 뒤 정식 공개 권한을 신청하고, 승인 후 최종 앱을 제출·검토받아 공개해요. 이 과정은 한 번에 끝나는 버튼 하나가 아니에요.
| 상태 | 뜻 |
|---|---|
| AAB 업로드 | 파일을 콘솔에 보냈어요. 아직 테스터가 설치할 수 있는지는 따로 확인해요. |
| 비공개 테스트 배포 | 참여한 테스터가 Play Store에서 설치할 수 있는 상태예요. |
| 정식 공개 권한 승인 | 해당 계정이 프로덕션 출시를 신청할 수 있어요. |
| 정식 공개 완료 | 일반 사용자가 스토어에서 설치할 수 있어요. |
먼저 준비하고, 테스트하고, 출시해요
- 앱 소개·이미지와 개인정보처리방침, 데이터 보안 답변을 실제 앱에 맞게 준비해요.
- 필요한 계정은 비공개 테스트에 AAB를 올리고 테스터가 직접 참여·설치하게 해요.
- 피드백과 수정 기록을 남기고 Play Console에서 참여 요건을 확인해요.
- 정식 공개 권한을 신청하고, 승인되면 프로덕션 버전을 제출해요.
- 심사·게시 상태를 확인하고, 다른 계정으로 스토어 설치까지 확인해요.
A. 스토어 소개와 앱 콘텐츠 준비하기
스토어에서 보일 소개를 준비해요
사람들이 설치 전에 보는 앱 이름, 이미지, 설명을 준비해요. 이 부분은 개발 중에도 만들 수 있고, 비공개 테스트 전에 필요해요. 최종 스크린샷은 실제 앱과 맞춰 주세요.
| 항목 | 준비할 내용 |
|---|---|
| 앱 이름·설명 | 이 앱이 누구를 위해 무엇을 하는지 설명해요. 글자 수 제한은 콘솔 입력칸에서 확인해요. |
| 앱 아이콘 | 스토어용 512×512px 이미지를 준비해요. 폰의 설치 아이콘 설정과는 별도로 확인해요. |
| 대표 이미지 | 1024×500px 이미지를 준비해요. 배경 투명도·파일 형식 등은 공식 규격과 대조해요. |
| 휴대전화 스크린샷 | 최소 2장을 준비하고, 현재 앱의 핵심 기능이 드러나게 해요. |
| 연락처·국가·가격 | 지원 이메일, 배포할 국가, 무료/유료 여부 등을 정해요. |
실제 앱의 정보 처리와 이용 조건을 알려줘요
개인정보처리방침은 사용자에게 설명하는 문서, 데이터 보안 설문은 구글에 제출하는 답변이에요. 둘 다 실제 앱 동작과 맞아야 해요.
| 콘솔에서 묻는 것 | 무엇을 확인하나요? |
|---|---|
| 개인정보처리방침 | 어떤 정보를 왜 다루고, 어디에 저장·전달하고, 언제 지우는지 등을 설명해요. 누구나 로그인 없이 열 수 있는 웹 주소를 준비하고 앱 안에도 접근 경로를 둬요. |
| 데이터 보안 | 앱 밖으로 보내는 데이터와 제3자 도구의 처리를 확인해요. 로그인 기능이 없더라도 분석·광고 도구가 정보를 보낼 수 있어요. |
| 콘텐츠 등급·대상 연령 | 앱에 실제로 들어 있는 내용과 이용 대상을 기준으로 답해요. |
| 광고·앱 접근 권한 | 광고 유무를 답하고, 로그인이 필요하면 심사자가 사용할 계정과 접근 방법을 제공해요. |
| 추가 항목 | 계정 생성, 결제, 민감한 권한 등 앱 기능에 따라 추가 정책과 설정을 확인해요. |
우리 앱의 실제 코드와 사용 중인 외부 서비스를 확인해서 스토어 신고 준비표를 만들어줘. 데이터 종류 / 기기 안에만 저장하는지 / 외부로 보내는지 / 보내는 곳 / 목적 / 삭제 방법을 정리해줘. 분석·광고·오류 수집 도구도 포함해줘. 코드만으로 알 수 없는 서비스 설정은 “확인 필요”로 남겨줘. 그 표를 바탕으로 개인정보처리방침 초안을 만들고, 실제 운영자가 확인할 질문을 따로 알려줘. 모르는 항목을 임의로 “수집 안 함”으로 쓰지 마.
개인정보처리방침의 웹 주소는 어떻게 만들죠?
문서를 컴퓨터에 저장하는 것만으로는 주소가 생기지 않아요. 웹에 공개해야 해요. 기존 홈페이지를 사용하거나 GitHub Pages 같은 정적 페이지 호스팅을 이용할 수 있어요. 공개 후에는 로그아웃한 브라우저에서도 읽히는지 확인하세요. 데이터가 없는 앱도 데이터 보안 설문과 방침이 필요해요.
B. 필요한 계정은 비공개 테스트하기
이 단계에서는 무엇을 하나요?
정식 공개 전에 지정한 사람에게 테스트 버전을 배포해요. 2023년 11월 13일 이후 만든 개인 개발자 계정은 정식 공개 권한을 신청하기 전에 이 조건을 충족해야 해요. 조직 계정에는 이 신규 개인 계정 조건이 적용되지 않지만 앱 심사는 필요해요.
초대와 실제 참여는 달라요
신청 시점에, 바로 앞의 14일 동안 연속으로 참여 상태를 유지한 테스터가 최소 12명 있어야 해요. 이메일을 등록하거나 APK를 전달한 것만으로는 충족되지 않아요. 테스터가 참여 링크에서 직접 참여해야 해요.
12명 중 한 명이 빠졌다고 모든 사람의 참여 이력이 한꺼번에 삭제된다는 뜻은 아니에요. 새로 들어온 사람의 하루를 기존 사람의 14일로 계산할 수 없다는 뜻이에요. 여유 있게 15~20명을 모집하는 것은 이 가이드의 운영 제안이에요. 공식 조건 확인
테스트를 열기 전에 확인해요
위에서 준비한 스토어 소개와 앱 콘텐츠 설정을 비공개 테스트 전에 완료해야 해요. 비공개 테스트를 시작하려면 앱 설정을 완료해야 하기 때문이에요. 설정이 비어 있다면 앞의 A 항목으로 돌아가 채워요. 앱 소개와 정책 답변은 실제 앱이 바뀌면 다시 확인해요.
따라 할 순서
- Play Console에서 앱을 만들고, 필요한 스토어 정보와 앱 콘텐츠를 입력해요.
- 비공개 테스트(Closed testing)에서 테스트 트랙을 만들어요. 트랙은 앱 버전을 배포할 대상을 나누는 구분이에요.
- 테스터가 Play Store에서 사용하는 Google 계정 이메일을 등록해요. 테스트 대상 국가·지역도 확인해요.
- AAB를 올려 테스트 출시를 만들고, 콘솔이 요구하는 검토·배포 절차를 마쳐요. 파일 업로드 완료와 테스터 설치 가능 상태는 달라요.
- 참여 링크를 전달해요. 테스터가 등록한 계정으로 참여한 다음 Play Store에서 앱을 설치하도록 안내해요.
- 날짜만 기다리지 말고 실제 사용 의견을 모아요. 발견한 문제, 수정한 내용, 다시 확인한 결과를 남겨요.
- 콘솔에서 조건 충족 상태를 확인하고 정식 공개 권한(프로덕션 액세스)을 신청해요. 조건 충족이 자동 승인이나 자동 출시를 뜻하지는 않아요.
내부 테스트와 혼동하지 마세요
내부 테스트는 팀이 빠르게 설치해 보는 데 유용해요. 하지만 위의 12명·14일 비공개 테스트 조건을 대신하지는 못해요.
테스트 기록은 이렇게 남겨요
| 날짜·기기 | 문제 | 수정·재확인 |
|---|---|---|
| 예: 11/3 · Galaxy A 시리즈 | 키보드가 올라오면 저장 버튼을 못 누름 | 입력 화면의 스크롤을 수정하고 같은 폰에서 다시 확인 |
참여 링크가 안 열릴 때
초대한 이메일과 폰의 Play Store 계정이 같은지, 테스트가 실제로 배포됐는지, 해당 국가·기기가 지원되는지 순서대로 확인해요. 링크를 보낸 시각을 14일 시작 시각으로 단정하지 마세요.
여기까지 되면 다음 단계로
Play Console의 비공개 테스트 준비를 도와줘. 현재 앱에 필요한 스토어 정보·앱 콘텐츠 설정과 AAB를 점검해줘. 테스터에게 보낼 참여·설치 안내 문장을 쉬운 말로 써줘. 14일 동안 날짜, 기기, 문제, 수정·재확인 결과를 기록할 표도 만들어줘.
C. 정식 출시 제출하고 공개 확인하기
정식 공개 권한 승인 뒤, 출시를 제출해요
- 위 비공개 테스트가 필요한 계정이라면 정식 공개 권한이 승인됐는지 확인해요. 테스트 내용이나 준비 상태가 부족하면 추가 테스트를 요구받을 수 있어요.
- 프로덕션(Production)에서 정식 출시 버전을 만들어요. 테스트한 버전을 승격하거나 최신 AAB를 올리는 등 콘솔이 제공하는 방법을 사용해요.
- 앱 파일·소개·정책 답변·국가를 다시 확인하고 심사에 제출해요. 공개 권한 신청과 앱 출시 심사는 별개의 절차예요.
- 검토 중인지, 수정이 필요한지, 게시 준비 상태인지 확인해요. 최초 공개는 출시를 시작하면 공개될 수 있으니 제출·게시 화면의 안내를 끝까지 읽어요. 정확한 시각의 공개를 약속하지 마세요.
- 반려되면 사유와 해당 항목을 확인해 고친 후 다시 제출해요. 공개 후에도 오류 문의와 새 버전 업데이트를 관리해요.
출시 완료는 여기서 확인해요
콘솔에 파일이 올라간 것만으로 끝난 게 아니에요. 배포 대상 국가의 다른 사용자가 Play Store에서 앱 페이지를 열고 설치할 수 있는지 확인하세요. 설치한 앱의 버전도 팀이 올린 최신 버전과 비교해요.
여기까지 되면 다음 단계로
승인은 여러 종류예요
PR 승인은 코드 병합 판단, 정식 공개 권한 승인은 해당 계정의 출시 신청 자격, 앱 검토 통과는 제출한 앱과 스토어 정보에 대한 Google Play의 판단이에요. 어느 하나만 끝나도 자동으로 앱이 공개되는 것은 아니에요. 게시 설정과 실제 스토어 상태를 확인하세요.
09. 출시 후 로그를 보고 개선하기
문제의 단서를 찾아 고치고, 새 버전에서 결과를 확인해요.
이 단계에서는 무엇을 하나요?
출시 후 앱을 쓰다가 어디에서 멈추거나 꺼지는지 살펴봐요. 문제를 재현하고, 로그에서 단서를 찾고, 새 브랜치에서 고친 다음 새 버전을 올려 같은 문제가 줄었는지 확인해요.
로그는 어디에서 보나요?
| 도구 | 언제 쓰나요? |
|---|---|
| Android Studio의 Logcat | 내 폰에서 문제를 다시 일으키며 그 순간의 앱 로그를 볼 때 써요. |
| Play Console의 Android vitals | 출시된 앱에서 크래시나 ANR이 여러 사용자에게 반복되는지 볼 때 써요. |
크래시는 앱이 갑자기 꺼지는 일, ANR은 앱이 오랫동안 반응하지 않는 일이에요. 웹 화면 안의 오류는 Android 로그만으로 다 보이지 않을 수도 있어요.
따라 할 순서
- 어떤 폰과 앱 버전에서, 어느 화면의 어떤 버튼을 눌렀는지 적어요.
- 내 폰에서 같은 순서로 다시 해 보고 Android Studio의 Logcat을 열어 오류를 찾아요.
- Play Console의 Android vitals → Crashes and ANRs에서 비슷한 문제가 얼마나 생겼는지 봐요.
- 새 브랜치에서 한 문제만 고치고 정상·실패 상황을 다시 시험해요.
- commit → push → PR → merge 후 새 AAB와 더 큰 versionCode로 업데이트해요.
- 새 버전에서 같은 문제가 줄었는지 다시 확인해요.
오류 문구를 공유할 때 비밀번호, 인증 토큰, 개인정보는 지워요. 로그에 이런 정보를 새로 적지도 마세요.
앱에서 문제가 났어. 아래의 재현 순서와 오류 문구를 보고 원인을 조사해줘. 기기/Android 버전: [입력] 앱 버전: [입력] 한 행동: [입력] 실제로 나온 결과: [입력] 기대한 결과: [입력] Logcat 또는 Play Console의 오류: [비밀 값을 가린 뒤 입력] 먼저 확인할 가설과 직접 시험할 방법을 알려줘. 고친 뒤에는 새 브랜치와 PR로 반영해줘.
여기까지 되면 다음 단계로
출시 일정 잡기
만드는 시간과 기다리는 시간을 따로 적고, 목표일에서 거꾸로 계산해요.
12월 4일 공개를 목표로 한다면
아래는 2026년 12월 4일(금) 공개를 목표로 한 일정 계산 예시예요. 구글이 보장하는 처리 일정이 아니에요. 14일은 참여 조건이고, 인증·검토·추가 수정에는 별도의 시간이 들어가요.
| 목표 시점 | 끝낼 일 |
|---|---|
| 지금부터 | 개발자 계정 인증, 작업 자료 준비, 테스터 모집, 스토어 문구 초안 |
| 10/30까지를 내부 목표로 | 핵심 기능이 동작하는 첫 테스트 버전과 스토어 설정 준비·검토 제출 |
| 11/6까지를 내부 목표로 | 테스터 설치 가능 상태 확인, 필요한 인원의 참여 시작 |
| 11/20 이후 조건 충족 시 | 콘솔에서 14일 조건 충족을 확인하고 정식 공개 권한 신청 |
| 권한 승인 뒤 | 최종 앱의 프로덕션 출시 심사 제출 |
| 12/4 목표 | 심사·게시 상태 확인 후 공개 및 설치 확인 |
일정을 읽는 방법
11월 6일에 참여를 시작했더라도 11월 20일 아침에 무조건 끝나는 것은 아니에요. 참여 시각과 콘솔의 조건 충족 상태를 확인해야 해요. 공개 권한 심사와 앱 심사가 길어지거나 수정이 필요하면 목표일이 밀릴 수 있어요.
시간이 부족하면 무엇을 줄일까요?
테스트 기간을 줄이려고 하기보다 첫 출시의 기능 범위를 줄이세요. 기록 앱이라면 “선택 → 저장 → 다시 보기”를 먼저 완성하고, 공유·통계·꾸미기는 다음 버전으로 미룰 수 있어요. 다만 첫 테스트도 빈 화면이나 눌러도 반응 없는 시안이 아니라, 핵심 흐름을 실제로 사용할 수 있어야 해요.
네 가지 상태는 달라요
| 상태 | 뜻 |
|---|---|
| AAB 업로드 완료 | 구글에 파일을 보낸 상태 |
| 테스트 배포 가능 | 초대한 사람이 설치할 수 있는 상태 |
| 정식 공개 권한 승인 | 프로덕션으로 출시 신청할 수 있는 상태 |
| 정식 공개 완료 | 일반 사용자가 스토어에서 설치할 수 있는 상태 |
여기까지 되면 다음 단계로
첫 테스트 버전은 어느 정도여야 하나요?
첫 비공개 테스트에 올릴 앱이 완벽할 필요는 없지만, 실제로 쓸 수 있는 핵심 흐름은 있어야 해요. 아래는 일정을 세울 때 사용할 수 있는 실무 기준 예시예요.
| 구분 | 첫 테스트 버전 | 정식 출시 전 |
|---|---|---|
| 안정성 | 설치와 실행이 되고 바로 꺼지지 않아요. | 주요 화면에서 크래시와 멈춤이 없어요. |
| 기능 | 핵심 기능 하나를 처음부터 끝까지 사용할 수 있어요. | 기획한 핵심 기능을 테스터가 모두 써 봤어요. |
| 화면 | 버튼을 누를 수 있고 상태바에 가리지 않아요. | 디자인과 크게 다르지 않고 작은 폰에서도 읽기 쉬워요. |
| 스토어 | 테스트 배포에 필요한 소개·정책 답변을 채워요. | 최종 이미지·설명·데이터 답변을 실제 앱과 맞춰요. |
목표일부터 거꾸로 적어 봐요
- 원하는 공개일을 쓰고, 심사나 수정이 늦어질 때를 위한 예비일을 따로 둬요.
- 앱 제출 전 필요한 정식 공개 권한 신청일을 정해요.
- 해당 계정이라면 12명의 연속 참여 14일이 언제 끝나는지 거꾸로 계산해요.
- 테스터가 설치할 수 있는 시점보다 앞서 첫 AAB와 스토어 설정을 준비해요.
- 개발자 계정 인증, 스토어 이미지·설명, 개인정보처리방침을 앱 개발과 함께 준비해요.
심사 기간은 확정된 약속이 아니에요. 참여가 늦거나 수정 요청을 받으면 계획을 다시 계산해요.
목표 공개일은 [날짜]야. 새 개인 개발자 계정인지 먼저 확인하고, 필요한 테스트·권한 신청·앱 심사 시간을 나눠서 역산해줘. 확정된 조건과 우리가 여유로 잡은 기간을 구분하고, 첫 테스트 버전에 필요한 최소 기능도 적어줘.
공식 자료와 확인할 정책
정책·규격·콘솔 메뉴는 바뀔 수 있어요. 실제 제출할 때 현재 안내를 다시 확인하세요.
버전과 변경 기록 · 웹 게시 v1.0
2026.10.27 · v1.0 — 최신 10단계 HTML을 웹 게시 기준본으로 지정했어요. 단계별 본문·예시·기능은 유지하고, 게시본의 버전 표시와 변경 기록을 추가했어요.