Claude Code로 「사용할수록 똑똑해지는」 자기 성장 서브 에이전트(Sub-agent)를 만들고, 그것을 진심으로 평가 및 튜닝(Tuning)한 기록입니다.

주제는 리뷰를 도와주는 에이전트이지만, 여기서 쓰는 교훈은 자기 성장 에이전트 전반에 적용될 것입니다. 용도나 도메인의 상세한 내용은 생략하고, 평가와 튜닝의 방법론만을 작성합니다.

만든 것

코드 리뷰나 사양 상담을 도와주는 서브 에이전트를 만들었습니다. 예를 들어 PR을 던지면 "이 처리, 과거에 유사한 디그레션(Degression)을 일으켰던 관점이 누락되지 않았나요?"라고 답해줍니다. 사양 상담을 하면 관련 문서를 확인한 뒤 "이 부분은 기존 사양과 모순됩니다"라고 지적해 주는——그런 리뷰 파트너입니다.

기왕이면 사용할수록 똑똑해졌으면 하기에, 특징은 자기 성장입니다. 리뷰나 회고를 통해 "이것은 재발할 것 같다"라고 판단한 교훈을 지식 베이스(Knowledge Base, 이하 KB)에 구조화하여 쌓아 나갑니다.

구현은 Claude Code의 서브 에이전트 기능을 사용했습니다. 정의는 프론트매터(Frontmatter, name / description / tools / model)가 포함된 한 장의 Markdown으로, 여기에 성격·절차·동작 모드를 작성합니다. 실제 모습은 다음과 같은 골격입니다 (내용은 일반화했습니다).

---
name: review-buddy
description: 코드 리뷰·사양 상담·테스트 리뷰를 돕는 자기 성장 에이전트
...

이후에 나오는 "프롬프트(Prompt)"는 이 정의 파일을, "KB를 로드한다"는 각 모드가 기동 시에 읽는 파일(bugs-and-regressions 등)을 의미한다고 생각하고 읽어주세요. 3개 층으로 구성되어 있습니다.

• 프롬프트 (정의)… 성격·절차·동작 모드를 작성한 한 장의 md (위의 것)
• 자기 성장 KB… 에이전트 스스로 키워나가는 지식 (과거의 결함·사양의 함정·테스트 누락을 리뷰 관점 리스트로 승격)
• 외부의 1차 자료… 사양이나 문서 등, 스스로는 고쳐 쓰지 않는 정본

그래서 작동하는 것은 비교적 금방 만들었습니다. 문제는 지금부터입니다.

「작동한다」와 「효과가 있다」는 별개였다

"적절하게 지적해 준다" 정도로는 아직 신뢰할 수 없습니다. 정말로 도움이 되는지 제대로 확인하고 싶었습니다.

그래서, 모범 문제와 채점 기준을 먼저 준비하여, 에이전트의 답변을 매번 그 잣대로 채점하기로 했습니다. "이 질문에는 이렇게 답해주길 바란다"라는 모범 문제집(Golden Task)과, "실제 코드를 읽었는가", "전문 외의 영역을 제대로 거절했는가"와 같은 관점별 채점표(Rubric). 나머지는 같은 질문을 조건만 바꿔서 던지고 결과를 세기만 하면 됩니다.

이 지루한 실측에 집중했더니, 만들고 있을 때는 "뭐, 그렇겠지"라고 생각했던 전제들이 꽤 어긋나기 시작했습니다. 직관에 반하는 발견이 여러 개 나왔습니다——이것이 지금부터 할 이야기입니다.

1. 과거의 버그로 테스트해도 똑똑함은 측정할 수 없었다

처음에 했던 평가가 이것입니다. 실제 존재했던 과거 버그에 대해 "이 테스트 계획, 고려 사항이 누락된 게 있어?"라고 물었더니, 에이전트는 훌륭하게 누락을 지적했습니다. 똑똑하잖아……라고 생각한 순간 깨달았습니다.

