본문으로 건너뛰기

동호회 회비 운영을 스킬 트리로 쪼갠 기록

박태진

2026.08.04

## 1. 한 줄 요약

농구동호회 모어의 회비 운영에서 제가 매달 반복하던 일을 **하나의 큰 자동화**가 아니라 **역할이 분리된 4개의 스킬**로 쪼갰고, 각 스킬의 입력·출력·승인 경계를 명시적으로 정했습니다. 이 4개를 묶을 정식 우산(umbrella) 스킬은 **아직 만들지 않았고, 다음 산출물로 남겨둔 상태**입니다.

---

## 2. 문제: 자동화하기 전에 제가 실제로 하던 일

동호회 총무 일은 겉보기엔 단순한데, 실제로는 성격이 전혀 다른 작업 네 덩어리가 매달 섞여 돌아갑니다.

**(1) 대회 영상을 찾는 일**
연도별 참가 대회와 경기 영상이 여러 YouTube 채널에 흩어져 있습니다. 팀명 표기도 `모어`, `서울 모어`, `More`, `MORE`, `Moore`로 제각각이라 한 번의 검색으로는 잡히지 않습니다. KBA D3는 여러 팀이 들어간 날짜별 통합 라이브라서, 이걸 모어 단독 경기 영상으로 착각하면 이후 계산이 전부 틀어집니다.

**(2) 찾은 영상을 회비웹에 넣는 일**
기존 영상 분석 화면은 경기마다 `URL / 우리팀 유니폼색 / 시작 / 끝`을 한 행씩 입력해야 했습니다. 대회 하나에 경기가 여러 개면 그만큼 반복입니다.

**(3) 통장 입금과 회비 기록을 맞춰보는 일**
입금은 계좌에 찍히고, 회비 반영은 웹앱에 있습니다. 이 둘이 어긋난 건은 눈으로 훑어서 찾고 있었습니다.

**(4) 미납 공지를 만드는 일**
누가 얼마 밀렸는지 정리하고, 그걸 사람이 읽을 문장과 이미지로 다시 만드는 일입니다.

처음엔 이걸 "회비 자동화 스킬" 하나로 만들려고 했습니다. 결과적으로 그게 이번 주의 실패이자 설계의 출발점이었습니다.

---

## 3. 왜 스킬 하나로는 안 되었나

한 스킬에 다 넣으려고 하니 세 가지가 계속 걸렸습니다.

**첫째, 데이터 성격이 다릅니다.**
대회 참가 이력·영상 아카이브는 "비용이 아직 없어도 쌓아둘 가치가 있는 기록"입니다. 반면 대회비 정산은 "확정되면 돈이 움직이는 기록"입니다. 같은 테이블, 같은 스킬에 억지로 넣으면 아직 정산할 일이 없는 경기 영상을 보관할 곳이 없어집니다.

**둘째, 위험도가 다릅니다.**
영상 후보를 잘못 찾으면 제가 검수하다 걸러집니다. 하지만 입금 대조를 잘못하면 회원에게 잘못된 금액이 나갑니다. 같은 승인 규칙을 쓸 수 없습니다.

**셋째, 트리거가 다릅니다.**
영상 아카이브는 대회가 끝난 뒤 비정기로, 입금 대조와 미납 공지는 월 단위로 돕니다. 하나로 묶으면 매달 쓰지도 않을 영상 검색 규칙까지 컨텍스트에 딸려 들어옵니다.

그래서 **"한 스킬 = 한 책임 = 한 승인 경계"** 를 기준으로 쪼갰습니다.

---

## 4. 스킬 트리

```text
[제안] more-club-finance-operations          ← 우산 스킬. 아직 만들지 않음
│
├── more-tournament-video-archive            ← 대회 영상 조사·검수 아카이브
│
├── more-fee-automation                      ← 영상 기반 대회비 안분 "준비"
│
├── more-payment-reconciliation              ← 입금 ↔ 회비 기록 대조 (읽기 전용)
│
└── more-unpaid-notice                       ← 미납 요약 + 공지 초안(텍스트/이미지)

(트리 밖 · 주변 도구)
    youtube-summary-docx                     ← 자막 기반 영상 요약 문서화.
                                                회비 계통 스킬이 아님
```

