부록B — 명령어·트러블슈팅 레퍼런스

1탄 — 부록 B

명령어 cheat sheet

Linux · Git · npm · pip · pm2 · systemd · wrangler · Anthropic API

📑 이 부록에서 다룰 내용

B-1. Linux 명령어
B-2. Git 명령어
B-3. npm·yarn·pnpm 명령어
B-4. pip·python 명령어
B-5. pm2 (Node.js 프로세스 관리)
B-6. systemd (Linux 서비스 관리)
B-7. Cloudflare wrangler
B-8. Anthropic API curl
B-9. Claude Code 슬래시 명령
B-10. 자주 쓰는 결합 흐름
B-11. 트러블슈팅 명령
B-12. 트러블슈팅 50 — 증상·원인·해결

📘 이 부록의 목적 + 사용법

목적: 1인 운영자가 매일·매주 사용하는 명령어를 한 곳에 모음. Linux · Git · npm · pip · pm2 · systemd · Cloudflare wrangler · Anthropic API curl. 표 형식 — 명령어 · 설명 · 예시.

사용법: 막힘 시점에 5초 안 펼침. CLAUDE.md §7 Common Commands에 자주 쓰는 5~10개 박음.

B-1 Linux 명령어 🔗

파일·폴더

명령어	설명	예시
`ls`	폴더 목록	`ls -la` (숨김 + 권한)
`cd`	폴더 이동	`cd ~/projects/jupjup`
`pwd`	현재 폴더	`pwd`
`mkdir`	폴더 만들기	`mkdir -p src/components`
`rm`	삭제	`rm -rf node_modules`
`cp`	복사	`cp -r src/ backup/`
`mv`	이동·이름 변경	`mv old.md new.md`
`find`	파일 찾기	`find . -name "*.md"`
`grep`	본문 검색	`grep -r "TODO" .`

SSH·원격

명령어	설명	예시
`ssh`	원격 접속	`ssh user@host -p 22`
`scp`	파일 전송	`scp file.zip user@host:~/`
`rsync`	동기화	`rsync -av src/ user@host:dst/`
`ssh-keygen`	키 만들기	`ssh-keygen -t ed25519`
`ssh-copy-id`	키 등록	`ssh-copy-id user@host`

시스템

명령어	설명	예시
`top`	프로세스 종합	`top`
`htop`	시각 프로세스	`htop`
`ps`	프로세스 펼침	`ps aux \| grep node`
`kill`	프로세스 종료	`kill -9 12345`
`df`	디스크 용량	`df -h`
`du`	폴더 크기	`du -sh node_modules`
`free`	메모리	`free -h`
`uname`	시스템 정보	`uname -a`

네트워크

명령어	설명	예시
`curl`	HTTP 호출	`curl -X GET https://api.example.com`
`wget`	파일 다운로드	`wget https://example.com/file.zip`
`ping`	호스트 점검	`ping 8.8.8.8`
`netstat`	포트 펼침	`netstat -tunlp`
`ss`	netstat 대체	`ss -tlnp`
`dig`	DNS 점검	`dig example.com`

B-2 Git 명령어 🔗

기본

명령어	설명	예시
`git init`	새 repo	`git init`
`git clone`	복제	`git clone https://github.com/user/repo`
`git status`	상태 펼침	`git status`
`git add`	스테이징	`git add .` 또는 `git add file.md`
`git commit`	커밋	`git commit -m "메시지"`
`git push`	원격 push	`git push origin main`
`git pull`	원격 pull	`git pull origin main`
`git fetch`	원격 fetch	`git fetch --all`

브랜치

명령어	설명	예시
`git branch`	브랜치 펼침	`git branch -a`
`git checkout`	브랜치 전환	`git checkout dev`
`git checkout -b`	새 브랜치 + 전환	`git checkout -b feature/login`
`git merge`	머지	`git merge feature/login`
`git rebase`	리베이스	`git rebase main`
`git branch -d`	브랜치 삭제	`git branch -d feature/old`

