Claude Code에서 바로 고치지 말고 계획부터: plan 모드로 기능 확장하기

01작아 보이는 수정도 먼저 변경 범위를 적기

현재 summarize.py는 expenses.csv를 읽어 월별 amount 합계를 출력합니다. 이번에는 기존 기능을 없애지 않고 `--by-category` 옵션을 줬을 때만 각 월의 category별 합계를 함께 표시하도록 확장합니다. 기능 하나를 더하는 일이라도 바로 파일을 수정하게 하면 출력 형식, 기존 동작 유지 여부, 정렬 순서 같은 세부사항을 AI가 임의로 정할 수 있습니다. 그래서 먼저 '무엇을 그대로 두고 무엇만 바꿀지'를 고정합니다.

여기서 중요한 것은 새 기능보다 회귀를 막는 기준입니다. 옵션을 추가해도 `python summarize.py expenses.csv`의 기존 출력이 달라지면 안 됩니다. 새 옵션의 결과만 보는 것이 아니라 기존 실행 결과도 함께 확인해야 합니다.

02plan 모드로 시작해 아직 수정하지 못하게 하기

Claude Code는 `claude --permission-mode plan`으로 계획 모드에서 시작할 수 있습니다. 이 모드는 읽기 중심으로 코드와 작업 범위를 분석하고 계획을 검토할 때 사용합니다. 초보자는 기존 코드가 있는 상태에서 바로 수정 권한을 넓히기보다 먼저 계획을 받아보는 방식이 이해하기 쉽습니다.

cd vibe-expenses
claude --permission-mode plan

세션이 시작되면 먼저 현재 summarize.py와 expenses.csv를 읽고, 어떤 부분을 바꿀지 설명하게 합니다. 이 단계의 요청문에는 '아직 수정하지 마'를 명시합니다. 계획이 마음에 들지 않으면 파일을 건드리지 않은 상태에서 요구사항부터 고칠 수 있습니다.

summarize.py를 읽고 현재 동작을 먼저 설명해줘.
그다음 `--by-category` 옵션을 추가하는 변경 계획만 작성해줘. 아직 파일은 수정하지 마.
기본 실행 `python summarize.py expenses.csv`의 출력은 그대로 유지해야 해.
옵션 실행 `python summarize.py expenses.csv --by-category`에서는 각 월의 category별 합계를 추가해줘.
Python 표준 라이브러리만 사용하고 expenses.csv는 수정하지 마.
2026-09의 기대 분류 합계는 food 20500, transport 2900, supplies 3200이야.

03계획에서 구현 방법보다 누락된 조건부터 찾기

계획을 받을 때는 코드가 세련되어 보이는지보다 요구사항이 모두 반영됐는지 먼저 봅니다. 특히 기존 출력 유지, 옵션이 없을 때의 동작, category 정렬, 잘못된 옵션 처리, 외부 패키지 추가 여부를 확인합니다. 계획이 모호하면 구현 전에 질문을 한 번 더 넣습니다.

[편집 예시 · 실제 응답 아님]
1. 현재 CSV 읽기와 월별 합계 계산 구조는 유지합니다.
2. 월별 category 합계를 함께 누적할 자료구조를 추가합니다.
3. 두 번째 인자가 `--by-category`인지 확인해 옵션 사용 여부를 결정합니다.
4. 기본 실행에서는 기존 월별 합계만 출력합니다.
5. 옵션 실행에서는 월별 합계 다음 줄에 category 이름과 합계를 정렬해 출력합니다.
6. 구현 후 기본 실행과 옵션 실행을 각각 수행해 기대값을 비교합니다.

• 기존 기본 실행의 출력이 그대로 유지되는가
• 옵션이 있을 때만 분류별 결과가 추가되는가
• 외부 패키지 설치를 새로 요구하지 않는가
• expenses.csv를 수정하거나 새 형식으로 바꾸지 않는가
• 기대값과 대조할 실행 명령이 계획에 포함되어 있는가

위 계획 예시는 설명을 위한 편집 예시이며 실제 Claude Code 응답이 아닙니다. 실제 세션에서는 모델이 다른 구현 순서를 제안할 수 있으므로, 계획 문장 자체를 정답으로 외우기보다 자신의 요구사항과 맞는지 확인해야 합니다.

04계획을 검토한 뒤 구현하고 완성 코드를 확인하기

