chore: 클로드 도구 서브에이전트 위임과 토큰 낭비 방지(#96)

[xunssoie]

PR Summary

스킬의 기계적인 사실 조립 작업(코드래빗 피드백 판정, 쿼리 출처 매핑)을 전용 서브에이전트로 위임하고, 장시간 명령의 실행 규칙(백그라운드, 로그 파일화, 유한 대기, 손절)을 CLAUDE.md에 신설했습니다.

Problem

문제 1 - 스킬 작업이 전부 메인 컨텍스트에서 수행됨

모든 스킬 작업이 메인 컨텍스트에서 이루어져, 판정과 가공의 중간 산출물이 그대로 컨텍스트에 쌓이고 있었습니다. review-feedback은 코드래빗 코멘트 원문(접힌 diff 포함)과 항목별 코드 탐색 흔적을, optimize-performance는 쿼리 출처를 찾는 Grep 탐색 흔적을 전부 메인에 남깁니다. 긴 세션에서 컨텍스트 점유가 커져 컴팩션 시점이 앞당겨지고, 분석 주도 문답의 맥락이 요약 과정에서 뭉개지는 영향이 있었습니다.

문제 2 - 장시간 명령의 반복 실패로 토큰이 낭비됨

그래들 빌드나 애플리케이션 기동 같은 장시간 명령을 포그라운드로 잡고 있다가 타임아웃되면 같은 명령을 처음부터 다시 돌리고, 실패할 때마다 로그 원문 전체가 컨텍스트에 반복 적재되고 있었습니다. 서버 기동을 무한정 대기하거나 테스트 수정, 재실행을 상한 없이 반복하는 경로도 열려 있어, 실패가 길어질수록 낭비가 선형으로 늘어나는 구조였습니다.

Solution

해결 1 - 사실 조립 작업만 전용 에이전트로 위임

위임 범위를 판단이 아닌 사실 조립으로 한정해 두 에이전트를 만들었습니다. 해석과 판단을 사용자에게 남기는 기존 분석 주도 규칙과 충돌하지 않게 하기 위해서입니다. feedback-judge는 코드래빗 항목별 타당성 판정을 병렬로 수행해 정형 행만 반환하고, query-source-mapper는 쿼리 통계 1차 출력을 템플릿 규칙대로 가공본으로 재작성합니다. 수집 단계도 원문을 파일로 리다이렉트하고 컨텍스트에는 body를 뺀 인덱스만 남기도록 바꿨습니다.

서브에이전트 위임은 총 토큰이 아니라 메인 컨텍스트 점유를 줄이는 조치이므로, 스킬 frontmatter에는 Agent(에이전트명) 표기로 해당 스킬이 띄울 수 있는 에이전트를 전용 워커 하나로 제한해 오남용을 막았습니다.

해결 2 - 명령 실행 규칙 신설과 재실행 상한

CLAUDE.md에 명령 실행 규칙 4가지를 신설했습니다. 2분 이상 예상되는 명령은 백그라운드로 실행하고, 빌드와 테스트 출력은 파일로 리다이렉트해 실패 시 tail과 grep으로만 읽으며, 준비 대기는 한 번의 호출 안에서 유한 루프로 수행하고, 같은 명령이 같은 원인으로 2회 실패하면 재시도를 멈추고 보고합니다. 테스트 수정, 재실행 반복에는 최대 3회 상한을 두어 무한 루프 경로를 닫았습니다.

Related Issue

• close chore: 클로드 도구 서브에이전트 위임과 토큰 낭비 방지 #96

🤖 Generated with Claude Code

[github-actions]

Test Results

284 tests   284 ✅  3s ⏱️
 91 suites    0 💤
 91 files      0 ❌

Results for commit 2c3e5af.