Claude Code로 첫 도구 만들기: 가계부 CSV 월별 합계

01첫 도구는 입력 하나와 출력 하나로 작게 시작하기

첫 실습의 목표는 기능이 많은 가계부 앱이 아니라 expenses.csv를 읽어 월별 amount 합계만 출력하는 summarize.py 한 파일입니다. 범위를 작게 잡으면 AI가 만든 결과가 맞는지 사람이 직접 확인하기 쉽습니다. 입력 파일은 UTF-8 CSV이고 열 이름은 date, category, amount입니다. date는 YYYY-MM-DD 형식, amount는 정수로 가정합니다.

이번 단계에서 중요한 점은 '가계부를 만들어줘'처럼 넓은 요청을 하지 않는 것입니다. AI가 UI, 데이터베이스, 차트, 로그인 같은 기능을 임의로 확장할 여지를 줄이고, 한 번의 실행으로 정답을 대조할 수 있는 작업만 맡깁니다.

02요청문에 입력·기대 출력·제약을 함께 넣기

Claude Code에 작업을 요청할 때는 입력 파일의 구조와 정답을 함께 제공합니다. 기대 출력이 있으면 AI가 코드를 작성한 뒤 무엇을 맞춰야 하는지 명확해지고, 사용자는 결과를 눈으로 비교할 수 있습니다. 또한 '표준 라이브러리만 사용', '원본 CSV를 수정하지 않기', 'summarize.py만 작성'처럼 하지 말아야 할 범위도 함께 적습니다.

현재 폴더의 expenses.csv를 읽어 월별 amount 합계를 출력하는 summarize.py를 만들어줘.

입력:
- UTF-8 CSV
- 열 이름: date, category, amount
- date 형식: YYYY-MM-DD
- amount는 정수

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

제약:
- Python 표준 라이브러리만 사용
- expenses.csv는 수정하지 않기
- 실행 명령은 python summarize.py expenses.csv
- 필요한 파일과 변경 내용을 먼저 설명한 뒤 summarize.py만 작성해줘.

이 코드 블록은 Claude Code의 응답이 아니라 사용자가 입력할 요청문입니다. 요청문에는 이미 정답으로 확인할 값이 들어 있으므로, 이후 결과가 그럴듯해 보이는지만 보지 않고 두 숫자가 정확히 일치하는지 비교할 수 있습니다.

03파일 수정 전에 무엇을 만들려는지 먼저 확인하기

Claude Code는 필요한 파일을 읽고 파일 수정이나 명령 실행 전에 승인을 요청할 수 있습니다. 승인 화면이 나오면 바로 Yes를 누르기보다 어떤 파일을 읽었는지, 새로 만들 파일이 summarize.py 하나인지, expenses.csv를 건드리지 않는지 확인합니다. 처음 보는 명령을 실행하려 한다면 그 명령의 목적을 설명해 달라고 요청해도 됩니다.

수정하기 전에 확인할게.
1) 읽을 파일과 만들 파일을 각각 알려줘.
2) expenses.csv는 수정하지 않는지 확인해줘.
3) 외부 패키지를 설치하지 않는지 확인해줘.
4) 실행 후 기대 출력과 비교하는 방법을 한 줄로 알려줘.

Claude Code의 실제 답변은 환경과 시점에 따라 달라질 수 있으므로 이 글에서는 특정 응답을 성공 사례처럼 만들지 않습니다. 확인할 대상은 응답 문체가 아니라 파일 범위와 명령 범위입니다.

04검증용 완성 코드와 실행 명령 확인하기

아래 summarize.py는 이 글의 요구사항을 만족하는 검증용 완성 코드입니다. csv.DictReader로 각 행을 읽고 date 앞 7글자에서 YYYY-MM을 얻은 뒤 amount를 정수로 변환해 월별로 더합니다. 출력 순서를 고정하기 위해 월 키를 정렬합니다. 이 코드는 Claude Code에서 실제 생성된 응답을 복사한 것이 아니라, 글의 실습 결과를 재현하기 위해 작성하고 별도로 실행 확인한 코드입니다.

