도키피디아 v1.3

깃허브는 이미
쓰고 계십니다.
모르고 계실 뿐이죠.

클로드코드와 코덱스는 여러분 대신 커밋하고, 푸시하고, 되돌립니다. 그래서 이 문서는 깃 명령어를 가르치지 않습니다. AI에게 뭐라고 말해야 하는지, 그리고 AI가 대신 못 해주는 것이 무엇인지만 다룹니다.

2026.08 기준 · 화면은 바뀔 수 있습니다

00 — 왜 알아야 하나

"클로드코드가 알아서 해주던데요?"

맞습니다. 사고가 나기 전까지는요.

AI에게 코딩을 맡기면 깃허브 작업도 같이 맡겨집니다. 편합니다. 문제는 사고도 AI 손에서 난다는 점입니다. API 키가 들어간 파일이 그대로 올라가고, 멀쩡하던 코드가 덮어씌워지고, 학생 명단이 공개 저장소에 올라갑니다. AI는 시킨 대로 했을 뿐이고요.

그래서 필요한 건 깃 실력이 아니라 세 가지 감각입니다. 무엇을 요청해야 하는지, 무엇은 내가 직접 해야 하는지, 그리고 뭐가 잘못됐을 때 어떻게 말해야 하는지.

이건 누가 하나요

하고 싶은 일을 눌러보세요.

위에서 하나를 골라주세요.

5분 요약

한 문장	뜻
커밋	게임의 세이브. 여기까지는 안전하다고 표시해두는 것
푸시	내 컴퓨터의 세이브 파일을 깃허브(인터넷)로 올리는 것
저장소	프로젝트 하나가 통째로 들어가는 폴더. 공개/비공개 선택
.gitignore	"이 파일들은 절대 올리지 마" 목록. 가장 중요합니다
브랜치	원본을 건드리지 않고 따로 작업하는 사본

이 다섯 개만 알면 1~4부는 다 읽으실 수 있습니다.

01 — 가입과 시작

AI가 대신 못 해주는 건 딱 세 가지

나머지는 전부 말로 시키면 됩니다. 그래서 이 장은 짧습니다.

손으로 해야 하는 것 · 딱 3개

AI가 대신 못 합니다

계정 만들기이메일 인증 · 캡차 · 사용자명 결정

2단계 인증(2FA) 켜기휴대폰 인증앱 + 복구코드 저장

브라우저에서 Authorize 누르기연결할 때 딱 한 번. 여기서 다들 멈춥니다

→

말하면 되는 것 · 나머지 전부

클로드코드 · 코덱스에게

저장소 만들기와 올리기
.gitignore 만들기
커밋 · 푸시 · 되돌리기
브랜치 · 합치기 · 충돌 해결
오픈소스 가져와 붙이기

전부 문장으로 요청하면 됩니다

이 노란색·파란색 구분은 문서 전체에서 계속 쓰입니다. 노란 칸이 보이면 손을 움직여야 한다는 뜻입니다.

준비 · 계정 만들기 전에 5초만

손으로

이메일은 개인 메일로, 사용자명은 영문 이름으로

계정의 주 이메일은 개인 메일로 하세요. 학교 메일로 만들면 전출·퇴직 때 계정이 통째로 곤란해집니다. 학교 메일은 나중에 추가 등록만 해두면 7부 교사 인증에 그대로 쓸 수 있습니다.

사용자명은 재직증명서에 찍히는 영문 이름과 비슷하게 잡아두면 교사 인증 심사가 수월했다는 후기가 많습니다.

1 · 계정 만들기

github.com에서 Sign up
개인 메일 주소, 비밀번호, 사용자명을 입력합니다.
퍼즐 캡차
동물 방향 맞추기 같은 게 나옵니다. 당황하지 마세요. 정상입니다.
메일로 온 8자리 코드 입력
안 오면 스팸함을 확인하세요.
학교 메일 추가 등록
Settings → Emails → Add email address. 인증 메일까지 눌러야 등록이 끝납니다.

2 · 2단계 인증(2FA) 켜기 — 건너뛰지 마세요

복구코드를 저장하지 않으면 계정을 잃습니다. 휴대폰을 바꾸거나 잃어버리면 로그인이 영영 막힙니다. 인증앱을 연결한 직후 나오는 복구코드 화면을 반드시 캡처하거나 인쇄해서 따로 보관하세요. 학교 컴퓨터 바탕화면 말고요.

