Agent Debug

디버깅 - 메인 + 독립 서브에이전트(Opus) 협업

메인이 증상을 분석하고 원인 가설을 수립한 뒤, 독립 서브에이전트가 실제 코드를 추적하여 가설을 검증합니다. 원인이 확정된 후에만 수정을 진행하며, 수정은 항상 메인이 직접 합니다 (서브에이전트는 분석 전용).

절차

1. 메인 선분석

사용자의 버그 리포트를 기반으로 codebase-memory-mcp 그래프 도구를 우선 사용하여 관련 코드를 확인하고 정리합니다.

• search_graph로 관련 함수/클래스 탐색, trace_call_path로 콜체인 추적
• detect_changes로 최근 변경의 영향 범위 분석
• 그래프에 없는 정보(에러 문자열, 설정값 등)만 Read/Grep으로 보완
• 정리 항목: 증상 및 기대 동작 / 재현 조건 / 의심 범위 / 원인 가설 1~3개 + 검증 방법

재현 정보가 부족하면 사용자에게 최소한의 추가 정보만 요청합니다.

2. 서브에이전트 독립 조사

증상, 관련 파일, 재현 조건(사실 정보만 — 메인의 원인 추정은 전달하지 않음)을 서브에이전트에게 전달하여 독립적으로 원인을 추적하게 합니다.

• 관련 파일 읽기, 에러 문자열/함수명 검색, 필요 시 빌드/테스트 실행
• 가설별 지지/반증 근거 정리
• 수정은 하지 않음 — 원인 추적만 진행 (READ-ONLY 명시)

단순한 버그(원인이 한 파일 안에서 명확)는 서브에이전트 없이 메인 단독으로 처리해도 됩니다.

3. 원인 확정

메인이 양쪽 분석을 종합하여 원인 후보를 축소합니다.

• 추가 검증이 필요하면 SendMessage로 같은 에이전트에 가장 효율적인 확인 1개를 요청

4. 수정/검증 (메인)

원인이 충분히 좁혀진 후 메인이 직접 최소 범위로 수정합니다.

• 무관한 리팩토링 금지, 기존 컨벤션 유지
• 수정 후 재현 절차 또는 빌드/타입 체크/테스트로 검증
• 수정이 기능 변경 수준이면 커밋 전 /agent-review 적용

5. 최종 보고

원인, 수정 내용, 검증 결과, 남은 리스크를 정리하여 보고합니다.

서브에이전트 호출 방법

Agent 도구를 사용합니다:

• subagent_type: "general-purpose", model: "opus"
• 백그라운드 실행이 기본 — 완료 시 task-notification 수신. 대기 중에는 선분석 정리 등 병렬 작업만 수행.

조사 요청 프롬프트

당신은 DmNote 프로젝트(Tauri + React)의 독립 디버거입니다.
READ-ONLY — 코드를 수정하지 말고 원인 분석만 보고하세요.
작업 디렉토리: (절대 경로). 파일 읽기/검색/빌드/테스트 실행 가능.

버그 증상: (사용자 입력)

관련 정보:
- 기대 동작: ...
- 재현 조건: ...
- 관련 파일/함수: (경로 목록)
- 최근 변경: (관련 커밋/diff 범위)

요청:
- 원인 후보를 독립적으로 도출하고 각각 근거 제시
- 재현 가능하면 최소 절차를 제시하고 직접 검증
- 원인 미확정 시 가장 효율적인 추가 확인 1개 제안

출력 형식 (반드시 준수):
## 원인 후보
1. (후보) - 근거: ... / 검증: ...
## 재현 결과
(재현 시도 내용과 결과)
## 추가 확인 필요
(미확정 시 다음 확인 사항)

재현 절차가 불명확하면 코드 검색과 정적 분석 위주로 조사하도록 지시합니다.

역할 분담 기준

메인 비중을 높이는 경우:

• 증상이 모호하고 의도 해석이 먼저 필요할 때
• 여러 서브시스템이 얽혀 있을 때
• 수정 전 영향 범위 판단이 중요할 때

서브에이전트 비중을 높이는 경우:

• 에러 메시지/스택트레이스가 명확할 때
• 재현 가능한 절차가 있을 때
• 다수 파일의 실행 경로를 빠르게 확인해야 할 때

실패 처리

• 서브에이전트 실패(결과 null) 시: → "서브에이전트 조사 실패: [원인]. 메인이 직접 디버깅합니다."
• 조사가 2회 이상 불충분하면 메인 단독 디버깅으로 전환합니다.
• fallback 발생 시 반드시 원인을 사용자에게 명시합니다.

피드백 필터링

서브에이전트 결과를 반영할 때 메인이 자체 판단으로 필터링합니다:

• 방어적 코딩 수준의 제안이 실질적 버그가 아니라 오버엔지니어링이면 반영하지 않습니다.
• 프로젝트 컨벤션에 부합하는 코드에 대한 지적은 무시합니다.

출력 형식

문제 요약

(증상, 기대 동작, 재현 가능 여부)

메인 선분석

(의심 범위, 초기 가설, 우선 조사 이유)

서브에이전트 조사 결과

(확인한 파일/명령, 재현 결과, 가설별 근거, 남은 유력 원인)

수정안

(수정 파일, 변경 요지. 미수정 시 사유)

검증 결과

(실행한 검증, 결과)

남은 리스크

(회귀 가능성, 추가 확인 포인트)