최상단 `more-club-finance-operations`는 **제안 상태**입니다. 현재 저는 4개 스킬을 상황에 따라 직접 골라 부르고 있고, 이걸 자동으로 라우팅해주는 정식 스킬 파일은 존재하지 않습니다. 트리 그림에 넣은 건 목표 구조를 보여주기 위해서지, 이미 있다는 뜻이 아닙니다.

`youtube-summary-docx`는 자막이 있는 YouTube 영상을 5줄 요약·기억할 문장·활용 포인트 형태의 Word 문서로 만드는 도구입니다. 이름에 YouTube가 들어가서 영상 계통으로 오해하기 쉬운데, **경기 영상의 출전시간이나 대회비 안분에는 쓸 수 없습니다.** 자막이 없으면 내용을 지어내지 않고 그대로 멈춥니다. 그래서 회비 트리의 자식이 아니라 옆에 놓인 별개 도구로 정리했습니다.

---

## 5. 각 스킬의 역할 / 입력 / 출력 / 트리거

### 5-1. `more-tournament-video-archive`

| 항목 | 내용 |
|---|---|
| 역할 | 특정 연도에 모어가 참가한 대회와 경기 영상 후보를 찾아 **검수용 아카이브**로 정리 |
| 입력 | 연도, 팀 별칭 목록(`모어`, `서울 모어`, `More`, `MORE`, `Moore`) |
| 출력 | `대회명 \| 날짜 \| 상대팀 \| 우리팀 유니폼색 \| URL 주소` 표와 CSV 초안, 각 행의 근거 |
| 트리거 | 대회가 끝난 뒤, 또는 특정 연도 영상 이력을 채워야 할 때 (비정기) |

정한 규칙:

- 기본 출처는 농구연구소 B-LAB, 동아리농구방 BDR, KBA Live이며 부족하면 YouTube 검색으로 보완합니다.
- 유니폼색은 영상이나 신뢰할 수 있는 설명에서 확인되지 않으면 추측하지 않고 `미확인`으로 씁니다.
- KBA D3는 날짜별 통합 라이브 URL과 **모어 경기 시작·끝 시각을 따로** 관리합니다.
- 농구연구소의 `디비전3`은 KBA D3와 다른 대회로 취급합니다. 이름이 비슷해서 실제로 헷갈렸던 부분입니다.
- 결과물은 기본적으로 검수용 표·CSV 초안이고, 명시적 승인 없이 회비웹 DB에 저장하지 않습니다.

### 5-2. `more-fee-automation`

| 항목 | 내용 |
|---|---|
| 역할 | 영상 분석 결과를 바탕으로 대회비 안분안과 월 회비 공지 초안을 **준비**. 확정은 하지 않음 |
| 입력 | 총비용, 지원금, 경기별 회원 출전시간, 제외·면제 대상 |
| 출력 | 회원별 청구액 초안, 검수 대상 목록, `clubTopUp` 금액 |
| 트리거 | 대회 영상 분석이 끝나고 대회비를 나눠야 할 때 |

계산 규칙:

- 실부담 = 총비용 − 지원금
- 여러 경기의 출전시간은 회원별로 합산합니다.
- 개인 청구액은 천 원 단위 버림입니다.
- 버림 차액과 면제·제외로 생긴 차액은 `clubTopUp`(회비 부담)으로 흡수합니다. 즉 **개인 청구액 합계 + clubTopUp = 실부담**이 항상 성립해야 합니다.
- 등번호 매핑 실패, 낮은 분석 신뢰도, 출전 0초, 제외·면제는 자동 처리하지 않고 검수 대상으로 분리합니다.

이 스킬의 이름에 automation이 들어가지만, 실제로 하는 일은 **계산과 분류까지**입니다. DB 반영, 공지 전송, 로그인은 제가 명시적으로 승인하기 전에는 실행되지 않습니다.

