AI TF GitHub 이용 규칙
버전: v0.6 (2026-09-21) · 문의: AI팀장 · GitHub 가이드 5편
처음이라면 0편. 한눈에 보는 Git과 GitHub부터 보세요.
이 문서의 규칙은 GitHub라는 서비스의 제약이 아니라 우리 TF가 정한 운영 규칙입니다. 일부는 팀장이 GitHub 설정으로 걸어 두지만, 설정이 막아 주지 못하는 부분은 각자 지켜야 합니다.
1. 핵심 규칙 다섯 가지
- 정해진 작업 폴더에서만 작업합니다. 회사 PC의
C:\tf폴더 밖에서는 AI 개발 도구(Codex)를 열지 않습니다. - 올리면 안 되는 자료가 있습니다. 비밀유지계약(NDA) 자료, 개인정보, 입찰·견적 정보, 비밀번호는 올리지 않습니다.
- 작업은
work에서, 완성본은main에.main은 아무도 직접 고치지 않습니다(팀장 포함). PR을 거쳐 팀장이 병합할 때만 바뀝니다. - 하루 작업이 끝나면 올립니다(푸시). PC가 고장 나도 작업이 남고, 팀장이 진행 상황을 볼 수 있습니다.
- 실수했다면 지우려 하지 말고 바로 알립니다. 더 진행하기 전에 알려 주시면 복구 방법을 함께 확인합니다.
2. 용어
| 용어 | 뜻 |
|---|---|
| 저장소(repository, repo) | 프로젝트 하나를 담는 폴더. 프로젝트마다 1개씩 있습니다 |
| 커밋(commit) | "여기까지 저장"이라고 찍는 도장. 한 줄 메모와 함께 남깁니다 |
| 푸시(push) | 내 PC에 찍어 둔 커밋을 GitHub에 올리는 것 |
| 풀(pull) | GitHub의 같은 브랜치에 새로 올라온 내용을 내 PC로 내려받는 것 |
| 브랜치(branch) | 같은 저장소 안의 "작업본". 우리는 work(작업본)와 main(완성본) 두 개만 씁니다 |
| PR(Pull Request) | "작업본을 완성본에 반영해 주세요"라고 요청하는 것 |
| 병합(merge) | 팀장이 PR을 받아들여 main 에 실제로 반영하는 것 |
3. 저장소 종류
| 이름 | 용도 | 내 권한 |
|---|---|---|
tf-handbook | 교육자료, 규칙, 교육 사이트 원본 | 읽기. 오탈자나 수정 제안은 팀장에게 메신저로 알려 주세요 |
tf-sandbox | 연습장. 브랜치 이름은 work-… | 읽기·쓰기 |
tf-template-web | 모든 프로젝트의 출발점이 되는 기본 틀 | 읽기 |
prj-부서코드-도구이름 | 부서 프로젝트. 브랜치 이름은 work | 내 프로젝트는 읽기·쓰기, 다른 부서 프로젝트는 읽기 |
- 저장소는 팀장이 만듭니다. 필요하면 팀장에게 메신저로 요청하세요.
- 다른 부서의 프로젝트도 볼 수 있습니다. 서로 참고하며 배우기 위해서입니다.
- 저장소는 비공개로 운영합니다. 비공개란 "초대받아 권한이 있는 계정만 볼 수 있다"는 뜻이지, 회사 네트워크 안에서만 열린다는 뜻이 아닙니다. 그래서 계정 보안과 "회사 PC에서만 작업한다"는 규칙이 중요합니다.
- 외부로 복사(fork), 공개 전환, 외부인 초대는 하지 않습니다. 팀장이 설정으로도 제한합니다.
4. 업로드 금지 자료
| 구분 | 예시 |
|---|---|
| 발주처와 비밀유지계약(NDA)을 맺은 자료 | 발주처 제공 도면, 보고서, 데이터 |
| 개인정보 | 주민등록번호, 연락처, 인사·급여 자료, 이력서 |
| 입찰·견적 정보 | 입찰가, 견적서, 원가 내역 |
| 비밀번호류 | 비밀번호, API 키(AI 서비스 이용 열쇠), .env 파일 |
| 문서 원본과 대용량 파일 | PDF, HWP, 도면, 엑셀 원본 (지식 DB용 문서는 별도 지정 장소에 둡니다) |
- 도구를 시험할 때는 가짜 데이터를 씁니다. AI에게 "테스트용 가짜 데이터를 만들어 줘"라고 하면 됩니다.
- 판단이 어려우면 올리기 전에 물어보세요.
- 도움 요청에 붙이는 화면 캡처와 오류 메시지도 마찬가지입니다. 비밀번호, 개인정보, 업무 자료가 보이지 않는지 확인하고 올립니다.
5. 작업 흐름
① GitHub Desktop에서 저장소 확인 (Current Repository)
② 작업 브랜치 선택 (Current Branch 가 work 인지 확인)
③ Fetch origin → 버튼이 Pull origin 으로 바뀌면 Pull (안 바뀌면 받을 것이 없는 것, 정상)
④ ChatGPT 앱의 Codex로 작업
⑤ 커밋 전 세 가지 확인
⑥ Commit (한 줄 메모) → Push: GitHub Desktop에서 직접, 또는 확인을 마친 뒤 Codex에게 시킴
⑦ 실제로 쓸 만한 상태가 되면: work → main PR 작성, 팀장에게 메신저로 알림
⑧ 팀장 검토·승인 → 팀장이 병합 (main 에 반영) → 별도 단계로 사내 서버 배포
- ①
⑥은 작업할 때마다 반복합니다. ⑦⑧은 "이 버전을 실제로 쓰고 싶다"고 판단될 때만 합니다. - 승인, 병합, 배포는 서로 다른 단계입니다. 승인됐다고 바로 서버에 올라가지 않습니다.
- 팀장 검토는 영업일 기준 2일 이내를 목표로 합니다.
커밋 전 세 가지 확인
코드를 전부 이해할 필요는 없지만, 결과를 확인하는 것은 작업한 사람의 책임입니다.
- 예상하지 못한 파일 변경이 없는가 (GitHub Desktop의 Changes 목록)
- 실제로 실행하거나 결과물을 열어 보니 요청한 대로 동작하는가
- 비밀번호·API 키·개인정보·업무 원본 자료가 포함되어 있지 않은가
Codex에 커밋을 맡기는 경우
교육 기간(온보딩 주간과 3편 실습)에는 커밋과 푸시를 GitHub Desktop으로 직접 합니다. 그 뒤 실무에서는 Codex에게 시켜도 됩니다. 단, 아래를 지킵니다.
- 확인이 먼저입니다. Codex가 작업을 마치면 세 가지 확인을 한 뒤에 "커밋하고 푸시해 줘"라고 합니다. Codex가 확인 전에 먼저 커밋하려 하면 멈추게 합니다.
work에서만 합니다. 새 브랜치, worktree,main직접 커밋은 시키지 않습니다.- PR은 직접 만듭니다. GitHub Desktop이나 웹에서 만들고 팀장에게 메신저로 알립니다.
- 되돌리기는 GitHub Desktop에서 합니다. ChatGPT 앱 화면의 Revert 는 "커밋하지 않은 변경을 버린다"는 뜻으로 GitHub Desktop의 Discard Changes와 같습니다. 이미 커밋한 것을 되돌리는 Revert Changes in Commit과 다릅니다.
- 상태가 헷갈리면 GitHub Desktop을 엽니다. 어느 쪽에서 커밋했든 History와 Changes에 그대로 보입니다. 푸시가 됐는지도 여기서 확인합니다.
PR 작성 이후
- PR이 열려 있는 동안
work에 푸시하면 그 변경도 그 PR에 들어갑니다. 수정 요청 반영은 그대로 푸시하면 됩니다. - 관련 없는 새 작업은 PR이 병합된 뒤에 시작합니다. 급하면 먼저 팀장에게 알립니다.
- 병합 뒤에도 같은
work를 계속 씁니다. 화면에 나타나는 Delete branch 버튼은 누르지 않습니다. main은 PR 병합으로만 바뀌므로, 병합 뒤에work를main에 맞추는 작업은 필요 없습니다. 평소 순서대로 시작하면 됩니다.- 팀장이 도와주려고
work에 수정을 넣어 준 경우에는 메신저로 알려 줍니다. 그때는 하던 것을 커밋·푸시한 뒤 Fetch origin → Pull origin 을 합니다. - 버튼 위치와 화면은 3편. 기본 실습, 요약은 6편. 한 장 요약을 보세요.
커밋 메모 작성법
한국어 한 줄로 "무엇을 왜" 했는지 씁니다.
- 좋은 예:
보고서 양식에 요약 표 추가,날짜가 하루 밀려 나오는 문제 수정 - 나쁜 예:
수정,ㅁㄴㅇㄹ,최종_진짜최종
6. 문제 발생 시 도움 요청
- 먼저 AI에게 오류 메시지를 붙여 넣고 뜻을 물어봅니다. AI가 제안한 명령을 직접 실행하게 하지는 않습니다.
- 15분 넘게 해결이 안 되면 팀장에게 메신저로 도움을 요청합니다.
도움을 요청할 때는 아래 네 가지를 적습니다. 보내기 전에 캡처와 오류 메시지에 민감한 정보가 없는지 확인합니다.
1. 하려던 일:
2. 실제로 일어난 일 (오류 메시지는 그대로 복사):
3. 화면 캡처:
4. 저장소 이름과 브랜치:
7. 실수 시 대처
| 상황 | 할 일 |
|---|---|
| 올리면 안 되는 자료를 올렸다 | 삭제하지 말고 즉시 팀장에게 메신저로 알립니다. 파일을 지워도 이력에는 남기 때문에 팀장이 이력까지 정리해야 합니다 |
| 비밀번호나 API 키를 올렸다 | 즉시 팀장에게 알립니다. 해당 키는 폐기하고 새로 발급합니다 |
| 작업이 꼬여서 되돌리고 싶다 | 아무것도 지우지 말고 팀장에게 메신저로 도움을 요청합니다. 커밋해 둔 내용은 되찾을 방법이 있는 경우가 많습니다 |
실수로 main 에서 작업했다 (커밋 전) | GitHub Desktop에서 work 로 바꿀 때 변경 사항을 work 로 가져가는 쪽을 선택합니다. 문구가 헷갈리면 누르지 말고 물어봅니다 |
실수로 main 에서 커밋했다 | 푸시하지 말고 멈춘 뒤 도움을 요청합니다 |
| 충돌(conflict) 안내가 떴다 (Pull, Revert, PR 화면) | 멈춤 → 캡처 → GitHub Desktop 창이라면 Abort merge → 팀장에게 메신저. 직접 해결하지 않습니다. 7편 |
실수를 알린 사람에게 불이익은 없습니다. 알리지 않은 실수만 문제가 됩니다.
8. 자주 묻는 질문
Q. 코드를 읽을 줄 모르는데 PR을 올려도 되나요?
네. 코드를 전부 이해할 필요는 없습니다. 다만 위의 세 가지 확인을 마친 뒤에 올립니다. 코드 자체는 팀장이 봅니다.
Q. 집 PC나 개인 노트북에서 작업해도 되나요?
안 됩니다. GitHub는 어디서든 접속되지만, 회사 PC에서만 작업하는 것이 우리 TF의 규칙입니다.
Q. 다른 기술(파이썬 등)로 만들고 싶어요.
기본 틀(tf-template-web)에서 시작하는 것이 원칙입니다. 업무 성격상 맞지 않으면 팀장에게 요청하세요. 팀장이 검토해 새 기본 틀을 추가합니다.
Q. AI가 브랜치를 새로 만들자고 합니다.
거절하고 "work 에서 계속해 줘"라고 하세요. 저장소의 AI 규칙 파일(AGENTS.md)에도 적어 둡니다.
Q. AI가 작업을 마치자마자 커밋하겠다고 합니다.
"잠깐, 내가 확인한 뒤에 말할게"라고 멈추게 하고 세 가지 확인을 먼저 합니다. 교육 기간에는 "커밋은 내가 할게"라고 답합니다.
이어서 읽기
- 다음 편: 6편. 한 장 요약 — 인쇄용 A4 한 장
- 함께 보기: 7편. 브랜치 분기와 충돌 대처 — 충돌 안내가 떴을 때
- 전체 목록: 가이드 전체 구성