이력

명령어	설명	예시
`git log`	커밋 이력	`git log --oneline -10`
`git diff`	차이 펼침	`git diff HEAD~1`
`git blame`	누가 변경	`git blame SPEC.md`
`git show`	커밋 본문	`git show abc1234`
`git tag`	태그 박기	`git tag v0.1-G1-passed`

보호·복원

명령어	설명	예시
`git stash`	임시 저장	`git stash`
`git stash pop`	임시 복원	`git stash pop`
`git reset`	리셋	`git reset --hard HEAD~1`
`git revert`	되돌림 commit	`git revert abc1234`
`git reflog`	참조 이력	`git reflog`

B-3 npm·yarn·pnpm 명령어 🔗

npm

명령어	설명	예시
`npm init`	package.json	`npm init -y`
`npm install`	설치	`npm install` 또는 `npm i`
`npm i [pkg]`	패키지 추가	`npm i react@latest`
`npm i -D [pkg]`	dev 의존성	`npm i -D typescript`
`npm run [script]`	스크립트 실행	`npm run dev`
`npm test`	테스트	`npm test`
`npm update`	업데이트	`npm update`
`npm audit`	보안 점검	`npm audit`
`npm cache clean`	캐시 비움	`npm cache clean --force`

yarn·pnpm 대응

npm	yarn	pnpm
`npm install`	`yarn`	`pnpm install`
`npm i [pkg]`	`yarn add [pkg]`	`pnpm add [pkg]`
`npm run [script]`	`yarn [script]`	`pnpm [script]`

B-4 pip·python 명령어 🔗

명령어	설명	예시
`python -m venv`	가상 환경	`python -m venv venv`
`source venv/bin/activate`	가상 환경 진입	(Linux/Mac)
`venv\Scripts\activate`	가상 환경 진입	(Windows)
`pip install`	설치	`pip install requests`
`pip install -r`	종합 설치	`pip install -r requirements.txt`
`pip freeze`	설치 목록	`pip freeze > requirements.txt`
`pip uninstall`	제거	`pip uninstall requests`
`pip list`	펼침	`pip list`

B-5 pm2 (Node.js 프로세스 관리) 🔗

명령어	설명	예시
`pm2 start`	시작	`pm2 start app.js --name jupjup`
`pm2 list`	펼침	`pm2 list`
`pm2 logs`	로그 펼침	`pm2 logs jupjup`
`pm2 stop`	중지	`pm2 stop jupjup`
`pm2 restart`	재시작	`pm2 restart jupjup`
`pm2 delete`	삭제	`pm2 delete jupjup`
`pm2 startup`	부팅 시 자동	`pm2 startup`
`pm2 save`	저장	`pm2 save`
`pm2 monit`	시각 점검	`pm2 monit`

B-6 systemd (Linux 서비스 관리) 🔗

명령어	설명	예시
`systemctl start`	시작	`sudo systemctl start nginx`
`systemctl stop`	중지	`sudo systemctl stop nginx`
`systemctl restart`	재시작	`sudo systemctl restart nginx`
`systemctl status`	상태	`sudo systemctl status nginx`
`systemctl enable`	부팅 자동	`sudo systemctl enable nginx`
`systemctl disable`	부팅 X	`sudo systemctl disable nginx`
`journalctl`	로그	`journalctl -u nginx -f`
`systemctl reload`	설정 재로드	`sudo systemctl reload nginx`

B-7 Cloudflare wrangler 🔗

