BasicLike

7강. Skill의 전환 + 종합 실습

BasicLike — Tue, 7 Jul 2026 23:30:01 +0900

7강 종합 실습 ⏱ 약 70분

0. 학습 목표

→ Claude.ai에서 배운 Skill 개념을 Claude Code로 옮기고, 지금까지 쌓아온 것을 하나의 1차 완성본으로 종합합니다.

0.1 이번 글에서 다룰 내용

이번 글은 종합 실습 강의입니다.

Claude.ai에서 배운 Skill 개념을 Claude Code로 옮기고,

지금까지 쌓아온 것을 하나의 프로젝트로 종합합니다.

6강에서 한 번 해본 백업 절차를

앞으로 매번 반복하는 대신 재사용 가능한 스킬로 묶고,

이 강의를 마치면 CLAUDE.md·재사용 스킬·백업본까지 갖춘 완성된 프로젝트 폴더, 이른바 1차 완성본이 만들어집니다.

0.2 이번 강의 실습 내용

이번 강의에서 직접 해보는 것은 다음과 같습니다.

6강의 백업 절차를 재사용 가능한 스킬로 등록하기
규모 있는 요청과 사소한 요청으로 스킬 발동 여부를 시험하기
폴더 구조를 정리하고 README.md로 1차 완성본을 마무리하기

구분	내용
재사용할 것	Claude.ai의 Skill 개념(항상 적용되는 게 아니라 필요할 때만), 6강의 백업 습관
만들 것	반복 절차를 담은 스킬, 그리고 완성된 1차 완성본 폴더

1. Claude.ai에서 배운 Skill의 핵심

→ Instructions와 Skill의 차이를 되짚고, 6강 백업이 왜 Skill감인지 찾아봅니다.

Instructions와 Skill의 차이를 되짚어봅니다.

Instructions는 모든 대화에 항상 적용되며 "내가 누구인지, 기본 말투"를 담습니다.

Skill은 관련 작업이 들어올 때만 적용되며 "특정 작업의 규칙과 처리 순서"를 담습니다.

5강에서 만든 CLAUDE.md는 사실 Instructions와 비슷한 위치입니다.

이 프로젝트라면 항상 적용되는 배경이기 때문입니다.

그렇다면 지금까지 겪은 것 중 "항상 필요한 건 아니고 특정 상황에서만 필요했던 절차"가 있었을까요.

6강에서 새 기능을 추가하기 전에 폴더를 백업하고, 작업 후 diff로 비교했던 그 절차가 딱 그렇습니다.

6강에서는 한 번 손으로 해봤지만, 규모 있는 작업마다 이걸 반복하려면 번거롭습니다.

이런 "특정 상황에서만 필요한 반복 절차"가 바로 Skill로 묶기 좋은 대상입니다.

2. CLAUDE.md와 Skill의 역할 나누기

→ 왜 백업 절차를 CLAUDE.md가 아니라 Skill에 담아야 하는지 확인합니다.

"새 기능 추가 전엔 백업부터"라는 규칙을 5강의 CLAUDE.md에 넣으면, 오타 하나 고치는 사소한 요청에도 이 절차가 매번 끌려 나옵니다. CLAUDE.md는 프로젝트에 늘 적용되는 배경이기 때문입니다. 반면 이것을 Skill로 만들면 규모 있는 기능 추가 작업일 때만 켜집니다. 정리하면 CLAUDE.md는 "항상 유효한 배경"을, Skill은 "특정 작업 유형에서만 필요한 절차"를 담당합니다. 같은 규칙이라도 어디에 두느냐에 따라 늘 켜질지, 필요할 때만 켜질지가 갈립니다.

3. Claude Code에서 스킬은 어떤 모습인가

→ 스킬 파일의 저장 위치와 구조, description의 역할을 확인합니다.

Claude Code에서 이런 재사용 절차는 프로젝트 폴더 안의 .claude/skills/ 폴더에 저장됩니다.

스킬 하나는 그 안에 자기 이름의 폴더를 갖고, 그 안에 SKILL.md라는 파일로 정의됩니다.

예를 들어 백업 절차 스킬이라면 .claude/skills/backup-before-feature/SKILL.md 같은 경로가 됩니다.

SKILL.md 파일의 맨 위에는 이 스킬이 무엇이고 언제 쓰는지를 적는 부분(YAML frontmatter)이 있고,

그 아래에 실제 수행할 절차가 적힙니다. 대략 이런 형태입니다.

---
name: backup-before-feature
description: 규모 있는 기능을 추가하기 전에 프로젝트를 백업하고, 작업 후 변경 내용을 비교하는 절차. 사소한 수정에는 쓰지 않는다.
---

# 기능 추가 전 백업 절차

1. 현재 프로젝트 폴더 전체를 백업본으로 복사한다
2. 요청받은 기능을 추가한다
3. 백업본과 현재 폴더의 차이를 비교해 보여준다

여기서 핵심은 description입니다.

Claude Code는 이 설명을 보고 "지금 요청이 이 스킬을 써야 하는 상황인지"를 스스로 판단합니다.

이는 Claude.ai에서 배운 "Skill의 description이 발동 여부를 결정한다"는 원리와 정확히 같습니다.

이 원리는 나중에 17강에서 나만의 MCP 서버를 만들 때 다시 등장합니다.

4. 실습 — 반복 절차를 스킬로 만들기

→ 6강 백업 절차를 스킬로 등록하고, 발동 여부를 시험합니다.

4.1 스킬 등록하기

inventory-project 폴더에서 Claude Code를 실행하고, 6강에서 손으로 해본 절차를 스킬로 정리해달라고 요청합니다.

cd ~/inventory-project
claude

[화면 캡처: 스킬 파일 생성 요청 화면]

6강에서 내가 손으로 했던 절차
(작업 전 폴더 백업 → 기능 추가 → 백업본과 비교)를
재사용 가능한 스킬로 만들어줘.

조건:
- 어떤 상황에서 이 절차를 써야 하는지 description에 명확히 적어줘
- 단계를 순서대로 나눠줘
- 이 프로젝트의 .claude/skills/ 아래에 등록되는 형태로 만들어줘

4.2 스킬 등록 확인하기

승인 후, .claude/skills/ 폴더 안에 스킬 폴더와 SKILL.md가 생겼는지 확인합니다.

cat .claude/skills/*/SKILL.md

cat은 "파일이 실제로 만들어졌는지"를 보는 방법입니다.

이와 별개로, Claude Code가 그 스킬을 실제로 인식하고 있는지는 세션 안에서 확인할 수 있습니다.

방법은 두 가지입니다. 하나는 슬래시 명령어를 쓰는 것이고, 다른 하나는 지금까지처럼 자연어로 물어보는 것입니다.

/skills

/skills를 입력하면 현재 세션이 인식하는 스킬 목록이 나옵니다.

방금 만든 백업 스킬 이름이 그 목록에 있으면 정상입니다. 명령어가 기억나지 않으면, 그냥 이렇게 물어봐도 됩니다.

지금 이 프로젝트에서 쓸 수 있는 스킬이 뭐가 있어?

파일이 생긴 것(cat)과 Claude Code가 그것을 인식하는 것(/skills)은 다른 확인입니다. 둘 다 맞아야 다음 단계에서 스킬이 제대로 발동합니다.

팁: 파일을 직접 고쳤는데 목록에 바로 안 보이면, 세션이 아직 이전 상태를 물고 있을 수 있습니다. 이럴 때는 /reload-skills로 다시 스캔하거나 세션을 재시작하면 반영됩니다. (슬래시 명령어 이름은 버전에 따라 다를 수 있으니, /만 입력해 뜨는 목록에서 "skill"이 들어간 명령을 찾아도 됩니다.)

4.3 스킬 실행 여부 시험하기

등록한 스킬이 필요할 때만 켜지는지 시험합니다.

3절에서 본 대로, 판단 근거는 스킬의 description입니다.

규모 있는 요청과 사소한 요청을 각각 넣어, 백업 절차가 켜지는 상황과 켜지지 않는 상황을 비교합니다.

재고 수량을 일괄 수정하는 기능을 추가해줘.

이런 규모 있는 작업에는 백업 절차가 먼저 제안되는지 봅니다.

4.3 발동 여부 시험하기

반대로 아래처럼 사소한 요청에는 그 절차가 끌려 나오지 않는지도 확인합니다.

출력 메시지의 오타 하나만 고쳐줘.

▶ 지금 해보세요

위 요청문으로 스킬을 만들고, cat .claude/skills/*/SKILL.md로 등록됐는지 확인합니다.
규모 있는 요청(일괄 수정)을 넣어 백업 절차가 제안되는지 봅니다.
사소한 요청(오타 수정)을 넣어 그 절차가 끌려 나오지 않는지 확인합니다.

✔ 확인 기준: 규모 있는 작업에는 절차가 제안되고, 사소한 작업에는 조용하면 성공입니다. description이 발동을 가른다는 것을 확인한 셈입니다.

5. 종합 실습 — 1차 완성본 만들기

→ 지금까지 쌓은 폴더 구조를 정리하고, README.md로 전체 내용을 기록합니다.

5.1 폴더 구조

이제 inventory-project 폴더가 어떤 구조인지 전체를 짚어봅니다. Claude Code 세션에서 나온 뒤(/exit) 터미널에서 확인하거나, 세션 안에서 "이 폴더 구조를 보여줘"라고 물어도 됩니다.

inventory-project/
├── CLAUDE.md              ← 5강에서 만든 프로젝트 배경·규칙
├── inventory.py           ← 3~6강에 걸쳐 기능이 추가된 본체
├── .claude/skills/        ← 이번 강의에서 만든 재사용 절차
└── (project_v1은 홈 폴더에 별도 보관된 6강 백업본)

5.2 README.md

여기에 마지막 한 조각을 더합니다.

지금까지 무엇을 만들었는지 한눈에 보이는 README.md입니다.

Claude Code에 프로젝트 정리를 요청해 문서로 남깁니다.

이 프로젝트의 현재 구조와 지금까지 추가된 기능을
README.md로 정리해줘.

[화면 캡처: Claude Code가 만든 README.md 내용]

승인 후, 실제로 README.md가 만들어졌는지 확인합니다.

터미널에서 cat README.md로 열어보거나, VS Code 같은 편집기로 열어봐도 됩니다.

프로젝트 설명과 지금까지 추가한 기능이 정리되어 있으면 됩니다.

cat README.md

이 README.md까지 더해지면, 최종 폴더 구조는 다음과 같습니다.

inventory-project/
├── CLAUDE.md              ← 5강 프로젝트 배경·규칙
├── inventory.py           ← 3~6강 기능이 쌓인 본체
├── README.md              ← 7강, 프로젝트 전체 요약
├── .claude/skills/        ← 7강 재사용 절차
└── (project_v1은 홈 폴더의 6강 백업본)

✔ 확인 기준: CLAUDE.md, 기능이 쌓인 inventory.py, 재사용 스킬, README.md, 백업본까지 갖춘 폴더가 완성되면 1차 완성본이 완성된 것입니다. 이 폴더는 사라지지 않고, 이후 MCP·VS Code 트랙을 마친 뒤 그대로 이어받아 확장판으로 발전합니다. 실습 PC에 잘 보관해 두세요.

6. 지금까지 만든 것은 자동화의 어떤 부분인가

→ 오늘까지 만든 조각들을 자동화 관점에서 정리하고, 다음 단계에 필요한 것을 상상해봅니다.

오늘까지 만든 조각들을 자동화 관점에서 정리해봅니다.

CLAUDE.md는 Claude가 "이 프로젝트에서 무엇을 해야 하는지"를 매번 새로 설명하지 않아도 되게 합니다.

4강의 승인 흐름은 사람이 개입해 확인하는 지점으로, 자동화될수록 줄어드는 부분입니다.

6강의 백업 절차는 실수해도 되돌릴 수 있는 안전망으로, 오히려 자동화될수록 더 중요해집니다.

그리고 이번에 만든 스킬은 사람이 짧게 지시만 해도 정해진 절차가 알아서 실행되게 합니다.

이 네 가지 중 "사람이 없어도 알아서 돌아가게" 만드는 데 가장 가까운 것은 스킬입니다.

다만 지금은 여전히 사람이 터미널에 입력해야 시작됩니다.

무언가 정해진 시간이나 외부 신호로 자동 실행되게 하려면 두 가지가 더 필요합니다.

하나는 MySQL이나 email 같은 외부 서비스와 연결하는 방법이고(다음 MCP 트랙),

다른 하나는 정해진 시간에 스스로 실행되게 하는 스케줄링입니다.

▶ 지금 해보세요

지금 만든 재고관리 프로젝트를 완전히 자동화한다면 무엇이 사람 개입 없이 돌아가면 좋을지 하나 고릅니다.
"언제 실행되면 좋은가 / 무엇을 하면 좋은가 / 사람이 꼭 확인해야 할 부분은 어디인가" 세 가지로 나눠 적어봅니다.
이 메모는 다음 MCP 트랙에서 다시 꺼내 쓰니 버리지 말고 보관합니다.

✔ 확인 기준: "완전 자동화"도 결국 오늘 배운 조각(CLAUDE.md, 승인 지점, 스킬)의 확장이라는 것, 그리고 "언제 실행되는가"와 "외부와 연결되는가"가 다음 단계의 핵심 질문이라는 걸 느끼면 충분합니다.

