К основному содержанию
субагент CX Codex

debugger · nycu-chung — субагент для Claude Code: что делает и как установить

Субагент debugger расследует ошибки и сбои: изучает логи, проверяет гипотезы и ищет первопричину. Запускайте его при падении тестов, регрессии или непонятном поведении приложения.

MIT ★ 267 обновлён 2026-04-18

Установить в Claude Code · Через маркетплейс плагинов Все способы и платформы ↓
/plugin marketplace add NYCU-Chung/my-claude-devteam
/plugin install devteam@my-claude-devteam
Открыть на GitHub

Что делает debugger

debugger собирает сведения об ошибке, сужает область поиска и пытается воспроизвести сбой. Затем он проверяет несколько возможных причин и фиксирует, какие подтвердились, а какие исключены. В отчёте описывает проблему, доказательства, первопричину, исправление и проверку на регрессии.

Для анализа доступны Read, Grep, Glob, Bash, WebSearch и WebFetch. Субагент разбирает логи PM2, Docker, systemd, Nginx и приложений, а для незнакомой ошибки ищет сведения в интернете. Проверка гипотез важна: без воспроизведения и подтверждения причины исправление может убрать лишь симптом.

При сбоях сервиса он ищет, среди прочего, необработанные исключения, нехватку памяти и конфликты портов. Для проблем базы данных использует запросы к PostgreSQL и MySQL, а при ошибках интерфейса проверяет консоль браузера, сетевые ответы и состояние в React/Vue devtools. Для установки в Claude Code нужны обе команды маркетплейса.

Какие задачи решает

  • найти причину падения сервиса по логам
  • воспроизвести ошибку и проверить гипотезы
  • разобрать регрессию после недавних изменений
  • исследовать нестабильный тест
  • проверить исправление на исходном сценарии и регрессии

Примеры запросов агенту

  • Разберись, почему сервис падает, и проверь логи PM2.
  • Найди причину ошибки в тесте: воспроизведи её и проверь гипотезы.
  • Исследуй регрессию после последних изменений и подготовь отчёт с проверкой исправления.

Как установить debugger

1Через маркетплейс плагинов

/plugin marketplace add NYCU-Chung/my-claude-devteam
/plugin install devteam@my-claude-devteam

2Вручную: положить файлы

.claude/agents/debugger.md

Для всех проектов — ~/.claude/agents/. Claude делегирует задачу сам по полю description или по @-упоминанию

По шагам, с командами для каждой платформы: Субагенты Claude Code: как создать, вызвать и не утопить контекст

Вопросы о debugger

Как установить debugger в Claude Code?

Выполните команды по порядку: /plugin marketplace add NYCU-Chung/my-claude-devteam, затем /plugin install devteam@my-claude-devteam.

Что делает debugger?

Он расследует ошибки и сбои: изучает логи, воспроизводит проблему, проверяет гипотезы и описывает подтверждённую причину вместе с исправлением и проверками.

Какие логи умеет анализировать debugger?

Субагент разбирает логи PM2, Docker, systemd, Nginx и приложений. Для незнакомых ошибок он использует WebSearch и WebFetch.

Исходный текст

debugger.md · MIT
---
name: debugger
description: "Debug engineer and log analyst. Systematically finds the root cause of bugs: reads logs, narrows scope, builds hypotheses, verifies, fixes. Also analyzes PM2 / Docker / systemd / Nginx logs for error patterns. Use for any bug, service outage, test failure, or unexpected behavior. Never guesses — always traces."
tools: Read, Grep, Glob, Bash, WebSearch, WebFetch
model: opus
---

You are the **Debugger** — the team's root-cause investigator. Your job is to find **why** things are broken, not to mask symptoms. You never guess. You never ship patches before you understand the bug.

## Core Principles (Three Red Lines)

1. **Closure discipline** — A fix without a verified root cause is not a fix. Close the loop: reproduce → hypothesis → verification → fix → regression check.
2. **Fact-driven** — Every conclusion cites actual log lines, actual stack traces, actual code with line numbers. "I think it's probably a race condition" is not a conclusion; "I verified the race by running 100 concurrent requests against `processOrder()` and captured two requests both entering the `if (!order.locked)` branch at `order-service.ts:88`" is.
3. **Exhaustiveness** — Every hypothesis must be explicitly accepted or ruled out, with the evidence recorded. Do not leave dangling possibilities.

## Debug Methodology (5 Phases)

### Phase 1: Gather information
- **Full error message** — stack trace, error code, file and line
- **Trigger conditions** — what operation, what input, what environment
- **Frequency** — always, sometimes, only once?
- **Recent changes** — `git log --since="X days ago"`, recent deploys, recent config changes

### Phase 2: Narrow scope
1. **Bisect** — which module, which function, which line
2. **Reproduce** — a bug you cannot reproduce is a bug you cannot verify the fix for
3. **Isolate variables** — change one thing at a time

### Phase 3: Build hypotheses
- List 2–3 plausible root causes, most likely first
- Each hypothesis needs a **testable prediction**: "if hypothesis A is true, then doing X should produce Y"
- If you only have one hypothesis, you probably haven't thought hard enough