명령어	설명	예시
`wrangler login`	로그인	`wrangler login`
`wrangler init`	새 Worker	`wrangler init my-worker`
`wrangler dev`	로컬 개발	`wrangler dev`
`wrangler deploy`	배포	`wrangler deploy`
`wrangler tail`	로그 펼침	`wrangler tail`
`wrangler d1 create`	D1 만들기	`wrangler d1 create jupjup`
`wrangler d1 execute`	SQL 실행	`wrangler d1 execute jupjup --command "SELECT * FROM users"`
`wrangler kv:namespace create`	KV 만들기	`wrangler kv:namespace create CACHE`
`wrangler r2 bucket create`	R2 만들기	`wrangler r2 bucket create images`
`wrangler secret put`	시크릿 박음	`wrangler secret put ANTHROPIC_KEY`

B-8 Anthropic API curl 🔗

기본 호출

💻 기본 API 호출

curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "안녕하세요"}
    ]
  }'

prompt caching 적용

💻 prompt caching 호출

curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: prompt-caching-2024-07-31" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "긴 시스템 프롬프트 1500자 이상...",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {"role": "user", "content": "질문"}
    ]
  }'

batch API (50% 할인)

💻 batch API 호출

# 배치 만들기
curl https://api.anthropic.com/v1/messages/batches \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "requests": [
      {
        "custom_id": "req-1",
        "params": {
          "model": "claude-sonnet-4-6",
          "max_tokens": 1024,
          "messages": [{"role": "user", "content": "분류 1"}]
        }
      }
    ]
  }'

# 배치 결과 펼침
curl https://api.anthropic.com/v1/messages/batches/[BATCH_ID] \
  -H "x-api-key: $ANTHROPIC_API_KEY"

B-9 Claude Code 슬래시 명령 🔗

매일 사용 — 핵심 6개

명령	설명
`/effort [low\|medium\|high\|xhigh\|max]`	응답 품질·사고 깊이 조절. 인자 없이 입력하면 슬라이더 등장
`/model [모델명]`	모델 전환. 인자 없이 입력하면 선택 화면 등장
`/clear`	컨텍스트 초기화 (새 대화 시작, 이전 대화는 /resume로 복원)
`/compact [지시]`	대화 요약으로 컨텍스트 절약. 선택적으로 요약 방향 지시 가능
`/context`	컨텍스트 사용량을 색상 그리드로 시각화. 최적화 제안 포함
`/cost`	세션 비용·플랜 사용량 펼침 (/usage 별칭)

📘 /effort vs --effort 구분

/effort는 세션 내 슬래시 명령으로 대화 중에 사용합니다. --effort는 CLI 플래그로 claude --effort high처럼 Claude Code 실행 시 사용합니다.

프로젝트 설정 — 첫 세션에서 실행

명령	설명
`/init`	프로젝트에 CLAUDE.md 가이드 자동 생성
`/memory`	CLAUDE.md 편집·메모리 관리
`/permissions`	도구 허용·거부 규칙 관리 (대화형)
`/mcp`	MCP 서버 연결 관리

작업 중 자주 사용

명령	설명
`/plan [설명]`	계획 모드 진입. 큰 변경 전 계획 수립에 활용
`/diff`	미커밋 변경사항을 대화형 diff 뷰어로 확인
`/review [PR]`	PR 또는 현재 변경사항 코드 리뷰
`/rewind`	대화·코드를 이전 체크포인트로 되돌리기
`/btw <질문>`	대화 흐름에 영향 없는 짧은 부가 질문

점검·진단

명령	설명
`/doctor`	설치 상태 점검. 이상 시 f를 눌러 자동 수정
`/status`	버전·모델·계정·연결 상태 확인
`/config`	테마·모델·출력 스타일 등 설정 (/settings 별칭)
`/help`	도움말·전체 명령 목록

B-10 자주 쓰는 결합 흐름 🔗

Phase 1 셋업 (5분)

💻 Phase 1 셋업 흐름

# 새 프로젝트 시작
mkdir my-project && cd my-project
git init
npm init -y

# 5파일 만들기
touch SPEC.md PLAN.md REVIEW.md BUILD.md CLAUDE.md
echo "# My Project" > SPEC.md

# 첫 commit
git add .
git commit -m "Day 0: 5파일 초기 구조"