→ 다음 강의 (8강): 이 1차 완성본을 외부 세계와 연결하는 첫걸음으로, MCP라는 개념을 이해합니다.

6강. 프로젝트 개념의 전환

BasicLike — Tue, 7 Jul 2026 23:28:00 +0900

6강 실습 중심 ⏱ 약 45분

0. 학습 목표

→ git 없이도 "작업을 되돌릴 수 있다"는 감각을, 폴더를 복사해 비교하는 방식으로 직접 체감합니다.

0.1 이번 글에서 다룰 내용

이번 글은 실습 중심 강의입니다.

5강 끝에서 예고한 대로, Claude Code가 파일을 직접 고치다 보면 "이전 상태로 되돌리고 싶다"는 순간이 옵니다.

이번 강의는 그 되돌리기를 가장 단순한 방식, 곧 폴더를 통째로 복사해두고 나중에 비교하는 방식으로 직접 해봅니다.

git이라는 전문 도구는 아직 쓰지 않습니다.

손으로 흉내 내보면서, 왜 나중에 git이 필요해지는지 그 밑거름을 먼저 쌓는 것이 목표입니다.

더불어 Claude.ai의 Projects(대화와 파일 묶음)가 Claude Code에서는 실제 폴더로 바뀐다는 점도 함께 짚습니다.

0.2 이번 강의 실습 내용

이번 강의에서 직접 해보는 것은 다음과 같습니다.

작업 전 프로젝트 폴더 전체를 project_v1으로 복사해 백업하기
원래 폴더에서 Claude Code로 새 기능을 추가하기
diff로 백업본과 작업본을 비교하고, 되돌리는 방법을 확인하기

구분	내용
재사용할 것	Claude.ai Projects의 "관련 파일을 한데 묶어 관리한다"는 개념
확인할 것	폴더 복사로 되돌릴 수 있다는 감각, 그리고 "무엇이 바뀌었는지 눈으로 찾기 번거롭다"는 불편함

1. Claude.ai Projects와 무엇이 같고 다른가

→ Claude.ai의 Projects와 Claude Code의 프로젝트 폴더가 어떻게 다른지 확인합니다.

Claude.ai의 Projects는 대화와 파일을 묶어 클라우드에 저장하는 것이었고,

파일을 참고하려면 업로드해야 했습니다.

Claude Code의 프로젝트는 내 컴퓨터의 실제 폴더이고,

그 안의 파일을 Claude Code가 직접 읽고 씁니다.

5강에서 만든 CLAUDE.md는 바로 이 폴더의 배경과 규칙을 적어두는 곳이었습니다.

즉 Claude Code에서 "프로젝트"란 곧 "폴더 하나"입니다.

이 점이 이번 강의의 되돌리기 방식과 직접 이어집니다.

폴더가 곧 프로젝트라면, 폴더를 통째로 복사해두는 것만으로 그 시점의 프로젝트 전체를 보존할 수 있기 때문입니다.

2. 왜 되돌리기 감각이 필요한가

→ Claude Code가 파일을 직접 고치는 방식에서 되돌리기가 왜 다르게 필요한지 살펴봅니다.

3강부터 5강까지, Claude Code는 inventory.py를 여러 번 직접 고쳤습니다.

5강에서는 CLAUDE.md 규칙에 따라 재고 삭제 기능까지 붙였습니다.

만약 이렇게 쌓인 수정 중 어느 시점의 결과가 마음에 안 든다면 어떻게 할까요.

Claude.ai는 답변만 만들었으니 "이전 답변으로 돌아가기"가 쉬웠지만, Claude Code는 파일 자체가 바뀌어버립니다.

되돌아갈 이전 상태를 따로 남겨두지 않았다면, 손으로 되돌리기가 막막해집니다.

전문적으로는 git이라는 도구가 이 문제를 해결하지만,

이번 강의에서는 git 없이 손으로 흉내 내는 방법으로 먼저 감각을 잡습니다.

작업 전에 폴더 전체를 복사해 project_v1으로 저장하고,

작업은 원래 폴더에서 진행한 뒤, 두 폴더를 나란히 열어 무엇이 달라졌는지 확인하는 방식입니다.

3. 실습 — 백업하고, 고치고, 비교하기

→ 폴더를 백업한 뒤 새 기능을 위임하고, 백업본과 비교해 되돌리기 감각을 잡습니다.

3.1 작업 전 폴더 백업하기

먼저 지금까지 쓰던 재고관리 프로젝트 폴더 전체를 복사해 백업본을 만듭니다.

cp -r은 폴더를 통째로(하위 파일까지) 복사하는 명령입니다.

cd ~
cp -r inventory-project project_v1

이제 홈 폴더에 project_v1이라는 백업본이 생겼습니다.

이 폴더는 이번 실습이 끝날 때까지 손대지 않고 그대로 둡니다.

작업은 원래 폴더인 inventory-project에서만 합니다.

3.2 원래 폴더에서 새 기능 위임하기

원래 폴더에서 Claude Code를 실행하고 새 기능을 요청합니다.

승인 화면이 나오면 4강에서 배운 대로 내용을 읽고 승인합니다.

[화면 캡처: 백업 후 새 기능 추가를 요청한 승인 화면]

cd ~/inventory-project
claude

재고 목록을 파일로 저장하는 기능과, 저장된 파일을
다시 불러오는 기능을 inventory.py에 추가해줘.

3.3 백업본과 비교하고 되돌리기

이제 백업본(project_v1)과 작업본(inventory-project)의 inventory.py가 어떻게 달라졌는지 비교합니다.

두 파일을 나란히 견주는 간단한 방법은 diff 명령입니다.

Claude Code 세션에서 나온 뒤(/exit) 터미널에 입력합니다.

[화면 캡처: diff 명령으로 두 파일의 차이를 확인한 결과]

diff ~/project_v1/inventory.py ~/inventory-project/inventory.py

양쪽에서 다른 코드 라인만 표시됩니다.

무엇이 새로 생겼는지, 그리고 바뀐 부분을 찾는 데 얼마나 걸렸는지 살펴봅니다.

되돌리는 방법도 명령으로 확인해 둡니다.

원리는 단순합니다.

지금 작업본을 지우고, 백업해둔 project_v1을 원래 이름으로 다시 복사하면 백업 시점으로 완전히 돌아갑니다.

# (되돌리기 예시 — 지금 실제로 실행하지 않아도 됩니다)
cd ~
rm -rf inventory-project
cp -r project_v1 inventory-project

첫 줄에서 홈 폴더로 이동하고, 둘째 줄에서 작업본 폴더를 통째로 지운 뒤, 셋째 줄에서 백업본을 원래 이름(inventory-project)으로 다시 복사합니다. 이렇게 하면 3.2에서 추가한 기능이 사라지고, 백업 시점 그대로 되돌아갑니다.

⚠ 주의: rm -rf는 폴더를 확인 없이 완전히 삭제하는 명령으로, 잘못 쓰면 되살릴 수 없습니다. 지울 대상 이름(inventory-project)이 정확한지 반드시 확인하고, 백업본(project_v1)이 멀쩡히 있는지 먼저 ls ~로 확인한 뒤 실행하세요. 이번 실습에서는 되돌리기가 어떻게 되는지 원리만 이해하면 되므로, 실제로 실행하지 않고 넘어가도 괜찮습니다.

▶ 지금 해보세요

3.1의 cp -r로 백업본을 만들고, ls ~로 홈 폴더에 project_v1이 생겼는지 확인합니다.
3.2의 요청으로 원래 폴더에 새 기능을 추가하고 승인합니다.
3.3의 diff로 두 폴더의 차이를 확인하고, 바뀐 부분을 찾는 데 얼마나 걸렸는지 느껴봅니다.
되돌리기 명령은 눈으로 읽어만 두고, 어떤 순서로 원래 상태로 돌아가는지 이해합니다. (실제 실행은 선택)

✔ 확인 기준: 백업본으로 "되돌릴 수 있다"는 감각을 갖게 되면 완료입니다. 다만 무엇이 바뀌었는지 찾는 과정이 번거로웠다는 것도 함께 느꼈다면, 이번 강의의 숨은 목표까지 달성한 것입니다.

4. 이 방식의 한계 — 왜 나중에 git이 필요한가

→ 폴더 복사 방식의 불편함을 짚고, 그것이 13강 git으로 어떻게 이어지는지 예고합니다.

Claude.ai의 Projects(자료 묶음)가 Claude Code에서는 실제로 실행되는 폴더로 바뀌었고,

git 없이도 "복사해서 백업 → 비교 → 필요시 되돌리기"로 안전망을 만들 수 있다는 것을 확인했습니다.

다만 한 가지를 정확히 짚어둘 필요가 있습니다.

이 폴더 복사 방식은 "되돌릴 수 있다"는 감각은 잘 주지만,

v1과 작업본 중 정확히 무엇이 달라졌는지 눈으로 찾는 과정이 불편합니다.

파일이 짧으면 금방 찾지만, 수백 줄짜리 파일이라면 이야기가 달라집니다.

또 기능을 추가할 때마다 project_v1, v2, v3처럼 폴더가 계속 쌓이는 것도 번거롭습니다.

나중에 배울 git은 바로

"무엇이 바뀌었는지 자동으로 보여주는" 부분과

"폴더를 쌓지 않고 한곳에서 이력을 관리하는" 부분을 해결합니다.

백업이라는 개념 자체가 필요 없어지는 것이 아니라,

백업·비교를 훨씬 편하게 만들어주는 것입니다.

오늘 느낀 이 불편함이,

13강에서 git을 배울 때 "왜 이게 필요한지" 바로 와닿게 하는 밑거름이 됩니다.

→ 다음 강의 (7강): 지금까지 쌓은 모든 것(CLAUDE.md·백업 습관·반복 작업)을 종합해 1차 완성본을 만들고, 반복 작업을 재사용 가능한 스킬로 등록하는 법을 배웁니다.

5강. 컨텍스트 엔지니어링의 전환

BasicLike — Tue, 7 Jul 2026 21:50:01 +0900

5강 실습 중심 ⏱ 약 45분

0. 학습 목표

→ 3강에서 요청마다 반복해 넣어야 했던 파일명과 조건을, CLAUDE.md 파일 하나로 줄이는 법을 익힙니다.

0.1 이번 글에서 다룰 내용

이번 글은 실습 중심 강의입니다.

3강에서 기존 파일을 고칠 때는 대상 파일·바꿀 지점·원하는 동작·유지할 것 네 가지를 요청문에 담아야 한다고 배웠습니다. 그런데 이걸 요청마다 매번 반복하려니 번거로웠습니다.

"또 inventory.py에서, 또 함수 구조는 유지하고…"를 매번 쓰는 셈이니까요.

이번 강의는 그 반복을 CLAUDE.md 파일 하나로 덜어내는 법을 다룹니다.

이것은 Claude.ai에서 배운 컨텍스트 엔지니어링의 Claude Code 버전입니다.

Claude.ai가 대화에 참고 자료를 넣는 것이었다면,

Claude Code에서는 프로젝트 폴더 자체가 컨텍스트가 되고, 그 폴더의 규칙을 적어두는 문서가 CLAUDE.md입니다.

0.2 이번 강의 실습 내용

이번 강의에서 직접 해보는 것은 다음과 같습니다.

/init으로 CLAUDE.md 초안 만들기
Claude Code에 요청해 초안에 규칙 두 가지를 덧붙이고 cat CLAUDE.md로 확인하기
파일명 없이 짧게 요청해, 규칙이 자동 반영되고 CLAUDE.md 자체는 그대로인지 확인하기

구분	내용
재사용할 것	Claude.ai의 컨텍스트 엔지니어링, 3강의 요청문 네 가지 요소
새로 익힐 것	/init으로 CLAUDE.md 초안 만들기, 규칙을 덧붙여 짧은 요청에 자동 반영시키기

1. 3강에서 반복했던 것

→ 요청마다 파일명과 조건을 반복해야 했던 번거로움을 되짚고, Claude.ai의 해법과 연결합니다.

3강에서 구체적인 요청을 만들 때, 우리는 "inventory.py 파일에서 재고 수량이 5개 미만이면… 기존 함수 구조는 그대로 유지해줘"처럼 대상 파일과 조건을 요청문에 직접 담았습니다.

결과는 정확했지만, 요청을 넣을 때마다 같은 파일명과 같은 조건을 반복해서 쓰는 것이 번거로웠습니다.

만약 이 프로젝트에 "출력할 때는 항상 로그를 남긴다" 같은 규칙이 더 있었다면, 그것마저 매번 붙여야 했을 것입니다.

Claude.ai에서 이 반복 문제를 어떻게 풀었는지 떠올려봅니다.

자주 쓰는 요소를 Instructions에 등록해두면 매번 설명하지 않아도 됐습니다.

Claude Code에도 같은 발상의 해법이 있습니다.

프로젝트에 한 번 적어두면, 이후 요청마다 자동으로 참고되는 문서를 두는 것입니다.

2. 컨텍스트가 프로젝트 폴더 자체가 되다

→ Claude.ai의 컨텍스트 개념이 Claude Code에서 어떻게 확장되는지 비교합니다.

Claude.ai에서 컨텍스트 엔지니어링은 "이번 대화에서 무엇을 참고 자료로 넣을지"를 다루는 일이었습니다.

Claude Code에서는 대화가 아니라 프로젝트 폴더 전체가 컨텍스트의 기본 단위입니다.

그리고 그 폴더의 배경과 규칙을 적어두는 문서가 CLAUDE.md입니다.

구분	Claude.ai	Claude Code
컨텍스트	대화창 안의 첨부 파일이나 이전 대화	프로젝트 폴더 안의 모든 파일
반복 설명 해결	Instructions	CLAUDE.md
적용 범위	계정 전체	해당 프로젝트 폴더 안

Instructions와 CLAUDE.md는 "반복 설명을 줄인다"는 목적은 같지만 적용 범위가 다릅니다.

하나는 계정 전체에 늘 적용되고, 다른 하나는 특정 프로젝트에서만 적용됩니다.

3. CLAUDE.md 만들고 규칙 덧붙이기

→ /init으로 초안을 만든 뒤 규칙을 덧붙이고, 그 내용을 화면에 띄워 기준으로 삼습니다.

3.1 /init으로 초안 만들기

CLAUDE.md는 프로젝트 폴더 맨 위에 두는 파일로, 직접 손으로 작성할 수도 있지만 Claude Code에는 초안을 자동으로 만들어주는 전용 명령 /init이 있습니다. 3강에서 쓰던 폴더에서 Claude Code를 실행한 뒤 /init을 입력하면, 폴더 구조를 스캔해 CLAUDE.md 초안을 만들어줍니다.

cd ~/inventory-project
claude

[화면 캡처: /init 실행 후 생성된 CLAUDE.md 초안]

/init

여기서 두 가지를 미리 알아두면 당황하지 않습니다.

첫째, /init이 만드는 초안은 대개 영어로, 프로젝트 구조 설명 위주로 채워집니다.

우리가 원하는 코딩 규칙까지 알아서 넣어주지는 않습니다. 영어로 나와도 정상이니 그대로 두면 됩니다.

둘째, 그래서 이 초안은 완성본이 아니라 출발점입니다.

다음 단계에서 우리가 필요한 규칙을 덧붙여야 비로소 이번 실습에 쓸 CLAUDE.md가 됩니다.

3.2 규칙 덧붙이고 내용 확정하기

초안에 이번 실습에서 확인할 규칙 두 가지를 덧붙입니다. 파일을 직접 편집기로 열지 않고, 지금까지 해온 것처럼 Claude Code에 자연어로 요청하면 됩니다. 규칙은 한국어로 덧붙여도 문제없습니다.

CLAUDE.md에 아래 두 규칙을 코딩 규칙 항목으로 추가해줘.
- 주요 파일은 inventory.py이다.
- 함수 이름은 동사로 시작한다. (예: add_item, remove_item)

승인 후, 지금 CLAUDE.md에 어떤 규칙이 적혀 있는지 화면에 띄워 눈으로 확인해둡니다.

이 내용이 곧 뒤에서 결과를 대조할 기준이 됩니다.

[화면 캡처: 규칙 추가 요청 후 cat CLAUDE.md로 확인한 결과]

cat CLAUDE.md

/init이 만든 영문 프로젝트 설명 아래에, 방금 덧붙인 두 규칙이 다음과 같이 들어가 있으면 됩니다.

## 코딩 규칙 (직접 추가)
- 주요 파일은 inventory.py이다.
- 함수 이름은 동사로 시작한다. (예: add_item, remove_item)

팁: /init이 만든 초안에는 필요 없는 설명이 섞여 있을 수 있습니다. 지금은 지우지 않고 규칙만 덧붙여도 실습에는 충분합니다. CLAUDE.md의 자동 인식 규칙과 세부 문법은 버전에 따라 달라질 수 있으니, 정확한 동작이 궁금하면 공식 문서(code.claude.com)에서 최신 내용을 확인하세요.

4. 실습 — 짧은 요청으로 규칙이 반영되는지 대조하기

→ 파일명을 밝히지 않고 짧게 요청해, 3강 방식과 결과를 비교합니다.

이제 규칙이 눈앞에 있으니, 파일명을 밝히지 않고 짧게 요청해 이 규칙이 실제로 지켜지는지 대조합니다.

재고 삭제 기능 추가해줘.

[화면 캡처: 짧은 요청만으로 inventory.py에 delete_item() 함수가 추가된 결과]

여기서 헷갈리지 말아야 할 것이 하나 있습니다. 이 요청으로 바뀌는 파일은 CLAUDE.md가 아니라 inventory.py입니다. CLAUDE.md는 수정되는 대상이 아니라, Claude Code가 작업 전에 자동으로 읽는 참고 문서입니다.

3.2에서 확인한 그 내용 그대로 읽히기만 하고, 한 글자도 바뀌지 않습니다.

(3.2에서 규칙을 덧붙일 때만 CLAUDE.md가 바뀌었고, 지금 이 요청은 CLAUDE.md를 읽기만 합니다.)

같은 작업을 3강 방식과 나란히 놓으면 무엇이 달라졌는지 분명해집니다.

구분	3강 (CLAUDE.md 없을 때)	5강 (CLAUDE.md 있을 때)
요청문	대상 파일·기준·유지 조건을 매번 담은 긴 문장	"재고 삭제 기능 추가해줘" (짧음)
대상 파일	요청문에 직접 명시	CLAUDE.md의 "주요 파일은 inventory.py"를 읽고 스스로 찾아감
규칙 적용	매번 요청문에 담아야 함	"함수 이름은 동사로 시작" 규칙이 자동 적용 → `delete_item()`처럼 생성

▶ 지금 해보세요

위의 짧은 요청을 입력하고, 승인 화면에서 어느 파일이 바뀌는지 확인합니다. (inventory.py여야 정상입니다.)
승인 후 cat inventory.py로 새로 생긴 함수 이름을 봅니다. 요청하지 않았는데도 동사로 시작하는지 확인합니다.
cat CLAUDE.md를 다시 실행해, 3.2에서 본 내용과 한 글자도 다르지 않은지 대조합니다. 읽히기만 했고 수정되지 않았음을 눈으로 확인합니다.

✔ 확인 기준: 짧은 요청 하나로 (1) 대상 파일을 스스로 찾아가고 (2) CLAUDE.md의 규칙대로 함수가 만들어지며 (3) CLAUDE.md 자체는 그대로라는 세 가지를 대조로 확인하면 완료입니다.

→ 다음 강의 (6강): Claude Code가 파일을 직접 고치다 보면 되돌리고 싶을 때가 생깁니다. v1/v2 백업 폴더 방식으로 "되돌리기" 감각을 익힙니다.

4강. 모델 선택 & 권한 승인 흐름

BasicLike — Tue, 7 Jul 2026 21:39:36 +0900

4강 실습 중심 ⏱ 약 45분

0. 학습 목표

→ 작업을 맡기기 전에 내가 쥘 수 있는 두 손잡이, 곧 승인(안전)과 모델(성능·비용)을 다루는 법을 익힙니다.

0.1 이번 글에서 다룰 내용

이번 글은 실습 중심 강의입니다.

3강까지 우리는 Claude Code에 일을 맡기는 법을 익혔습니다.

그런데 일을 맡긴다는 것은 통제를 완전히 넘기는 것이 아닙니다.

맡기기 전에, 그리고 맡기는 도중에 내가 쥐고 있어야 할 손잡이가 있습니다.

이번 강의는 그 손잡이 두 개를 다룹니다.

하나는 승인입니다.

Claude Code가 실제로 무엇을 바꾸기 전에 사람이 확인하는 장치로,

잘못된 실행을 막는 안전의 손잡이입니다.

3강에서 요청마다 열어 봤던 그 화면이 바로 이것입니다.

다른 하나는 모델입니다.

같은 일도 어떤 모델에 맡기느냐에 따라 속도·정확도·비용이 달라지는 성능의 손잡이입니다.

이 둘을 쥘 수 있으면, 일을 맡기면서도 결과를 내가 원하는 방향으로 끌어올 수 있습니다.

0.2 이번 강의 실습 내용

이번 강의에서 직접 해보는 것은 다음과 같습니다.

승인 화면을 누르기 전에 무엇이 바뀔지 예측하고 확인하기 (안전 손잡이)
/status로 현재 모델을 확인하고 /model로 다른 모델로 바꾸기 (성능 손잡이)
같은 작업을 모델을 바꿔가며 넣어 속도·정확도·비용 감각 비교하기

구분	내용
재사용할 것	3강에서 요청마다 살펴본 승인 화면, Claude.ai에서 배운 모델 등급(Opus·Sonnet·Haiku)
새로 익힐 것	승인 화면이 정확히 무엇을 묻는지, /model로 작업에 맞게 모델을 바꾸는 법

1. 첫 번째 손잡이 — 승인이라는 안전장치

→ 3강에서 요청마다 봤던 승인 화면이 정확히 무엇을 묻는지, 왜 안전장치인지 짚어봅니다.

1.1 그 화면이 묻던 것

1강의 hello.py, 3강의 inventory.py에서 모두 승인 화면이 나왔습니다.

그때는 별생각 없이 승인을 눌렀을 것입니다. 이번에는 그 화면이 정확히 무엇을 묻고 있었는지 봅니다.

[화면 캡처: Claude Code 승인 요청 화면(파일 변경 내용과 승인/거부 선택)]

3강에서는 요청을 넣을 때마다 승인 화면을 열어 "허술한 요청은 어디까지 바뀌려 하는지,

구체적인 요청은 내가 원한 부분만 바뀌는지"를 살펴봤습니다.

그때 본 그 화면이 정확히 무엇을 묻고 있었는지 이제 짚어봅니다.

Claude Code가 작업을 제안하면 "이렇게 바꿔도 될까요?"라고 물어봅니다.

승인하면 실행되고, 거부하면 실행되지 않은 채 다른 방식을 다시 제안합니다.

Claude.ai는 답변만 만들기 때문에 이런 "승인"이라는 개념 자체가 없었습니다.

Claude Code는 실제로 파일을 고치고 명령어를 실행하기 때문에, 잘못된 실행을 막는 장치가 필요한 것입니다.

신입 개발자에게 "이 파일 고쳐도 될까요?"라고 매번 확인받게 하는 것과 같습니다.

3강에서 허술한 요청이 엉뚱한 곳까지 바꾸려 할 때 이 화면에서 걸러낼 수 있었던 것도 바로 이 손잡이 덕분입니다.

1.2 어떤 작업에 승인이 필요한가

모든 작업에 승인이 필요한 것은 아닙니다.

대체로 시스템을 바꾸는 작업에는 승인을 묻고, 그냥 읽거나 살펴보는 작업은 승인 없이 진행되는 경우가 많습니다.

보통 승인을 묻는 작업	승인 없이 넘어가는 경우가 많은 작업
파일 내용 수정, 새 파일 생성·삭제, 터미널 명령어 실행	파일 읽기, 코드 분석·검색

무언가를 바꾸는 작업에는 승인이 필요하고, 읽기만 하는 작업은 대체로 그냥 진행됩니다.

다만 이 경계는 설정에 따라 달라질 수 있으므로, 승인 화면이 뜨면 무엇을 하려는지 읽는 습관을 들이는 것이 좋습니다.

안전 손잡이는 쥐고 있을 때만 손잡이입니다. 읽지 않고 누르면 없는 것과 같습니다.

2. 두 번째 손잡이 — 모델이라는 성능 조절기

→ 작업에 맞게 모델을 바꾸는 법과, 등급별 성격 차이를 확인합니다.

2.1 /model로 모델 바꾸기

승인이 "안전"을 쥐는 손잡이였다면, 모델은 "성능과 비용"을 쥐는 손잡이입니다.

Claude.ai에서는 입력창 근처 메뉴를 클릭해 모델을 바꿨습니다.

Claude Code는 터미널 안에서 세션 도중에 명령어로 전환합니다.

[화면 캡처: /status 실행 화면(현재 사용 중인 모델 표시)]

model 뒤에 별칭을 붙이면 즉시 바뀌고, 별칭 없이 /model만 입력하면 선택 메뉴가 뜹니다.

지금 어떤 모델을 쓰고 있는지는 /status로 확인합니다.

# 세션 도중 바로 전환
/model sonnet
/model haiku
/model opus

# 별칭 없이 입력하면 선택 메뉴가 열림
/model

직접 해보려면, 3강에서 쓰던 inventory-project 폴더에서 Claude Code를 실행한 뒤

/status로 현재 모델을 확인하고, /model haiku로 전환한 다음 다시 /status로 바뀐 것을 확인하면 됩니다.

[화면 캡처: /status 실행 화면(현재 모델 표시)]

# 현재 모델 확인
/status

팁: /model 뒤에 붙는 정확한 별칭은 버전에 따라 조금씩 바뀔 수 있습니다. 별칭이 헷갈리면 /model을 별칭 없이 입력해 뜨는 선택 메뉴에서 실제 표시되는 이름을 그대로 고르는 것이 가장 안전합니다.

2.2 어떤 작업에 어떤 등급

이 손잡이를 어디로 돌릴지는 작업의 복잡도가 정합니다.

Claude.ai에서 배운 모델 등급 개념이 Claude Code에서도 그대로 적용됩니다.

등급	적합한 작업
Opus	느리지만 정교함. 여러 파일에 걸친 복잡한 리팩토링이나 구조 설계에 적합
Sonnet	균형 잡힌 기본값. 대부분의 기능 추가·버그 수정에 사용
Haiku	빠르고 저렴함. 단순 오타 수정이나 짧은 스크립트에 적합

복잡한 일에 Haiku를 쓰면 결과가 부실하고, 단순한 일에 Opus를 쓰면 느리고 비용만 큽니다.

손잡이를 작업에 맞게 돌리는 감각은 다음 절에서 직접 비교하며 잡습니다.

3. 실습 — 두 손잡이를 직접 쥐어보기

→ 모델을 바꿔 같은 작업의 결과를 비교하고, 승인 화면을 예측하며 읽습니다.

3.1 성능 손잡이 — 모델 바꿔 비교하기

먼저 모델을 바꿔가며 같은 작업의 결과가 어떻게 다른지 봅니다.

/model haiku로 전환한 뒤 아래 요청을 넣고,

다시 /model opus로 전환해 같은 요청을 실행한 다음 두 결과를 비교합니다.

inventory.py에 있는 모든 함수 이름과 역할을
한 줄씩 정리한 주석을 파일 맨 위에 추가해줘.

그냥 "달라 보인다"로 끝내지 말고, 무엇을 기준으로 볼지 정해두고 비교하는 것이 중요합니다.

아래 네 가지 기준으로 보면 손잡이를 어디로 돌릴지 감이 잡힙니다.

비교 기준	무엇을 보는가
응답 속도	결과가 나오기까지 걸린 시간. Haiku가 대체로 더 빠름
주석의 상세함	함수 역할을 얼마나 정확하고 풍부하게 설명했는가
정확도	실제 코드와 주석 내용이 어긋나지 않는가
작업 비용 감각	이 정도 단순 작업에 최상위 모델이 꼭 필요했는가

단순 주석 작업에서는 Haiku로도 충분한 경우가 많습니다.

이런 판단이 쌓이면 성능 손잡이를 작업마다 알맞게 돌릴 수 있게 됩니다.

3.2 안전 손잡이 — 승인 화면 예측하며 읽기

[화면 캡처: 승인 화면에서 변경 내용을 예측한 뒤 승인하는 과정]

이번에는 안전 손잡이를 쥐는 연습입니다.

아래 요청을 넣고, 승인 버튼을 누르기 전에 "어떤 파일이 어떻게 바뀔지"를 스스로 예측해 봅니다.

inventory.py에 재고 목록을 CSV 파일로 내보내는
기능을 추가해줘.

예측한 대로 화면에 표시되는지 확인하고 승인합니다.

3강에서 허술한 요청이 예상보다 넓게 바뀌려 하던 것을 떠올리며, 이 요청은 어디까지 바뀌는지 비교해 봅니다.

▶ 지금 해보세요

주석 추가 요청을 haiku와 opus로 각각 실행해, 위 네 기준으로 결과를 비교합니다. (성능 손잡이)
CSV 내보내기 요청을 넣고, 승인 화면을 보기 전에 어떤 파일이 어떻게 바뀔지 먼저 예측합니다. (안전 손잡이)
예측과 실제 화면이 맞는지 확인한 뒤 승인합니다.

✔ 확인 기준: 승인 화면을 누르기 전에 무엇이 바뀔지 예측할 수 있고(안전), /model로 작업에 맞게 모델을 바꿀 수 있으면(성능) 완료입니다. 두 손잡이를 모두 쥐어본 것입니다.

→ 다음 강의 (5강): 3강에서 매번 "inventory.py에서"라고 밝히고 조건을 붙여야 했던 번거로움을, CLAUDE.md 파일 하나로 줄이는 법을 배웁니다.

3강. 프롬프팅의 전환

BasicLike — Tue, 7 Jul 2026 21:38:18 +0900

3강 실습 중심 ⏱ 약 50분

0. 학습 목표

→ 기존 파일을 고치는 위임형 요청문을 스스로 잘 쓰는 법을, 허술한 요청과 구체적인 요청의 결과 차이로 직접 익힙니다.

0.1 이번 글에서 다룰 내용

이번 글은 실습 중심 강의입니다.

2강에서 Claude Code가 파일을 직접 고친다는 것을 확인했습니다.

그렇다면 이제 실제로 중요한 질문은 이것입니다.

일을 맡길 때 요청문을 어떻게 써야 원하는 결과가 나오는가?

1강의 hello.py는 새 파일을 이름만 정해 만드는 단순한 요청이라 요청문을 크게 신경 쓸 필요가 없었습니다.

그러나 이미 만들어진 파일을 고칠 때는 이야기가 다릅니다.

같은 기능을 부탁해도, 요청문이 허술하면 엉뚱한 곳이 바뀌고 구체적이면 원하는 대로 바뀝니다.

이번 강의는 이 차이를 직접 만들어 봅니다.

같은 재고관리 프로그램에 허술한 요청과 구체적인 요청을 각각 넣어 결과를 비교하며,

기존 파일을 고치는 요청문에 무엇을 담아야 하는지 몸으로 익힙니다.

여기서 만드는 재고관리 프로젝트는 7강까지 이어서 발전시킬 실습 본체입니다.

0.2 이번 강의 실습 내용

이번 강의에서 직접 해보는 것은 다음과 같습니다.

Claude Code로 재고관리 프로그램의 기본 뼈대(inventory.py)를 만들기
같은 기능을 허술한 요청으로 넣어 결과가 어긋나는 것을 확인하기
같은 기능을 구체적인 요청으로 다시 넣어 결과가 정확해지는 것을 확인하기

구분	내용
만들 것	앞으로 이어서 발전시킬 재고관리 프로그램의 기본 뼈대(inventory.py)
확인할 것	허술한 요청과 구체적인 요청의 결과 차이, 기존 파일을 고칠 때 요청문에 담아야 할 네 가지

1. 실습용 재고관리 프로젝트 준비하기

→ 앞으로 계속 고쳐 나갈 재고관리 프로그램의 뼈대를 만듭니다.

1.1 작업 폴더 만들기

이번 강의부터는 hello.py가 아니라 여러 번 고쳐 나갈 프로그램이 필요합니다.

먼저 실습용 프로젝트 폴더를 만들고, 그 안에서 Claude Code를 실행합니다.

mkdir ~/inventory-project
cd ~/inventory-project
claude

폴더를 만들고 그 안으로 이동한 뒤 Claude Code를 실행하는 과정은 1강과 동일합니다. 실행 화면이 기억나지 않으면 1강의 「2. 첫 작업 맡겨보기」 스크린샷을 참고하세요.

1.2 기본 뼈대 만들기

이 폴더 안에서 실습의 출발점이 될 재고관리 프로그램을 만들어 달라고 요청합니다.

처음부터 완성된 프로그램이 아니라, 앞으로 기능을 붙여 나갈 최소한의 뼈대면 충분합니다.

[화면 캡처: Claude Code에 inventory.py 생성을 요청하는 화면]

재고관리 프로그램의 기본 뼈대를 inventory.py로 만들어줘.
지금은 재고 항목(이름, 수량)을 목록으로 저장하고,
전체 목록을 출력하는 기능만 있으면 돼.

파일 생성을 확인하는 화면이 나오면(1강에서 이미 본 그 화면입니다) 내용을 확인하고 승인합니다.

이제 이 폴더에는 앞으로 계속 고쳐 나갈 inventory.py가 준비되었습니다.

▶ 지금 해보세요

위 요청문을 Claude Code에 입력합니다.
파일 생성 승인 화면이 나오면 내용을 확인하고 승인합니다.
cat inventory.py로 뼈대가 만들어졌는지 확인합니다.

팁: Claude Code 세션을 잠시 나가려면 /exit을 입력합니다. 세션에 이름을 붙여두었다면 /resume으로 다시 불러올 수 있습니다. 이번 강의는 내내 이 inventory-project 폴더 안에서 작업한다는 점만 기억하면 됩니다.

2. 새로 만들 때와 고칠 때, 요청문이 달라야 하는 이유

→ 기존 파일을 고칠 때 요청문에 무엇을 담아야 하는지 정리합니다.

1강의 hello.py 요청은 새 파일을 처음부터 만드는 지시라 대상이 명확했습니다.

빈 종이에 처음 쓰는 것과 같아서, 파일 이름만 정해주면 무엇을 건드릴지 헷갈릴 여지가 없었습니다.

그러나 이미 여러 기능이 들어 있는 파일을 고칠 때는 다릅니다.

Claude Code는 파일 전체를 볼 수 있기 때문에,

요청이 두루뭉술하면 "이 정도면 이렇게 하라는 거겠지" 하고 넘겨짚어 엉뚱한 부분까지 손대거나,

멀쩡히 잘 돌아가던 기존 코드를 바꿔버릴 수 있습니다.

그래서 기존 파일을 고칠 때는 아래 네 가지를 요청문에 담는 것이 안전합니다.

담을 것	왜 필요한가
대상 파일	어느 파일을 고칠지 이름으로 지정 (예: `inventory.py`)
바꿀 지점	파일 안 어디를 고칠지, 어떤 기능에 손댈지 명시
원하는 동작	무엇이 어떻게 동작해야 하는지 구체적으로 (예: 기준 수량, 출력 문구)
유지할 것	건드리면 안 되는 부분을 못 박기 (예: 기존 함수 구조 유지)

이 네 가지가 빠지면 요청이 "허술한 요청"이고, 갖춰지면 "구체적인 요청"입니다.

다음 두 절에서 같은 기능을 각각의 방식으로 넣어, 결과가 실제로 어떻게 갈리는지 확인합니다.

3. 실습 — 허술한 요청부터 넣어보기

→ 일부러 두루뭉술하게 요청해, 결과가 어떻게 어긋나는지 관찰합니다.

먼저 일부러 두루뭉술하게 요청해 봅니다. "재고 부족을 알려주면 좋겠다"는 필요를, 2절의 네 가지 없이 한 줄로만 던집니다.

[화면 캡처: 허술한 요청을 넣은 뒤 승인 화면에서 변경 범위를 확인하는 장면]

재고 부족한 거 알려주게 해줘.

이 요청에는

어느 파일인지,
"부족"의 기준이 몇 개인지,
어떻게 알려줘야 하는지,
무엇을 건드리면 안 되는지가 하나도 없습니다.

Claude Code는 빈칸을 스스로 넘겨짚어 채우거나, 필요한 부분을 다시 추가 요청합니다.

그 결과

기준 수량이 내 생각과 다르게 정해지거나,
출력 방식이 예상과 다르거나,
승인 화면에 예상보다 넓은 범위의 변경이 올라올 수 있습니다.

승인하기 전에 어디가 바뀌는지 반드시 살펴봅니다.

▶ 지금 해보세요

위 허술한 요청을 Claude Code에 그대로 입력합니다.
승인 화면에서 내가 의도하지 않은 부분까지 바뀌려 하는지 살펴봅니다.
기준 수량이나 출력 방식이 내 생각과 다르면, 어디가 왜 어긋났는지 메모해 둡니다. (승인은 해도 되고, 취소하고 넘어가도 됩니다.)

팁: 결과가 "우연히 잘 맞을" 수도 있습니다. 그렇더라도 그건 Claude가 넘겨짚은 것이 맞아떨어진 것일 뿐, 내가 통제한 결과는 아닙니다. 다음 절에서 같은 기능을 구체적으로 요청해 그 차이를 확인합니다.

4. 실습 — 구체적인 요청으로 다시 넣기

→ 같은 기능을 2절의 네 가지를 갖춰 요청하고, 3절 결과와 비교합니다.

이번에는 같은 기능을, 2절에서 정리한 네 가지를 모두 갖춰 요청합니다.

대상 파일, 바꿀 지점, 원하는 동작, 유지할 것이 한 요청 안에 모두 들어 있습니다.

[화면 캡처: 구체적인 요청 후 cat inventory.py로 의도대로 추가된 코드를 확인하는 화면]

inventory.py 파일에서 재고 수량이 5개 미만이면
"재고 부족 경고" 메시지를 출력하는 기능을 추가해줘.
기존 함수 구조는 그대로 유지해줘.

이 요청은 추가해줘로 끝나는 실행 지시이고, 대상 파일(inventory.py)을 지정했으며,

기준(5개 미만)과 출력 문구(재고 부족 경고)를 못 박고, 기존 함수 구조는 유지하라는 조건까지 붙였습니다.

3절의 허술한 요청과 달리, Claude Code가 넘겨짚을 빈칸이 거의 없습니다.

▶ 지금 해보세요

위 구체적인 요청을 Claude Code에 입력합니다.
승인 화면에서 변경 범위가 내가 요청한 부분에 한정되는지, 3절보다 예측 가능한지 살펴본 뒤 승인합니다.
cat inventory.py로 기준 수량과 출력 문구가 요청한 그대로인지 확인합니다.
3절에서 메모해 둔 허술한 요청의 결과와 나란히 비교합니다.

두 결과를 나란히 놓으면 차이가 분명해집니다. 같은 도구, 같은 기능인데도 요청문의 구체성만으로 결과의 정확도와 예측 가능성이 달라졌습니다. 이것이 위임형 요청문을 잘 써야 하는 이유입니다. Claude Code가 넘겨짚어야 할 빈칸을 줄일수록, 결과는 내가 의도한 것에 가까워집니다.

✔ 확인 기준: 허술한 요청과 구체적인 요청의 결과를 비교해, 기존 파일을 고칠 때 요청문에 대상 파일·바꿀 지점·원하는 동작·유지할 것 네 가지를 담아야 하는 이유를 설명할 수 있으면 완료입니다.

→ 다음 강의 (4강): 방금 요청마다 확인한 승인 화면이 정확히 무엇을 묻는지 제대로 이해하고, 작업에 맞게 모델을 바꾸는 법을 익힙니다.

2강. Claude Code란? — 하네스(harness)

BasicLike — Tue, 7 Jul 2026 21:36:41 +0900

2강 개념 중심 ⏱ 약 40분

0. 학습 목표

→ 1강에서 설명 없이 겪었던 경험을, "정확히 무엇이었는가"로 정리합니다.

0.1 이번 글에서 다룰 내용

이번 글은 개념 중심 강의입니다.

1강에서는 설명 없이 일단 Claude Code를 실행해봤습니다.

이번 강의는 그때 일어난 일을 정확히 무엇이었는지 정리하는 시간입니다.

1강 Claude Code 사용 경험을 계속 다시 꺼내며, Claude Code 사용이 Claude.ai와 근본적으로 무엇이 다른지 이해하고,

앞으로 배울 강의들이 왜 이런 순서로 진행되는지 전체 지도를 그립니다.

구분	내용
되짚을 것	1강에서 `hello.py`로 겪은 위임 경험
이해할 것	Claude.ai와 Claude Code의 근본적 차이, 프롬프트·컨텍스트·하네스 3층위 구분

1. 방금 겪은 일, 다시 보기

→ 1강의 요청 한 줄이 실제로 무엇을 일으켰는지 순서대로 다시 짚어봅니다.

1강에서 입력했던 요청을 다시 봅니다.

간단한 파이썬 인사말 스크립트 hello.py를 만들어줘.
실행하면 "안녕하세요"를 출력하게 해줘.

이 요청이 실제로 일으킨 일을 순서대로 늘어놓으면,

지시를 입력하자
Claude가 파일을 새로 생성하고
코드를 직접 작성한 뒤,
여러분의 승인을 거쳐 파일을 저장하고,
터미널에서 직접 실행해 결과를 냈습니다.

같은 요청을 Claude.ai 대화창에 넣었다면 흐름이 이렇게 달랐을 것입니다.

지시를 입력하면
Claude.ai가 코드를 텍스트로 답변하고,
그다음 사람이 직업 파일을 만들고
사람이 직업 그 코드를 복사해 붙여넣고
사람이 직업 직접 실행해야 했을 것입니다

같은 요청인데 결과가 다릅니다. 이 차이를 이해하는 것이 오늘 강의의 전부입니다.

2. 왜 이런 차이가 나는가

→ 입력·출력의 성격 차이와 LLM 활용 3층위 구조로 이 차이를 설명합니다.

2.1 입력과 출력이 다르다

두 도구는 입력과 출력의 성격 자체가 다릅니다.

Claude.ai는 대화창에 텍스트를 넣으면 텍스트 답변이 나오고,

그 답변을 실제로 쓰려면 사람이 옮겨야 합니다.

반면 Claude Code는 터미널에서 작업을 지시하면

파일이 직접 생성되고 수정됩니다.

1강 경험으로 바꿔 말하면,

Claude.ai였다면 hello.py 코드를 "알려줬을" 뿐이지만,

Claude Code에서는 hello.py가 실제로 만들어지고 실행까지 됐습니다.

비유하자면

Claude.ai는 상담사에게 물어보는 것에 가깝고,

Claude Code는 신입 개발자에게 일을 맡기는 것에 가깝습니다.

2.2 LLM 활용 3층위로 보기

이 차이를 조금 더 구조적으로 보면, LLM을 활용하는 방식은 세 개의 단계로 나눌 수 있습니다.

[화면 캡처: 프롬프트·컨텍스트·하네스 3층위 구조를 보여주는 도식]

가장 처음 프롬프트 엔지니어링(어떻게 요청하는가),

그 다음이 컨텍스트 엔지니어링(무엇을 참고 자료로 주는가),

그리고 마지막 하네스 엔지니어링(도구와 실행 환경을 어떻게 연결하는가)입니다.

2.3 LLM 활용 3층위를 Claude Code 로 보기

Claude.ai는 아래 두 층위, 즉 프롬프트와 컨텍스트를 다룹니다. Claude Code는 여기에 더해 하네스까지 다룹니다.

Claude.ai   : 프롬프트 엔지니어링 + 컨텍스트 엔지니어링
Claude Code : 위 두 가지 + 하네스 엔지니어링
              (1강에서 겪은 "직접 실행"이 바로 하네스의 실체)

1강에서 터미널이 열리고, 파일이 생성되고, 실행까지 이어진 그 전체 과정 자체가 바로 하네스(harness)입니다.

도구와 파일, 실행 환경이 하나로 연결된 상태를 말합니다.

Claude.ai가 "말로 조언하는" 데서 멈춘다면,

Claude Code는 그 조언을 "실제로 실행하는" 팔다리까지 갖춘 셈입니다.

단순히 실행 도구가 있다는 것이 하네스라는 뜻이 아니라,

그 실행 환경을 어떻게 설계하고 통제할 것인가? — 이 부분이 하네스 엔지니어링입니다.

3. 앞으로 배울 것 — 큰그림 그리기

→ 1강에서 스쳐 지나간 것들이 앞으로 어떤 강의로 이어지는지 전체 그림을 봅니다.

1강에서 이미 살짝 스쳐 지나간 것들이, 앞으로 각각 하나의 강의가 됩니다.

지금 전체 그림을 봐두면 이후 강의가 낯설지 않습니다.

3강에서는 1강의 "만들어줘"라는 지시 방식을 발전시켜, 프롬프팅을 위임형으로 쓰는 법을 깊게 다룹니다.

4강에서는 1강에서 그냥 지나쳤던 승인 요청 화면의 의미를 제대로 이해하고, 모델을 전환하는 법도 배웁니다.

5강부터는 1강에서 아직 만나지 못한 것들입니다.

여러 파일이 있는 프로젝트에서 맥락을 관리하는 법(5강),
작업을 되돌리는 감각(6강),
반복 작업을 재사용 가능한 절차로 만드는 법(7강)으로 이어집니다.

4. 개념 확인해보기

→ 방금 배운 3층위를 1강 경험에 직접 대입해, 각 층위가 어디에 해당했는지 짚어봅니다.

개념은 말로 들을 때보다 내가 겪은 일에 대입해볼 때 확실히 남습니다.

1강의 hello.py 경험을 프롬프트·컨텍스트·하네스 세 층위에 하나씩 대입해봅니다.

층위	1강에서 이것에 해당한 것	Claude.ai 였다면
프롬프트	"hello.py를 만들어줘"라고 입력한 요청문	동일하게 존재 (요청은 어디서든 함)
컨텍스트	`claude-practice` 폴더가 작업 대상이라는 정보	제공하면 알 수 있음. 프로젝트, 업로드 파일, GitHub 연동 등으로 참고 가능
하네스	로컬 폴더에 hello.py가 실제 생성·저장되고 터미널에서 실행된 것	없음 — 코드를 텍스트로 알려줄 뿐

*harness 정의: "LLM 추론과 도구 호출, 사용자 상호작용의 런타임을 제공하는 것"

핵심은 맨 아랫줄입니다.

앞의 두 층위는 Claude.ai에도 있지만, "파일이 실제로 만들어지고 실행까지 되는" 하네스는 Claude Code에만 있습니다.

1강에서 느낀 "다르다"의 정체가 바로 이 하네스의 유무였던 셈입니다.

이제 이 대입이 맞는지 직접 확인합니다. 먼저 1강에서 만든 폴더로 이동해 파일 내용을 다시 엽니다.

cd ~/claude-practice
cat hello.py

▶ 지금 해보세요

화면에 보이는 hello.py를 가리키며 "이 파일이 존재한다는 것 자체가 하네스가 작동한 증거"라는 것이 이해되었는지 확인합니다.
같은 요청("hello.py를 만들어줘")을 지금 Claude.ai 대화창에도 넣어보고, 파일이 생기는지 아니면 코드가 글로만 오는지 확인합니다.
두 결과를 놓고, 위 표의 세 층위 중 어느 줄에서 차이가 났는지 짚어봅니다. (프롬프트·컨텍스트는 같고, 하네스에서 갈립니다.)

→ 다음 강의 (3강): 1강의 hello.py(새 파일 생성)보다 실무에 가까운 재고관리 프로그램(기존 파일 수정)으로 같은 비교를 반복하며, 위임형 요청문을 스스로 만드는 감각을 잡습니다.

1강. Claude Code 실행해보기

BasicLike — Tue, 7 Jul 2026 21:33:59 +0900

1강실습 중심 ⏱ 약 50분

0. 학습 목표

→ Claude Code를 내 컴퓨터에 설치해 실행하고, 간단한 파일 하나를 만들어보며 "위임"이라는 감각을 직접 느껴봅니다.

0.1 이번 글에서 다룰 내용

이번 글은 실습 중심 강의입니다.

지금까지

Claude.ai 학습 트랙에서는 대화창에 질문을 던지는 방식을 익혔습니다.

이번 강의부터는 방향이 달라집니다.

Claude 에게 질문을 하는 것이 아니라, 터미널 안에서 작업 자체를 맡기는 Claude Code를 다룹니다.

0.2 이번 강의 실습 내용

오늘은

Claude Code를 바로 쓸 수 있는 상태로 만들고

hello.py 생성과 실행을 처음으로 직접 실행해본 뒤, 위임하는 작업을 처음으로 경험합니다.

다음 강의에서

이번 강의 실습 내용에 대해 "방금 무슨 일이 일어난 것인지" 자세히 설명합니다.

구분	내용
해볼 것	Claude Code 설치·로그인, `hello.py` 생성과 실행 위임 경험
확인할 것	파일이 실제로 생성·실행되는 과정, Claude.ai 사용과의 흐름 차이

1. 터미널 열고 Claude Code 설치하기

→ 터미널을 열고, 명령어 한 줄로 Claude Code를 설치한 뒤 로그인까지 마칩니다.

1.1 터미널 열기

"터미널"이라는 검은 화면이 처음에는 낯설게 느껴질 수 있습니다.

Claude.ai 에서 마우스로 버튼을 누르던 작업을, 키보드로 대화를 입력하며 진행한다고 생각하면 편합니다.

결국은 Claude 와 대화하는 또 다른 창일 뿐입니다.

[화면 캡처: 우분투 터미널 창]

우분투에서는 Ctrl+Alt+T 단축키를 누르면 터미널이 열립니다.

단축키가 안 되면 화면 좌측 하단의 Activities를 클릭하고 "Terminal"을 검색해도 됩니다.

깜빡이는 커서가 있는 검은 창이 뜨면 준비가 된 것입니다.

1.2 Claude Code 설치하기

예전에는 Claude Code를 설치하려면 Node.js라는 프로그램을 먼저 깔아야 했습니다.

하지만 지금(2026.07)은 네이티브 설치 방식이 공식 권장 방법이 되면서, 별도 프로그램 없이 명령어 한 줄로 설치가 끝납니다.

curl -fsSL https://claude.ai/install.sh | bash

설치 완료 메시지가 나오면, 터미널 창을 완전히 닫았다가 다시 엽니다. << 이 단계는 꼭 필요합니다.

건너뛰면 다음 단계에서 "명령어를 찾을 수 없다"는 오류가 날 수 있는데, 시스템이 새로 설치된 claude 명령어의 위치를 아직 인식하지 못했기 때문입니다.

Windows·macOS라면: Windows는 PowerShell에서 irm https://claude.ai/install.ps1 | iex를 입력합니다. macOS는 터미널(Cmd+Space → "터미널" 검색)을 열고 우분투와 동일한 curl 명령어를 그대로 씁니다.

1.3 설치 확인

설치가 잘 됐는지는 버전 확인으로 알 수 있습니다.

claude --version

버전 번호가 뜨면 정상입니다.

만약 버전이 안 뜨거나 오류가 난다면, 자가진단 명령어로 원인을 확인할 수 있습니다.

claude doctor

1.4 로그인하기

정상적으로 설치된 상태가 확인되면 Claude Code를 실행합니다.

claude

처음 Claude Code 를 실행하면 테마 설정이 시작됩니다.

원하는 테마로 설정합니다.

그리고 Claude.ai 계정으로 로그인을 진행합니다.

Claude Code v2.1.202 시작 화면입니다.

Claude Code는 Claude 구독 계정으로 사용할 수 있고,
또는 Anthropic Console 계정의 API 사용량 기준으로 결제해 사용할 수 있습니다.

로그인 방식을 선택하세요.

1. Claude 구독 계정 # ✅ 선택
   Pro, Max, Team, Enterprise 플랜 사용자

2. Anthropic Console 계정
   API 사용량 기준 결제 사용자

3. 타사 플랫폼
   Amazon Bedrock, Microsoft Foundry, Vertex AI 사용자

브라우저에서 권한 허용을 누르면, 터미널로 돌아왔을 때 입력을 기다리는 프롬프트가 보입니다.

[화면 캡처: 브라우저에 기존 로그인이 했었다면 승인만 해주면 됩니다. 아니면 재로그인하시면 됩니다.]

[화면 캡처: Claude Code 로그인 성공 화면입니다. Enter를 눌러 계속 진행합니다.]

Welcome to Claude Code v2.1.202
→ Claude Code v2.1.202에 오신 것을 환영합니다.

Login successful. Press Enter to continue ...
→ 로그인이 완료되었습니다. 계속하려면 Enter를 누르세요.

[화면 캡처: Claude Code 보안 안내 화면입니다.Enter를 눌러 계속 진행합니다.]

Claude Code v2.1.202에 오신 것을 환영합니다.

보안 안내:

1. Claude도 실수할 수 있습니다.
Claude가 수행한 작업에 대한 책임은 사용자에게 있으므로,
특히 코드를 실행할 때는 항상 내용을 검토해야 합니다.

2. 프롬프트 인젝션 위험이 있으므로,
신뢰할 수 있는 코드에서만 사용하세요.

자세히 보기:
https://code.claude.com/docs/en/security

계속하려면 Enter를 누르세요.

[화면 캡처: Claude Code 작업 폴더 신뢰 확인 화면입니다. 1번을 선택해 신뢰한다고 확인한 뒤 Enter를 눌러 계속 진행합니다.]

작업 공간 접근 중:

/home/basiclike

빠른 안전 확인:
이 프로젝트는 직접 만든 프로젝트이거나 신뢰할 수 있는 프로젝트인가요?
예를 들어 본인이 작성한 코드, 잘 알려진 오픈소스 프로젝트,
또는 팀에서 작업 중인 프로젝트인지 확인합니다.

그렇지 않다면 먼저 이 폴더 안에 무엇이 들어 있는지 검토하세요.

Claude Code는 이 위치의 파일을 읽고, 수정하고, 실행할 수 있습니다.

보안 가이드

> 1. 예, 이 폴더를 신뢰합니다.
  2. 아니요, 종료합니다.

Enter를 눌러 확인합니다. Esc를 누르면 취소합니다.

1.5 Claude Code 첫 화면

팁: Claude Code는 무료 플랜으로는 쓸 수 없습니다. Pro 이상의 유료 플랜(또는 API 계정)이 있어야 로그인이 됩니다.

✔ 확인 기준: 터미널에 입력 대기 표시가 떠 있으면 이 단계는 완료입니다. 그것이 정확히 무엇인지는 아직 몰라도 괜찮습니다.

2. 첫 작업 맡겨보기 — hello.py

→ "왜 되는지" 설명 없이, 일단 시켜보고 무슨 일이 일어나는지 눈으로 확인합니다.

앞서 실행한 claude 세션이 아직 열려 있다면 /exit으로 먼저 빠져나온 뒤 진행합니다.

먼저 연습용 폴더를 하나 만들고, 클로드를 해당 폴더 경로에서 실행합니다.

mkdir ~/claude-practice
cd ~/claude-practice
claude

이제 Claude Code 프롬프트에 아래처럼 요청합니다.

간단한 파이썬 인사말 스크립트 hello.py를 만들어줘.
실행하면 "안녕하세요"를 출력하게 해줘.

Claude Code가 파일을 만드는 과정을 지켜봅니다.

도중에 승인을 요청하는 화면이 나올 텐데, 이것은 실수를 막기 위한 안전장치입니다.

지금은 자세히 몰라도 되니 일단 승인만 해봅니다. 이 화면의 의미는 다음 강의에서 제대로 다룹니다.

[화면 캡처: Claude Code가 파일을 생성하는 과정과 승인 요청 화면]

▶ 지금 해보세요

승인이 끝나면 cat hello.py로 파일이 실제로 만들어졌는지 내용을 확인합니다.
터미널에서 python3 hello.py로 직접 실행해봅니다.
"안녕하세요"가 출력되는지 확인합니다.

✔ 확인 기준: 파일이 실제로 생성되고 "안녕하세요"까지 출력됐다면 완료입니다. 지금은 "왜"를 몰라도 괜찮습니다.

3. 방금 한 일이 Claude.ai 와 무엇이 다른가?

→ 방금 겪은 경험을 Claude.ai에서 같은 걸 했을 때와 비교해봅니다.

방금 겪은 것을 되짚어봅니다.

여러분은 "만들어줘"라고 지시했고, 파일이 실제로 생성됐으며, 터미널에서 바로 실행까지 했습니다.

만약 같은 일을 Claude.ai 에서 했다면 어땠을까요?

"만들어줘" 대신 "어떻게 만드는지 알려줘"라고 물었을 것이고, 파일이 생기는 대신 코드가 텍스트 답변으로 나왔을 것입니다.

그리고 그 코드를 직접 복사해서 내 컴퓨터에 붙여넣고 따로 실행해야 했을 것입니다.

같은 목적인데 흐름이 완전히 다릅니다.

이 차이가 무엇을 의미하는지에 대한 설명은 다음 강의에서 이어집니다. 지금은 "다르다"는 것만 느끼면 충분합니다.

→ 다음 강의 (2강): 오늘 겪은 hello.py 경험에 이름을 붙입니다. 그때 일어난 일이 정확히 무엇이었는지를 개념으로 정리하고, 앞으로 배울 강의들이 왜 이런 순서로 진행되는지 지도를 그립니다.

6강. launch.json으로 실행·디버그 설정 관리하기

BasicLike — Sat, 4 Jul 2026 09:37:22 +0900

6강 구현 중심 ⏱ 약 20분

0. 학습 목표

→ 디버그 설정을 launch.json 파일에 저장해, 원하는 방식으로 반복 실행합니다.

이번 글은 구현 중심 강의이며, 시리즈의 선택 강의입니다.

5강까지로도 VSCode에서 코드를 실행하고 디버깅하는 데는 충분합니다.

이번 강의는 디버깅을 "매번 같은 조건으로", "값을 전달하면서" 반복해야 할 때 유용한 도구를 다룹니다.

지금 필요하지 않다면 나중에 그런 상황이 왔을 때 돌아와도 됩니다.

5강에서 F5를 누르면 VSCode가 알아서 디버깅을 시작했습니다.

이때 VSCode는 기본 설정으로 실행한 것입니다.

그런데 실제 프로그램은 실행할 때 값을 받거나(명령행 인자), 특정 환경변수가 필요한 경우가 많습니다.

이런 조건을 매번 손으로 맞추는 대신 launch.json이라는 파일에 저장해두고 재사용하는 것이 이번 강의의 주제입니다.

구분	내용
이해할 것	`launch.json`이 디버그 실행 조건을 저장하는 파일이라는 것
만들 것	실행 인자·환경변수가 지정된 디버그 구성 (`.vscode/launch.json`)
확인할 것	저장한 구성으로 실행했을 때 인자·환경변수가 코드에 전달되는지

1. 왜 실행 설정을 저장하는가

→ 기본 F5 실행으로는 부족한 상황을 확인합니다.

5강의 debug_practice.py는 점수 목록이 코드 안에 고정되어 있었습니다.

하지만 실제 프로그램은 실행할 때 값을 밖에서 받는 경우가 많습니다.

예를 들어 실행하는 사용자 이름을 인자로 받는 스크립트를 생각해 봅시다. debug_practice.py를 아래처럼 바꿉니다.

import sys
import os

user = sys.argv[1] if len(sys.argv) > 1 else "손님"   # 실행 시 전달된 첫 번째 인자를 받는다
mode = os.environ.get("APP_MODE", "일반")             # 환경변수 APP_MODE를 읽는다

print(f"사용자: {user}, 모드: {mode}")

이 코드는 실행할 때 사용자 이름을 인자로, 실행 모드를 환경변수로 받습니다. 터미널에서라면 이렇게 실행합니다.

APP_MODE=관리자 python debug_practice.py 홍길동      # 환경변수와 인자를 함께 전달

사용자: 홍길동, 모드: 관리자

그런데 5강처럼 그냥 F5를 누르면 인자도 환경변수도 없이 실행되어 사용자: 손님, 모드: 일반이 나옵니다.

디버깅할 때마다 인자와 환경변수를 넣고 싶다면, 그 조건을 어딘가에 저장해 두어야 합니다.

그 저장소가 launch.json입니다.

2. launch.json 만들기

→ 디버그 구성 파일을 생성하고, 기본 구조를 확인합니다.

왼쪽 액티비티 바에서 Run and Debug 아이콘(삼각형에 벌레 모양)을 클릭합니다.

아직 구성이 없으면 "create a launch.json file" 링크가 보입니다.

이것을 클릭하고, 디버거 종류를 물으면 Project → Python Debugger → Python File을 선택합니다.

그러면 프로젝트에 .vscode 폴더가 생기고 그 안에 launch.json이 만들어집니다. 사이드바에서 확인할 수 있습니다.

~/Dev/Project/
├── .vscode/
│   └── launch.json          ← ➕ 이번 강의에서 생성 (디버그 설정 저장)
├── .venv/
├── debug_practice.py
└── main.py

(➕ 새로 생성 · ✏️ 수정 · 표시 없음은 변경 없음)

생성된 launch.json의 기본 내용은 다음과 같습니다. 5강에서 F5가 자동으로 하던 일이 이 파일로 적혀 나온 것입니다.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python Debugger: Current File",   // 구성 이름 (실행 목록에 표시됨)
      "type": "debugpy",                          // 디버거 종류
      "request": "launch",                        // 실행 방식: 새로 실행
      "program": "${file}",                       // 실행 대상: 현재 열린 파일
      "console": "integratedTerminal"             // 결과를 통합 터미널에 출력
    }
  ]
}

configurations는 실행 구성들의 목록입니다. 지금은 하나뿐이고, "program": "${file}"은 "지금 편집 영역에 열린 파일을 실행하라"는 뜻입니다. 5강에서 F5가 현재 파일을 디버깅했던 것이 바로 이 설정 때문입니다.

3. 인자와 환경변수 추가하기

→ 구성에 실행 인자와 환경변수를 지정하고, 저장한 설정으로 실행합니다.

3.1 구성에 설정 추가하기

1번에서 터미널로 전달했던 인자(홍길동)와 환경변수(APP_MODE=관리자)를 launch.json에 적어 넣습니다. console 줄 뒤에 args와 env 두 항목을 추가합니다.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "관리자 모드로 실행",                    // ✏️ 알아보기 쉬운 이름으로 변경
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "args": ["홍길동"],                            // ➕ 실행 인자 (sys.argv[1]로 전달됨)
      "env": { "APP_MODE": "관리자" }                // ➕ 환경변수 (os.environ으로 읽힘)
    }
  ]
}

args는 실행할 때 코드에 전달할 인자 목록으로, 1번의 sys.argv[1]로 들어갑니다. env는 실행 중 사용할 환경변수로, os.environ.get("APP_MODE")로 읽힙니다. 터미널에서 손으로 붙이던 조건을 파일에 적어 고정한 것입니다. 파일을 저장(Ctrl+S)합니다.

3.2 저장한 구성으로 실행하기

debug_practice.py를 편집 영역에 열어둔 상태에서 F5를 누릅니다.

이번에는 방금 저장한 "관리자 모드로 실행" 구성이 사용됩니다. 통합 터미널에 다음이 출력됩니다.

사용자: 홍길동, 모드: 관리자      ← launch.json의 args·env가 그대로 전달됨

1번에서 터미널에 길게 입력했던 조건이, 이제 F5 한 번으로 재현됩니다.

Run and Debug 화면 위쪽의 드롭다운에서 구성 이름("관리자 모드로 실행")을 확인할 수 있고, 구성을 여러 개 만들어 두면 상황에 따라 골라 실행할 수도 있습니다.

디버깅이므로 5강에서 배운 것이 그대로 됩니다. 중단점을 찍어두면 이 구성으로 실행해도 그 지점에서 멈추고, 그때 user·mode 변수에 전달된 값이 들어 있는 것을 변수 패널에서 확인할 수 있습니다. launch.json은 "어떤 조건으로 디버그를 시작할지"를 정할 뿐, 멈추고 값을 보는 디버깅 자체는 5강 그대로입니다.

- launch.json = 디버그 실행 조건을 저장하는 파일 (.vscode 폴더 안)
- F5의 기본 동작도 사실 이 파일의 기본 구성으로 실행되는 것
- args = 실행 인자(sys.argv), env = 환경변수(os.environ)를 고정
- 저장해 두면 F5 한 번으로 같은 조건을 반복 실행 — 구성을 여러 개 둘 수도 있다

✔ 확인 기준: F5로 실행했을 때 통합 터미널에 사용자: 홍길동, 모드: 관리자가 출력되면 이번 강의 완료입니다. 손님·일반이 나오면 launch.json에 args·env가 제대로 저장됐는지, 파일을 저장(Ctrl+S)했는지 확인하세요. JSON은 쉼표·따옴표에 민감하므로, 편집 영역에 표시되는 오류 밑줄이 없는지도 확인합니다.

