운영 중인 서비스를 넘겨받는 일을 자주 합니다. 앞선 개발사가 손을 뗐거나, 담당자가 나갔거나, 프리랜서와 계약이 끝난 경우입니다.
보통 웹이나 앱은 코드를 읽으면 대체로 파악됩니다. AI 기능은 코드만 봐서는 모릅니다.
코드에 안 적혀 있는 것들
model: "..." 한 줄과 프롬프트 문자열은 보입니다. 그런데 이런 건 안 보입니다.
이 문장이 왜 들어갔나
const SYSTEM = `
당신은 고객 문의를 분류합니다.
- 환불 요청은 "환불"로 분류합니다.
- 배송 지연 문의도 환불 의사가 명시되면 "환불"입니다.
- 단, "환불 규정이 궁금하다"는 "안내"입니다. // ← 왜?
- 금액을 언급해도 그것만으로 환불로 보지 않습니다. // ← 왜?
`;
주석이 없으면 다음 사람은 아래 두 줄을 쓸데없는 잔소리로 보고 지웁니다. 그리고 같은 문제가 다시 터집니다.
저런 문장은 대개 뭔가 잘못됐던 사례를 막으려고 넣은 겁니다. 그 사례가 어디에도 없으면 문장은 근거를 잃습니다.
이 숫자가 왜 0.72인가
if (confidence < 0.72) return "manual";
확신도 기준값 같은 숫자는 재보고 정한 값입니다. 근거가 없으면 손을 못 댑니다. 올리면 수동 처리가 늘고 내리면 오류가 늡니다. 어느 쪽이 얼마나 늘어나는지 모르면 아무도 안 건드립니다.
뭘 해봤고 결과가 어땠나
해보고 접은 방법을 모르면 다음 사람이 똑같은 걸 또 해봅니다. "벡터 검색만으로 해봤는데 문서번호를 못 찾아서 키워드 검색을 섞었다" 한 줄이 몇 주를 아낍니다.
모델 버전이 고정돼 있나
API에서 모델을 별칭으로 써두면 제공사가 모델을 갱신할 때 결과가 달라집니다. 어제까지 잘 되던 분류가 오늘 다르게 나옵니다.
버전을 못 박아두고, 새 버전으로 옮길 때는 평가 세트로 비교한 뒤 옮기는 게 맞습니다. 이 원칙이 문서에 없으면 인수인계 후 첫 사고가 대개 여기서 납니다.
넘겨받을 때 같이 받아야 할 것
인수인계 문서에 이게 있는지 확인하세요.
| 항목 | 없으면 |
|---|---|
| 프롬프트 변경 이력과 이유 | 지우면 안 될 문장을 지웁니다 |
| 정확도 평가 세트 | 고쳐도 좋아졌는지 알 수 없습니다 |
| 기준값의 근거 | 손대지 못하고 방치됩니다 |
| 모델·버전과 고정 여부 | 어느 날 갑자기 결과가 달라집니다 |
| 월 사용량과 비용 추이 | 요금이 왜 늘었는지 못 찾습니다 |
| 실패 사례 모음 | 같은 함정을 다시 밟습니다 |
평가 세트가 특히 중요합니다. 질문과 정답을 모아둔 목록인데, 이게 없으면 프롬프트를 고친 뒤 좋아졌는지 나빠졌는지 판단할 방법이 없습니다. 그러면 아무도 손대지 않고, 기능은 그대로 굳습니다.
형식은 단순해도 됩니다.
[
{
"input": "어제 시킨 거 아직도 안 왔는데 그냥 취소해주세요",
"expected": "환불",
"note": "배송 지연 + 취소 의사 → 환불. 2025-03 오분류 사례"
},
{
"input": "환불 규정이 어떻게 되나요?",
"expected": "안내",
"note": "규정 문의는 환불 아님. 프롬프트 세 번째 줄의 근거"
}
]
note가 핵심입니다. 이 한 줄이 프롬프트의 그 문장과 이어집니다.
프롬프트도 코드처럼 다루세요
프롬프트를 관리자 화면에서 바로 고치게 만들어둔 경우를 종종 봅니다. 편해 보이는데 위험합니다. 누가 언제 뭘 바꿨는지 안 남고 되돌릴 수도 없습니다.
프롬프트는 코드와 같이 저장소에 두고 이력을 남기는 편이 낫습니다. 급하게 바꿔야 하는 값이 있으면 그 값만 설정으로 빼고, 문장은 이력이 남는 곳에 둡니다.
prompts/
classify-inquiry.md ← 프롬프트 본문 + 각 규칙의 근거
classify-inquiry.eval.json ← 같은 폴더에 평가 세트
같은 폴더에 있으면 프롬프트를 고칠 때 평가 세트가 눈에 들어옵니다. 다른 데 있으면 잊습니다.
비용 추이가 없으면 이상을 못 잡습니다
토큰 사용량을 기능별로 안 남기고 있으면, 요금이 두 배가 됐을 때 어느 기능 때문인지 알 수 없습니다.
넘겨받을 때 최소한 이 정도는 받으세요.
- 기능별 월 토큰 사용량 (입력·출력·캐시 각각)
- 캐시 적중률
- 요청당 평균 토큰
캐시 적중률이 특히 쓸모 있습니다. 이 값이 갑자기 0으로 떨어졌다면 누가 프롬프트 앞부분을 건드린 겁니다. 원인이 바로 좁혀집니다.
넘길 때도 마찬가지입니다
저희가 만든 걸 넘길 때도 같은 목록을 씁니다. 코드와 함께 프롬프트가 그렇게 된 이유, 평가 세트, 기준값의 근거, 비용 추이를 정리해 드립니다.
인수인계가 잘 되면 다음 사람이 고칠 수 있고, 고칠 수 있으면 그 기능은 계속 좋아집니다. 못 고치면 굳고, 굳으면 결국 통째로 다시 만듭니다. 다시 만드는 값이 문서 쓰는 값보다 훨씬 큽니다.
정리
AI 기능은 판단 근거가 코드 밖에 있습니다.
넘겨받으실 때 이 넷을 요구하시면 이후 유지보수가 완전히 달라집니다.
- 프롬프트 변경 이력과 각 문장의 이유
- 정확도 평가 세트 (
note포함) - 기준값을 그렇게 잡은 실험 기록
- 모델 버전 고정 여부와 교체 절차
계약할 때 산출물 목록에 넣어두세요. 끝나고 나서 달라고 하면 그 사람은 이미 없습니다.