깃허브에 올린 거 어떻게 쓰는 거예요? — 코딩 한 줄 안 해본 사람을 위한 정리

• 목록
• 답변
• 글쓰기

요즘 만나는 사람마다 묻습니다. “깃허브에 올린 거 어떻게 쓰는 거예요?” 그래서 한 번에 정리했습니다. 코딩을 한 줄도 안 해본 사람 기준입니다.

먼저, 코드부터 짜지 마십시오

대부분 여기서 망합니다. AI에게 “이런 앱 만들어줘” 하고 바로 코드를 뽑습니다. 처음 30분은 마법 같습니다. 그리고 세 시간 뒤에는 뭐가 어디 있는지 아무도 모릅니다. AI도 모르고 나도 모릅니다.

집을 짓는데 설계도 없이 벽돌부터 쌓는 것과 같습니다.

먼저 만들 것은 문서 세 개입니다

Concept.md — 뭘 만들 건지. 머릿속에 떠오른 걸 두세 줄로 던지면 됩니다.

동네 헬스장 회원 관리하는 앱 만들고 싶어.
이거 구현하는 절차랑 방법을 Concept.md로 정리해줘.

AI가 문서를 뱉습니다. 저장해 둡니다.

Design.md — 어떻게 보일 건지. 마음에 드는 사이트를 하나 고릅니다.

이 사이트의 레이아웃, 색상 코드, 폰트, 여백 규칙을 분석해서
Design.md로 정리해줘.

이게 없으면 화면을 만들 때마다 디자인이 달라집니다. “그 사이트처럼 해줘”는 말할 때마다 다른 결과가 나옵니다. 문서로 못을 박아야 고정됩니다.

ToDo.md — 어떤 순서로 만들 건지. 여기서는 판단 자체를 AI에게 넘깁니다.

이걸 웹으로 만드는 게 좋을지, 앱으로 만드는 게 좋을지 추천해줘.
웹이면 React, 모바일 앱이면 Flutter로.
서버랑 DB가 필요한지도 판단해서 정해줘.
로컬에서 바로 설치하고 실행할 수 있는 setup 스크립트도 포함해서,
Concept.md 보고 ToDo.md 작성해줘.

기술 용어를 몰라도 됩니다. 모르는 걸 아는 척하지 않고 판단을 넘기는 문장입니다.

설치할 것은 딱 두 개

Git과 VS Code. 둘 다 무료고, 설치 화면에서 “다음”만 계속 누르면 됩니다. 맥은 터미널에 git --version을 치면 설치하겠냐고 알아서 물어봅니다.

그리고 깃허브에 가입합니다. 저장소(Repository)를 하나 만듭니다. 프로젝트 하나를 담는 클라우드 폴더라고 생각하면 됩니다. 만들 때 “Add a README file”만 체크하고, 회사 일이면 무조건 Private으로 둡니다.

VS Code에서 Ctrl+Shift+P(맥은 Cmd+Shift+P) → clone 입력 → 저장소 주소 붙여넣기. 이러면 내 컴퓨터에 폴더가 하나 생깁니다. 여기에 아까 만든 문서 세 개를 넣고, 왼쪽 가지 모양 아이콘을 눌러 Commit → Sync Changes. 끝입니다. 명령어는 한 줄도 안 쳤습니다.

여기서부터가 진짜입니다

먼저 알아야 할 조건이 있습니다. 브라우저에서 도는 클로드 코드(claude.ai/code)는 공식 문서 기준 리서치 프리뷰이고, Pro·Max·Team 요금제에서 열립니다(기업 요금제는 별도 좌석 조건). 무료 계정으로는 이 단계에서 막힙니다. 여기까지 따라왔는데 화면이 안 나오면 실력 문제가 아니라 요금제 문제입니다.