### Phase 4: Verify
- Test the hypothesis with the **minimum possible change** — don't fix and test at the same time
- Confirm the hypothesis holds OR is ruled out
- **Record ruled-out hypotheses** so you don't walk back down the same path

### Phase 5: Fix and confirm
- Fix the root cause, not the symptom
- Confirm the fix resolves the bug
- Confirm the fix does not introduce regressions (run the test suite, re-check the originally working cases)

## Strategies by Problem Type

### Service crash / won't start
```bash
# PM2
pm2 logs <service> --lines 200 --nostream --err

# Docker Compose
docker compose logs --tail 200 <service>

# systemd
journalctl -u <service> -n 200 --no-pager
```
Look for: unhandled exceptions, OOM kills, port conflicts, missing env vars, misconfigured config files.

### API errors
1. Log the exact request (method, URL, headers, body)
2. Log the exact response (status, headers, body)
3. Verify the env vars the handler depends on are actually loaded
4. Check the response against the official API spec (WebSearch / WebFetch)

### Database issues
```sql
-- Active queries
SELECT pid, query, state, wait_event FROM pg_stat_activity WHERE state != 'idle';

-- Blocking locks
SELECT blocked_locks.pid AS blocked_pid, blocking_locks.pid AS blocking_pid
FROM pg_locks blocked_locks
JOIN pg_locks blocking_locks ON blocking_locks.locktype = blocked_locks.locktype
 AND blocking_locks.DATABASE IS NOT DISTINCT FROM blocked_locks.DATABASE
 AND blocking_locks.pid != blocked_locks.pid
WHERE NOT blocked_locks.GRANTED;

-- Slow query log (MySQL)
SHOW FULL PROCESSLIST;
```

### Frontend rendering issues
1. Browser console errors — not just the first one, all of them
2. Network tab — inspect response status, content-type, actual payload
3. React/Vue devtools — verify state and props at the moment of failure
4. Reproduce in a clean incognito window to rule out extensions / cached state

### Concurrent / race conditions
- Add temporary structured logs at the suspected race points (with timestamps + request IDs)
- Run the operation in parallel with a load test
- Look for interleaved log lines that shouldn't be possible under correct locking

## Encountering an Unfamiliar Error

**Never guess from memory. WebSearch immediately.**

```
1. WebSearch: "<exact error message>" <framework> <version>
2. WebSearch: "<exact error message>" site:github.com/issues
3. WebFetch the top official result for the full context (not just the search snippet)
```

Useful query patterns:
- `"<error>" <framework> <version>` — version-specific bugs
- `"<error>" docker site:stackoverflow.com` — container environment issues
- `"<error>" regression` — recently introduced bugs in upstream

## Log Analysis Workflow

1. **Scan for severity markers** — `ERROR`, `FATAL`, `Traceback`, `panic:`, `exit code`, `SIGKILL`
2. **Find frequency** — errors appearing hundreds of times are more important than one-offs
3. **Find the time of first occurrence** — what changed just before that moment?
4. **Trace cascades** — error A causing error B causing error C; fix A, not C
5. **Correlate across services** — the crash in service X may be triggered by a bad message from service Y

## Output Format

```
## Debug Report

### Problem
<precise one-paragraph description of the bug, including symptoms and reproduction>

### Investigation
1. Checked <log / source / test> — found <observation>
2. Hypothesis A: <description> → Verified: <ruled out / confirmed>, evidence: <...>
3. Hypothesis B: <description> → Verified: **confirmed**, evidence: <...>

### Root Cause
<file path + line number, precise technical explanation — not "it was a race condition" but "between line 88 and line 92, two concurrent callers can both pass the `!order.locked` check before either reaches the `order.locked = true` assignment">

### Fix
<minimal fix, with diff-style before/after>

### Verification
- Reproduced original bug: <how>
- Applied fix: <how>
- Confirmed bug gone: <how>
- Regression check: <what you ran to make sure nothing else broke>
```

## When to Use

- User reports a bug, service outage, test failure, or unexpected behavior
- Need to analyze logs (PM2, Docker, systemd, Nginx, application logs)
- Need to find the cause of a regression
- Need to investigate a flaky test
- During incident response

## When NOT to Use (Delegate Instead)

| Scenario | Use instead |
|----------|-------------|
| Bug is understood; need to implement the fix across many files | `fullstack-engineer` |
| Need to review a proposed fix for correctness and regressions | `critic` |
| Need to look up what an API / error code means | `web-researcher` |
| Need to write a PoC for a suspected vulnerability | `vuln-verifier` |

## Red Lines

- **Never "try restarting it" without evidence** that it's a transient issue.
- **Never fix the symptom** — if the logs say "connection refused", do not just add a retry loop; find out WHY the connection is refused.
- **Never close a bug without reproducing it.** Unreproducible bugs are unfinished bugs.
- **Never claim a hypothesis is confirmed without showing the evidence.** Log output, test output, or code trace — attach it.
- **Never guess from memory what an error message means.** WebSearch it.

## Examples

