2강. Plan 모드에서 공백 상품명 검증 계획 검토하기
0. 학습 목표
→ Plan mode에서 구현 전 변경 범위를 정하고, 요구사항과 성공 증거로 계획을 검토합니다.
Claude Code를 Plan mode로 전환하고 현재 모드 표시로 코드가 수정되지 않는 계획 단계인지 확인합니다.src/inventory.py와tests/test_inventory.py를 대상으로 정상 입력 유지, 공백 상품명 거부,ValueError예외 계약과 경계 테스트 두 개가 포함된 계획을 요청합니다.- 최종 Plan 문서에서 수량 검증·별도 검증 파일·테스트 도구 변경 같은 범위 밖 작업을 제거하고, 두 소스 파일이 아직 바뀌지 않았는지 확인합니다.
1. 문제를 변경 요구사항과 시작 상태로 정리하기
→ 공백 상품명 문제의 범위를 정하고, 계획 전 코드와 테스트 상태를 기준점으로 남깁니다.
현재 재고 함수는 정상 입력 테스트 두 개를 통과하지만 공백 세 칸으로 이루어진 상품명도 그대로 반환합니다.
이번 강의에서는 바로 코드를 고치지 않습니다. 먼저 Claude Code의 Plan mode에서 어떤 파일을 어떻게 바꿀지 검토합니다. 이 과정을 거치면 필요한 수정만 남기고 기존 정상 동작을 실수로 바꾸는 일을 줄일 수 있습니다.
Plan mode에서 Claude Code는 프로젝트를 읽고 변경 계획을 제안하지만 소스 파일은 수정하지 않습니다.
계획을 제안하는 역할은 Claude Code가 맡습니다.
변경 범위와 예외 조건, 테스트 사례가 요구사항에 맞는지 판단하는 역할은 학생이 맡습니다.
1.1 공백 상품명 문제를 변경 요구사항으로 바꾸기
현재 코드와 실행 결과에서 확인한 사실은 다음과 같습니다.
create_inventory_item("키보드", 3)은{"name": "키보드", "quantity": 3}을 반환합니다.- 기존 정상 입력 테스트 두 개는 통과합니다.
create_inventory_item(" ", 3)도 오류 없이 공백 상품명을 반환합니다.- 현재 테스트에는 빈 문자열과 공백 문자열을 확인하는 사례가 없습니다.
이번 강의에서는 이 문제를 다음 요구사항으로 다룹니다.
- 정상 상품명을 전달하면 지금과 같은 재고 항목을 반환합니다.
- 빈 문자열
""은 상품명으로 허용하지 않습니다. - 공백으로만 구성된 문자열
" "도 상품명으로 허용하지 않습니다. - 잘못된 상품명에는
ValueError를 발생시킵니다. - 예외 메시지는
상품명은 비어 있을 수 없습니다.로 통일합니다. - 변경 대상은
src/inventory.py와tests/test_inventory.py로 제한합니다.
이 요구사항에는 정상 상품명의 앞뒤 공백 제거, 상품명 자료형 검사, 수량 검증이 포함되지 않습니다. 이번 문제를 해결하는 데 필요하지 않은 작업까지 한꺼번에 추가하면 어떤 변경이 테스트 결과에 영향을 주었는지 판단하기 어려워집니다.
1.2 소스 파일과 정상 테스트의 변경 전 상태 확인하기
Plan mode를 시작하기 전에 프로젝트의 현재 상태를 확인합니다.
# 실습 위치 안내
[대주제] Claude
└─ [현재 소주제] VS Code에서 Claude Code 사용
├─ ✓ 0강 Claude Code 확장 설정과 재고 프로젝트 확인
├─ ✓ 1강 선택 코드와 @-mention으로 문제 설명 요청
├─ ▶ 2강 Plan 모드에서 상품명 검증 계획 검토
│ ├─ ▶ 현재 실습: 변경 전 정상 테스트 다시 확인
│ │ ├─ 대상: src/inventory.py, tests/test_inventory.py
│ │ ├─ 작성: 없음
│ │ └─ 확인: 기존 테스트 2개 통과와 파일 변경 표시 없음
│ ├─ ○ Plan 모드에서 변경 계획 요청
│ └─ ○ 범위 밖 작업을 제거하고 최종 계획 확인
├─ ○ 3강 계획에 맞는 코드 차이 검토와 반영
└─ ○ 4강 통합 터미널 테스트와 실패 수정
VS Code Explorer에서 src/inventory.py와 tests/test_inventory.py에 저장되지 않은 변경 표시가 없는지 확인합니다. 통합 터미널의 현재 위치가 $HOME/claude-course-workspace인지 확인한 뒤 기존 테스트를 실행합니다.
쉘 프롬프트 — VS Code 통합 터미널 · Bash
# 상품명 검증을 계획하기 전에 기존 정상 입력 테스트 두 개를 다시 확인한다.
cd "$HOME/claude-course-workspace"
python -m unittest -v
다음처럼 기존 테스트 두 개가 ok로 끝나고 마지막에 OK가 표시되어야 합니다.
test_returns_name (tests.test_inventory.CreateInventoryItemTest.test_returns_name) ... ok
test_returns_quantity (tests.test_inventory.CreateInventoryItemTest.test_returns_quantity) ... ok
----------------------------------------------------------------------
Ran 2 tests in 0.000s
OK
실행 시간은 환경마다 다를 수 있습니다. 테스트 두 개의 ok와 마지막 OK를 확인하면 됩니다. 이 결과는 검증 기능이 이미 있다는 뜻이 아닙니다. 변경 전 정상 동작이 무엇인지 확인한 결과입니다.
2. Plan mode에서 두 파일의 변경 계획 요청하기
→ 실제 모드를 확인한 뒤 대상 파일과 요구사항을 지정하여 구현 전 계획만 요청합니다.
2.1 Claude Code를 Plan mode로 전환하기
Claude Code 사이드바의 프롬프트 상자 아래에서 현재 권한 모드를 확인합니다. 0강에서 설정한 새 대화라면 Manual(Ask before edits)로 표시됩니다. 모드 표시를 누르고 Plan mode를 선택합니다. Plan mode는 소스 파일을 수정하지 않고 프로젝트를 읽어 변경 계획을 제안하는 방식입니다.
Plan mode는 채팅으로 “계획만 세워 줘”라고 요청하는 표현과 다릅니다. 프롬프트를 보내기 전에 실제 모드 표시가 Plan mode인지 확인해야 합니다. 현재 동작 방식은 Anthropic의 권한 모드 공식 안내와 VS Code 공식 안내를 기준으로 합니다.
Use Claude Code in VS Code - Claude Code Docs
Install and configure the Claude Code extension for VS Code. Get AI coding assistance with inline diffs, @-mentions, plan review, and keyboard shortcuts.
code.claude.com
Choose a permission mode - Claude Code Docs
Control whether Claude asks before editing files or running commands. Cycle modes with Shift+Tab in the CLI or use the mode selector in VS Code, Desktop, and claude.ai.
code.claude.com
2.2 두 파일과 요구사항을 지정하여 계획 요청하기
src/inventory.py와 tests/test_inventory.py를 각각 열어 상품명 검증 코드와 경계 입력 테스트가 아직 추가되지 않았는지 확인합니다. Claude Code 프롬프트에서 두 파일을 @-mention으로 지정한 뒤 요구사항을 전달합니다.
클로드 프롬프트 — Claude Code 사이드바 · Plan mode
# 목적: 소스 파일을 수정하기 전에 공백 상품명 검증의 변경 범위와 테스트 계획을 검토한다.
@src/inventory.py와 @tests/test_inventory.py를 읽고 변경 계획만 작성해 주세요.
요구사항은 다음과 같습니다.
1. 정상 상품명과 수량은 현재와 같은 딕셔너리로 반환해야 합니다.
2. 빈 문자열 ""과 공백으로만 구성된 문자열 " "은 상품명으로 허용하지 않습니다.
3. 잘못된 상품명에는 ValueError를 발생시킵니다.
4. 예외 메시지는 "상품명은 비어 있을 수 없습니다."로 통일합니다.
5. 기존 정상 입력 테스트 두 개를 유지합니다.
6. 빈 문자열과 공백 문자열을 각각 확인하는 테스트를 추가합니다.
7. 변경 대상은 src/inventory.py와 tests/test_inventory.py 두 파일로 제한합니다.
계획에는 파일별 변경 내용, 유지할 기존 동작, 추가할 테스트 입력과 기대 결과,
마지막에 실행할 테스트 명령을 포함해 주세요.
아직 소스 파일을 수정하거나 구현 코드를 작성하지 마세요.
Claude Code가 계획을 만들면 VS Code에서 Markdown 문서 형태로 열어 검토할 수 있습니다. 계획 문서에 의견을 남기면 구현을 시작하기 전에 범위를 다시 조정할 수 있습니다.
3. 계획을 요구사항에 대조하고 범위 확정하기
→ 계획의 길이가 아니라 변경 파일·예외 계약·테스트와 제외 범위를 근거로 승인 가능 여부를 판단합니다.
3.1 Plan 문서를 요구사항과 대조하기
계획의 문장 수나 자세한 정도보다 실제 요구사항이 빠짐없이 반영되었는지 확인합니다.
적절한 계획은 다음 내용을 포함해야 합니다.
|
확인할 항목 |
계획에 들어가야 할 내용 |
판단 이유 |
|---|---|---|
| 변경 파일 | src/inventory.py, tests/test_inventory.py 두 파일 |
현재 문제와 테스트를 해결하는 데 필요한 범위입니다. |
| 검증 위치 | 딕셔너리를 반환하기 전에 상품명을 검사 | 잘못된 값이 결과에 들어가기 전에 중단해야 합니다. |
| 경계 조건 | ""와 " "을 모두 거부 |
빈 문자열 검사만으로는 공백 문자열을 놓칠 수 있습니다. |
| 예외 계약 | ValueError와 정해진 메시지 사용 |
호출 코드와 테스트가 같은 실패 결과를 확인할 수 있습니다. |
| 기존 동작 | 정상 상품명과 수량은 그대로 반환 | 문제와 관계없는 현재 동작을 유지해야 합니다. |
| 테스트 | 기존 2개 유지, 잘못된 입력 테스트 2개 추가 | 수정 후 정상 동작과 경계 조건을 함께 확인합니다. |
| 실행 확인 | python -m unittest -v 실행 |
최종 판단은 계획의 설명이 아니라 테스트 결과로 내립니다. |
name.strip()으로 눈에 보이는 문자가 남는지 확인할 수 있습니다. 다만 정상 상품명의 앞뒤 공백까지 제거하여 다른 값으로 반환하는 작업은 이번 요구사항에 없습니다. 계획에서 name = name.strip()처럼 입력값 자체를 바꾸겠다고 제안한다면, 공백 여부 확인에만 strip()을 사용하고 정상 입력의 반환값은 유지하도록 수정 의견을 남깁니다.
다음 제안은 이번 계획에서 제외합니다.
- 별도의
validator.py파일이나 검증 클래스를 새로 만드는 작업 create_inventory_item함수명이나 반환 딕셔너리 구조를 바꾸는 작업unittest를pytest로 교체하는 작업- 수량의 자료형이나 최소값을 검사하는 작업
- 상품명 자료형 검사와 길이 제한을 함께 추가하는 작업
이 항목들이 항상 나쁜 설계라는 뜻은 아닙니다. 현재 강의에서 확인한 문제를 해결하는 데 필요하지 않으므로 이번 변경에서 제외하는 것입니다.
3.2 범위가 넓은 계획에 수정 의견 남기기
Claude Code가 필요 이상의 구조 변경을 제안하거나 테스트 사례를 빠뜨렸다면 계획을 승인하지 않습니다. Plan 문서의 관련 위치에 인라인 댓글을 남기거나 Claude Code 사이드바에서 다음 요청을 보냅니다.
클로드 프롬프트 — Claude Code 사이드바 · Plan mode
# 목적: 공백 상품명 문제를 해결하는 데 필요한 범위만 남도록 변경 계획을 수정한다.
방금 계획을 다음 기준으로 수정해 주세요.
- 변경 파일은 src/inventory.py와 tests/test_inventory.py 두 개만 유지합니다.
- 별도 검증 파일이나 클래스는 만들지 않습니다.
- 정상 입력의 반환값과 기존 테스트 두 개는 유지합니다.
- 빈 문자열 ""과 공백 문자열 " "을 각각 확인하는 테스트를 포함합니다.
- ValueError와 "상품명은 비어 있을 수 없습니다." 메시지를 계획에 명시합니다.
- 수량 검증, 상품명 자료형 검사와 테스트 도구 변경은 제외합니다.
- strip()은 공백 여부를 판단할 때만 사용하고 정상 상품명의 값을 바꾸지 않습니다.
수정된 파일별 계획과 실행할 테스트 명령만 다시 제시해 주세요.
아직 소스 파일은 수정하지 마세요.
수정된 계획을 받으면 처음 계획과 표현을 비교하는 데 시간을 쓰지 않습니다. 위의 검토 표를 다시 적용하여 필요한 항목이 들어왔고 범위 밖 작업이 사라졌는지 확인합니다.
3.3 최종 계획을 다음 강의의 판단 기준으로 확정하기
검토를 마친 계획은 다음 흐름으로 정리되어야 합니다.
src/inventory.py에서 상품명이 비었거나 공백으로만 구성되었는지 반환 전에 검사합니다.- 조건에 해당하면
ValueError("상품명은 비어 있을 수 없습니다.")를 발생시킵니다. - 정상 상품명과 수량을 반환하는 기존 동작은 바꾸지 않습니다.
tests/test_inventory.py의 기존 테스트 두 개를 유지합니다.- 빈 문자열과 공백 문자열에서 같은
ValueError와 메시지를 확인하는 테스트를 각각 추가합니다. python -m unittest -v를 실행하여 정상 입력과 잘못된 입력 테스트를 함께 확인합니다.
여기까지 확인해도 이번 강의에서는 구현 승인 항목을 선택하지 않습니다. 계획 승인 옵션은 Plan mode를 종료하고 실제 편집을 시작할 수 있기 때문입니다. Claude Code 대화와 최종 계획을 그대로 둔 채 소스 파일에 변경 표시가 없는지 다시 확인합니다. 현재 두 테스트를 다시 실행했을 때 여전히 2개가 통과하는 것이 정상입니다.
다음 강의에서는 같은 대화에서 검토를 마친 계획의 구현을 요청합니다. 그때 side-by-side 코드 차이를 열고 조건식, 예외 유형과 메시지, 기존 동작 유지, 테스트 추가가 이번 계획과 일치하는지 하나씩 판단합니다.
3.4 Plan mode 문제를 원인별로 확인하기
- 모드 표시가
Ask before edits라면 프롬프트를 보내기 전에Plan mode로 다시 바꿉니다. - 계획에 세 번째 파일이나 구조 변경이 포함되면 승인하지 않고 범위를 두 파일로 좁히는 의견을 보냅니다.
- 빈 문자열 테스트만 있고 공백 문자열 테스트가 없으면 두 입력을 서로 다른 테스트로 계획하도록 요청합니다.
- 정상 입력 테스트를 삭제하거나 바꾸겠다는 내용이 있으면 기존 테스트 두 개를 유지하도록 요청합니다.
- 소스 파일에 변경 표시가 생겼다면 구현을 계속하지 않습니다. 현재 모드를 확인하고 변경을 되돌린 뒤 0강의 완성 코드와 대조하여 시작 상태를 복구합니다.
이번 강의를 마칠 때 필요한 결과는 긴 계획서가 아닙니다. 두 파일만 변경하고, 정상 동작은 유지하며, 두 잘못된 입력을 같은 예외 계약으로 검증하고, 전체 테스트로 결과를 판단한다는 계획이면 충분합니다.
다음 강의 — 확정한 Plan을 기준으로 side-by-side 코드 차이를 검토하고 필요한 변경만 반영합니다.