지난 글에서 PRD 문서를 통해 내가 원하는 기능을 구현하는 과정을 적었다.
투자에 대해 잘 알지도 못하면서, DART(전자공시시스템)에서 재무제표와 공시일을 자동으로 긁어올 수 있다는 사실을 알게 된 게 시작이었다.
"이 정도면 Claude Code한테 시켜서 뭐든 만들 수 있겠는데?" 싶었지만, 그냥 "이런 거 만들어줘"라고 던지기보다는 내가 먼저 요구사항을 정리하고 싶었다.
그래서 PRD 한 장을 써서 Claude Code에게 넘겼고, 그 결과로 종목의 3년치 실적 발표 이벤트와 초과수익률(CAR)을 계산해주는 파이프라인이 나왔다.
문제는 그다음이었다.
"다 됐는데, 왜 이렇게 쓰기 불편하지?"
기능 자체는 완벽하게 돌아갔다.
하지만, 매번 터미널을 열고, 종목코드를 정확히 외워서 타이핑하고, 결과는 텍스트로 좌르륵 출력되고, 차트는 별도 HTML 파일을 찾아서 브라우저로 열어야 했다.
사용법이 워낙 불편하다 보니 GUIDE.md 파일도 만들어서 사용할때 참고하게 만들었다.
나 하나 쓰자고 만든 도구인데도 "이걸 매번 이렇게 써야 하나" 싶은 마음이 들었다.
화면 하나 띄워놓고 종목 검색하고 버튼 누르면 바로 결과가 보이는, 그런 게 필요했다.
코드만 수정하려다 든 불안감
처음엔 단순하게 생각했다.
PRD 문서를 열어서 "GUI 추가" 요구사항을 끼워 넣고, 그대로 Claude Code한테 구현을 맡기면 될 것 같았다.
그런데 막상 시작하려니 걸리는 게 있었다.
이미 앞서 만들었던 프로그램은 잘 동작하고 있었다. 그러니 다시 처음부터 새로 만들어 달라고 요청하는 것 보다는 앞서 만들었던 코드를 수정하는 방식으로 접근하는 것이 좋겠다는 생각이 들었다.
걱정은 이 파일을 손대는 과정에서 "리팩터링하다가 멀쩡하던 CLI가 망가지면 어떡하지?"라는 생각이 계속 들었다.
PRD 문서 하나만 고쳐서 "이거 보고 구현해줘" 하기엔, 이번엔 손댈 코드 범위가 넓었다.
안전장치: 예전에 만들어 뒀던 잘 만들어둔 CLAUDE.md 내 프로젝트에 맞게 고치기
그래서 방향을 바꿨다.
기능을 구현하기 전에, "어떻게 개발할지"에 대한 규칙부터 만들기로 했다.
마침 다른 프로젝트(업무 자동화용 저장소)에 잘 정리된 "CLAUDE.md"가 있었다.
이 CLAUDE.md 파일은 Hermes를 설치해둔 나의 AI Agent용 PC의 Skill 개발용 폴더에 만들어놓은 CLAUDE.md 파일이었다. 사무 자동화에 특화된...
그 파일을 그대로 이 프로젝트에 가져왔다.
물론 그대로 쓸 순 없었다 — 그 문서는 "Hermes"라는 자동화 실행기에 등록할 스킬(자동화 스크립트)들을 관리하는 용도였고, 내 프로젝트는 부동산·주식 데이터를 분석해서 재테크에 써먹는 게 목적이었으니까.
Claude Code에게 "이 샘플 문서를 참고해서, 우리 프로젝트 목적(재테크 분석)에 맞게 다시 만들어줘.
Hermes 관련 내용은 다 빼고, 대신 데이터는 DuckDB로 관리하고 pandas보다 polars를 우선 쓰는 원칙을 넣어줘"라고 요청했다. 결과로 나온 새 CLAUDE.md는 내 프로젝트의 실제 폴더 구조를 그대로 반영하면서, 개발 방식에 대한 규칙만 이식한 문서가 됐다.
CLAUDE.md에서 진짜 중요했던 세 가지
문서 하나 만든다고 뭐가 달라지나 싶었는데, 막상 쓰고 보니 아래 세 가지가 실질적으로 작업 방식을 바꿔놓았다.
1. 폴더 구조. 루트에 아무렇게나 흩어져 있던 PRD.md 파일과 GUIDE.md 같은 문서들을 하나의 폴더에 모았다. 앞으로 새 기능을 만들 때도 정해진 폴더명에 PRD·GUIDE를 모아두기로 정했다.
2. 개발 원칙 — "PRD → (필요할 때만) SRS → (필요할 때만) Implementation Plan → 개발". 이번처럼 로직이 복잡하지 않은 패치(GUI 추가, 검색 기능)는 PRD만 갱신하고 바로 개발로 들어가도 된다는 걸 문서로 못 박아뒀다. 반대로 외부 API가 2개 이상 얽히거나 상태 관리가 필요한 큰 기능은 SRS, 필요하면 Implementation Plan까지 단계별로 쪼개서 진행하기로 했다. 덕분에 "이번 작업은 문서를 얼마나 무겁게 써야 하나"를 매번 새로 고민하지 않아도 됐다.
3. Git 관리 원칙 — 의미 단위로 쪼개서 커밋.
PRD 갱신 → 로직 리팩터링 → GUI 추가 → 테스트 → 문서 정리, 이렇게 단계별로 커밋하기로 정해뒀다. 이를 통해 나중에 "리팩터링 커밋만 따로 리버트하고 싶다" 같은 상황에서도 안심할 수 있게 됐다.
실제로 이번 GUI 작업도 정확히 이 순서(PRD → 리팩터링 → GUI → 테스트 → 문서) 그대로 커밋 5개로 나뉘어 올라갔다.
이 세 가지 덕분에 "리팩터링하다 기존 코드를 망가뜨릴지 모른다"는 불안감이 실제로 줄었다.
로직을 고칠 때도 "CLI가 쓰던 함수를 그대로 재사용하고, 계산 결과를 검증하는 테스트를 먼저 만들어두자"는 게 자연스러운 흐름이 됐으니까.
만들어진 최종 CLAUDE.md 파일은 아래와 같다.
그러고 나니, 기능 구현은 오히려 쉬웠다
역설적이게도, 규칙을 정하는 데 공을 들이고 나니 정작 GUI 구현 자체는 순식간이었다.
"실적발표 이벤트 기반 주가 반응 분석 기능을 강화하자. GUI를 만들어서 바로 입력할 수 있게 하고, 종목코드는 검색해서 선택할 수 있게 하자"라고 한 번 요청했더니,
Claude Code는:
- PRD를 v0.2로 갱신하면서 GUI/검색 요구사항(F1-5, F1-6)을 추가하고
- 기존 계산 로직을 바로 수정하고,
- 이미 있던 DART 상장사 전체 매핑 캐시(`data/dart_corp_codes.csv`)를 재활용해서 종목 풀 5개로 한정하지 않고 아무 상장사나 검색할 수 있게 하고
- Streamlit GUI(`dashboard/earnings_app.py`)를 새로 만들었다.
"해줘, 해줘" 두세 번이면 원하던 그림이 그대로 나왔다.
이전처럼 DART API 필드 의미를 하나하나 되짚어가며 싸울 일도 없었다 — 이미 검증된 로직을 그대로 재사용하는 작업이었으니까.
결과물
한국사이트 스크린샷
- 사이드바에서 빠른 선택(기존 종목 풀 5개) 또는 검색(기업명/종목코드 일부 입력)으로 종목을 고르는 화면
- "분석 실행" 버튼 하나로 데이터 수집(필요 시) → 분기별 실적 표 → CAR 요약 지표 → CAR 곡선/그룹 비교/산점도 차트까지 한 화면에 표시
다음 단계
이번 CLAUDE.md는 앞으로 이 프로젝트의 모든 기능(부동산 분석, 다른 종목 비교 등)에 계속 적용될 규칙이 될 것이다.
이제 이 파일을 뼈대로 앞으로 필요한 기능들을 순차적으로 추가해 나가고, 이 폴더 자체를 나만의 완성된 투자관리 프로젝트 폴더로 관리해 나가보련다.