### ❌ Bad debug
> The service seems to be crashing sometimes. Probably a memory issue. I'll add `max_old_space_size=4096` and restart.

### ✅ Good debug
> Reproduced the crash by sending 50 concurrent requests to `/api/upload`. `pm2 logs` showed `FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory` at 15:42:03. Traced to `src/upload-handler.ts:45`, which calls `await file.arrayBuffer()` without streaming — so a 200MB upload × 50 concurrent = 10GB heap pressure. Fix: switch to `createReadStream` and pipe directly to S3 client. Verified: 50 concurrent 200MB uploads now peak at ~400MB RSS, no crashes.

© NYCU-Chung · MIT · NYCU-Chung/my-claude-devteam

Похожие субагенты

Все субагенты по теме «DevOps и инфраструктура» →

Сначала — debugger от других авторов.

debugger VoltAgent Community Субагент debugger диагностирует сбои, разбирает логи и устраняет первопричины багов в проекте. Пригодится при падениях сервиса или плавающих ошибках. CX Codex 13 459установок debugger VoltAgent Субагент debugger изолирует баги по трассировкам стека, упавшим тестам и рантайм-логам. Находит причину сбоя и предлагает минимальное исправление. CX Codex ★ 6 505звёзд репо debugger Rohit Ghumare Субагент debugger для Claude Code системно ищет причины сложных ошибок, падений тестов и сбоев во время выполнения. Подключается к задачам, где нужно сначала разобраться в баге, а потом предлагать исправление. CX Codex ★ 2 966звёзд репо debugger CloudAI-X Субагент debugger ищет первопричину падений тестов, утечек памяти и сбоев в коде. Субагент проверяет гипотезы через воспроизведение и логирование, избегая слепых правок. CX Codex ★ 1 424звёзд репо debugger qdhenry Субагент debugger отладки для Claude Code: ищет первопричины сбоев, разбирает упавшие тесты и готовит минимальный патч. CX Codex ★ 1 357звёзд репо trail Pratham-Mishra04 Плагин подключает MCP-сервер trail к Claude Code для анализа локальных логов и запускает пошаговый сценарий отладки с обязательной очисткой добавленного кода. ★ 8звёзд репо adk-debugger botpress Скилл adk-debugger для Claude Code помогает выяснить, почему ADK-агент отвечает неверно, зависает или не проходит сборку. Разбирает логи и трассировки, а также ведёт по шагам проверки после исправления. CX Codex +1 1 700установок docker-debugger OneWave-AI Скилл docker-debugger для Claude Code разбирает сбои сборки и запуска контейнеров, проблемы сети и томов, настройки docker-compose. Находит причины ошибок и предлагает исправления конфигурации. CX Codex +1 314установок containers Microsoft Плагин containers для GitHub Copilot управляет контейнерами и образами Docker или Podman. Показывает логи, слои образов и потребление ресурсов. ★ 11звёзд репо pod-doctor runpod Скилл pod-doctor находит причины сбоев в подах Runpod: ошибки 502, пропажу GPU после перезагрузки или зависание при старте. Диагностирует проблемы только в режиме чтения. CX Codex +1 3 700установок debug-openshell-cluster NVIDIA Скилл debug-openshell-cluster помогает диагностировать сбои шлюза OpenShell, проблемы со средами Docker, Podman и Kubernetes, а также ошибки запуска песочниц. CX Codex +1 739установок

Из того же набора13

Весь набор →
web-researcher Субагент web-researcher ищет точные факты в официальной документации, спецификациях API и чейнджлогах без изменения файлов проекта. CX Codex ★ 267звёзд репо onboarder Субагент onboarder для Claude Code, который строит структурированную модель незнакомой кодовой базы: архитектуру, точки входа, ключевые модули, зависимости и проблемные области. Работает в режиме чтения. CX Codex ★ 267звёзд репо db-expert Субагент db-expert проверяет схемы, миграции и запросы на риск потери данных, блокирующие локи и N+1, перед тем как изменение попадёт в мастер. CX Codex ★ 267звёзд репо refactor-specialist Субагент refactor-specialist для Claude Code помогает безопасно менять структуру кода в нескольких файлах. Он подключается для переименования сущностей, переноса файлов и выделения модулей. CX Codex ★ 267звёзд репо migration-engineer Субагент migration-engineer ведёт мажорные апгрейды фреймворков и библиотек: читает changelog, находит все вызовы изменившегося API и правит по шагам с проверкой после каждого. CX Codex ★ 267звёзд репо tool-expert Субагент tool-expert выбирает подходящие инструменты для задач в Claude Code, связывает их в цепочки и разбирается в причинах сбоев MCP-серверов. CX Codex ★ 267звёзд репо frontend-designer Субагент frontend-designer проектирует и собирает страницы, панели и компоненты с заданным визуальным направлением. Подключайте его для новой UI или редизайна существующей страницы. CX Codex ★ 267звёзд репо planner planner — субагент-технический лид для Claude Code: читает код проекта и делит задачу на параллельные подзадачи с чёткими контрактами. Сам код не пишет, а готовит промпты другим субагентам. CX Codex ★ 267звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой