Android 앱 작업공간 준비 1단계: GitHub와 SSH

바이브코딩으로 앱을 만들 수 있다는 이야기는 많이 들어봤지만, 막상 직접 시작하려고 하면 어디서부터 손대야 할지 막막합니다. 이번 시리즈에서는 간단한 시연용 앱이 아니라 실제 배포와 운영을 고려한 Markdown Viewer를 만들어봅니다. 그 첫 단계가 Android 앱 작업공간 준비입니다.

시리즈 1편에서는 우리가 만들 앱과 Markdown의 관계를 먼저 짚어봅니다. 그다음 GitHub에 비공개 저장소를 만들고 SSH로 내 PC에 clone합니다. 여기까지 끝나면 이후의 명령과 Codex·Claude Code 작업은 모두 clone한 폴더에서 진행합니다.

Table of Contents

Android 앱 작업공간 준비 전에 확인할 것

Linux 또는 Windows PC에 Codex나 Claude Code 같은 AI 코딩 에이전트가 설치되어 있어야 합니다. 폴더를 만들고 이동하거나 명령 한 줄을 실행하는 정도의 터미널 사용법도 알고 있어야 합니다.

Codex·Claude Code 설치법과 계정 요금제 선택은 이 시리즈의 범위에서 제외합니다. Android Studio 또는 VS Code도 사용할 수 있어야 하지만, Android SDK와 JDK의 세부 버전까지 미리 맞출 필요는 없습니다. 개발 도구의 호환 조합은 2편에서 점검합니다.

GitHub 계정에는 로그인할 수 있어야 합니다. Linux 터미널이나 Windows PowerShell에서 git --version을 실행했을 때 버전 번호가 나오면 Git도 준비된 것입니다.

git --version

우리가 만들 앱은 Markdown Viewer다

우리가 만들 Markdown Viewer가 여는 파일은 이름 끝에 .md가 붙습니다. 파일 안에는 일반 텍스트와 함께 제목, 목록, 링크, 굵은 글씨, 코드 블록, 표를 나타내는 기호가 들어갑니다. 이처럼 몇 가지 기호로 문서 구조를 표현하는 형식이 Markdown입니다. 메모장이나 코드 편집기만 있어도 내용을 열어볼 수 있습니다.

다만 일반 텍스트 편집기로 .md 파일을 열면 #, -, **, 코드 블록을 나타내는 백틱 같은 문법 기호가 원문에 그대로 보입니다. 문서 구조를 표현하는 데 필요한 기호지만, 내용을 읽기만 하려는 사람에게는 화면이 복잡해 보일 수 있습니다.

우리가 만들 앱은 이 기호를 화면에 그대로 늘어놓지 않습니다. 파일의 문법을 해석해 제목은 제목답게, 목록은 가지런한 목록으로, 굵은 글씨와 코드 블록은 각각 알맞은 형태로 그려줍니다. 원본 .md 파일을 바꾸는 것이 아니라 작성자가 의도한 구조에 따라 읽기 좋은 화면으로 렌더링해 보여주는 앱입니다.

# 오늘 할 일

Markdown Viewer 프로젝트를 시작합니다.

- 비공개 저장소 만들기
- SSH 키 등록하기
- 저장소 clone하기

**완료 조건:** 로컬 폴더에서 저장소를 열 수 있다.

```kotlin
println("Hello Markdown")
```

위 예시에서 #은 제목, -는 목록, **는 굵은 글씨를 뜻합니다. Markdown Viewer는 이런 기호를 Markdown Parser로 해석한 뒤 제목과 목록에 맞는 화면 요소로 바꿉니다.

Markdown 원문의 제목 목록 링크 코드 표가 파서를 거쳐 스마트폰의 읽기 좋은 문서로 렌더링되는 과정 — Markdown은 기호가 포함된 일반 텍스트를 파싱해 제목, 목록, 코드와 표가 있는 문서로 보여줍니다.

Markdown 문법을 전부 외울 필요는 없습니다. 제목, 문단, 목록, 링크, 코드 블록 정도를 알아보고 수정할 수 있으면 충분합니다. 어떤 파일을 열어 어떤 모습으로 보여줄지 분명히 알고 있으면 이후 구현 결과도 직접 판단할 수 있습니다.