계획이 요구사항과 맞는 것을 확인한 뒤 구현을 진행합니다. Claude Code에서 실제 파일 수정과 명령 실행은 환경과 권한 설정에 따라 승인을 요청할 수 있습니다. 아래 코드는 이 글에서 결과 검증에 사용한 완성 예시입니다. Claude Code의 실제 응답을 복사한 것이 아니라, 이 글의 요구사항에 맞춰 작성하고 GPT 채팅의 Python 실행 환경에서 별도로 실행한 코드입니다.

import csv
import sys
from collections import defaultdict

def read_totals(path):
    monthly = defaultdict(int)
    by_category = defaultdict(lambda: defaultdict(int))

    with open(path, newline="", encoding="utf-8") as f:
        reader = csv.DictReader(f)
        for row in reader:
            month = row["date"][:7]
            amount = int(row["amount"])
            monthly[month] += amount
            by_category[month][row["category"]] += amount

    return monthly, by_category

def main():
    if len(sys.argv) not in (2, 3):
        print("Usage: python summarize.py expenses.csv [--by-category]")
        raise SystemExit(2)

    if len(sys.argv) == 3 and sys.argv[2] != "--by-category":
        print("Usage: python summarize.py expenses.csv [--by-category]")
        raise SystemExit(2)

    monthly, by_category = read_totals(sys.argv[1])
    show_category = len(sys.argv) == 3

    for month in sorted(monthly):
        print(f"{month} = {monthly[month]}")
        if show_category:
            for category in sorted(by_category[month]):
                print(f"  {category} = {by_category[month][category]}")

if __name__ == "__main__":
    main()

이 코드는 csv 모듈과 collections.defaultdict만 사용합니다. 기본 실행에서는 월별 합계만 출력하고, 정확히 `--by-category`가 두 번째 인자로 들어왔을 때 월별 합계 아래에 category별 합계를 정렬해서 표시합니다. 다른 옵션이나 인자 개수가 들어오면 사용법을 보여주고 종료합니다.

05새 기능뿐 아니라 기존 실행도 다시 확인하기

기능 추가 후에는 두 가지 실행을 모두 확인합니다. 먼저 옵션 없이 실행해 기존 결과가 유지되는지 보고, 그다음 `--by-category`를 붙여 새 기능을 확인합니다. 이 원고의 Python 코드는 GPT 채팅 Python 도구에서 실제로 실행했으며 아래 기대 출력과 정확히 일치했습니다.

python summarize.py expenses.csv
python summarize.py expenses.csv --by-category

기본 실행 기대 출력:
2026-09 = 26600
2026-10 = 9800

--by-category 기대 출력:
2026-09 = 26600
  food = 20500
  supplies = 3200
  transport = 2900
2026-10 = 9800
  food = 9800

9월 category의 출력 순서는 알파벳 정렬이므로 food, supplies, transport 순서입니다. 합계 자체는 시리즈 첫 글에서 정한 기준값 food 20500, transport 2900, supplies 3200과 모두 같습니다. 10월에는 food 한 종류만 있으므로 9800이 표시됩니다.

06구현 승인 전에 보는 짧은 체크리스트

plan 모드의 목적은 AI의 계획을 길게 받는 것이 아니라 수정 전에 사람이 판단할 지점을 만드는 데 있습니다. 다음과 같이 몇 가지 질문만 통과하면 구현을 승인하고, 하나라도 모호하면 먼저 계획을 고칩니다.

다음 글에서는 이런 변경을 하기 전과 후를 git으로 기록합니다. Claude Code의 체크포인트가 있더라도 git은 별도의 버전 관리 수단이며, 사람이 변경 파일과 diff를 읽는 흐름을 익혀두면 AI가 무엇을 바꿨는지 더 명확하게 추적할 수 있습니다.

직접 확인할 항목

GPT 채팅 Python 도구의 Python 실행 환경에서 가상 expenses.csv와 본문의 summarize.py를 파일로 저장해 실제 실행 · Claude Code 실제 실행 없음

• 기본 실행에서 2026-09 = 26600, 2026-10 = 9800이 정확히 출력되는지 확인
• `--by-category` 실행에서 2026-09 food = 20500, supplies = 3200, transport = 2900이 정확히 출력되는지 확인
• `--by-category` 실행에서 2026-10 food = 9800이 출력되는지 확인
• 두 실행 모두 종료 코드 0으로 완료되는지 확인
• Python 표준 라이브러리만 사용하며 expenses.csv를 수정하지 않는 코드인지 확인
• Claude Code 계획 응답 예시는 '[편집 예시 · 실제 응답 아님]'으로 표시했는지 확인