이것으로 VSCode 시리즈가 마무리됩니다.

편집기 설치(2·3강)부터 가상환경 연결과 실행(4강), 디버깅(5·6강)까지

지난 시리즈에서 터미널로 하던 Python 개발을 이제 VSCode 안에서 온전히 할 수 있게 되었습니다.

두 시리즈를 통해 가상환경으로 환경을 관리하고, VSCode로 편하게 개발하고 디버깅하는 기본기가 갖춰진 것입니다.

여기서 배운 도구들은 앞으로 어떤 Python 프로젝트를 하더라도 그대로 쓰이는 토대가 됩니다.

5강. 디버깅 — 중단점으로 코드 흐름 따라가기

BasicLike — Sat, 4 Jul 2026 09:26:22 +0900

5강 구현 중심 ⏱ 약 25분

0. 학습 목표

→ 중단점으로 코드를 멈춰 세우고, 변수 값을 직접 확인하며 버그를 찾습니다.

0.1 이번 글에서 다룰 내용

이번 글은 구현 중심 강의이자, 이 시리즈의 핵심입니다.

지금까지는 코드가 잘 동작했습니다.

하지만 실제 개발에서는 "실행은 되는데 결과가 이상한" 상황이 훨씬 많습니다.

지난 시리즈에서는 이럴 때 print를 여기저기 넣어 값을 찍어 보는 것이 전부였습니다.

이번 강의에서는 코드를 원하는 지점에서 멈춰 세우고, 그 순간 변수에 어떤 값이 들어 있는지 화면에서 직접 들여다보는 디버깅을 배웁니다.

실습에는 지금까지 쓰던 GUI 프로그램 대신, 버그가 하나 숨어 있는 작은 계산 스크립트를 새로 만듭니다.

창을 띄우는 프로그램은 실행 흐름을 멈춰 관찰하기에 적합하지 않기 때문입니다.

이 스크립트의 잘못된 결과를 디버깅으로 추적해 원인을 찾는 것이 목표입니다.

버그 있는 스크립트 실행 → 결과가 이상함
        ↓
중단점(breakpoint) 설정 → F5로 디버그 실행
        ↓
멈춘 지점에서 변수 값 확인 → 한 줄씩 실행하며 추적
        ↓
값이 어긋나는 순간 발견 → 버그 원인 확인          ← 이번 강의의 성공 지점

구분	내용
이해할 것	중단점·단계 실행·변수 패널의 역할과, print 방식보다 나은 이유
만들 것	디버깅 실습용 `debug_practice.py`
확인할 것	중단점에서 실행이 멈추고, 변수 패널에 그 순간의 값이 보이는지

0.2 이번 강의에서 직접 다루는 구조

~/Dev/Project/
├── .venv/                   ← 유지 (4강에서 연결한 가상환경)
├── main.py                  ← 유지
├── requirements.txt         ← 유지
└── debug_practice.py        ← ➕ 이번 강의에서 생성 (디버깅 실습용)

(➕ 새로 생성 · ✏️ 수정 · 표시 없음은 변경 없음)

1. 문제 상황 — print만으로는 힘든 버그

→ 결과가 이상한 스크립트를 만들고, print 방식의 한계를 확인합니다.

사이드바에서 새 파일 debug_practice.py를 만들고(파일 탐색기 상단의 새 파일 아이콘 또는 우클릭 → New File), 아래 코드를 입력합니다. 점수 목록의 평균을 구하는 짧은 프로그램입니다.

def calculate_average(scores):
    total = 0
    count = 0
    for score in scores:
        total = total + score          # 점수를 하나씩 더한다
        count = count + 1              # 개수를 센다
    average = total / count
    # total = total + scores[-1]         # ✏️ 실수로 들어간 줄 — 마지막 점수를 한 번 더 더함
    return average

scores = [80, 90, 100]                 # 평균은 90이어야 한다
result = calculate_average(scores)
print("평균:", result)

80, 90, 100의 평균이니 90이 나와야 합니다. 4강에서 배운 실행 버튼(▷)으로 실행해 봅니다.

평균: 90.0

이 코드는 사실 정상입니다. 여기에 버그를 하나 심어 문제 상황을 만들어 보겠습니다.

합계를 구한 뒤 마지막 점수를 한 번 더 더하는 실수가 있다고 가정합니다. 반복문 아래에 다음 한 줄을 추가합니다.

    average = total / count
    total = total + scores[-1]         # ✏️ 실수로 들어간 줄 — 마지막 점수를 한 번 더 더함
    return average

이제 다시 실행하면 결과가 이상해야 할 것 같은데, 실행하면 여전히 90.0이 나옵니다.

값이 이미 계산된 뒤에 더했기 때문입니다.

이처럼 "어디서 무엇이 잘못됐는지" 눈에 안 보이는 상황이 실제 버그의 모습입니다. print로 찾으려면 이렇게 됩니다.

    for score in scores:
        total = total + score
        count = count + 1
        print("중간 total:", total, "count:", count)   # 값을 보려고 print를 심는다
    print("최종 total:", total, "count:", count)        # 또 심는다

값을 볼 때마다 print를 넣고, 확인이 끝나면 다시 지워야 합니다.

줄이 많아지면 print도 늘어나고, 지우다가 실수하기도 쉽습니다.

디버깅은 이 과정을 코드를 고치지 않고 대신해 줍니다.

방금 넣은 print 줄들은 지우고, 버그 한 줄(total = total + scores[-1])은 남긴 채로 다음으로 넘어갑니다.

2. 중단점 설정하고 디버그 실행하기

→ 코드에 멈출 지점을 표시하고, 디버그 모드로 실행합니다.

2.1 중단점 설정하기

중단점(breakpoint)은 "여기서 실행을 잠깐 멈춰라"라고 표시하는 지점입니다.

편집 영역에서 줄 번호 왼쪽 여백에 마우스를 올리면 흐릿한 빨간 점이 나타나고, 클릭하면 빨간 점이 고정됩니다.

이 점이 찍힌 줄에서 실행이 멈춥니다.

반복문 안의 total = total + score 줄에 중단점을 찍습니다.

반복이 돌 때마다 값이 어떻게 변하는지 보기 위해서입니다.

2.2 F5로 디버그 실행하기

4강에서 실행 버튼으로 실행했을 때는 코드를 끝까지 한 번에 돌렸지만, 디버그 실행은 중단점에서 멈춥니다.

키보드 F5를 누릅니다. (또는 명령 팔레트에서 Debug: Start Debugging.)

처음 실행하면 어떤 방식으로 디버그할지 물어볼 수 있는데, Python File을 선택하면 됩니다.

실행이 시작되고, 곧 중단점을 찍은 줄에서 멈춥니다.

그 줄이 노란색으로 강조되는데, 이는 "이 줄을 아직 실행하지 않았고, 지금 여기서 멈춰 있다"는 뜻입니다.

디버깅은 4강에서 연결한 .venv를 그대로 사용하므로, 인터프리터를 따로 지정할 필요는 없습니다.

✔ 확인 기준: F5를 눌렀을 때 중단점 줄이 노랗게 강조되며 실행이 멈추면 디버그가 시작된 것입니다. 멈추지 않고 끝까지 실행된다면 중단점(빨간 점)이 제대로 찍혔는지 확인하세요. 실행이 아예 안 되면 4강처럼 상태 바의 인터프리터가 .venv인지 확인합니다.

3. 변수 값 보며 한 줄씩 따라가기

→ 멈춘 상태에서 변수 값을 확인하고, 한 줄씩 실행하며 버그를 추적합니다.

3.1 변수 패널 읽기

실행이 멈춘 지금, 왼쪽 사이드바가 디버그 화면으로 바뀌어 있습니다. 여기 변수(Variables) 패널에 현재 시점의 모든 변수와 그 값이 표시됩니다. print를 심지 않아도, 멈춘 순간의 값이 그대로 보이는 것입니다.

변수(Variables) 패널 — 첫 번째 멈춤 시점

  scores = [80, 90, 100]
  total  = 0            ← 아직 total = total + score 줄을 실행하기 전이라 0
  count  = 0
  score  = 80           ← 이번 반복에서 처리할 값

각 변수에 어떤 값이 들어 있는지 한눈에 보입니다. 이것이 디버깅의 핵심입니다 — 코드를 멈춘 그 순간의 상태를 있는 그대로 들여다볼 수 있습니다.

3.2 한 줄씩 실행하기

멈춘 상태에서 화면 위쪽에 디버그 도구 막대가 나타납니다.

여기서 코드를 한 줄씩 진행시킬 수 있습니다. 가장 많이 쓰는 세 가지만 알면 됩니다.

동작	단축키	하는 일
한 줄 실행 (Step Over)	F10	현재 줄을 실행하고 다음 줄로 이동
계속 실행 (Continue)	F5	다음 중단점까지 한 번에 진행 (반복문에서는 다음 반복으로)
중지 (Stop)	Shift+F5	디버깅 종료

F10을 눌러 한 줄씩 진행하며 변수 패널을 지켜봅니다. total = total + score를 실행하는 순간 total이 0에서 80으로 바뀌는 것이 패널에 즉시 반영됩니다. 반복이 돌 때마다 값이 어떻게 쌓이는지 눈으로 따라갈 수 있습니다.

F10을 누르며 변수 패널 관찰

1번째 반복 후:  total = 80,   count = 1
2번째 반복 후:  total = 170,  count = 2
3번째 반복 후:  total = 270,  count = 3      ← 여기까지는 정상 (합계 270)

average = total / count 실행 후:  average = 90.0   ← 평균도 정상!

그다음 줄 total = total + scores[-1] 실행 후:
  total = 370                                 ← total이 갑자기 바뀐다! 버그 발견

버그의 정체가 드러났습니다.

average는 이미 90으로 정상 계산되었는데, 그 뒤에 total을 다시 건드리는 줄이 있었던 것입니다.

그래서 결과(90.0)는 멀쩡했지만 total에는 엉뚱한 값이 남았습니다.

만약 이 함수가 나중에 total도 반환하도록 바뀐다면 곧바로 문제가 될 코드입니다.

print로는 "결과가 90이니 괜찮네"하고 넘어갔을 문제를, 디버깅은 값이 변하는 순간을 잡아 드러낸 것입니다.

원인을 찾았으니 디버깅을 멈추고(Shift+F5) 버그 줄(total = total + scores[-1])을 지우면 됩니다.

3.3 print 디버깅과 무엇이 다른가

비교	print 방식	중단점 디버깅
코드 수정	print를 넣었다 지워야 함	코드를 건드리지 않음
볼 수 있는 값	print로 찍은 것만	그 순간 모든 변수
진행 방식	한 번에 끝까지 실행	원하는 지점에서 멈춰 한 줄씩

- 중단점 = "여기서 멈춰라" 표시 (줄 번호 왼쪽 여백 클릭)
- F5로 디버그 실행 → 중단점에서 멈춤 / F10으로 한 줄씩 진행
- 변수 패널에서 그 순간의 모든 변수 값을 print 없이 확인
- 디버깅은 코드를 고치지 않고, 값이 변하는 순간을 잡아낸다

✔ 확인 기준: 중단점에서 멈춘 뒤 F10으로 한 줄씩 진행하며, 변수 패널에서 total·count 값이 반복마다 바뀌는 것을 눈으로 확인했다면 — 이 시리즈의 핵심 목표를 달성한 것입니다. 0강에서 약속한 "중단점을 걸어 변수 값을 확인하는" 성공 기준이 바로 이것입니다.

→ 다음 강의 (6강, 선택): 지금은 F5를 누를 때마다 VSCode가 알아서 실행했지만, 실행할 때 값을 전달하거나 특정 설정으로 디버그하고 싶을 때가 있습니다. 이런 디버그 설정을 launch.json 파일에 저장해 재사용하는 방법을 다룹니다. 초급 단계에서 당장 필요하지는 않으므로 선택 강의입니다.

4강. 가상환경을 VSCode에 연결하기

BasicLike — Sat, 4 Jul 2026 09:24:54 +0900

4강 구현 중심 ⏱ 약 30분

0. 학습 목표

→ VSCode가 사용할 Python을 인터프리터로 연결·검증하고, 그 인터프리터로 코드를 실행하는 두 가지 방법을 익힙니다.

이번 글은 구현 중심 강의이자, 가장 중요한 강의입니다.

3강에서 "VSCode가 .venv의 존재는 알지만 사용은 아직 정해지지 않았다"고 했습니다.

VSCode에게 "코드를 실행할 때 이 .venv 안의 Python을 써라"라고 지정하는 것을 인터프리터 선택이라고 합니다.

최신 VSCode(2026년 기준, Python Environments 확장 포함)는 프로젝트 폴더를 열 때 그 안에 이미 있는 .venv를 자동으로 찾아 바로 사용하는 경우가 많지만, 그렇지 않으면 직접 선택해야 합니다.

이번 강의는 세 단계로 이어집니다.

먼저 인터프리터가 자동으로 지정됐는지 확인하고, 안 됐다면 직접 연결합니다.

연결이 됐으면 3중으로 검증하고, 마지막으로 그 인터프리터를 실제로 써서 코드를 실행합니다.

실행 버튼과 통합 터미널 중 무엇을 쓰든, 이 검증을 통과한 같은 .venv가 쓰입니다.