Markdown Viewer가 화면에 보여주는 개략적인 과정

파일 관리자나 공유 기능에서 .md 파일을 받습니다.
Android가 전달한 Content URI에서 텍스트를 안전하게 읽습니다.
Markdown Parser가 제목, 문단, 목록, 코드, 표의 구조를 해석합니다.
해석 결과를 Jetpack Compose 화면 요소로 바꿉니다.
한글, 긴 문서, 링크, Dark Mode 같은 조건에서도 읽기 좋게 렌더링합니다.

이 내부 동작을 지금 모두 이해하거나 직접 구현할 필요는 없습니다. 다만 “파일 입력 → 파싱 → 화면 렌더링 → 검증”이라는 흐름은 알고 있어야 AI가 제안한 구조가 우리가 원하는 앱에 맞는지 판단할 수 있습니다. 세부 기술을 외우는 것보다 어떤 파일을 받아서 어떤 화면을 보여줄 것인지 분명히 아는 일이 먼저입니다.

Git과 GitHub는 무엇이 다른가

프로젝트 파일을 만들기 시작하면 변경 이력도 함께 관리해야 합니다. Git은 언제 어떤 파일을 바꾸었는지 내 PC에 기록합니다. 작업 단위를 commit으로 남겨두면 문제가 생겼을 때 이전 상태와 비교하거나 되돌릴 수 있습니다.

GitHub는 그 Git 저장소를 원격 서버에 보관합니다. 내 PC만 사용해도 개발은 가능하지만, 디스크 고장이나 실수에 대비하려면 원격 저장소가 있는 편이 낫습니다. 한 단계의 작업을 마칠 때마다 GitHub로 push하면 그 시점의 결과도 함께 남습니다.

repository: 프로젝트 파일과 변경 이력을 담는 저장소
commit: 하나의 의미 있는 작업 단위를 기록한 시점
push: 내 PC의 commit을 GitHub 원격 저장소로 보내기
pull: GitHub의 새 변경 이력을 내 PC로 가져오기
clone: 원격 저장소와 전체 이력을 내 PC에 처음 복제하기

GitHub 비공개 저장소 만들기

아직 공개할 준비가 되지 않은 소스와 개발 문서가 인터넷에 노출되지 않도록 비공개 저장소(Private Repository)로 시작합니다. 이후에는 비공개 저장소라고 부르겠습니다. 소유자와 접근 권한을 받은 사용자만 저장소를 볼 수 있습니다.

GitHub에 로그인하고 우측 상단 + 메뉴에서 New repository를 선택합니다.
Owner가 자신의 GitHub 계정인지 확인합니다.
Repository name에 markdown-viewer를 입력합니다.
Visibility에서 Private를 선택합니다.
Add a README file, .gitignore, License는 선택하지 않습니다.
Create repository를 눌러 빈 저장소를 만듭니다.

초기 파일을 선택하지 않는 이유는 다음 편에서 AI가 Android 프로젝트 구조와 관리문서를 한 번에 만들도록 하기 위해서입니다. 저장소 화면에서 Code → Local → SSH를 선택하면 다음 형식의 주소가 보입니다.

git@github.com:USERNAME/markdown-viewer.git

USERNAME은 자신의 GitHub 사용자 이름입니다. 화면에 보이는 SSH 주소를 사용하면 오타를 줄일 수 있습니다.

SSH 키를 만들고 GitHub에 등록하기

비공개 저장소는 아무나 clone하거나 push할 수 없습니다. GitHub는 접속한 PC가 저장소 소유자의 허가를 받은 PC인지 확인해야 합니다. 이때 SSH 키 쌍을 사용합니다.

id_ed25519는 PC에만 보관해야 하는 개인키이고, id_ed25519.pub는 GitHub에 등록하는 공개키입니다. 공개키는 자물쇠에 가깝고 개인키는 그 자물쇠를 여는 열쇠에 가깝습니다.