인증앱은 아무거나 괜찮습니다. 학교에서 지급한 폰이 없다면 개인 폰에 설치하시면 됩니다.

3 · 내 컴퓨터와 연결하기

여기가 초심자 이탈 1순위 구간입니다. 그런데 명령어를 외울 필요는 없습니다. 클로드코드나 코덱스에게 그냥 이렇게 말하세요.

이렇게 말하세요

깃허브 계정은 만들어뒀어. 이 컴퓨터랑 연결해줘. 중간에 내가 브라우저에서 해야 할 게 있으면 멈추고 알려줘.

마지막 문장이 핵심입니다. 이 한 줄을 붙이면 AI가 멈춰서 "이제 브라우저에서 이걸 누르세요"라고 알려줍니다.

터미널파를 위한 명령

$ gh auth login # GitHub.com → HTTPS → 브라우저 인증 순서로 선택

화면이 이렇게 멈추면, 고장 난 게 아닙니다

! First copy your one-time code: A1B2-C3D4 Press Enter to open github.com in your browser... ▍

지금 멈춘 게 아니라, 당신을 기다리는 중입니다. 화면에 뜬 8자리 코드를 복사 → 엔터를 누르면 브라우저가 열립니다 → 코드를 붙여넣고 → 초록색 Authorize 버튼을 누르세요. 터미널로 돌아오면 알아서 진행됩니다.

① 터미널A1B2-C3D4코드를 복사

→

② 엔터브라우저가 열림자동으로 열립니다

→

③ 붙여넣기코드 입력복사해둔 8자리

→

④ 마지막Authorize 클릭초록색 버튼

연결은 처음 한 번뿐입니다. 이 네 단계만 넘기면 이후로는 전부 말로 시킬 수 있습니다.

비밀번호로는 안 올라갑니다. 예전 방식대로 아이디·비밀번호를 넣으면 거부당합니다. 위 방식(브라우저 인증)이나 GitHub Desktop을 쓰셔야 합니다. 이건 깃허브 정책이라 어쩔 수 없습니다.

4 · 첫 저장소 만들고 올리기

깃허브 웹사이트에서 저장소를 먼저 만들지 마세요. README에 체크하고 만들면 첫 업로드에서 충돌이 나서 초심자는 손도 못 댑니다. 내 폴더 → AI에게 요청 한 갈래로만 가세요.

이렇게 말하세요

이 폴더를 깃허브 비공개 저장소로 올려줘. 먼저 .gitignore를 만들어서 .env나 키가 들어간 파일은 절대 안 올라가게 하고, 뭐가 올라갈지 목록부터 보여줘.

"목록부터 보여줘"가 3부에서 다룰 사고를 절반은 막아줍니다.

터미널파를 위한 명령

$ git init $ git add . $ git status # 뭐가 올라갈지 확인 $ git commit -m "첫 업로드" $ gh repo create 이름 --private --source=. --push

5 · 저장하고 이어가기

이렇게 말하세요

여기까지 잘 되니까 커밋해줘. 뭐가 바뀌었는지 한 줄로 요약해서 메시지 달아줘.

터미널파를 위한 명령

$ git add . && git commit -m "메시지" $ git push

GitHub Desktop은 필수가 아닙니다

AI가 다 해주는 흐름에서는 프로그램이 하나 더 느는 것뿐입니다. 다만 "내 눈으로 확인하는 창"으로는 꽤 좋습니다. 뭐가 바뀌었는지 색으로 보여주고, 실수한 파일을 클릭 한 번으로 되돌릴 수 있습니다. 불안하신 분만 설치하세요. 선택 사항입니다.

코덱스를 웹으로 쓰신다면확인 필요
브라우저에서 쓰는 코덱스는 깃허브 계정을 먼저 연결해야 하고, 어떤 저장소에 접근을 허용할지 고르는 화면이 따로 나옵니다. 터미널에서 쓰는 도구들과 순서가 다르니, 본인이 쓰는 도구 화면 기준으로 진행하세요.

02 — 용어 사전

커밋은 세이브, 푸시는 업로드

외울 필요 없습니다. AI가 말할 때 알아듣기만 하면 됩니다.