### 5-3. `more-payment-reconciliation`

| 항목 | 내용 |
|---|---|
| 역할 | 통장 입금 내역과 회비 기록을 대조해 **어긋난 건을 찾아냄**. 읽기 전용 |
| 입력 | 기간(연도), 입금 내역, 회비 기록 |
| 출력 | 미반영 후보·부족 후보 목록과 각 건의 판단 근거 |
| 트리거 | 월 마감, 또는 연 단위 점검 |

이 스킬은 **쓰기 동작을 아예 갖고 있지 않습니다.** 승인하면 쓰겠다는 뜻이 아니라, 이 스킬로는 DB를 못 고칩니다. 대조 결과는 목록으로만 나오고, 실제 수정은 제가 회비웹 화면에서 직접 합니다. 회계 대조에서 "찾는 것"과 "고치는 것"을 같은 도구에 넣으면 잘못 찾은 걸 그대로 반영해버릴 위험이 있어서 그렇게 했습니다.

### 5-4. `more-unpaid-notice`

| 항목 | 내용 |
|---|---|
| 역할 | 미납 현황을 요약하고, 공지용 텍스트와 이미지 **초안**을 만듦 |
| 입력 | 기준 시점, 미납 집계 결과 |
| 출력 | 미납 요약, 공지 문안 초안, 공지 이미지 초안 |
| 트리거 | 월 공지 시점 |

공지는 **초안까지만** 만듭니다. 어디에도 자동으로 보내지 않습니다. 제가 내용을 읽고, 필요하면 고치고, 직접 복사해서 올립니다.

---

## 6. 실행 순서

두 갈래가 따로 돕니다. 하나로 합치지 않은 게 이번 설계의 핵심입니다.

**갈래 A — 대회비 (비정기)**

```text
1. more-tournament-video-archive
   YouTube 채널·검색 → 대회별 영상 후보 + 근거 수집
        ↓
2. 사람 검수
   대회 구분, 유니폼색, KBA D3 통합 라이브 구간 확인
        ↓
3. 회비웹: 영상 목록 일괄 붙여넣기 (TSV)
   대회 하나를 열고 여러 경기 행을 한 번에 생성
        ↓
4. 회비웹: 영상 분석
        ↓
5. 사람 검수
   등번호 매핑, 출전시간, 신뢰도 확인
        ↓
6. more-fee-automation
   실부담 계산 → 회원별 청구액 초안 + clubTopUp + 검수 대상 분리
        ↓
7. 사람 승인 → 회비웹에서 대회비 반영
```

**갈래 B — 월 회비 (월 단위)**

```text
1. more-payment-reconciliation
   입금 내역 ↔ 회비 기록 대조 (읽기 전용) → 미반영·부족 후보 목록
        ↓
2. 사람 검수 및 수정
   회비웹 화면에서 직접 반영
        ↓
3. more-unpaid-notice
   미납 요약 + 공지 텍스트·이미지 초안
        ↓
4. 사람이 읽고 수정 후 직접 게시
```

두 갈래 모두 **마지막 단계는 사람**입니다. 예외 없습니다.

---

## 7. 구현한 것: TSV 일괄 붙여넣기

갈래 A의 3단계는 스킬이 아니라 웹앱 기능으로 만들었습니다. 이유가 있습니다.

처음엔 아카이브 스킬이 링크 목록을 뱉어주면 될 거라고 생각했습니다. 그런데 막상 써보니 제가 URL을 하나씩 드래그해서 복사하고, 유니폼색을 다시 입력하고 있었습니다. 링크 목록은 **읽기에는 좋지만 입력에는 최악의 형식**이었습니다.

그래서 출력 형식을 웹 입력폼이 바로 먹을 수 있는 TSV로 바꾸고, 회비웹 쪽에 그걸 받는 입구를 만들었습니다. 관리자 대회비의 영상 분석 패널에 `목록 붙여넣기` UI를 추가했고, 대회 하나를 열어 아래 블록을 통째로 붙여넣습니다.