개인키 내용은 GitHub, AI 프롬프트, 메신저, 블로그 어디에도 붙여 넣으면 안 됩니다. GitHub에 등록하는 파일은 이름 끝에 .pub가 붙은 공개키뿐입니다.

개인키는 내 PC에 보관하고 공개키만 GitHub 비공개 저장소에 등록한 뒤 프로젝트를 clone하는 SSH 흐름 — 개인키는 PC 밖으로 내보내지 않고 공개키만 GitHub에 등록한 뒤 SSH로 저장소를 clone합니다.

1. 기존 SSH 키 확인

운영체제에 맞는 명령으로 .ssh 폴더부터 확인합니다.

# Linux
ls -al ~/.ssh

# Windows PowerShell
Get-ChildItem $env:USERPROFILE/.ssh

id_ed25519와 id_ed25519.pub가 보이면 기존 키가 있는 것입니다. 기존 키가 어떤 서비스에 사용되는지 모른다면 덮어쓰지 않습니다. 파일이나 폴더가 없어도 오류가 아니라 아직 키를 만들지 않았다는 뜻입니다.

2. ed25519 SSH 키 생성

새 키를 만드는 명령은 Linux 터미널과 Windows PowerShell에서 같습니다. 이메일은 자신의 GitHub 계정 이메일로 바꿉니다.

ssh-keygen -t ed25519 -C "your-email@example.com"

Enter file in which to save the key가 나오면 기존 키가 없는 경우 Enter를 눌러 기본 경로를 사용합니다. 이어서 키를 보호할 암호(passphrase)를 설정할 수 있습니다. 비워둘 수도 있지만, PC를 분실했을 때 개인키가 곧바로 사용되는 것을 막으려면 암호를 설정하는 편이 안전합니다.

기존 파일을 덮어쓸지 묻는 메시지가 나오면 n을 입력해 중단합니다. 기존 키를 지우지 말고 id_ed25519_github처럼 별도 파일명을 사용합니다. 별도 이름으로 만들었다면 아래의 ssh-add, cat, Get-Content 명령에 있는 id_ed25519도 같은 이름으로 바꿔야 합니다. 파일명은 알려줘도 되지만 개인키 내용은 AI에게 보여주지 않습니다.

3. ssh-agent에 키 등록

Linux에서는 ssh-agent를 시작하고 개인키를 등록합니다.

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Windows에서는 관리자 권한 PowerShell을 한 번 열어 OpenSSH Authentication Agent의 시작 유형을 설정하고 서비스를 시작합니다.

Get-Service -Name ssh-agent | Set-Service -StartupType Manual
Start-Service ssh-agent

서비스가 시작되면 관리자 PowerShell을 닫고 일반 PowerShell에서 개인키를 Agent에 등록합니다.

ssh-add $env:USERPROFILE/.ssh/id_ed25519

회사나 학교에서 관리하는 PC는 서비스 설정을 바꾸기 전에 조직의 보안 정책을 우선합니다. Git for Windows의 SSH와 Windows OpenSSH가 함께 설치된 환경에서 push할 때 암호를 계속 묻는다면, 두 프로그램이 서로 다른 SSH 실행 파일을 사용하고 있는지도 확인해야 합니다.

4. 공개키 내용 복사

공개키를 복사할 때도 운영체제에 맞는 명령 하나만 실행합니다.

# Linux
cat ~/.ssh/id_ed25519.pub

# Windows PowerShell
Get-Content $env:USERPROFILE/.ssh/id_ed25519.pub

보통 ssh-ed25519로 시작해 이메일 설명으로 끝나는 한 줄이 출력됩니다. 이 한 줄 전체를 복사합니다. .pub가 없는 개인키 파일은 열거나 복사하지 않습니다.

5. GitHub에 공개키 등록

GitHub 우측 상단 프로필 사진에서 Settings를 선택합니다.
SSH and GPG keys로 이동합니다.
New SSH key를 선택합니다.
Title에는 My Windows PC 또는 Linux Development PC처럼 알아볼 수 있는 이름을 적습니다.
Key type은 Authentication Key를 선택합니다.
Key에 앞에서 복사한 .pub 공개키 한 줄을 붙여 넣고 저장합니다.

6. SSH 인증 시험