여기서 작업합니다

내 컴퓨터

작업 폴더의 파일들
커밋 = 세이브

커밋까지는 내 컴퓨터 안의 일입니다

→

origin — 원본이 있는 곳

깃허브 (인터넷)

저장소 · 비공개 또는 공개

푸시하면 올라가고, 풀하면 내려받습니다. 클론은 처음 통째로 가져오는 것.

커밋은 내 컴퓨터 안에서만 일어납니다. 푸시를 해야 비로소 인터넷에 올라갑니다. 4부의 되돌리기가 두 갈래로 갈리는 이유가 이것입니다.

'스테이징'은 일부러 넣지 않았습니다. AI에게 맡기는 방식에서는 쓸 일이 없습니다.

03 — 사고 방지

가장 중요한 장입니다

커밋하는 주체가 AI라는 건, 사고도 AI 손에서 난다는 뜻입니다.

올라가면 안 되는 것

내 폴더

index.html
style.css
.env
학생명단.xlsx
app.js

→

거름망

.gitignore

.env
*.xlsx
node_modules/

여기 적힌 것은 통과하지 못합니다

→

깃허브에 올라간 것

index.html
style.css
app.js

빨간 두 개는 걸러졌습니다

.gitignore는 체입니다. 문제는 이 체를 올리기 전에 만들어야 한다는 것. 한 번 올라간 뒤에는 늦습니다.

지운다고 사라지지 않습니다. 깃은 모든 과거를 기록으로 남깁니다. 키가 올라간 걸 뒤늦게 발견하고 파일을 지워도, 과거 기록에는 그대로 남아 있습니다. 그래서 대처는 삭제가 아니라 무효화입니다.

키를 올려버렸을 때 순서

발급처로 가서 그 키를 폐기(revoke)
구글, OpenAI, 앤트로픽 등 키를 발급받은 사이트에서 해당 키를 삭제합니다. 이게 1번입니다.
새 키를 발급받아 .env에 넣기
그리고 .env가 .gitignore에 있는지 확인합니다.
저장소를 비공개로 돌리거나, 급하면 삭제
공개 저장소였다면 이미 봇이 긁어갔다고 가정하는 편이 안전합니다.

순서를 거꾸로 해서 파일부터 지우면, 그 사이에 키는 계속 살아 있습니다.

공개인지 비공개인지 눈으로 확인

첫 업로드가 끝나면 반드시 깃허브 사이트에 들어가서 파일 목록을 훑어보세요. AI에게 물어보는 게 아니라 내 눈으로요.

my-classroom-tool Public

index.html2분 전

app.js2분 전

.env← 이게 보이면 즉시 위 3단계

README.md2분 전

이름 옆이 Public이면 전 세계가 볼 수 있습니다. Private인지 확인하세요.

깃허브의 자동 감지에 기대지 마세요. 깃허브는 잘 알려진 형태의 키가 올라가면 자동으로 잡아내 알려주기도 합니다. 하지만 모든 키를 잡지는 못하고, 학생 명단 같은 건 애초에 감지 대상이 아닙니다.

학생 정보는 비공개 저장소여도 올리지 마세요. 이름, 학번, 사진, 생활기록 관련 내용 전부입니다. 비공개는 "남이 못 본다"일 뿐, 학교 밖 외부 서비스에 개인정보를 보관하는 것 자체가 별개의 문제입니다. 테스트용 데이터는 가짜 이름으로 만드세요. AI에게 "샘플 데이터 20명 만들어줘"라고 하면 됩니다.

업로드 전 체크리스트

.gitignore를 만들었고 .env가 그 안에 있다 AI에게 "뭐가 올라갈지 목록부터 보여줘"를 시켰다 저장소가 Private인지 눈으로 확인했다 실제 학생 이름·학번이 들어간 파일이 없다 올린 뒤 깃허브 사이트에서 파일 목록을 훑어봤다

이렇게 말하세요

올리기 전에 확인하자. 지금 커밋에 API 키나 비밀번호, 개인정보가 들어간 파일이 있는지 훑어보고, 있으면 .gitignore에 추가한 다음 다시 알려줘.

터미널파를 위한 명령

$ git status # 올라갈 파일 목록 $ git rm --cached .env # 추적에서 빼기(기록엔 남음)

