Git 기초 입문 [#1] — 설치·커밋·브랜치·원격 저장소 한 번에

[Git 실전 가이드 #1] Git 기초 입문

이 글을 읽으면 Git 설치부터 커밋·브랜치·원격 저장소 연동까지 기본 흐름을 따라 할 수 있습니다. Git은 소프트웨어 개발에서 가장 많이 사용되는 버전 관리 시스템(VCS—파일 변경 이력을 추적하고, 이전 버전으로 되돌리거나 여러 사람이 협업할 수 있게 해 주는 도구)입니다. 코드의 변경 이력을 추적하고, 여러 사람이 협업할 수 있게 해주는 필수 도구입니다. 이 글에서는 Git의 기본 개념부터 실전에서 자주 사용하는 명령어까지, 초보자가 Git을 시작하는 데 필요한 모든 내용을 다룹니다.
처음에는 “커밋 → 푸시” 흐름만 익혀도 실제 작업에 쓸 수 있고, 브랜치와 병합은 Git 브랜치와 병합에서 이어서 다룹니다. 명령어보다 “변경 이력을 스냅샷으로 남긴다”는 생각을 먼저 잡는 것이 중요합니다. 헷갈리기 쉬운 것: git add는 “커밋할 목록에 넣는 것”이지, 아직 서버에 올라가는 게 아닙니다. 실제로 원격 저장소에 반영되려면 git push까지 해야 합니다. 반대로 git pull은 원격의 변경을 가져와서 현재 브랜치에 합치는 것이므로, 협업 시 자주 쓰게 됩니다.

1. Git이란?

버전 관리가 없던 시절

여러분도 이런 경험이 있지 않나요? Git을 사용하지 않을 때:

project_0315.zip
project_0320_수정.zip
project_0325_진짜최종.zip
project_0326_진짜진짜최종.zip
project_0327_이번진짜최종.zip

이런 방식은 다음과 같은 문제가 있습니다:

• 어떤 파일이 최신 버전인지 헷갈립니다.
• 각 버전에서 무엇이 바뀌었는지 알 수 없습니다.
• 이전 버전으로 되돌리기가 어렵습니다.
• 여러 사람이 협업하기 거의 불가능합니다. Git을 사용하면:

# 복사해 붙여넣은 뒤: 터미널에서 실행 (Git 설치 필요)
git log --oneline -5   # 최근 커밋 5개 한 줄씩 확인
git diff               # 작업 디렉터리와 스테이징 차이
git branch              # 현재 브랜치 목록

실행 결과: git log --oneline -5는 이미 커밋이 있는 저장소에서 최근 5개 커밋 해시와 메시지를 한 줄씩 보여 줍니다. 새 폴더에서는 먼저 git init 후 git add . → git commit -m "first"로 커밋을 하나 만든 뒤 실행해 보세요.

Git과 GitHub의 차이

초보자가 자주 혼동하는 개념입니다: Git:

• 버전 관리 도구 (소프트웨어)
• 여러분의 컴퓨터(로컬)에 설치됩니다.
• 혼자서도 사용할 수 있습니다. GitHub:
• Git 저장소를 온라인으로 호스팅하는 서비스
• 클라우드에서 코드를 공유하고 협업합니다.
• GitLab, Bitbucket 같은 대안도 있습니다. 간단히 말하면, Git은 도구이고 GitHub는 Git을 사용하는 온라인 서비스입니다.

2. Git 설치 및 초기 설정

Windows

• 공식 설치 프로그램: git-scm.com/download/win에서 설치 파일을 받아 실행합니다. 기본 옵션으로도 대부분의 개발 환경에 맞습니다.
• winget(Windows 10/11):

winget install Git.Git

설치 후 Git Bash 또는 PowerShell에서 아래 설치 확인을 실행합니다.

macOS

• Homebrew:

brew install git

• Xcode Command Line Tools만 설치해도 Git이 포함됩니다: 터미널에서 xcode-select --install 후 안내에 따릅니다.

Linux

배포판에 따라 패키지 관리 명령이 다릅니다.

# Ubuntu / Debian
sudo apt update && sudo apt install git
# Fedora
sudo dnf install git
# Arch Linux
sudo pacman -S git

설치 확인

git --version

예: git version 2.43.x처럼 버전이 출력되면 정상입니다.

git config 필수 설정

커밋마다 작성자 이름·이메일이 기록되므로, 처음 한 번은 전역(--global)으로 설정합니다.

git config --global user.name "표시될 이름"
git config --global user.email "[email protected]"

GitHub를 쓴다면 계정에 등록된 이메일과 맞추는 것이 좋습니다. 주소를 공개하고 싶지 않으면 GitHub 설정의 noreply 이메일을 user.email에 넣을 수 있습니다. 설정이 잘 들어갔는지 확인:

git config --global --list

특정 프로젝트만 다른 이름을 쓰려면 해당 폴더에서 --global 없이 git config user.name "..."처럼 설정하면 됩니다. 자주 쓰는 선택 설정:

git config --global init.defaultBranch main
git config --global core.editor "code --wait"   # VS Code로 커밋 메시지 편집 (경로는 환경에 맞게)

SSH 키 설정 (GitHub 연동)

HTTPS URL로 git push할 때마다 인증을 묻는 대신, SSH로 연결하면 키 한 번 등록 후 편하게 쓸 수 있습니다.

1. 기존 키가 있는지 확인: ls -al ~/.ssh
2. 없으면 생성(이메일은 본인 것으로):

ssh-keygen -t ed25519 -C "[email protected]"

프롬프트가 나오면 기본 경로(~/.ssh/id_ed25519)를 쓰고, passphrase는 분실에 대비해 설정하는 것을 권장합니다. 3. ssh-agent에 키를 등록합니다. macOS는 GitHub 문서의 ssh-add 절차를 따르는 것이 안전합니다. 4. 공개 키 내용을 복사합니다: cat ~/.ssh/id_ed25519.pub 5. GitHub → Settings → SSH and GPG keys → New SSH key에 붙여넣습니다. 6. 연결 테스트: ssh -T [email protected] — 성공 메시지가 나오면 준비 완료입니다. 원격 저장소 URL은 [email protected]:사용자명/저장소명.git 형식으로 두면 SSH로 push/pull 합니다. (아래 GitHub 연동에서 git remote add 예시와 함께 설명합니다.)

3. 핵심 개념

작업 영역

Working Directory → Staging Area → Repository
     (작업 중)      (git add)      (git commit)

파일 상태

• Untracked: Git이 추적하지 않는 새 파일
• Modified: 수정된 파일
• Staged: 커밋 준비된 파일
• Committed: 저장소에 저장된 파일

4. 기본 워크플로우 심화

작업 디렉터리(Working Directory), 스테이징 영역(Staging Area), 로컬 저장소(Repository)의 관계를 한 번에 보면 다음과 같습니다. 스테이징은 “다음 커밋에 넣을 변경만 골라 담는 바구니”라고 이해하면 됩니다.

// 실행 예제
flowchart TB
  subgraph WD["작업 디렉터리 (Working Directory)"]
    F1["편집한 파일"]
  end
  subgraph SA["스테이징 영역 (Staging Area / Index)"]
    F2["git add로 선택된 스냅샷"]
  end
  subgraph REPO["로컬 저장소 (Repository .git)"]
    C["커밋 객체 — git commit"]
  end
  WD -->|git add| SA
  SA -->|git commit| REPO
  REPO -.->|git checkout / restore로 특정 버전 반영| WD

• 작업 디렉터리: 실제로 편집하는 폴더 트리입니다.
• 스테이징: git add로 “이번 커밋에 포함할 변경”을 표시합니다. 같은 파일이라도 일부만 스테이징할 수 있습니다(git add -p).
• 저장소: git commit으로 스테이징된 내용이 커밋(스냅샷)으로 기록됩니다.

git add: -A vs -u vs .

현재 디렉터리 기준으로 자주 쓰는 형태입니다(경로를 붙이면 그 범위만 적용됩니다).

명령	대략적인 의미
git add .	현재 디렉터리 이하의 변경·새 파일을 스테이징합니다. 상위 디렉터리의 파일은 포함하지 않습니다.
git add -A (또는 --all)	저장소 전체에서 추적 대상이 되는 변경과 삭제까지 포함해 스테이징합니다(보통 프로젝트 루트에서 실행).
git add -u (또는 --update)	이미 추적 중인 파일의 변경·삭제만 스테이징합니다. 새로 만든 untracked 파일은 포함하지 않습니다.
정리하면, 새 파일까지 한꺼번에 올리려면 git add . 또는 git add -A, “예전부터 있던 파일만” 고치는 단계에서는 git add -u를 쓰는 경우가 많습니다.

커밋 메시지 작성 규칙 (Conventional Commits)

팀·오픈소스에서 읽기 쉬운 이력을 남기려면 Conventional Commits 형태를 쓰는 경우가 많습니다. 형식: <type>(optional scope): <짧은 설명> 자주 쓰는 type 예:

• feat: 새 기능
• fix: 버그 수정
• docs: 문서만 변경
• style: 포맷·세미콜론 등 동작에 영향 없는 스타일
• refactor: 리팩터링
• test: 테스트 추가·수정
• chore: 빌드·보조 도구 등 예시:

feat(auth): add OAuth2 login handler
fix(api): handle empty response body
docs: update install steps for Windows

본문이 필요하면 제목 다음 빈 줄 뒤에 왜 바꿨는지 적습니다. 한 커밋에는 한 가지 논리적 변경만 담는 것이 나중에 git revert나 리뷰에 유리합니다.

5. 기본 명령어

저장소 생성

mkdir myproject
cd myproject
git init

파일 추가 및 커밋

Git의 가장 기본적인 워크플로우입니다:

# 1. 파일 생성 (예시)
echo "Hello Git" > README.md
# README.md 파일에 "Hello Git" 내용 작성
# 2. 상태 확인
git status
# 출력 예시:
# On branch main
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#         README.md
# 
# nothing added to commit but untracked files present
# 
# 설명: README.md가 Untracked 상태 (Git이 아직 추적하지 않음)
# 3. 스테이징 (Staging Area에 추가)
git add README.md
# 또는 모든 변경 파일 추가
# git add .
# 
# 스테이징: 커밋할 파일을 선택하는 단계
# "이 파일들을 다음 커밋에 포함시키겠다"는 의미
# 4. 상태 재확인
git status
# 출력 예시:
# On branch main
# Changes to be committed:
#   (use "git restore --staged <file>..." to unstage)
#         new file:   README.md
# 
# 설명: README.md가 Staged 상태 (커밋 준비 완료)
# 5. 커밋 (변경 사항을 저장소에 기록)
git commit -m "Add README"
# -m "메시지": 커밋 메시지 (변경 내용 설명)
# 커밋: 현재 스테이징된 변경사항의 스냅샷을 저장
# 각 커밋은 고유한 해시(SHA-1)를 가짐
# 
# 출력 예시:
# [main 1a2b3c4] Add README
#  1 file changed, 1 insertion(+)
#  create mode 100644 README.md

워크플로우 정리:

1. 파일 수정 (Working Directory)
2. git add: 스테이징 (Staging Area)
3. git commit: 저장소에 기록 (Repository)
4. git push: 원격 저장소에 업로드 (Remote Repository)

변경 이력 확인

git log
git log --oneline  # 간단히 보기

변경 내용 확인

git diff  # 작업 디렉토리 vs 스테이징
git diff --staged  # 스테이징 vs 저장소

파일 되돌리기

# 작업 디렉토리 변경 취소
git restore README.md
# 스테이징 취소
git restore --staged README.md

브랜치

브랜치는 독립적인 작업 공간을 만들어 여러 기능을 동시에 개발할 수 있게 해줍니다:

# 1. 브랜치 생성
git branch feature
# "feature"라는 이름의 새 브랜치 생성
# 현재 커밋을 가리키는 포인터가 생성됨
# 아직 브랜치를 이동하지는 않음
# 2. 브랜치 목록 확인
git branch
# 출력 예시:
# * main      (* 표시: 현재 브랜치)
#   feature
# 3. 브랜치 이동
git checkout feature
# HEAD가 feature 브랜치로 이동
# 작업 디렉토리가 feature 브랜치 상태로 변경됨
# 
# 출력: Switched to branch 'feature'
# 4. 생성 + 이동 (한 번에)
git checkout -b feature
# 위의 1번과 3번을 한 번에 수행
# -b: 브랜치 생성 옵션
# 
# 최신 Git에서는 switch 명령도 사용 가능:
# git switch -c feature
# 5. 브랜치에서 작업 후 커밋
echo "new feature" > feature.txt
git add feature.txt
git commit -m "Add new feature"
# feature 브랜치에만 커밋이 추가됨
# main 브랜치는 영향 받지 않음
# 6. 브랜치 병합 (merge)
git checkout main
# main 브랜치로 이동
git merge feature
# feature 브랜치의 변경사항을 main에 병합
# 
# 출력 예시 (Fast-forward):
# Updating abc1234..def5678
# Fast-forward
#  feature.txt | 1 +
#  1 file changed, 1 insertion(+)
# 
# Fast-forward: main이 feature의 조상이면 포인터만 이동
# 3-way merge: 두 브랜치가 갈라졌으면 새 커밋 생성
# 7. 브랜치 삭제 (병합 후)
git branch -d feature
# -d: 병합된 브랜치만 삭제 (안전)
# -D: 강제 삭제 (병합 안 된 브랜치도 삭제)

브랜치 사용 시나리오:

• main: 안정적인 배포 버전
• develop: 개발 중인 버전
• feature/login: 로그인 기능 개발
• bugfix/crash: 버그 수정 병합 충돌 해결:

# 병합 시 충돌 발생 시
git merge feature
# 출력: CONFLICT (content): Merge conflict in file.txt
# 충돌 파일 확인
git status
# 충돌 파일에는 다음과 같은 마커가 표시됨:
# <<<<<<< HEAD
# main 브랜치의 내용
# =======
# feature 브랜치의 내용
# >>>>>>> feature
# 충돌 해결 후
git add file.txt
git commit -m "Resolve merge conflict"

6. 실전 시나리오

첫 프로젝트 Git 시작하기 (init부터 push까지)

로컬에서 새 폴더를 만들고 GitHub에 처음 올리는 흐름입니다.

1. 프로젝트 폴더 준비

mkdir my-app && cd my-app
git init

2. .gitignore와 README.md를 두고 첫 커밋(아래 .gitignore 참고)

echo "# my-app" > README.md
git add README.md
git commit -m "chore: initial commit"

3. GitHub에서 빈 저장소 생성(README 없이 생성하면 로컬과 충돌이 적습니다).
4. 원격 추가 후 push — HTTPS 예시:

git remote add origin https://github.com/YOUR_USER/my-app.git
git branch -M main
git push -u origin main

SSH를 쓰는 경우 origin URL은 [email protected]:YOUR_USER/my-app.git 형식으로 넣습니다. -u는 이후 git push만으로 같은 브랜치를 올릴 수 있게 upstream을 기억해 둡니다.

실수한 커밋 수정하기 (amend)

방금 만든 마지막 커밋의 메시지를 고치거나, 빠뜨린 파일을 같은 커밋에 합치고 싶을 때 사용합니다.

# 메시지만 수정 (에디터가 열리거나 -m으로 한 줄 수정)
git commit --amend -m "fix: correct commit message"
# 스테이징을 추가한 뒤 마지막 커밋에 합치기
git add forgotten.txt
git commit --amend --no-edit

주의: 이미 git push로 원격에 올린 커밋을 --amend로 바꾸면 히스토리가 달라지므로, 혼자 쓰는 브랜치가 아니면 git push --force-with-lease가 필요하고 팀 규칙을 확인해야 합니다.

파일 되돌리기 (restore, checkout)

Git 2.23 이후로는 작업 트리·스테이징 되돌리기에 git restore를 쓰는 방식이 권장됩니다.

# 작업 디렉터리의 변경을 버리고, 마지막 커밋 상태로 되돌림 (주의: 복구 어려움)
git restore README.md
# 스테이징만 취소 (파일 내용은 그대로, unstaged로만)
git restore --staged README.md
# 특정 커밋의 파일 내용만 가져와 작업 디렉터리에 반영
git restore --source=HEAD~1 README.md

브랜치 전환은 예전처럼 git checkout other-branch 또는 최신 문법으로 git switch other-branch를 씁니다. git checkout -- file은 git restore file과 대응되는 옛 표현입니다.

7. 흔한 문제 해결

fatal: not a git repository

이 메시지는 현재 디렉터리(또는 상위)에 .git 폴더가 없을 때 나옵니다.

• 프로젝트 루트로 이동했는지 확인: pwd, ls -la
• 처음이라면 git init으로 저장소를 만들거나, 기존 저장소를 git clone으로 받았는지 확인합니다.
• 하위 폴더가 아니라 저장소 루트에서 명령을 실행하는지 확인합니다.

rejected - non-fast-forward (push 거절)

원격에 로컬에 없는 커밋이 있을 때, 단순히 push만으로는 안전하게 앞으로 갈 수 없어서 거절됩니다.

1. 먼저 원격 변경을 가져와 합칩니다:

git pull --rebase origin main
# 또는
git pull origin main

2. 충돌이 없으면 다시 git push.
3. 강제 push(git push --force)는 원격의 커밋을 덮어쓰므로, 혼자 쓰는 브랜치가 아니면 사용하지 않습니다. 필요할 때는 --force-with-lease가 조금 더 안전합니다.

.gitignore 작성법

버전에 올리지 않을 파일을 나열합니다. 빌드 산출물, 의존성 폴더, OS·IDE 설정, 비밀 키 등을 제외하는 데 씁니다.

• 저장소 루트에 .gitignore 파일을 둡니다.
• 한 줄에 하나씩 패턴을 씁니다. 예:

# 빌드 출력
/build/
/dist/
*.o
*.exe
# Node
node_modules/
# Python
__pycache__/
.venv/
# 환경·비밀
.env
.env.local

• 이미 추적 중인 파일은 .gitignore에 넣어도 자동으로 빠지지 않습니다. 추적을 끊으려면 git rm --cached <파일> 후 커밋합니다.
• gitignore.io 등에서 언어·OS에 맞는 템플릿을 생성할 수 있습니다.

8. GitHub 연동

원격 저장소 추가 (remote add)

로컬 저장소에 별칭 이름(보통 origin)과 URL을 연결합니다.

git remote add origin https://github.com/username/repo.git
# SSH 예시
# git remote add origin [email protected]:username/repo.git

이미 잘못 넣었다면 git remote set-url origin <새 URL>로 바꿉니다. 확인은 git remote -v.

첫 push 하기

브랜치 이름이 main일 때:

git push -u origin main

GitHub 저장소가 비어 있고, 로컬에 커밋이 있으면 위 한 번이면 됩니다. 이후 같은 브랜치는 git push만으로 충분합니다.

풀·클론

git pull origin main
git clone https://github.com/username/repo.git

README.md 작성 팁

• 프로젝트 이름과 한 줄 설명을 맨 위에 둡니다.
• 설치 방법, 실행 방법, 환경 변수가 있으면 단계별로 적습니다.
• 라이선스·기여 방법은 링크로 연결해도 좋습니다.
• 스크린샷·다이어그램은 README에 넣으면 새 참여자가 구조를 빨리 이해합니다.

자주 쓰는 명령어 요약

# 초기화
git init
# 상태 확인
git status
# 스테이징
git add <file>
git add .  # 모든 파일
# 커밋
git commit -m "message"
# 이력 확인
git log
git log --oneline
# 브랜치
git branch <name>
git checkout <name>
git checkout -b <name>
git merge <name>
# 원격 저장소
git remote add origin <url>
git push -u origin main
git pull origin main
git clone <url>

마무리

핵심 요약

Git의 기본 개념을 정리하겠습니다: ✅ Git의 역할: 코드 변경 이력을 체계적으로 관리하고, 여러 사람이 협업할 수 있게 해줍니다. ✅ 기본 워크플로우: git add로 스테이징 → git commit으로 저장 → git push로 원격 저장소에 업로드합니다. ✅ 브랜치: 독립적인 작업 공간을 만들어 동시에 여러 기능을 개발할 수 있습니다. ✅ GitHub 연동: 원격 저장소를 사용하면 코드를 백업하고 다른 사람과 공유할 수 있습니다.

자주 사용하는 명령어 모음

# 초기 설정
git config --global user.name "Your Name"
git config --global user.email "[email protected]"
# 저장소 관리
git init  # 새 저장소 생성
git clone <url>  # 원격 저장소 복제
# 변경 사항 관리
git status  # 상태 확인
git add .  # 모든 변경 사항 스테이징
git commit -m "message"  # 커밋
git push  # 원격 저장소에 업로드
git pull  # 원격 저장소에서 가져오기
# 브랜치 관리
git branch  # 브랜치 목록
git checkout -b <name>  # 새 브랜치 생성 및 이동
git merge <name>  # 브랜치 병합

다음 단계

Git의 기본을 익혔다면, 이제 팀 협업을 위한 브랜치 전략과 고급 기능을 배울 차례입니다.

자주 묻는 질문 (FAQ)

Q. 이 내용을 실무에서 언제 쓰나요?

A. Git 설치부터 기본 명령어까지 초보자를 위한 완벽 가이드. 커밋, 브랜치, 원격 저장소 연동까지 한 번에 익힙니다. 실무에서는 위 본문의 예제와 선택 가이드를 참고해 적용하면 됩니다.

Q. 선행으로 읽으면 좋은 글은?

A. 각 글 하단의 이전 글 링크를 따라가면 순서대로 배울 수 있습니다. C++ 시리즈 목차에서 전체 흐름을 확인할 수 있습니다.

Q. 더 깊이 공부하려면?

A. Git 공식 문서와 Git 시리즈 목차의 다음 글(#2 브랜치·#3 원격·#4 되돌리기)을 이어서 보시면 됩니다. 다음 글: Git 실전 가이드 #2: 브랜치와 병합 — branch, merge, 충돌 해결

참고 자료

• Git 공식 문서
• GitHub Guides
• Git 시각화 학습 도구

---

같이 보면 좋은 글 (내부 링크)

이 주제와 연결되는 다른 글입니다.

• Git 실전 가이드 시리즈 목차 | 기초·브랜치·원격·rebase
• C++ 컴파일러 최적화 | PGO·LTO로 “느린 프로그램” 성능 30% 향상시키기
• C++ 멀티 컴파일러 전략과 CI/CD 파이프라인 구축 | 실무 가이드

실전 팁 (Git)

• git status로 작업 트리·스테이징을 먼저 확인합니다. 무엇이 다음 커밋에 들어가는지 모른 채 명령을 치면 실수가 누적됩니다.
• 문제가 생기면 git log --oneline과 git branch -vv로 “지금 어느 커밋·브랜치인지”를 고정한 뒤 diff로 원인을 좁힙니다.
• 이미 푸시한 커밋을 되돌릴 때는 reset --force보다 팀 규칙에 따라 revert가 안전한 경우가 많습니다.

---

실전 체크리스트 (Git)

스테이징·커밋

• git diff / git diff --staged로 의도한 변경만 올라갔는가?
• 토큰·키·대용량 바이너리가 포함되지 않았는가?

원격·병합

• pull 전에 로컬 작업을 정리했는가(stash·임시 브랜치)?
• 충돌 해결 후 다시 빌드·테스트했는가?

공유 브랜치

• 히스토리를 다시 쓰기 전에 팀에 알렸는가?

---

이 글에서 다루는 키워드 (관련 검색어)

Git, 버전관리, GitHub, 협업, 초보자가이드 등으로 검색하시면 이 글이 도움이 됩니다.

관련 글

• Git push pull 차이 | 원격 저장소·GitHub 협업·Pull Request 완벽 가이드
• Git 실전 가이드 시리즈 목차 | 기초·브랜치·원격·rebase
• 개발자를 위한 리눅스·맥 명령어 실전 가이드 — Git과 함께 쓰는 터미널 기본
• C++ 오픈소스 기여: 유명 라이브러리 분석부터 첫 Pull Request까지 [#45-1]
• C++ ABI 호환성 완벽 가이드 | PIMPL·C 인터페이스·버전 관리·프로덕션 패턴 [#55-4]

심화 부록: 구현·운영 관점

이 부록은 앞선 본문에서 다룬 주제(「Git 기초 입문 [#1] — 설치·커밋·브랜치·원격 저장소 한 번에」)를 구현·런타임·운영 관점에서 다시 압축합니다. 도메인별 세부 구현은 글마다 다르지만, 입력 검증 → 핵심 연산 → 부작용(I/O·네트워크·동시성) → 관측의 흐름으로 장애를 나누면 원인 추적이 빨라집니다.

내부 동작과 핵심 메커니즘

flowchart TD
  A[입력·요청·이벤트] --> B[파싱·검증·디코딩]
  B --> C[핵심 연산·상태 전이]
  C --> D[부작용: I/O·네트워크·동시성]
  D --> E[결과·관측·저장]

sequenceDiagram
  participant C as 클라이언트/호출자
  participant B as 경계(런타임·게이트웨이·프로세스)
  participant D as 의존성(API·DB·큐·파일)
  C->>B: 요청/이벤트
  B->>D: 조회·쓰기·RPC
  D-->>B: 지연·부분 실패·재시도 가능
  B-->>C: 응답 또는 오류(코드·상관 ID)

• 불변 조건(Invariant): 버퍼 경계, 프로토콜 상태, 트랜잭션 격리, FD 상한 등 단계별로 문장으로 적어 두면 디버깅 비용이 줄어듭니다.
• 결정성: 순수 층과 시간·네트워크·스케줄에 의존하는 층을 분리해야 테스트와 장애 분석이 쉬워집니다.
• 경계 비용: 직렬화, 인코딩, syscall 횟수, 락 경합, 할당·GC, 캐시 미스를 의심 목록에 둡니다.
• 백프레셔: 생산자가 소비자보다 빠를 때 버퍼·큐·스트림에서 속도를 줄이는 신호를 어디에 둘지 정의합니다.

프로덕션 운영 패턴

영역	운영 관점 질문
관측성	요청 단위 상관 ID, 에러율·지연 p95/p99, 의존성 타임아웃·재시도가 대시보드에 보이는가
안전성	입력 검증·권한·비밀·감사 로그가 코드 경로마다 일관적인가
신뢰성	재시도는 멱등 연산에만 적용되는가, 서킷 브레이커·백오프·DLQ가 있는가
성능	캐시·배치 크기·커넥션 풀·인덱스·백프레셔가 데이터 규모에 맞는가
배포	롤백 룬북, 카나리/블루그린, 마이그레이션·피처 플래그가 문서화되어 있는가
용량	피크 트래픽·디스크·FD·스레드 풀 상한을 주기적으로 검증하는가

스테이징은 데이터 양·네트워크 RTT·동시성을 프로덕션에 가깝게 맞출수록 재현율이 올라갑니다.

확장 예시: 엔드투엔드 미니 시나리오

앞선 본문 주제(「Git 기초 입문 [#1] — 설치·커밋·브랜치·원격 저장소 한 번에」)를 배포·운영 흐름에 맞춰 옮긴 체크리스트입니다. 도메인에 맞게 단계 이름만 바꿔 적용할 수 있습니다.

1. 입력 계약 고정: 스키마·버전·최대 페이로드·타임아웃·에러 코드를 경계에 둔다.
2. 핵심 경로 계측: 요청 ID, 단계별 지연, 외부 호출 결과 코드를 로그·메트릭·트레이스에서 한 흐름으로 본다.
3. 실패 주입: 의존성 타임아웃·5xx·부분 데이터·락 대기를 스테이징에서 재현한다.
4. 호환·롤백: 설정/마이그레이션/클라이언트 버전을 되돌릴 수 있는지 확인한다.
5. 부하 후 검증: 피크 대비 p95/p99, 에러율, 리소스 상한, 알림 임계값을 점검한다.

handle(request):
  ctx = newCorrelationId()
  validated = validateSchema(request)
  authorize(validated, ctx)
  result = domainCore(validated)
  persistOrEmit(result, idempotentKey)
  recordMetrics(ctx, latency, outcome)
  return result

문제 해결(Troubleshooting)

증상	가능 원인	조치
간헐적 실패	레이스, 타임아웃, 외부 의존성, DNS	최소 재현 스크립트, 분산 트레이스·로그 상관관계, 재시도·서킷 설정 점검
성능 저하	N+1, 동기 I/O, 락 경합, 과도한 직렬화, 캐시 미스	프로파일러·APM으로 핫스팟 확인 후 한 가지씩 제거
메모리 증가	캐시 무제한, 구독/리스너 누수, 대용량 버퍼, 커넥션 미반납	상한·TTL·힙/FD 스냅샷 비교
빌드·배포만 실패	환경 변수, 권한, 플랫폼 차이, lockfile	CI 로그와 로컬 diff, 런타임·이미지 버전 핀
설정 불일치	프로필·시크릿·기본값, 리전	스키마 검증된 설정 단일 소스와 배포 매트릭스 표준화
데이터 불일치	비멱등 재시도, 부분 쓰기, 캐시 무효화 누락	멱등 키·아웃박스·트랜잭션 경계 재검토

권장 순서: (1) 최소 재현 (2) 최근 변경 범위 축소 (3) 환경·의존성 차이 (4) 관측으로 가설 검증 (5) 수정 후 회귀·부하 테스트.

배포 전에는 git add → git commit → git push 후 npm run deploy 순서를 권장합니다.