ssh -T git@github.com

처음 연결할 때 호스트를 신뢰할지 묻는 메시지가 나오면 접속 대상이 github.com인지 확인합니다. 화면에 표시된 키 지문이 GitHub가 공개한 SSH 키 지문과 일치할 때만 yes를 입력합니다.

결과 메시지에 자신의 GitHub 사용자 이름과 인증 성공 안내가 나오면 연결된 것입니다. GitHub는 SSH 셸을 제공하지 않으므로 이 테스트는 성공해도 종료 코드 1을 반환합니다. 종료 코드만 보고 실패로 판단하지 말고 사용자 이름이 포함된 성공 메시지를 확인합니다.

비공개 저장소를 내 PC로 clone하기

이제 앱 프로젝트를 둘 작업 공간을 만듭니다. 나중에 생성할 릴리스 키스토어가 앱 저장소에 들어가지 않도록 키스토어 보관 폴더도 처음부터 따로 만듭니다.

Linux

mkdir -p ~/workspace/keystores
cd ~/workspace
git clone git@github.com:USERNAME/markdown-viewer.git
cd markdown-viewer
git remote -v

Windows PowerShell

New-Item -ItemType Directory -Force D:/workspace/keystores
Set-Location D:/workspace
git clone git@github.com:USERNAME/markdown-viewer.git
Set-Location markdown-viewer
git remote -v

USERNAME은 자신의 GitHub 사용자 이름으로 바꿉니다. 저장소가 비어 있다는 경고는 정상입니다. git remote -v 결과의 fetch와 push 주소가 모두 git@github.com:USERNAME/markdown-viewer.git 형식이면 SSH 주소로 올바르게 연결된 것입니다.

workspace/
    ├── markdown-viewer/  # Git으로 관리할 앱 프로젝트
    └── keystores/       # Git 저장소 밖에서 별도 보관

clone이 실패할 때 확인할 것

ssh -T git@github.com 결과에 사용자 이름과 인증 성공 안내가 표시되는가
GitHub에 등록한 키가 .pub 공개키인가
ssh-add로 현재 개인키를 ssh-agent에 등록했는가
clone 주소가 https://가 아닌 git@github.com: 형식인가
GitHub 사용자 이름과 저장소 이름에 오타가 없는가
저장소가 비공개로 생성되었고 현재 계정이 소유자인가

앞으로는 clone한 폴더에서 작업한다

clone이 끝나면 내 PC에 markdown-viewer 폴더가 생깁니다. 앞으로 이 시리즈의 모든 명령과 AI 작업은 이 폴더 안에서 진행합니다. 위의 Linux와 Windows 명령은 마지막에 이미 markdown-viewer 폴더로 이동하도록 작성되어 있습니다.

현재 위치가 맞는지 확인하려면 Linux에서는 pwd, Windows PowerShell에서는 Get-Location을 실행합니다. 이어서 git status를 실행했을 때 Git 저장소라는 결과가 나오면 작업 위치가 맞습니다.

터미널에서 Codex 또는 Claude Code 실행하기

현재 위치가 markdown-viewer 폴더인지 확인한 다음 사용할 AI 코딩 에이전트를 실행합니다.

Linux 터미널:

pwd
git status
codex # Claude Code를 사용하면 claude

Windows PowerShell:

Get-Location
git status
codex # Claude Code를 사용하면 claude

Android Studio나 VS Code에서 실행하기

IDE를 사용한다면 먼저 markdown-viewer 폴더를 프로젝트 폴더로 엽니다. Android Studio에서는 Open으로 이 폴더를 선택하고, VS Code에서는 Open Folder로 엽니다. 그다음 IDE의 내장 터미널에서 Codex나 Claude Code를 실행하거나, 설치해 둔 AI 확장 기능을 이 작업 공간에서 사용합니다.

workspace 같은 상위 폴더에서 AI 도구를 실행하면 다른 프로젝트 파일까지 작업 범위에 들어갈 수 있습니다. 프롬프트를 입력하기 전에는 현재 열린 폴더가 항상 markdown-viewer인지 확인합니다.

준비 상태를 확인할 때 사용할 실제 프롬프트