04 — 되돌리기

"AI가 멀쩡한 코드를 망쳐놨어요"

이 장 하나 때문에 깃허브를 쓴다고 해도 과언이 아닙니다.

커밋 1 · 화면 완성돌아갈 수 있는 지점
커밋 2 · 기능 추가돌아갈 수 있는 지점
커밋 3 · 여기까진 잘 됐음돌아가고 싶은 지점
지금 · AI가 다 망침커밋 안 함
↑ 커밋 3으로 되돌리기

커밋을 자주 해두면 언제든 이 지점으로 돌아올 수 있습니다. 커밋을 안 해두면 돌아갈 곳이 없습니다. 잘 되는 순간마다 "커밋해줘" 한 마디면 됩니다.

증상별로 눌러보세요

지금 상황과 가장 비슷한 걸 고르세요.

위에서 증상을 골라주세요.

판단은 딱 하나 — 푸시했는가

깃허브에 푸시했나요?

아니오

내 컴퓨터 안의 일

마음껏 되돌려도 됩니다.
"방금 수정 전으로 되돌려줘. 아직 깃허브엔 안 올렸어."

예

남도 볼 수 있는 상태

기록을 지우지 말고, 취소하는 커밋을 새로 쌓으세요.
"그 커밋을 취소하는 커밋을 만들어줘."

혼자 쓰는 저장소면 어느 쪽이든 큰일은 안 납니다. 하지만 5부처럼 동료와 같이 쓰는 저장소라면 이 구분이 중요합니다.

공동 저장소에서는 "강제로 밀어넣기"를 하지 마세요. AI가 --force를 제안하면 멈추고, 혼자 쓰는 저장소인지 먼저 확인하세요. 동료가 올려둔 작업이 통째로 사라질 수 있고, 이건 되돌리기 어렵습니다.

이렇게 말하세요 · 안전한 표현

이 저장소는 동료들이랑 같이 쓰는 거야. 기록을 지우거나 강제로 덮어쓰지 말고, 취소하는 커밋을 새로 만드는 방식으로 되돌려줘.

터미널파를 위한 명령

$ git log --oneline # 커밋 목록 확인 $ git revert <커밋해시> # 안전 · 취소 커밋을 새로 쌓음 $ git reset --hard <해시> # 위험 · 기록 자체를 되감음 # 공동 저장소에서 push --force 는 금지

05 — 동호회 공동작업

같이 만들면 훨씬 멀리 갑니다

다만 조직부터 만들지 마세요. 순서가 있습니다.

1단계 · 오늘 바로

내 저장소에 동료 초대

내 저장소 하나에 Collaborator로 2~3명을 초대합니다. Settings → Collaborators.

둘이서 앱 하나 만들 때는 이걸로 충분합니다

→

2단계 · 동호회 규모가 되면

조직(Organization) 만들기

공용 자료 저장소
앱 A
앱 B

저장소가 여러 개가 되고 사람이 드나들기 시작할 때

처음부터 조직을 만들면 권한 설정에서 지칩니다. 1단계로 시작해서, 저장소가 서너 개를 넘어갈 때 2단계로 옮기세요.

조직을 만들면 소유자(Owner)를 반드시 2명 이상으로. 만든 사람 혼자 Owner인 상태에서 그분이 전출·휴직하면, 동호회 자료 전체가 손댈 수 없는 상태가 됩니다. 이건 실제로 자주 벌어지는 일입니다.

브랜치는 두 개면 충분합니다

main은 언제나 작동하는 버전으로 두고, 새 기능은 작업 브랜치에서 만든 뒤 합칩니다. 이름은 timer-fix처럼 뭘 하는지만 적으면 됩니다.

이렇게 말하세요

main은 건드리지 말고, timer-fix라는 작업 브랜치를 새로 만들어서 거기서 작업해줘. 다 되면 깃허브에 올리고 PR(합쳐달라는 요청)까지 만들어줘.

여기서부터는 별권으로

브랜치를 어떻게 나누고, PR에 무엇을 적고, 리뷰를 어떻게 주고받고, 충돌이 났을 때 무엇을 정해야 하는지는 공동작업 대백과에서 따로 다룹니다. 용어마다 학교 비유를 붙이고 흐름을 모식도로 그려 두었으니, 동료와 저장소를 같이 쓰기 시작했다면 그쪽을 보세요.

