비개발자 PM이 Claude Code로 정산 봇 설계도를 만들었다 : 내용보다 구조가 먼저다 (1주_과제1)
## 📝 한줄 요약
매달 수작업으로 하던 분납 정산을 자동화하기 위해, 데이터보다 봇의 뼈대를 먼저 만들었다.
**바쁘시면 이것만 읽어도 돼요:**
- Claude Code로 정산 자동화 봇의 설계도(SOUL.md / AGENTS.md / MEMORY.md) 3파일 완성
- "내용 없이 설계도 먼저" — 실제 데이터 없이도 봇이 막히는 지점을 정확히 짚어냄
- 봇 파일을 3개로 나눴더니 "이 봇은 누구인가 / 어떻게 일하는가 / 뭘 기억하는가"가 명확히 분리됨
- Human Gate 3개로 "사람이 언제 개입해야 하는가"를 설계에 박아 넣음
- 봇 vs 에이전트, 어느 게 더 위력적인가 — 아직 탐색 중 (슬랙 연동 자가개선 루프 도전 예정)
---
## 🎯 이런 분들께 도움돼요
- 반복 업무를 AI로 자동화하고 싶은데 어디서 시작할지 모르는 비개발자 PM
- 봇을 만들고 싶은데 "설정 파일을 어떻게 써야 하는지" 막막한 분
- Claude Code를 써봤는데 단순 질답 말고 더 쓸 수 있는 방법이 궁금한 분
---
## 😫 문제 상황 (Before)
매달 같은 일이 반복됐다.
라이브클래스에서 분납 수강생들의 이번 달 결제 여부를 확인하고, 안 낸 분들한테 안내 메시지를 보내고, 정산 시트를 업데이트하는 일. 수강생이 몇 명 없을 땐 그냥 했다. 그런데 기수가 쌓이고 수강생이 늘어나면서 엑셀 파일과 원장 시트를 번갈아 열고 이름과 금액을 하나하나 대조하는 작업이 버거워졌다.
실수도 생겼다. 금액이 비슷한 사람을 헷갈리거나, 이미 낸 사람한테 미납 메시지가 가거나. 미납자 메시지도 매달 손으로 직접 썼는데, 내용은 거의 같은데 사람마다 금액이나 회차가 달라서 복붙도 쉽지 않았다.
더 이상 미룰 수 없다고 느낀 건 세 가지가 한꺼번에 겹쳤을 때였다. 수작업 실수, 반복 메시지 작성, 그리고 수강생 수 증가. 이걸 자동화하지 않으면 매달 같은 자리에서 같은 실수를 반복할 것 같았다.
---
## 🛠️ 사용한 도구
- **도구**: Claude Code (Hermes CLI 포함)
- **모델**: Claude Sonnet 4.6
- **특이사항**: Hermes CLI와 Claude Code CLI가 같은 프로젝트 폴더를 공유하는 구조
---
## 🔧 작업 과정
### 먼저 시스템 전체 흐름을 잡았다
자동화를 시작하기 전에, 이 작업이 어떤 순서로 돌아가야 하는지부터 정리했다.
```
데이터 수집 → 분납 대상자 추출 → 결제 대사 → 메시지 초안 생성 → 발송 → 정산 시트 생성
```
그런데 이 흐름 중에 사람이 직접 확인해야 하는 지점이 분명히 있었다. 계좌이체 입금은 봇이 알 수 없고, 금액 불일치 케이스는 내가 판단해야 하고, 미납자 메시지는 발송 전에 내가 검토해야 한다.
그래서 흐름 안에 **Human Gate 3개**를 박아 넣었다. 봇이 알아서 다 해주는 구조가 아니라, "여기까지 하고 사람한테 확인받고, 그다음 진행"하는 구조로.
```
데이터 수집
↓
🔴 Gate 1: 세금계산서 입금 수동 확인
↓
분납 대상자 추출 → 결제 대사
↓
🔴 Gate 2: 예외 케이스 PM 판단
↓
메시지 초안 생성
↓
🔴 Gate 3: 발송 전 최종 승인
↓
발송 + 정산 시트 생성
```
---
### 설계도를 먼저 만들었다 — 내용 없이
가장 신기했던 부분이 여기였다.
봇에게 실제 데이터를 주기 전에, **이 봇이 어떻게 생각하고 어떻게 일해야 하는지를 파일로 먼저 작성**했다. 마치 건물을 짓기 전에 도면을 그리는 것처럼. 내용물은 없는데 구조부터 잡는 작업이었다.
과제에서 주어진 질문들을 따라가면서 자연스럽게 파일 3개가 나왔다.
```
이 봇은 누구인가? → SOUL.md
이 봇은 어떻게 일하는가? → AGENTS.md
이 봇은 뭘 기억해야 하는가? → MEMORY.md
```
파일을 3개로 나누고 나니, 각 파일의 역할이 명확해졌다.
**SOUL.md**에는 봇의 정체성과 말투만 담았다.
```
이 봇의 이름은 "Nova의 정산 파트너"다.
숫자와 사실 위주로 보고한다. 해석은 PM이 한다.
추측으로 판단하지 않는다. 데이터에 없으면 없다고 한다.
```
**AGENTS.md**에는 업무 절차와 도구 사용 규칙만 담았다.
```
PHASE 1. 데이터 수집 → 🔴 Gate 1 → PHASE 2. 대상자 추출 → ...
예외 케이스 분류 기준: 연락처 일치 + 금액 일치 → 납부완료 / 불일치 → 예외
원장 시트는 읽기 전용. 수정 도구 호출 금지.
```
**MEMORY.md**에는 봇이 매번 물어보지 않아도 되는 것들을 담았다.
```
데이터 소스 위치, 반복되는 예외 패턴, 절대 규칙 요약
```
이렇게 나누고 나니, 나중에 봇이 이상하게 행동할 때 어느 파일을 고쳐야 할지도 명확해졌다. 말투가 이상하면 SOUL.md, 절차가 잘못되면 AGENTS.md, 판단 기준이 틀리면 MEMORY.md.
---
### 실제로 테스트했다 — 데이터 없이도 동작을 확인할 수 있었다
설계도를 완성하고 Hermes CLI에서 한 줄만 입력했다.
```
이번달 정산하자
```
봇은 이렇게 답했다.
> data/input 폴더에 .xlsx 파일이 없습니다. config.json이 없습니다. 구글 드라이브 인증이 되어 있지 않습니다. PHASE 1 데이터 수집 불가 상태입니다. 다음을 준비해주세요: (1) 매출 파일 추가 (2) config.json 생성 (3) 구글 인증 연결
데이터가 하나도 없는 상황에서 봇이 헤매지 않고 정확하게 "뭐가 없어서 못 진행한다"고 짚어냈다. 추측하거나 임의로 넘어가지 않았다. AGENTS.md에서 정의한 흐름을 그대로 따른 결과였다.
---
### 헷갈렸던 것: Hermes CLI vs Claude Code, 어디서 접근해야 하나
처음에 두 도구가 같은 폴더를 공유한다는 건 알았는데, 봇을 실행할 때 어느 쪽을 써야 하는지 헷갈렸다.
결론은 둘 다 써도 된다. SOUL.md, AGENTS.md, MEMORY.md는 프로젝트 폴더 안의 파일이고, 어떤 도구로 접근해도 같은 파일을 읽는다. Hermes CLI는 페르소나 파일을 더 명시적으로 불러오는 방식이고, Claude Code는 CLAUDE.md를 기반으로 동작한다는 차이 정도다.
---
## ✅ 결과 (After)
### Before vs After
| 항목 | Before | After (예상) |
| -------------- | ----------------------- | -------------------------- |
| 분납 대사 방식 | 엑셀 + 원장 수작업 비교 | 자동 대사 → 예외만 확인 |
| 미납자 메시지 | 매달 직접 작성 | 초안 자동 생성 → 검토만 |
| 실수 위험 | 누락·금액 오류 가능 | 정수 처리 + 예외 자동 분류 |
| 사람 개입 시점 | 전 과정 수동 | Gate 3개에서만 |
### 결과물
- `SOUL.md` / `AGENTS.md` / `MEMORY.md` — 정산 봇 설계도 3파일
- Human Gate 3개가 포함된 자동화 흐름 설계
- 데이터 없이도 동작 검증 완료
---
## 💬 이 과정에서 배운 AI 활용 팁
### 효과적이었던 것
1. **내용보다 구조 먼저** — 실제 데이터가 없어도 봇의 동작 방식을 설계할 수 있다. 도면 없이 건물부터 올리면 나중에 뜯어야 한다.
2. **파일을 역할별로 분리** — SOUL.md(누구인가), AGENTS.md(어떻게 일하나), MEMORY.md(뭘 기억하나)로 나누면 나중에 고칠 때 어디를 봐야 할지가 명확하다.
3. **Human Gate를 설계에 박기** — "봇이 알아서 다 하면 좋겠다"는 욕심보다, 사람이 꼭 확인해야 하는 지점을 미리 정해두는 게 더 안전하고 실용적이다.
### 이렇게 하면 안 돼요
1. **SOUL.md에 업무 절차 다 넣기** — 봇의 성격과 일하는 방법은 다른 파일에 있어야 나중에 수정이 편하다.
2. **데이터 없이 완성됐다고 착각하기** — 설계도가 완성된 것이지, 자동화가 완성된 건 아니다. 실제 데이터 연동은 별도 작업이다.
---
## 🌍 다른 업무에 적용한다면?
이 구조는 정산 말고도 비슷한 반복 업무에 그대로 쓸 수 있다.
- **채용 스크리닝**: 지원자 데이터 대사 → 합격/보류/탈락 분류 → 안내 메시지 초안 생성
- **고객 응대 정리**: 문의 내역 분류 → 유형별 초안 생성 → 담당자 검토 후 발송
- **리포트 자동화**: 데이터 수집 → 요약 생성 → 사람이 검토 후 공유
공통점은 **반복 + 분류 + 메시지 생성** 패턴이 있는 업무라는 것. 이런 업무라면 같은 방식으로 설계도를 먼저 만들어볼 수 있다.
---
## 🚀 앞으로의 계획
1. **실제 데이터 연동**: 매출 엑셀 파일 + 구글 원장 시트 연결해서 실제 정산 한 사이클 돌려보기
2. **슬랙 연동 자가개선 루프**: Human Gate를 슬랙 메시지로 받고, 피드백이 쌓이면 봇이 반영하는 구조 실험
3. **봇 vs 에이전트 경계 탐색**: 지금 구조는 오케스트레이터 + 서브에이전트 병렬/선형 파이프라인인데, 봇 페르소나가 어느 지점에서 진짜 위력을 발휘하는지 — 아직 탐색 중이다.
---
## 📋 재사용 가능한 프롬프트
### 프롬프트 1: 봇 설계도 파일 3종 한번에 만들기
> 내 업무를 자동화하는 봇을 위한 파일 3개를 만들어줘.
>
> 업무 설명: [여기에 반복하는 업무를 편하게 설명]
>
> SOUL.md에는: 봇 이름과 한 줄 정체성, 말투와 어조, 절대 하지 않는 것
> AGENTS.md에는: 처리 절차, 사용 도구, 응답 형식, 사람이 꼭 확인할 지점
> MEMORY.md에는: 데이터 소스 위치, 판단 기준, 반복되는 예외 패턴
>
> SOUL.md에 업무 절차 넣지 말고, AGENTS.md에 성격 설명 넣지 마.
### 프롬프트 2: Human Gate 설계하기
> 내 업무 흐름에서 사람이 꼭 확인해야 하는 지점을 찾아줘.
>
> 업무 흐름: [단계 나열]
>
> Human Gate 기준:
>
> - 봇이 판단할 수 없는 것 (외부 정보 필요)
> - 실수가 생기면 되돌리기 어려운 것
> - 최종 책임이 사람한테 있는 것
>
> Gate마다 PM이 해야 할 행동과 완료 신호를 같이 정의해줘.
