한 줄 요약
만들기에만 집중하던 보이스다이어리를 다시 돌아보며, 아키텍처 리뷰 → 3레이어 리팩토링 → 테스트 안전망 추가 → AI 비용 최적화까지 한 번에 정리하고 적용해본 경험입니다.
요약
처음에는 기능이 돌아가는 것이 가장 중요해서 빠르게 붙여 만들어지는 것 자체에 보람을 크게 느꼈습니다. 그런데 최수민님의 <클린코드로 바이브코딩하기> 강연을 듣고, 만들면서 느꼈던 개발 개념이 전혀 없다.. 라는 결핍에 대한 인지를 크게 체감하였습니다. 그래서 최수민님이 소개해준 아래 깃헙을 참고하여, Existing-code-review의 프롬프트를 실행해보았습니다.
수민님 깃헙 링크 👉 https://github.com/greatSumini/gpters-lecture-260323
server.py, bot.py, sheets.py에 역할이 섞이고, 같은 파이프라인 로직이 여러 곳에 중복되어 있다는 점이 점점 크게 보이기 시작했습니다. 특히 “분류 → 저장 → 리뷰” 흐름이 웹과 텔레그램에 각각 따로 들어가 있었고, 테스트도 전혀 없어서 수정할 때마다 왜 계속 버그가 생기는가 라는 것에 대한 답이 아닌가 싶었습니다.
또한 TRD.md 파일도 하나 만들고, 코드 리뷰와 3레이어 구조로 만들어달라고 요청했습니다.
음성 일기 기술 참조 문서 trdb
그래서 이번에는 단순 기능 추가보다 구조를 다시 리뷰하고, CLAUDE.md도 실제 협업과 유지보수에 맞게 튜닝했습니다. 그 과정에서 3레이어 구조(Presentation / Logic / Data-Adapter), 클린 코드, 서비스 계층 분리, 테스트 피라미드 관점의 안전망, 변경 전 호출자 전수 확인 습관 같은 것들을 새롭게 배우고 실제 코드에 반영했습니다.
리팩토링의 핵심은 흩어져 있던 비즈니스 로직을 services/diary_service.py로 모으는 것이었습니다. 그 결과, 플랫한 파일 구조를 역할 중심 구조로 바꾸고, server.py는 앱 생성과 라우트 등록만 담당하도록 가볍게 만들 수 있었습니다. bot.py도 메시지 입출력만 담당하도록 얇아졌고, sheets.py에서는 데이터 접근만 남기도록 정리했습니다. 또 OpenAI 클라이언트가 여러 파일에서 중복 생성되던 부분도 한곳으로 모아 관리 포인트를 줄였습니다.
비용 측면에서도 꽤 큰 인사이트가 있었습니다. 기존에는 기록이 저장될 때마다 Claude Opus가 리뷰를 생성해서, 좋은 품질 대신 비용이 과하게 커지는 구조였습니다. 전체 운영비의 대부분이 여기서 발생했고, 결국 “매 입력마다 리뷰”가 아니라 하루 1회 종합 리뷰로 바꾸는 방향이 훨씬 합리적이라는 결론에 도달했습니다. 입력 직후의 짧은 피드백은 GPT-4o-mini로도 충분했고, 진짜 품질이 중요한 일일 종합 리뷰만 Opus에 맡기면 비용을 크게 줄이면서도 체감 품질을 유지할 수 있었습니다.
한국어 텍스트가 있는 검은 화면
검정색 배경에 한국어 텍스트가 있는 검정색 화면
여기서 끝이 아니라, 버그를 매 번 겪고 나서는 '이 일이 왜 일어났는지 분석하고, 재발방지 안을 제안해줘' 라고 클로드에게 말하자,
클로드코드가 알아서 제보 → 호출자 전수 검색 → 테스트 수행 루프를 작업 습관으로 추가했습니다. (클로드코드가)CLAUDE.md에는 AI 함수나 엔드포인트를 바꾸기 전에 관련 호출자를 모두 grep으로 확인하라는 규칙도 넣었습니다. 백엔드 변경 시 프론트엔드 fetch 호출까지 같이 보게 만든 것도 꽤 컸습니다. 예전에는 “수정했다”에서 끝났다면, 이제는 “영향 범위를 확인했고, 테스트로 다시 검증했다”까지 가게 된 셈입니다.
돌아보면 이번 작업은 개발이라는 과정에 대해 개념을 탑재하는 과정에 가까왔습니다. 단순히 이거 만들어줘~ 저거 만들어줘~에 이어서,
아키텍처를 나누는 이유, 테스트가 왜 안전망인지, 비용은 왜 기능만큼 중요한 설계 요소인지 몸으로 배운 시간이었습니다. 그리고 무엇보다, 좋은 구조는 처음부터 완벽하게 만드는 것이 아니라, 실제 운영 중에 아픈 지점을 발견하고 하나씩 개선해가는 과정이라는 걸 많이 느꼈습니다.
핵심 포인트만 뽑으면
기능 구현 중심이던 프로젝트를 아키텍처 중심으로 다시 점검했다.
플랫 구조를 3레이어 구조로 정리해 책임을 분리했다.
중복된 파이프라인 로직을 서비스 계층으로 통합했다.
테스트가 없던 상태에서 리팩토링 안전망의 필요성을 체감했다.
AI 리뷰 호출 방식을 바꿔 운영비를 큰 폭으로 줄일 수 있는 구조를 설계했다.
버그 대응 과정에서 호출자 전수 확인 + 테스트 루프를 개발 습관으로 추가했다.
진행 방법
수민님 깃헙 링크 👉 https://github.com/greatSumini/gpters-lecture-260323
CLAUDE.md에 역할 부여
TRD 작성 프롬프트 추가
existing-code-review 프롬프트 활용
/bkit의 /pdca team <feature> 활용
결과와 배운 점
개발 개념 일부 탑재
클로드코드 작업을 대기하는 기다림 해결 방법 깨달음
병렬 진행 : 터미널을 여러개 띄워서 병렬로 진행하면 대기시간 없이 빠르게 할 수 있다는 걸 배움
git 커밋도 해달라고 claude.md에 넣어두니 알아서 깃 푸시 커밋 다 해줌
앞으로 개발 개념을 위해 추천받은 책을 읽어봐야겠다.
이후 계획
옵시디언으로 PKM, PCM 하는데 관심이 많아져서, 노트를 이전하고 옵시디언에서 쓰다보니,
구글시트+보이스다이어리와 옵시디언을 각각 어떻게 활용하고 통합하고 싱크하고 AI에게 어떻게 feeding할지 검토중입니다.
이 부분은 다음 사례로... 총총총