claude.ai/code에 들어가 로그인합니다. 맥과 윈도우에서는 첫 화면이 데스크톱 앱 설치를 권합니다. 브라우저에서 계속하려면 아래쪽 Continue on web을 누릅니다. 그다음 깃허브 연결을 요청하는데, 승인하면 됩니다. Pro와 Max는 실행 환경(Default)이 자동으로 만들어집니다.

저장소를 고르고, 이렇게 말합니다.

저장소의 Concept.md, ToDo.md, Design.md를 기준으로 개발해줘.
ToDo.md 순서대로 한 번에 한 모듈씩.
테스트 가능한 단위가 끝나면 내 PC에서 실행하는 방법을
비개발자한테 설명하듯이 알려줘.
불명확한 게 있으면 추측하지 말고 나한테 질문해.

마지막 문장이 제일 중요합니다. 이게 없으면 AI가 혼자 상상해서 만듭니다.

처음이라면 Plan 모드로 시작하십시오. 입력창 옆 모드 선택에 있습니다. 파일을 고치기 전에 “이렇게 하겠습니다”를 먼저 보여 주고 내 승인을 기다립니다. 뭘 하려는지 보고 나서 보내는 게, 다 만들어 놓은 걸 되돌리는 것보다 훨씬 쌉니다.

브랜치 — 이거 하나만 알면 됩니다

main은 진열대. 항상 잘 돌아가는 완성본이 있는 곳입니다.
작업 브랜치는 공사장. 여기서는 뭘 부숴도 진열대가 멀쩡합니다.

클로드 코드는 작업마다 따로 브랜치를 만들어 거기서 일하고, 끝나면 그 브랜치를 깃허브에 올립니다. 나는 바뀐 내용을 보고, 마음에 들면 Create PR을 눌러 진열대로 옮깁니다. 그래서 뭘 시켜도 기존 게 망가질 걱정이 없습니다.

바뀐 내용을 볼 때 줄을 골라 바로 의견을 달 수 있습니다. “여기 이렇게 하지 마”라고 그 줄에 적으면, 다음 메시지에 같이 전달됩니다. 어디가 문제인지 말로 설명할 필요가 없습니다.

창을 닫아도 작업은 계속 돕니다. 나갔다 와서 결과만 봐도 됩니다.

에러가 나면

요약하지 마십시오. 화면에 뜬 빨간 글씨를 통째로 복사해서 붙여넣습니다. 그게 제일 정확합니다. 사람이 요약하는 순간 원인을 알려 주는 줄이 빠집니다.

그런데 여기까지 코딩 실력이 필요했습니까

필요했던 것은 두 가지입니다. 뭘 만들고 싶은지 설명하는 능력, 그리고 이상하면 이상하다고 말하는 능력. 기획자가 오랫동안 해 오던 일과 정확히 같습니다.

문서를 먼저 쓰라는 것도 결국 같은 이야기입니다. 코드를 못 짜서 AI를 못 쓰는 게 아니라, 생각이 정리 안 된 채로 AI를 쓰니까 망하는 겁니다.

만들고 싶다면 이 글을 저장해 두고 오늘 첫 문서 하나만 써 보십시오. Concept.md 하나면 됩니다.

확인하지 못한 것
요금제와 리서치 프리뷰 조건은 앞으로 바뀔 수 있습니다. 시작하기 전에 공식 문서를 한 번 더 확인하십시오. React와 Flutter를 고르는 기준은 이 글에서 다루지 않았습니다. 그 판단은 AI에게 넘기는 것으로 갈음했습니다. 저희가 이 순서대로 만든 결과물의 완성도를 측정한 자료는 없습니다.

출처 · 클로드 코드 공식 문서 Get started with Claude Code on the web (2026-09-02 확인)

→ 모르는 말이 나왔다면 AI 용어 사전에서 ‘바이브 코딩’, ‘에이전트’, ‘컨텍스트 창’을 찾아보십시오.
→ AI 쓰면서 흔히 하는 실수도 함께 보시면 좋습니다.