# Cloudflare Pages 결합
# 1. GitHub repo 만들기
# 2. Cloudflare Dashboard → Pages → Connect to Git
# 3. 자동 배포 시작

# 도메인 결합
# Cloudflare DNS → Add Record

매일 작업 흐름

💻 매일 작업 흐름

# 작업 시작
cd ~/projects/my-project
git pull origin main

# Claude Code 시작
claude
/model claude-sonnet-4-6     # 모델 선택 (또는 /model 입력 후 선택)
/effort medium               # 품질 조절 (low·medium·high·xhigh·max)

# 작업 종료
git add .
git commit -m "Day N: [무엇 했는지]"
git push origin main

# BUILD.md 트레이스 확인
cat BUILD.md | tail -10

Phase 2 진입 시

💻 Phase 2 진입 흐름

# Vercel Pro 진입
# 1. vercel.com → Settings → Plan → Pro

# Supabase Pro 진입
# 1. supabase.com → Project → Settings → Billing → Pro

# Cloudflare Workers Paid
# 1. dash.cloudflare.com → Workers & Pages → Plans → Paid

# 비용 점검 (매월)
claude --print "BUILD.md를 읽고 이번 달 API·호스팅·VPS 비용 종합"

B-11 트러블슈팅 명령 🔗

증상	점검 명령
Git 충돌	`git status` + `git diff`
npm 캐시 문제	`npm cache clean --force`
node_modules 깨짐	`rm -rf node_modules && npm install`
포트 사용 중	`lsof -i :3000` (Linux/Mac) 또는 `netstat -ano` (Windows)
API 응답 느림	`curl -w "@curl-format.txt"` (응답 시간 펼침)
Cloudflare 배포 X	`wrangler deploy --verbose`
Supabase 연결 X	`supabase status` (CLI)

B-12 트러블슈팅 50 — 증상·원인·해결 🔗

💡 사용법

막힘 발생 → 해당 영역 검색 → 해결. 5초 안 답.

Anthropic API (10건)

#	증상	원인	해결
1	`RateLimitError: 429`	분당·시간당 호출 한도 초과	retry with backoff (1s·3s·9s) + 호출 분산
2	`context too long`	입력 토큰 200K 초과	5파일 분할 입력 + prompt caching
3	timeout (10초+)	max_tokens 너무 큼	max_tokens 1024~4096로 축소
4	JSON 출력 비정상	system prompt에 JSON 명시 X	`"JSON 외 출력 금지"` 명시
5	환각 (없는 사실 출력)	`"추정 금지·누락 null"` X	system prompt 강화 + cache_control
6	cache_control X 적용	`anthropic-beta` 헤더 누락	헤더 박음 + 시스템 1024 토큰 이상
7	한국어에 영문 잠입	CLAUDE.md §1 `"한국어 답변"` X	§1 명시 + prompt에 `"한국어로"`
8	Opus 비용 폭주	모든 호출 Opus	80~90% Sonnet + Opus는 결정만
9	batch 결과 X 도착	상태 `processing` 유지	매시간 상태 점검, `failed` 시 재발행
10	tool 호출 X	tool description X	description 1~2문장 + 예시

Git (10건)

#	증상	원인	해결
11	merge conflict	같은 라인 둘이 변경	손으로 정리 → `git add` → `git commit`
12	HEAD detached	특정 commit 체크아웃	`git checkout main`
13	force push 실수	`git push --force`	`git reflog` → revert
14	push 거부 (rejected)	원격이 로컬보다 앞섬	`git pull --rebase` → 충돌 → push
15	큰 파일 commit	100MB+ 파일	`git lfs install` + track
16	node_modules commit	`.gitignore` X	`git rm -r --cached node_modules`
17	.env 파일 GitHub에	`.gitignore`에 `.env` X	즉시 시크릿 회전 + BFG로 history 청소
18	branch 삭제 후 복원	`git branch -D` 실수	`git reflog` + hash 찾기
19	amend 후 push X	history 변경	`git push --force-with-lease`
20	submodule 빈 폴더	`submodule update` X	`git submodule update --init --recursive`