```tsv
URL	우리팀 유니폼색	시작	끝
https://www.youtube.com/watch?v=sUGRhJRhrcA	남색		
https://www.youtube.com/watch?v=nyLI70LE8Xg	흰색		
https://www.youtube.com/watch?v=6rirVPGI41Q	흰색		
```

동작:

- 한 줄당 한 경기 행을 만듭니다.
- 헤더와 빈 줄은 무시합니다.
- YouTube URL 형식과 `H:MM:SS` 또는 `M:SS` 시간 형식을 검사합니다.
- 이미 입력된 URL, 그리고 붙여넣기 안에서 중복된 URL은 추가하지 않습니다.
- 시작·끝이 비어 있으면 기존 흐름대로 영상 전체 분석을 뜻합니다.
- **붙여넣기만으로는 저장도, 분석 실행도, 대회비 반영도 하지 않습니다.**

관련 코드:

- `app/(dashboard)/admin/fee-events/video-analysis-panel.tsx`
- `lib/video-bulk-import.ts`
- `lib/video-bulk-import.test.ts`

---

## 8. Code as Gate / Eval — 모델이 판단해도, 통과는 코드가 정한다

스킬을 쪼개면서 같이 정한 규칙입니다. 모델 출력이 다음 단계로 넘어가려면 **코드가 검사해서 통과시켜야 합니다.** 프롬프트에 "정확하게 해줘"라고 쓰는 건 게이트가 아닙니다.

### Gate (통과 조건 — 코드가 판정)

| 지점 | 게이트 | 실패 시 |
|---|---|---|
| TSV 붙여넣기 | YouTube URL 형식 검사 | 해당 행 버림 |
| TSV 붙여넣기 | `H:MM:SS` / `M:SS` 시간 형식 검사 | 시간값만 거부, 유효한 URL은 살림 |
| TSV 붙여넣기 | 기존 URL·붙여넣기 내 중복 검사 | 행 추가 안 함 |
| 대회비 안분 | 개인 청구액 합계 + `clubTopUp` = 실부담 | 안분안 자체가 성립 안 함 |
| 대회비 안분 | 매핑 실패·낮은 신뢰도·출전 0초·면제 | 자동 처리 금지, 검수 큐로 분리 |
| 입금 대조 | 쓰기 동작 미보유 | 애초에 DB 반영 불가 |
| 유니폼색 | 근거 없으면 `미확인` | 추측값 기입 금지 |

시간 형식 게이트는 특히 신경 썼습니다. 잘못된 시간값 하나 때문에 멀쩡한 URL까지 통째로 버려지면, 사람이 뭐가 빠졌는지 모릅니다. 그래서 **시간값만 거부하고 URL은 살리도록** 설계했고, 그 동작을 테스트로 고정했습니다.

### Eval (반복 검증)

- `lib/video-bulk-import.test.ts` — `parseBulkVideos`에 대해 3개 케이스를 고정했습니다.
  1. 탭 구분 `URL / 유니폼색 / 시작 / 끝` 파싱
  2. 헤더·빈 줄·잘못된 URL·이미 존재하는 URL 건너뛰기
  3. 잘못된 시간값을 거부하되 유효한 URL은 버리지 않기
- 2026-07-25 기준 전체 Vitest: **5개 파일, 72개 테스트 통과**
- 2026-07-25 기준 `next build` **성공** (프로덕션 빌드)
- 전체 ESLint는 기존 파일들의 오류로 실패했습니다. 다만 새로 추가한 일괄 붙여넣기 파일들은 그 오류 목록에 없었습니다. 이건 통과가 아니라 **아직 정리 안 된 부채**로 적어둡니다.

### 운영 실측 (2026년 대조)

2026년 입금 대조를 `more-payment-reconciliation`으로 한 번 돌렸을 때:

- 읽은 입금 건수: **66건**
- 눈에 보이는 미반영·부족 후보로 식별된 건수: **14건**

이 66/14는 스킬이 실제 데이터에서 돌아갔다는 기록이자, 앞으로 회귀 여부를 볼 기준선입니다. 다만 14건은 **후보**입니다. 확정된 오류 건수가 아니고, 각 건은 제가 회비웹에서 직접 확인해야 합니다. 그리고 스킬은 이 중 어느 것도 자동으로 고치지 않았습니다.