아래 첫 번째 프롬프트는 SSH 키를 만들기 전이나 인증이 되지 않을 때 사용합니다. 두 번째 프롬프트는 clone을 마치고 markdown-viewer 폴더로 이동한 뒤 사용합니다. 점검 과정에서도 개인키의 내용은 AI에게 보여주지 않습니다.

Git과 SSH 준비 상태 점검

현재 PC에서 GitHub 비공개 저장소를 SSH로 사용할 준비가 되었는지 점검해줘.

확인할 항목:
- 운영체제와 셸 종류
- Git 설치 및 버전
- 사용자 홈의 .ssh 폴더
- ed25519 공개키와 개인키 존재 여부
- ssh-agent 실행 상태
- ssh-add에 등록된 키
- ssh -T git@github.com 인증 결과

중요:
- 기존 SSH 키를 삭제하거나 덮어쓰지 마.
- 키 파일명이 id_ed25519가 아니라면 이후 모든 명령에 실제 파일명을 사용해.
- 개인키 내용은 절대로 화면이나 문서에 출력하지 마.
- GitHub에는 .pub 공개키만 등록한다고 설명해.
- 첫 연결에서는 GitHub 공식 문서의 SSH 키 지문과 화면의 지문을 비교해.
- ssh -T는 인증에 성공해도 종료 코드 1을 반환할 수 있어.
  종료 코드만 보지 말고 사용자 이름이 포함된 인증 성공 메시지로 판단해.
- 변경이 필요하면 실행 전에 무엇을 바꾸는지 먼저 설명해.
- 사용자가 GitHub 웹 화면에서 직접 해야 할 작업은 별도로 구분해.
- 마지막에 성공 항목, 미완료 항목, 다음 행동을 정리해.

저장소 clone 결과 점검

현재 폴더가 markdown-viewer Git 저장소인지 점검해줘.

다음을 실제 명령으로 확인해.
- 현재 절대 경로
- git status
- git remote -v
- 원격 주소가 SSH 형식인지
- 원격 저장소 이름이 markdown-viewer인지
- 저장소가 비어 있는 초기 상태인지

검사만 수행하고 아직 Android 프로젝트나 파일은 만들지 마.
민감한 정보나 개인키 내용은 출력하지 마.
결과를 통과, 주의, 실패로 나눠 설명해.

1편 완료 체크리스트

Markdown의 제목, 목록, 굵은 글씨, 코드 블록을 구분할 수 있다.
Git과 GitHub, commit, push, clone의 차이를 설명할 수 있다.
GitHub에 markdown-viewer 비공개 저장소를 만들었다.
개인키와 공개키의 차이를 이해하고 개인키를 외부에 공유하지 않았다.
.pub 공개키만 GitHub SSH and GPG keys에 등록했다.
ssh -T git@github.com 결과에서 사용자 이름과 인증 성공 메시지를 확인했다.
SSH 주소로 저장소를 clone하고 git remote -v를 확인했다.
앱 저장소와 키스토어 보관 폴더를 분리했다.
markdown-viewer 폴더에서 Codex 또는 Claude Code를 실행할 수 있다.
아직 Android 프로젝트 구현은 시작하지 않았다.

다음 편에서 할 일

여기까지 마쳤다면 GitHub의 빈 저장소가 내 PC의 markdown-viewer 폴더와 연결된 상태입니다. 이제 이 폴더에서 실전 바이브코딩 #2: Markdown Viewer MVP와 ROADMAP 설계하기를 이어갑니다. 다음 편에서는 프로덕션 수준의 Markdown Viewer라는 목표를 구체화하고 Android 개발환경을 점검한 뒤 DEVELOPMENT_ENVIRONMENT.md, MVP.md, ROADMAP.md를 작성합니다.

함께 읽을 글과 공식 문서

Previous Git 코딩 일지: 1인 개발자를 위한 백업과 되돌리기 3가지 개념

Next 실전 바이브코딩 #2: Markdown Viewer MVP와 ROADMAP 설계하기

실전 바이브코딩 #1: GitHub와 SSH로 Android 앱 작업공간 준비하기