상태 바에서 자동 지정 여부 확인
        ↓
[케이스 A] 이미 .venv로 지정됨 → 바로 검증으로
[케이스 B] 아직 지정 안 됨 → 명령 팔레트로 직접 선택 → 검증
        ↓
3중 검증 통과 (상태 바 · 통합 터미널 · which python)
        ↓
실행 버튼 또는 통합 터미널로 실행 → .venv의 python이 실행됨      ← 이번 강의의 성공 지점

구분	내용
이해할 것	인터프리터 자동/수동 지정의 의미와, 그 지정이 실행 버튼·통합 터미널 실행에 그대로 이어지는 이유
만들 것	`.venv`의 Python이 인터프리터로 연결되고, 그 안에서 `main.py`가 실행되는 VSCode 워크스페이스
확인할 것	상태 바 · 통합 터미널의 `(.venv)` · `which python` 3중 검증, 그리고 실행 버튼·통합 터미널 모두에서 뜨는 실행 결과 창

1. 지금 상태 확인하기 — 자동 지정 여부

→ 상태 바를 먼저 확인해 자동으로 지정됐는지 보고, 아니라면 그 이유를 직접 실행해 확인합니다.

1.1 상태 바로 자동 지정 여부 확인하기

화면 맨 아래 상태 바를 봅니다.

3강에서 폴더를 워크스페이스로 열어둔 이 프로젝트에는 이미 .venv가 존재하므로,

VSCode가 그 환경을 자동으로 인터프리터로 지정했을 수 있습니다. 최신 VSCode의 Python 확장은 워크스페이스에 환경이 하나뿐이면 별도 선택 없이 바로 그 환경을 사용하는 경우가 많기 때문입니다.

구분	상태 바 표시	지금 할 일
자동 지정됨 (케이스 A)	`Python 3.13.x ('.venv': venv)`	2번 건너뛰고 3번 검증으로 이동
수동 지정 필요 (케이스 B)	시스템 Python 경로, 인터프리터 미지정 표시	아래에서 원인을 확인한 뒤 2번에서 직접 지정

지금 상태 바에 이미 .venv가 표시되어 있다면 자동으로 연결된 것이므로, 아래 실패 재현 없이 3번 연결 검증하기로 바로 넘어가도 됩니다. 상태 바가 시스템 Python을 가리키거나 인터프리터가 표시되지 않는다면, 아래에서 그 이유를 직접 실행해 확인합니다.

1.2 자동 지정되지 않았다면 — 실행해서 원인 보기

아직 인터프리터가 지정되지 않은 상태에서 main.py를 실행해 보겠습니다.

편집 영역에 main.py를 열고 오른쪽 위의 실행 버튼(▷)을 누릅니다.

(실행 방법은 4번에서 자세히 다루므로, 지금은 오류를 보기 위한 것입니다.)

하단 통합 터미널에 다음과 같은 메시지가 나타납니다.

Traceback (most recent call last):
  File "main.py", line 2, in 
    from PySide6.QtWidgets import QApplication, QWidget, QLabel, QVBoxLayout
ModuleNotFoundError: No module named 'PySide6'

지난 시리즈에서 여러 번 본 바로 그 오류입니다.

코드는 지난 시리즈에서 정상 실행되던 그대로인데 왜 실패할까요? 원인은 어떤 Python이 실행했는가에 있습니다.

지난 시리즈 (터미널)
→ source .venv/bin/activate 로 가상환경 활성화 후 실행
→ .venv의 Python이 실행 → PySide6 있음 → 성공

지금 (VSCode, 인터프리터 미지정)
→ VSCode가 기본값인 시스템 Python으로 실행
→ 시스템 Python에는 PySide6 없음 → ModuleNotFoundError      ← 원인

지난 강의에서 PySide6를 .venv 안에만 설치하고, 시스템 Python은 깨끗하게 유지했던 것을 떠올려 보세요.

그때 deactivate 후 pip show를 하면 시스템에서는 PySide6를 못 찾았습니다. 지금 VSCode가 겪는 것이 정확히 그 상황입니다 — 아직 .venv를 쓰라는 지시를 받지 못해 기본값인 시스템 Python으로 실행한 것입니다. 터미널에서는 activate로 이 문제를 해결했다면, VSCode에서 그에 해당하는 동작이 바로 인터프리터 선택입니다.

2. 인터프리터를 .venv로 수동으로 연결하기

→ 명령 팔레트로 인터프리터를 선택해 케이스 B를 해결하고, 필요하면 자동 지정된 환경도 바꿉니다.

인터프리터(interpreter)는 Python 코드를 실행하는 Python 실행 파일을 가리키는 말입니다.

지난 시리즈에서 which python으로 확인하던 그 python 실행 파일이 곧 인터프리터입니다.

VSCode에 "이 실행 파일로 코드를 돌려라"라고 알려주는 것이 인터프리터 선택이며, 케이스 B처럼 자동 지정이 되지 않았을 때는 물론, 케이스 A에서 자동 지정된 환경을 다른 것으로 바꾸고 싶을 때도 똑같은 방법을 씁니다.

명령 팔레트를 엽니다(Ctrl+Shift+P). 검색창에 Python: Select Interpreter를 입력하고 Enter를 누릅니다.

2강에서 배운 대로, 메뉴 위치를 외울 필요 없이 기능 이름으로 찾는 방식입니다.

그러면 VSCode가 찾은 Python 목록이 나타납니다.

목록에서 경로에 Project/.venv/bin/python이 포함된 항목을 고릅니다.

선택 후보 예시

  /usr/bin/python3                              ← 시스템 Python (고르지 않음)
  ~/Dev/Project/.venv/bin/python   3.13.x       ← 이것을 선택! (우리 프로젝트의 가상환경)

여러 후보 중 반드시 프로젝트 폴더 안의 .venv 경로를 골라야 합니다.

시스템 Python을 고르면 1번에서 본 오류가 그대로 반복됩니다.

항목을 선택하는 순간, VSCode는 이 워크스페이스에서 앞으로 그 인터프리터를 쓰겠다고 기억합니다.

이 선택은 워크스페이스에 저장되므로, 다음에 이 폴더를 다시 열어도 유지됩니다.

3. 연결 검증하기 — 3중 확인

→ 세 곳에서 VSCode가 정말 .venv를 쓰고 있는지 눈으로 확인합니다.

케이스 A로 자동 지정됐든, 케이스 B에서 방금 수동으로 선택했든 "연결됐다"는 말만 믿지 않고 세 곳에서 직접 확인합니다. 지난 시리즈에서 가상환경 활성화 후 which python으로 경로를 눈으로 확인했던 것과 같은 검증 습관입니다.

3.1 확인 1 — 상태 바 표시

화면 맨 아래 상태 바(2강에서 본 맨 아래 가로 띠)를 봅니다.

인터프리터가 연결되어 있으면 이곳에 현재 연결된 Python이 표시됩니다.

화면 맨 아래 상태 바

  ...                                        Python 3.13.x ('.venv': venv)      ← 여기에 .venv가 표시되면 연결됨

.venv와 버전이 함께 표시되면 첫 번째 확인 통과입니다. 앞으로 이 상태 바만 흘깃 봐도 "지금 VSCode가 내 가상환경을 쓰고 있구나"를 알 수 있습니다.

3.2 확인 2 — 통합 터미널의 (.venv) 표시

통합 터미널을 새로 엽니다(Terminal → New Terminal). 인터프리터가 연결되어 있으면 VSCode가 터미널을 열 때 자동으로 가상환경을 활성화해 줍니다. 그래서 프롬프트 앞에 (.venv)가 이미 붙어 있습니다.

(.venv) user@ubuntu:~/Dev/Project$      ← activate를 직접 치지 않았는데 (.venv)가 붙어 있다

지난 시리즈에서는 매번 source .venv/bin/activate를 직접 입력해야 했지만, VSCode는 인터프리터를 지정해 두면 터미널을 열 때 이 활성화를 대신 해 줍니다. 인터프리터 선택 하나가 터미널 활성화까지 처리해 주는 것입니다.

3.3 확인 3 — which python으로 경로 확인

마지막으로, 지난 강의에서 하던 그 명령을 통합 터미널에서 그대로 실행합니다. 가장 확실한 검증입니다.

which python      # VSCode 통합 터미널에서 실행

/home/사용자명/Dev/Project/.venv/bin/python      ← 시스템이 아닌 .venv 경로!

지금까지 봤던 것과 똑같은 경로가 나옵니다. 시스템 /usr/bin/python3가 아니라 프로젝트 .venv 안의 Python입니다. 세 곳의 확인이 모두 .venv를 가리키면, VSCode와 가상환경의 연결이 완성된 것입니다.

확인 위치	확인 내용	지난 시리즈 대응
상태 바	`('.venv': venv)` 표시	(VSCode 고유)
통합 터미널 프롬프트	`(.venv)` 자동 표시	activate 후 프롬프트
`which python`	`.venv/bin/python` 경로	경로 검증 그대로

✔ 확인 기준: 상태 바에 ('.venv': venv)가 표시되고, 통합 터미널 프롬프트에 (.venv)가 붙고, which python이 .venv/bin/python을 출력하면 연결 완료입니다. 목록에 .venv가 안 보이면 폴더를 ~/Dev/Project로 열었는지(3강) 확인하고, 명령 팔레트에서 Developer: Reload Window로 새로고침한 뒤 다시 시도하세요.

4. 검증된 인터프리터로 실행하기

→ 실행 버튼과 통합 터미널, 두 가지 방법으로 main.py를 실행하고 결과를 확인합니다.

4.1 실행 버튼으로 실행하기

편집 영역 오른쪽 위에 삼각형 모양의 실행 버튼(▷)이 있습니다. main.py를 열어둔 상태에서 이 버튼을 누릅니다.

버튼을 누르면 하단에 통합 터미널이 열리면서 실행 명령이 자동으로 입력되고, 잠시 후 "환경 재현 성공"이라는 제목의 창이 뜹니다. 1번에서 ModuleNotFoundError로 실패했던 바로 그 코드가 이번에는 성공한 것입니다.

실행 버튼이 통합 터미널에 찍은 명령을 보면 이유가 보입니다.

실행 버튼이 자동으로 입력한 명령 (예시)

/home/사용자명/Dev/Project/.venv/bin/python main.py
─────────────────────────────────────────
방금 검증한 .venv의 python으로 실행된다      ← 시스템 python3가 아니다!

실행 버튼은 마법이 아닙니다. 3번에서 검증한 인터프리터, 즉 .venv/bin/python을 사용해 현재 파일을 실행하는 명령을 대신 입력해 준 것뿐입니다. 그래서 .venv 안에 있던 PySide6를 정상적으로 찾을 수 있었습니다.

4.2 통합 터미널로 실행하기

실행 버튼 말고, 지난 시리즈에서 하던 방식으로도 실행할 수 있습니다. 통합 터미널을 열고(Terminal → New Terminal) 직접 명령을 입력합니다.

python main.py      # 통합 터미널에서 직접 실행

역시 같은 창이 뜹니다. 여기서 눈여겨볼 것은 source .venv/bin/activate를 직접 입력하지 않았는데도 성공했다는 점입니다. 3.2에서 확인했듯, VSCode는 인터프리터가 연결된 상태에서 통합 터미널을 열면 가상환경을 자동으로 활성화해 줍니다. 프롬프트의 (.venv) 표시가 그 증거입니다.

방법	어떻게	편한 상황
실행 버튼 (▷)	현재 파일을 클릭 한 번으로 실행	지금 열어둔 파일을 빠르게 실행할 때
통합 터미널	`python main.py` 직접 입력	실행 인자를 붙이거나 다른 명령과 섞어 쓸 때

두 방법 모두 3번에서 검증한 같은 .venv를 씁니다. 자동으로 지정됐든 직접 연결했든, 한 번 제대로 검증해 두면 실행 방식과 무관하게 항상 올바른 Python이 쓰입니다.

- 인터프리터는 자동으로 지정되기도 하고(케이스 A), 수동으로 지정하기도 한다(케이스 B)
- 어느 쪽이든 상태 바 · 통합 터미널 (.venv) · which python 3중 검증으로 확인한다
- 실행 버튼과 통합 터미널 모두 검증된 같은 .venv의 python을 사용한다
- 실행 문제가 나면 가장 먼저 상태 바의 인터프리터 표시를 확인한다

✔ 확인 기준: 실행 버튼(▷)과 통합 터미널의 python main.py 두 방법 모두에서 "환경 재현 성공" 창이 뜨면 이번 강의 완료입니다. 창이 안 뜨고 ModuleNotFoundError가 나면 상태 바가 ('.venv': venv)인지 먼저 확인하고, 아니라면 2번의 인터프리터 선택을 다시 진행하세요.

→ 다음 강의 (5강): 지금까지는 코드가 잘 동작했지만, 값이 잘못 나올 때는 어떻게 원인을 찾을까요? 지난 시리즈에서는 print를 여기저기 넣어 보는 것이 전부였습니다. 5강에서는 코드를 원하는 지점에서 멈춰 세우고 그 순간의 변수 값을 직접 들여다보는 디버깅을 배웁니다 — 이 시리즈의 핵심 보상입니다.