동호회 공용 저장소 운영 팁

상황	이렇게
영상·대용량 자료	파일 하나가 50MiB부터 경고, 100MiB부터 차단됩니다. 영상과 큰 PPT는 링크만 적어두세요
완성된 앱 배포	Releases에 압축본을 올리면 코드를 모르는 선생님도 받아 쓸 수 있습니다
사람이 늘어날 때	개인 저장소에서는 읽기 권한만 주는 것이 불가능합니다. 협업자로 부르면 곧바로 쓰기 권한이 갑니다. 권한을 나누려면 조직(Organization)으로 옮겨야 합니다
리뷰 강제하기	보호 규칙은 GitHub Team 이상에서만 걸 수 있습니다. 다만 7부의 교사 인증을 받으면 Team이 무료라, 조직을 만들고 여기에 붙이면 규칙을 걸 수 있습니다

06 — 오픈소스 활용

남이 만든 걸 가져다 쓰기

깃허브의 진짜 가치는 여기 있습니다. 우리가 만들려던 건 대개 이미 누군가 만들어뒀습니다.

가져오는 방법 네 가지

ZIP 다운로드

그냥 파일만 받기. 깃 연결 없음

한 번 보고 말 때

클론 Clone

원본과 연결된 채로 내 컴퓨터에 복사

업데이트를 따라갈 때

포크 Fork

내 깃허브 계정으로 통째로 복사

고쳐서 내 것으로 쓸 때

Use this template

과거 기록 없이 깨끗한 새 저장소로

동호회 공용 틀 배포

동호회에서 공용 틀(예: 수업도구 기본 뼈대)을 나눠줄 때는 포크보다 Use this template이 낫습니다. 받는 사람 저장소가 남의 기록 없이 깨끗하게 시작됩니다.

이렇게 말하세요

이 깃허브 주소 좀 봐줘. 우리 프로젝트에 쓸 만한지, 어떻게 갖다 붙이면 되는지 알려줘. 그대로 가져오지 말고 뭘 하는 코드인지 먼저 설명해줘.

README 읽는 법 — 세 군데만

맨 위 소개 문단 — 이게 뭘 하는 물건인지
Installation / Usage — 설치와 사용법. 여기 명령어가 있으면 통째로 복사해서 AI에게 "이거 우리 환경에 맞게 해줘"
License — 아래 표 참고

영어라 막막하면 주소만 던지고 "이 저장소 README 요약해줘"라고 하세요. 그게 더 빠릅니다.

오류가 나면 Issues부터

설치하다 에러가 났다면 그 저장소의 Issues 탭에서 에러 메시지를 검색해보세요. 열에 아홉은 이미 누군가 겪었고 해결책이 달려 있습니다. 닫힌 이슈(Closed)까지 같이 보는 게 요령입니다.

라이선스 — 학교에서 쓸 때만 조심하면 됩니다

이름	수업에 쓰기	주의할 점
MIT	자유롭습니다	저작권 표시만 남겨두면 됩니다. 가장 흔하고 가장 편합니다
Apache 2.0	자유롭습니다	변경한 부분을 표시해야 합니다
GPL	주의	이 코드를 섞은 결과물을 남에게 배포하면, 내 코드도 같은 조건으로 공개해야 할 수 있습니다. 우리 반에서만 쓰면 대개 문제가 없지만, 동호회에 배포한다면 확인이 필요합니다
없음	쓰지 마세요	라이선스가 없으면 "마음대로 써도 된다"가 아니라 권리가 전부 원저작자에게 있다는 뜻입니다

Star(별)는 즐겨찾기입니다. 쓸 만한 걸 발견하면 눌러두세요. 나중에 내 Stars 목록이 자료 창고가 됩니다.

07 — 교사 인증 혜택

재직증명서 한 장이면 됩니다

한국 교사도 승인받은 사례가 있습니다. 다만 까다롭습니다.

동호회 입장에서 진짜 큰 건 코파일럿이 아닙니다.
인증된 교사는 GitHub Team을 무료로 쓸 수 있습니다. 인원 제한 없이 비공개 저장소로 협업할 수 있다는 뜻이라, 5부의 동호회 조직을 공짜로 제대로 굴릴 수 있게 됩니다. 코파일럿(Copilot Pro)과 브라우저 개발환경 추가 시간도 함께 붙습니다.