> 이 문서에는 회원 이름, 금액, 은행 정보, 개별 회비 내역을 일절 싣지 않습니다. 건수만으로도 스킬이 돌았다는 증거는 충분합니다.

---

## 9. 승인 경계

명시적 승인 없이는 절대 실행하지 않는 것들입니다.

- 회비웹 DB 반영 (대회비 확정, 회비 기록 수정)
- 공지 전송·게시
- 로그인이 필요한 동작
- 아카이브 결과의 DB 저장

스킬이 만드는 건 전부 **초안**입니다. 표, CSV, 계산안, 대조 목록, 공지 문안. 이걸 실제 상태로 바꾸는 동작은 제가 화면에서 직접 합니다.

이렇게 나눈 이유는 단순합니다. 영상 분석이 등번호를 잘못 읽으면 누군가 안 낸 돈을 내게 되거나, 낸 돈을 또 내게 됩니다. 그건 되돌리는 비용이 자동화로 아낀 시간보다 훨씬 큽니다.

---

## 10. 아직 만들지 않은 것 (솔직하게)

사례글에서 이 부분을 빼면 나머지가 다 과장으로 읽힙니다.

**만들지 않은 것:**

- **정식 우산 스킬 `more-club-finance-operations`** — 없습니다. 지금은 제가 상황 보고 4개 중 하나를 직접 부릅니다.
- **대회·경기영상 아카이브 전용 화면** — 대회 참가 이력과 URL을 대회비 이벤트와 분리해 보관할 화면이 없습니다. 지금은 비용이 없는 경기 영상을 쌓아둘 곳이 마땅치 않습니다.
- **아카이브 → 분석 화면 자동 전달** — 아카이브에서 고른 경기를 TSV로 자동 생성하거나 분석 화면으로 바로 넘기는 연결이 없습니다. TSV는 아직 제가 옮깁니다.
- **영상 분석 검수 보조** — 첫 경기 등번호 매핑을 다음 경기로 복사하기, 유니폼색별 매핑 템플릿, 낮은 신뢰도·미매핑·출전시간 급변만 강조하기, KBA D3 통합 라이브의 지정 구간만 분석하기. 전부 아이디어 단계입니다.
- **주기적 영상 후보 수집** — 정기적으로 새 후보만 모아 보고하는 흐름이 없습니다.

**하지 않은 주장:**

- 프로덕션 배포 완료라고 쓰지 않습니다. 로컬 프로덕션 빌드가 성공했다는 것과 배포됐다는 건 다른 얘기고, 배포 상태는 이 문서 기준으로 확인하지 않았습니다.
- 자동 청구, 자동 DB 반영은 하지 않습니다. 만들다 만 게 아니라 **일부러 안 만든** 것입니다.
- 영상 분석 결과가 정확하다고 말하지 않습니다. 그래서 검수 단계가 있습니다.
- 메신저 연동은 검토도 구현도 계획도 없습니다. 공지는 제가 복사해서 올립니다.

---

## 11. 이번 주에 배운 것

**하나의 큰 스킬보다 경계가 분명한 작은 스킬 4개가 낫습니다.** 쪼개니까 각 스킬이 "무엇을 받아서 무엇을 내놓는지"를 한 문장으로 쓸 수 있게 됐고, 그게 안 써지는 스킬은 아직 설계가 덜 된 스킬이라는 신호였습니다.

**출력 형식이 사람의 다음 동작을 결정합니다.** 같은 정보라도 링크 목록으로 주면 사람이 드래그하고, TSV로 주면 붙여넣습니다. 스킬 품질을 올리는 것보다 출력 형식을 바꾸는 게 병목을 더 크게 줄였습니다.

**게이트는 프롬프트가 아니라 코드로 써야 합니다.** "중복 URL은 넣지 마"라고 지시하는 것과, 중복이면 행을 만들지 않는 코드에 테스트를 붙여두는 건 다릅니다. 후자만 다음 달에도 똑같이 동작합니다.

