# Agent Debug

> 버그 원인 추적 및 수정을 위한 메인 + 독립 서브에이전트(Opus) 협업 디버깅. 에러/증상 분석, 재현, 원인 특정, 회귀 디버깅 시 사용.

- Skill: `dmnote-app/agent-debug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dmnote-app/agent-debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dmnote-app/agent-debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: dmnote-app (https://skillmd.com/u/dmnote-app)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dmnote-app/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 발생 시 반드시 원인을 사용자에게 명시합니다.

## 피드백 필터링

서브에이전트 결과를 반영할 때 메인이 자체 판단으로 필터링합니다:
- **방어적 코딩 수준의 제안**이 실질적 버그가 아니라 오버엔지니어링이면 반영하지 않습니다.
- 프로젝트 컨벤션에 부합하는 코드에 대한 지적은 무시합니다.

## 출력 형식

### 문제 요약
(증상, 기대 동작, 재현 가능 여부)

### 메인 선분석
(의심 범위, 초기 가설, 우선 조사 이유)

### 서브에이전트 조사 결과
(확인한 파일/명령, 재현 결과, 가설별 근거, 남은 유력 원인)

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

### 검증 결과
(실행한 검증, 결과)

### 남은 리스크
(회귀 가능성, 추가 확인 포인트)