신청 순서

학교 메일을 계정에 등록해둔다
1부에서 해둔 그 작업입니다. 인증 메일까지 눌러 확인 표시가 떠 있어야 합니다.
행정실에서 영문 재직증명서 발급
영문 이름과 학교명이 또렷하게 나오게 받으세요. 사진으로 제출합니다.
Settings → Billing & plans → Education benefits
역할은 Teacher를 선택합니다. 여기서 Student를 고르면 반려됩니다.
증명서 촬영해서 업로드
계정 이름과 증명서의 영문 이름이 다르면 반려율이 올라갑니다. 미리 맞춰두는 편이 좋습니다.
결과 대기
하루 만에 되기도 하고, 일주일 넘게 걸렸다는 국내 후기도 있습니다. 반려되면 서류를 바꿔 다시 넣을 수 있습니다.

혜택은 영구적이지 않습니다. 깃허브는 자격을 매달 다시 확인합니다. 학교를 옮기거나 휴직하면 학교 메일이 막히면서 혜택이 끊길 수 있습니다. 계정 자체를 학교 메일로 만들면 안 되는 이유가 여기 또 나옵니다.

2026년에 한 번 막혔다가 다시 열렸습니다.
깃허브는 2026년 4월 개인용 코파일럿 신규 가입을 중단했다가, 6월 17일 Student·Pro·Pro+·Max를 몇 주에 걸쳐 순차 재개한다고 밝혔습니다. 지금은 교사 인증이 통과하면 Copilot Pro가 무료입니다. 다만 화면과 혜택 구성은 시점에 따라 다를 수 있으니, 신청 직전에 깃허브 공식 안내를 한 번 열어 확인하세요. (2026-08-23 확인)

08 — 학교 환경 대처

학교 컴퓨터는 원래 안 됩니다

막히는 지점이 정해져 있습니다. 미리 알고 가면 됩니다.

설치 권한이 없을 때

학교 업무용 PC는 대개 프로그램 설치가 막혀 있습니다. 이럴 때 답은 브라우저에서 도는 개발환경입니다. 깃허브 저장소 화면에서 키를 하나 누르면 브라우저 안에 편집기가 열립니다. 설치가 필요 없습니다.

저장소 주소에서 github.com 대신 github.dev를 입력하거나, 저장소 화면에서 마침표(.) 키를 눌러보세요. 더 본격적인 작업이 필요하면 Codespaces를 쓸 수 있고, 무료 사용량 한도가 정해져 있습니다확인 필요. 7부 인증을 받으면 여유가 늘어납니다.

자주 막히는 것들

증상	대처
학교 망에서 접속이 안 됨	교육청 필터링일 수 있습니다. 개인 노트북이나 휴대폰 테더링으로 되는지 먼저 확인해 원인을 가르세요
인증앱 넣을 폰이 없음	개인 폰에 설치해도 됩니다. 복구코드는 별도 보관
집에서 작업을 이어가고 싶음	집 컴퓨터에서 저장소를 클론하면 됩니다. AI에게 "이 저장소 여기로 가져와줘"
동료에게 앱을 통째로 넘기고 싶음	저장소 주소만 주면 끝입니다. 파일 압축해서 메신저로 보낼 일이 없어집니다

전출·퇴직 전 체크리스트

계정 주 이메일이 개인 메일인지 확인 (학교 메일이면 지금 바꾸기) 동호회 조직의 소유자(Owner)가 나 말고 한 명 더 있는지 학교 업무용으로 만든 저장소를 후임에게 넘길지, 내가 가져갈지 정리 교사 인증 혜택이 끊길 수 있다는 점 인지 (비공개 저장소 개수 등) 2FA 복구코드가 학교 PC가 아닌 곳에 보관돼 있는지

＋ 부록

요청 문장 모음

이 문서에서 쓴 문장들입니다. 그대로 복사해서 쓰세요.

이 문서를 쓰실 때

확인 필요 표시가 붙은 항목은 시점에 따라 달라질 수 있는 내용입니다. 직접 화면을 확인하고, 스크린샷을 찍어 넣으실 때는 날짜를 함께 적어두시길 권합니다. 깃허브 화면은 자주 바뀝니다.