import csv
import sys
from collections import defaultdict

def summarize_monthly(path):
    totals = defaultdict(int)

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

    return totals

def main():
    if len(sys.argv) != 2:
        raise SystemExit("Usage: python summarize.py expenses.csv")

    totals = summarize_monthly(sys.argv[1])
    for month in sorted(totals):
        print(f"{month} = {totals[month]}")

if __name__ == "__main__":
    main()

표준 라이브러리만 사용하므로 별도 패키지 설치는 필요하지 않습니다. 실행 명령은 아래와 같고, Windows 환경에서 python 대신 py가 설정되어 있다면 `py summarize.py expenses.csv`를 사용할 수 있습니다.

python summarize.py expenses.csv

05실행 결과를 기대값과 한 줄씩 대조하기

GPT 채팅의 Python 도구에서 위 코드와 가상 expenses.csv를 파일로 저장한 뒤 `python summarize.py expenses.csv`를 실제 실행했습니다. 표준 출력은 아래 두 줄과 정확히 일치했습니다. 이 검증은 Claude Code에서 수행한 것이 아닙니다.

2026-09 = 26600
2026-10 = 9800

이 단계에서는 두 줄이 맞았다는 사실만 확인합니다. 향후 다른 형식의 CSV, 비어 있는 값, 잘못된 숫자까지 모두 처리된다고 확대 해석하면 안 됩니다. 현재 테스트 데이터와 현재 요구사항에 대해서만 결과가 일치한 것입니다.

합계를 손으로도 한 번 확인할 수 있습니다. 9월은 12000 + 1450 + 8500 + 3200 + 1450 = 26600이고, 10월은 9800 한 건이므로 9800입니다. 이렇게 작은 예제에서는 프로그램 출력과 사람이 계산한 기준값이 같은지 교차 확인해 두면, 이후 기능을 확장했을 때 어디서 결과가 달라졌는지 추적하기 쉬워집니다.

06정답이 맞으면 기능을 더 붙이지 않고 멈추기

첫 도구에서 가장 흔한 범위 확대는 '이왕 만든 김에 분류별 합계, 그래프, 자동 저장도 추가하자'는 식입니다. 하지만 이번 글의 완료 조건은 월별 합계 두 줄이 맞는 것입니다. 완료 조건을 충족했다면 현재 상태를 기준점으로 남기고 다음 기능은 별도 요청으로 나누는 편이 좋습니다.

• summarize.py 외에 예상하지 않은 파일이 생기지 않았는지 확인한다.
• expenses.csv 내용이 바뀌지 않았는지 확인한다.
• 외부 패키지 설치가 추가되지 않았는지 확인한다.
• 실행 결과 두 줄이 기대값과 정확히 일치하는지 확인한다.
• 추가 기능은 이번 요청에 섞지 않고 다음 작업으로 분리한다.

다음 글에서는 매번 긴 제약을 다시 쓰지 않도록 프로젝트 규칙을 CLAUDE.md에 정리합니다. 그 파일도 강제 설정이 아니라 Claude Code가 세션 시작 시 읽는 프로젝트 맥락이므로, 짧고 구체적으로 유지하는 것이 핵심입니다.

직접 확인할 항목

GPT 채팅 Python 도구에서 Python 3으로 summarize.py와 가상 expenses.csv를 저장한 뒤 `python summarize.py expenses.csv` 실행 · Claude Code 실제 실행 없음

• Python 코드가 표준 라이브러리 csv, sys, collections.defaultdict만 사용하는지 확인
• expenses.csv를 UTF-8 읽기 전용으로 열고 원본을 수정하지 않는지 확인
• date의 앞 7글자로 월을 구하고 amount를 int로 변환해 합산하는지 확인
• 실제 실행 stdout이 `2026-09 = 26600`과 `2026-10 = 9800` 두 줄과 정확히 일치하는지 확인
• 요청문에 입력·기대 출력·표준 라이브러리 제약·원본 수정 금지가 포함됐는지 확인
• Claude Code에서 실행 또는 검증했다고 잘못 표현하지 않았는지 확인