**위험도가 다른 작업은 승인 경계도 달라야 합니다.** 영상 후보 조사와 입금 대조를 같은 규칙으로 다루면, 둘 중 하나는 과하게 막히거나 위험하게 열립니다.

---

## 12. 다음 단계

다음 산출물은 **정식 우산 스킬 `more-club-finance-operations`** 입니다.

지금 트리 최상단에 그려둔 그 노드를 실제 스킬 파일로 만드는 작업입니다. 상황을 보고 4개 자식 스킬 중 어느 것을 부를지 라우팅하고, 공통 승인 경계(DB 반영·공지 전송·로그인 금지)와 개인정보 취급 규칙을 한 곳에서 관리하는 게 목적입니다.
3

함께 이야기해요 3

로그인하고 댓글을 남겨 주세요

Giacomo 프로필 이미지
Giacomo2026.08.06

박태진님, 영상 후보 조사부터 대회비 안분, 입금 대조, 미납 공지까지를 ‘회비 자동화’ 하나에 넣지 않고 실제 운영의 두 갈래로 다시 나눈 과정이 아주 선명했어요. 특히 우산 스킬은 아직 제안 상태이고 네 자식 스킬을 직접 골라 부르고 있다는 점, TSV 전달도 아직 사람이 맡는다는 점을 결과와 계획에서 분리해 적어 주셔서 현재 완성 범위를 과장 없이 이해할 수 있었습니다.

구조를 쪼갠 뒤 웹앱의 입력 병목까지 발견한 흐름도 좋았습니다. 링크 목록을 더 잘 만드는 대신 출력 형식을 TSV로 바꾸고, 헤더·빈 줄·잘못된 URL·중복 URL·시간 형식을 코드로 검사하게 만든 건 ‘스킬의 설명’이 실제 다음 동작과 맞물려야 한다는 사례로 읽혔어요. 글에 남긴 실행 기록에서는 5개 테스트 파일의 72개 테스트와 로컬 프로덕션 빌드가 통과했고, 전체 ESLint 실패는 기존 부채로 따로 남겼습니다. 배포 상태와 영상 분석 정확도는 확인하지 않았다고 선을 그은 점도 결과·부채·미검증을 정확히 나눠 줍니다.

또 2026년 입금 66건에서 14건을 ‘오류’가 아니라 검수 후보로만 분류하고 스킬에는 쓰기 권한 자체를 두지 않은 기록은, 자동화율보다 오판 비용을 먼저 계산한 운영 판단을 보여줘요. 발견과 수정, 초안과 게시, 계산과 확정을 서로 다른 인터페이스로 막아 둔 것이 이 설계에서 다른 운영에도 옮겨 갈 수 있는 부분이라고 느꼈습니다.

정식 우산 스킬을 만들 때 첫 검증 장면은 거창한 통합 실행보다 네 종류의 대표 요청을 하나씩 넣어 ‘어느 자식만 선택됐는지’와 ‘DB 반영·공지 전송·로그인이 끝까지 금지됐는지’를 함께 읽어보는 정도면 충분해 보여요. 성공 기준도 모든 일을 자동화했는지가 아니라, 올바른 갈래를 고르고 사람 승인 앞에서 멈춘 기록이 남는지로 잡을 수 있겠습니다.

동호회 총무의 반복 업무를 책임·입출력·트리거·승인 경계로 풀어내고, 실제 72개 테스트와 대조 기록뿐 아니라 아직 없는 우산 스킬과 배포 미확인 상태까지 함께 공개해 주신 태도가 정말 단단했어요. 자동화가 어디까지 갔는지보다 어디서 멈춰야 하는지를 다른 운영자도 판단할 수 있게 만든 기록입니다.

자연어회계처리 프로필 이미지

영상 검수와 입금 대조의 위험도 차이를 다르게 보고 승인 규칙을 분리요거 너무좋은데요

자연어회계처리 프로필 이미지

태진님 마크다운 ㅠㅠㅠ

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기