그 진인(Root Cause)도 재발 방지책도, 이미 KB에 적혀 있습니다. 이 에이전트 스스로가 과거에 쌓아온 것이기 때문입니다. 즉, 측정되고 있는 것은 "미지의 누락을 추론으로 찾아내는 능력(Detection)"이 아니라 "KB를 검색하는 능력(Recall)"일 뿐입니다. 자신이 쓴 답을 스스로 찾아내고 있을 뿐입니다. 원리적으로 똑똑함을 측정할 수 없는 것입니다.

그래서 주제를 바꿨습니다. KB에 아직 없는 소재를 골라, 그 논점이 KB에 없음을 grep으로 확인한 뒤, 힌트 없이(Cold) 던집니다. 그랬더니 아직 버그가 되지 않은 고려 사항 누락(예: 어떤 배치 처리 기능에서 "데이터 건수가 많을 때의 페이지네이션 경계", "중간 실패 시의 재시도와 멱등성(Idempotency)", "처리 중에 참조원이 변경된 경우")을 제대로 스스로 제시했습니다. 이것이 진짜 Detection입니다.

2. 동작을 바꾸는 레버는 3개. 효과가 전혀 달랐다

"생각보다 얕다", "보고 싶은 관점을 봐주지 않는다"——그럴 때 무엇을 건드려야 고쳐지는가. 여기서 말하는 동작이란, 예를 들어 어디까지 파고들 것인가 (실제 코드까지 읽을 것인가, 사양만으로 답할 것인가) 또는 어떤 관점에서 지적할 것인가와 같이 조정하고 싶어지는 행동을 말합니다. 조작할 수 있는 수단은 3가지가 있었고, 효과가 나타나는 지점이 완전히 달랐습니다.

가장 큰 발견은, 프롬프트의 문구는 "작성 방식"에 따라 효과가 천차만야라는 점이었습니다.

효과 없음: "오류의 무게와 정보의 최신성을 '판단'하여 깊이를 결정하라" $\rightarrow$ 모호한 판단을 통째로 떠넘기는 규칙. 몇 번을 다시 써도 안정되지 않았습니다. -
효과 있음: "테스트 리뷰라면 코드를 읽어라" $\rightarrow$ 단순한 mode $\rightarrow$ action. 이것을 추가했더니, 콜드 스타트 상황에서도 5회 중 5회 모두 실제 코드를 읽고 기능 고유의 누락 사항을 찾아내기 시작했습니다.

3. 지식(Knowledge)은 '로그'가 아니라 '원칙'으로 만들어야 비로소 효과가 있다

자기 성장의 핵심은 KB입니다. 하지만 무엇을 어떻게 쓰느냐에 따라 가치가 천차만별로 달라집니다. 가장 흔히 저지르는 실수는 발생한 버그를 그대로 기록하는 것입니다. 이것은 **로그 (Log)**일 뿐이며, 다른 상황의 리뷰에는 전혀 전용될 수 없습니다.

효과가 있었던 것은, 유사한 사례를 모아 **한 단계 추상화한 "재사용 가능한 원칙"**으로 격상시키고, 그 모드가 읽는 위치에 두었을 때입니다. 이것만으로도 힌트 없이 원칙이 발화하여, 기록되지 않은 누락 사항을 지적하기 시작했습니다.

Before (로그 · 전용되지 않음)
"현상 X에서 값 Y가 사라짐"
After (원칙 · 콜드 스타트 시 발화)
...

요령은 추상도를 딱 적당한 높이로 유지하는 것 (너무 낮으면 전용되지 않고, 너무 높으면 "에지 케이스를 테스트하라" 급의 노이즈가 됨)과, 그것을 사용하는 모드가 읽는 파일에 두는 것입니다. 좋은 원칙이라도 아무도 읽지 않는 곳에 있다면 발화하지 않습니다.