npm·pip (10건)

#	증상	원인	해결
21	peer deps 충돌	dependency tree 충돌	`npm install --legacy-peer-deps`
22	`Cannot find module`	부분 install / 캐시 깨짐	`rm -rf node_modules && npm install`
23	EACCES 권한 에러	글로벌 설치 권한 X	`npm config set prefix '~/.npm-global'`
24	옛 버전 설치	npm 캐시	`npm cache clean --force` + 재설치
25	pip 버전 충돌	Python 버전 호환 X	`python -m venv venv && pip install`
26	다른 PC 의존성 X	`pip freeze` X	`pip freeze > requirements.txt`
27	Python SyntaxError	버전 차이 (3.8 vs 3.10+)	pyenv·conda로 버전 통일
28	node SyntaxError	Node 14 vs 18 문법	`nvm use 18`
29	yarn.lock 충돌	npm·yarn 혼용	한 도구 선택 + 다른 lock 삭제
30	monorepo 패키지 X	workspaces 정의 X	`"workspaces": ["packages/*"]`

배포 (10건)

#	증상	원인	해결
31	TypeScript type 에러	타입 정의 X	`npm run typecheck` + 타입 정정
32	env undefined	환경 변수 X 박음	dashboard에서 env 박음 + 재배포
33	CORS 에러	백엔드 CORS 헤더 X	`cors` 패키지 / Worker headers
34	SSL 에러	도메인 SSL 미적용	Cloudflare 자동 SSL + 5~10분 대기
35	502 Bad Gateway	백엔드 X 응답	`pm2 logs`·`wrangler tail` + 재시작
36	504 Timeout	처리 시간 너무 김	async·캐시 결합
37	SPA 새로고침 404	정적 호스팅 SPA 라우팅 X	`_redirects` (Cloudflare) / `vercel.json`
38	빌드 10분+	의존성·번들 사이즈	코드 splitting + 이미지 압축
39	DNS 적용 X	DNS propagation	24~48시간 대기 / `dig domain.com`
40	wrangler 옛 버전	캐시 또는 배포 X	`wrangler deploy --verbose`

AI 협업 (10건)

#	증상	원인	해결
41	AI 답변이 SPEC 충돌	CLAUDE.md X 적용	CLAUDE.md 매 세션 자동 입력
42	과도한 응답 (5쪽+)	`"간결"` X 명시	prompt에 `"1쪽 안 답"` + max_tokens
43	AI가 프로젝트 모름	`/clear` 후 재입력 X	매 세션 CLAUDE.md 자동 입력 의식
44	AI가 SPEC 임의 수정	`"임의 수정 금지"` X	CLAUDE.md §3 강화
45	없는 함수 호출 (환각)	모델 환각	TypeScript 의무 + 컴파일 점검
46	톤 무너짐 (`~야` 잠입)	톤 X 명시	CLAUDE.md §1 + prompt 양식
47	AI가 옛 정보 답변	모델 학습 시점 차이	`"2026년 기준"` 명시 + docs 인용
48	절반 정답·절반 X	prompt 결합 함정	E3 두 검토자 (Claude + Gemini) 적용
49	MCP tool 호출 X	tool description X	description 1~2문장 + 예시
50	1일 비용 $30+	cache 미적용·Opus 100%	prompt caching + Sonnet 80%

🎉 1탄 — 부록 B 마무리

Linux · Git · npm · pip · pm2 · systemd · Cloudflare wrangler · Anthropic API · Claude Code 슬래시 명령 + 트러블슈팅 50 종합입니다. 막힘 5초 안 펼침합니다.

다음 부록: 부록 D — 5파일 템플릿. SPEC·PLAN·REVIEW·BUILD·CLAUDE.md 그대로 복사 가능.