규칙은 이미 20KB짜리 문서에 다 있었는데, 왜 매번 다시 설명하고 있었나
2026.07.27
한 줄 요약
가계부 입력 규칙을 문서로 정리해뒀는데도 매번 다시 설명하게 되는 이유를 찾아보니, 문서가 부족한 게 아니라 "아는 것(Context)"만 있고 "일하는 순서(Skill)"가 없었기 때문이었습니다. 첫 Skill을 만들어 한 번 돌려봤고, 제가 쓴 중복 검사 규칙이 오히려 중복을 만드는 걸 발견해 한 곳을 고쳤습니다.
시작 전 상태
은행·카드 내역을 복식부기 가계부에 입력하는 일을 반복하고 있습니다. 계정과목 매핑 규칙은 이미 20KB짜리 문서로 정리해뒀고, 프로젝트 설정 파일에 "작업 전 반드시 이 문서를 먼저 읽을 것"이라고 지시까지 걸어뒀습니다.
그런데도 매번 같은 설명을 반복하고 있었습니다. 규칙을 안 적어서 그런 줄 알았는데, 적어도 그대로였습니다.
입력과 맥락
사용 자료: 개인 가계부 규칙 문서(20KB, 285줄), 카드 이용대금명세서
실행 검증에는 합성 데이터 7건을 사용했습니다. 실제 명세서에는 계좌번호·실명이 있어 공개 글에 실을 수 없어서입니다.
이 글의 경로·금액 일부는 익명화했습니다.
내가 직접 내린 판단
1. 첫 Skill의 범위를 좁게 잡았다.
"파일 하나 통째로 처리"와 "명세서 1건 입력" 중 후자를 골랐습니다. 이번 주 목표가 완벽한 자동화가 아니라 한 번 실행하고 관찰하기라서, 완료 기준이 선명한 쪽이 실패를 더 빨리 보여줄 거라고 봤습니다. 트레이드오프로 실제 통증이 가장 큰 "파일 통째" 케이스는 다음으로 미뤘습니다.
2. Skill을 전역이 아니라 프로젝트에 뒀다.
이 작업은 한 워크스페이스에서만 하고 기초자료도 거기 있어서, 전역에 두면 다른 프로젝트에서 라우팅 노이즈만 될 거라고 판단했습니다.
3. 문서를 먼저 정리하지 않고 Skill부터 만들었다.
"문서 쪼개기부터"라는 선택지도 있었지만, 진단이 어차피 수리 후보를 뽑아주므로 순서를 뒤집었습니다.
만든 것 또는 해본 것
진단 1 — 지금 세션에 뭐가 실제로 로딩돼 있나
파일 목록을 세는 대신, 현재 세션에 실제로 조립된 프롬프트를 읽어 13개 출처를 tier별로 분류했습니다. 여기서 비대칭이 보였습니다.
어디에 있나 | 언제 있나 | |
가계부 도구(MCP) | stable 층 | 항상 |
가계부 규칙(매핑·절차) | 어디에도 안 실림 | 누가 읽어와야만 |
설정 파일은 규칙 문서를 가리키기만 했습니다. 포인터는 Context지 Skill이 아닙니다. 에이전트는 "무엇을 아는지"는 받지만 "어떤 순서로 일하고 언제 끝난 걸로 치는지"는 못 받고 있었고, 매번 제가 그 빈칸을 말로 채우고 있었던 겁니다.
진단 2 — 규칙 문서 건강검진
문서를 수정하지 않고 진단만 했습니다. 가장 큰 발견:
우선순위 규칙이 두 곳에 흩어져 서로 모순처럼 읽힘
§2.1 — "등록 템플릿이 패턴 매칭보다 우선"
§7.7 — "해당 시점 명세서가 템플릿보다 우선"
실제 사슬은
명세서 > 템플릿 > 패턴3단계인데, 어디에도 한 번에 적혀 있지 않았습니다.
그리고 그 함정에 빠진 기록이 같은 문서 이력 절에 남아 있었습니다 — "이 보험은 템플릿상 A카드지만 실제로는 B카드로 결제됨". 문서가 자기 함정에 스스로 걸린 셈입니다.
부수적으로, 이력 절이 1년 5개월 전 작업 로그였고(규칙이 아니라 미완료 작업 상태), 이번 작업 범위에 무관한 절이 약 40% 였습니다.
진단 3 — 만들어 둔 Skill이 왜 안 불렸나
이 학습 자체가 증거였습니다. /스킬명으로 부르지 못하고 경로를 지정해 수동으로 읽혀서 시작했거든요.
원인 후보 3개를 소거했습니다.
후보 | 검증 | 결과 |
frontmatter 문제 | name·description 정상 | 배제 |
새 세션 필요 | 같은 조건의 다른 스킬은 정상 등재 | 배제 |
저장 위치 | 등재된 것과 미등재된 것의 유일한 차이 | 확정 |
스킬은 아무 폴더에 둔다고 발견되지 않고, 런타임이 스캔하는 경로에 있어야 했습니다. 저장·발견·호출은 각각 다른 사건이었습니다.
만든 것 — 첫 Skill
명세서 1건 입력 Skill을 발견되는 자리에 만들었습니다. 넣은 것:
우선순위 사슬을 한 곳에 3줄로 선언 (진단 1의 수리)
카드사별 청구주기 표 — 카드마다 "N월 입력분"의 기간이 다름
금액은
이용금액이 아니라결제원금컬럼판별 불가 건은 추측 금지,
미결정표시입력 전 승인 필수 / 합계 검증 없이 완료 선언 금지
증거와 관찰
합성 명세서 7건으로 실행했습니다.
통과 — 청구주기 필터
반대 방향 예외 2건이 동시에 맞았습니다. 기간 밖이라 빼야 하는 건(다이소)과, 기간 밖인데 넣어야 하는 건(마감 후 환불)이 각각 정확히 처리됐습니다.
통과 — 결제원금 규칙
합성 데이터에서는 이용금액 기준과 결제원금 기준이 크게 갈렸습니다. 다만 이 수치는 나중에 실제 파일에서 뒤집혔습니다 — 아래 "실제 파일에서 드러난 것"에 적었습니다.
설계대로 동작 — 미결정 처리
품목이 안 보이는 간편결제 건과 취소 수수료 건을 추측하지 않고 미결정으로 남겼습니다.
실패·막힘·수정
첫 병목은 제가 쓴 규칙 자체였습니다.
중복 검사를 "금액·항목 기준" 으로 하라고 썼는데, 구독 결제에서 무너졌습니다.
등록해둔 매월입력 : ClaudePro 32,000원
이번 명세서 : 클로드프로 33,700원
구독료는 변동합니다. 제 규칙대로면 금액이 다르니 다른 거래로 판단하고 또 입력 — 원래 문서가 경고했던 바로 그 중복이, 제가 쓴 중복 방지 규칙 때문에 발생하는 구조였습니다.
한 곳만 고쳤습니다.
수리 전 | 수리 후 | |
1순위 키 | 금액·항목 동등 | item 이름 |
금액 | 판단 키 | 확정 키 아님 |
이름 같고 금액 다름 | 규정 없음 | 중복 처리 + 차이 제시 + 사용자에게 판단 요청 |
같은 입력으로 다시 돌리니 중복을 잡았습니다. 다만 조건부 통과입니다 — 이 검사는 앞 단계에서 가맹점명을 기존 표기로 정규화하는 게 선행돼야 작동합니다. 순서가 바뀌면 이름 키도 깨집니다. 이번 주 범위를 넘어서 다음 실험으로 넘겼습니다.
또, 합계 검증 단계는 합성 데이터라 실제 결제액과 대조하지 못해 not_checked로 남겼습니다.
결과와 다음 실험
가장 크게 바뀐 건 문제를 보는 방향입니다. "규칙을 더 잘 적어야지"에서 "이 규칙은 아는 것인가, 하는 것인가" 로 바뀌었습니다. 20KB 문서 안에 사실(매핑표)과 절차(입력 순서)가 뒤섞여 있었고, 사실만 전달되고 절차는 매번 제 입으로 나가고 있었습니다.
다음 하나만 고른다면 — 실제 명세서로 입력 직전까지만 가는 dry-run입니다. 합계 검증(not_checked)이 유일하게 못 확인한 단계고, 그게 완료 기준의 핵심이라서요.
실제 파일에서 드러난 것
합성 데이터로 만족하지 않고 실제 명세서로 한 번 더 돌렸습니다. Skill이 틀렸습니다.
정답 (기록에 남아 있던 실제 청구액) : 1,630,960
Skill을 쓴 그대로 적용 : 1,594,500 ← 36,460 부족
틀린 이유 1 — 이미 잘라놓은 걸 또 잘랐다
카드사별 청구주기 표를 넣어뒀는데, 그게 오히려 화근이었습니다. 이용대금명세서는 카드사가 이미 청구주기로 잘라서 준 결과물입니다. 거기에 같은 기준을 다시 적용하니 이중 필터가 됐습니다.
게다가 실제 명세서 범위는 규칙에 적힌 기간을 양쪽으로 하루씩 벗어나 있었습니다. 그래서 경계에 있던 연회비와 보험료 2건이 통째로 탈락했습니다.
원래 문서에는 이미 답이 있었습니다 — "raw 거래내역이 아니라 명세서의 결제원금이 실제 청구액". 저는 입력 유형이 두 가지라는 걸 못 보고 하나의 절차에 섞어 썼습니다.
틀린 이유 2 — 금액이 한 컬럼에만 있는 게 아니었다
"금액은 결제원금 컬럼을 쓴다"고 단정했는데, 연회비와 수수료는 결제원금이 0이고 다른 컬럼에 들어 있었습니다. 규칙을 단정적으로 쓴 대가입니다.
틀린 이유 3 — 필요한 데이터가 입력 파일에 아예 없었다
"마감 후 환불은 이번 결제분에 포함"이라는 예외를 넣어뒀는데, 정작 그 환불은 명세서 파일에 없었습니다. 명세서 청구액과 은행 실결제액의 차이로만 존재를 알 수 있는 값이었습니다. Skill의 입력을 "파일 1개"로 정의한 것 자체가 구멍이었고, 필수 입력에 은행 결제액을 추가했습니다.
그리고 앞서 쓴 걸 정정합니다
합성 테스트에서 "결제원금과 이용금액이 13만원 넘게 차이난다"고 봤는데, 실제 파일에서는 두 합계가 똑같았습니다. 제가 합성 데이터를 만들 때 취소 상쇄행을 빼먹어서 생긴 착시였습니다.
실제 값어치는 다른 데 있었습니다 — 금액이 0인 발권/취소 쌍 9건을 걸러낸다는 것. 합계는 어차피 맞지만, 이걸 놓치면 장부에 의미 없는 9건이 남습니다. 합계의 문제가 아니라 내역의 문제였습니다.
세 곳을 고치고 다시 돌리니 합계가 정확히 맞았습니다(38건 / 1,630,960). 판별 못 한 10건은 추측하지 않고 미결정으로 남겼습니다.
여기서 배운 게 제일 큽니다. 내가 만든 테스트 데이터는 내 규칙을 통과하도록 만들어진다. 합성 데이터 7건은 전부 통과했지만 실제 파일 하나가 세 개의 오류를 한꺼번에 드러냈습니다.
덧붙임 — 진단이 맞았다는 확인
글을 마무리하던 중에 확인이 하나 됐습니다. 새로 만든 Skill이 설치 직후 같은 세션에서 목록에 잡혔습니다. 새 세션을 열 필요도 없었습니다.
저장 위치만 바꿨을 뿐인데 안 보이던 게 보였습니다. "원인은 저장 위치"라는 진단이 추측이 아니었다는 게 이렇게 확인됐습니다. 저장·발견·호출이 각각 다른 사건이라는 게 이번 주에 가장 오래 남을 것 같습니다.
watchdog_handoff:
program: 지피터스 23기 에이전트하네스
week: W1
source_skill: w1-learning-guide
learner_display_name: whooing
candidate_title: "규칙은 이미 20KB짜리 문서에 다 있었는데, 왜 매번 다시 설명하고 있었나"
learner_claimed_url: none
source_status: draft
decision_authority: watchdog
skill_decision: not_performed
watchdog_live_verification: required
reward_delivery: separate_downstream_operation
로그인하고 댓글을 남겨 주세요
검증하는 과정을 재미있게 잘읽었습니다!!
20KB 규칙 문서가 있어도 사실을 아는 것과 일을 순서대로 수행하는 것은 다르다는 진단을, 세션 맥락과 문서 충돌을 직접 살펴 증명한 점이 좋았어요. 명세서, 등록 템플릿, 키워드 패턴의 우선순위를 한곳에 모으고 합성 데이터 뒤에 실제 파일까지 넣어 세 가지 설계 오류를 고친 과정도 배움의 흐름이 선명합니다.
실제 파일에서 합계는 맞췄지만 이름 기반 중복 검사는 가맹점명 정규화가 먼저 된다는 조건에 의존하고, 미결정 10건도 남아 있어요. 다음에는 같은 거래명의 표기만 조금씩 바꾼 입력을 넣어 정규화와 중복 판정의 순서를 바꿨을 때 어느 단계에서 차이가 나는지 확인해주시면 남은 취약점이 구체적으로 드러날 것 같아요.

유피테르님, 에이전트에게 단순히 방대한 문서를 던져주는 것(Context)과 일하는 순서(Skill)를 잡아주는 게 다르다는 진단부터 무릎을 탁 치게 만드네요. 게다가 중복을 막으려고 세운 규칙이 변동 구독료 때문에 오히려 중복 결제를 만들고 있었다는 문제를 발견하고 바로 수정해나가는 과정이 정말 흥미진진했습니다. 문제를 도구 탓으로 돌리지 않고 에이전트의 경로 설정부터 규칙의 모순까지 차근차근 소거법으로 해결하시는 디테일에서 깊은 배움을 얻고 갑니다. 저도 제 에이전트 규칙들을 당장 뜯어보고 싶어지는 글이네요. 👍