흥미로운 점은 이것이 절 2의 프롬프트와 반대라는 것입니다. 프롬프트는 추상적으로 쓰면 미끄러지고, KB는 추상적으로 쓰지 않으면 효과가 없습니다. 차이는 "추상화라는 판단을 누가 하느냐"입니다. 프롬프트는 그것을 실행 시점의 AI에게 떠넘기기 때문에 흔들립니다. KB는 사람이 미리 원칙으로 격상시켜 두기 때문에, AI는 이를 적용하기만 하면 됩니다.

4. 위험한 자기 판단은 '현명한 분류'가 아니라 '틀려도 안전한 쪽'으로 해결한다

이 에이전트는 질문에 따라 실제 코드까지 파고들지 않고, 사양서나 KB만으로 답변합니다 (속도를 위해). 코드를 파고들면 구현에 맞춰 답변할 수 있지만 시간이 걸립니다. 파고들지 않으면 빠르지만 구현과 어긋날 수 있다는 — 트레이드오프(Trade-off)가 존재합니다.

곤란한 점은, 언제 파고들지/파고들지 않을지에 대한 자기 판단이 흔들리는 것입니다. 가장 무서운 것은 코드를 파고들지 않고 단정 지어, 실제 코드와 내용이 어긋나는 케이스입니다. 사양서에는 "저장된다"고 되어 있는 값이 구현에서는 저장되지 않는 — 식의 괴리는 흔히 발생합니다.

"언제 파고들지"를 올바르게 판단하게 할 수 없다면, 판단의 정밀도를 높이기보다 틀려도 안전한 쪽으로 기울기로 했습니다. 핵심은 비용의 비대칭성입니다. 파고들 필요가 없는 상황에서 파고들면 느려질 뿐이지만, 파고들어야 할 상황에서 파고들지 않고 단정하면 틀리게 됩니다. 그렇다면 저렴한 실패 쪽을 택하겠습니다. 구체적인 대책은 두 가지입니다.

• 답변의 근거가 실제 코드에 있는 영역은, 파고들지 않는 선택지를 만들지 않고 항상 실제 코드를 읽는다 (코드 리뷰 / 버그 조사 / 테스트 리뷰). 속도는 뒷전입니다. -
• 파고들지 않았을 때는 "실제 코드 미확인"이라고 자기 신고하게 한다. 무서운 것은 파고들지 않는 것 자체가 아니라, **"실제 코드를 보지 않고도 단정하는 것"**이기 때문입니다.

요약: 평가는 한 번으로 끝나지 않는다

"사용할수록 똑똑해지는 에이전트"를 만들고 싶어 시작했지만, 실측해 보며 얻은 가장 큰 배움은 이것이었습니다 —— 에이전트의 가치는 만든 순간이 아니라, 평가하고 고쳐 나가는 과정에서 결정된다. 위의 발견들은 모두, 실제로 돌려보고 숫자를 세어보기 전까지는 보이지 않았습니다.

자신이 가르친 정답으로는 똑똑함을 측정할 수 없다. 테스트하려면 아직 모르는 문제로 해야 한다. -
AI에게 판단하게 하지 말고, 행동을 지시하라. 망설여지는 판단은 사람이나 지식(Knowledge)이 가져야 한다. -
기록이 아니라 교훈을 남겨라. 사용하는 곳에 두어야 지식은 비로소 효과를 발휘한다. -
올바르게 판단하게 하기보다, 틀려도 안전하게. 모를 때는 "모른다"라고 말하게 한다.

그리고 자기 성장 에이전트는 사용할 때마다 내용물(KB)이 변합니다. 출시 전에 한 번 OK를 받았더라도, 다음 주에는 다른 물건이 되어 있습니다. 게다가 "아직 기록에 없는 주제"를 가장 많이 던져주는 것은 바로 매일의 실운용 그 자체입니다.

따라서 평가는 실험실에서의 단 한 번으로 끝나는 것이 아니라, 운용하면서 계속해서 돌려나가는 행위가 되어야 할 것입니다—— 이것이 제작을 마친 시점에서의 가설입니다. 사실 아직 실운용(production)에는 투입하지 않았으므로, 운용 단계에 올리면 다시 측정하여 기록하겠습니다.

Discussion