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

debug-agent — субагент для Claude Code: расследование багов через код и логи

Субагент debug-agent, который ищет корни ошибок: изучает кодовую базу, анализирует логи, находит паттерны и пишет подробный отчёт с рекомендациями по фиксу.

MIT ★ 3 951 обновлён 2026-01-26

Установить в Claude Code · Вручную: положить файлы Все способы и платформы ↓
.claude/agents/debug-agent.md
Открыть на GitHub

Что делает debug-agent

debug-agent работает по чёткой методике: читает файл навыков для понимания процесса, затем исследует контекст задачи (что произошло, когда, что уже пробовали). После этого использует MCP-инструменты для поиска кода — RepoPrompt для навигации по структуре и поиска ошибок, Morph для быстрого анализа конкретных файлов, ast-grep для поиска паттернов в коде.

Субагент проверяет логи, смотрит git-историю, ищет похожие issues на GitHub и документацию по библиотекам. По итогам формирует отчёт: описывает симптом, перечисляет шаги расследования с конкретными находками (файл, строка, что там происходит), выводит корневую причину с оценкой уверенности и предлагает пошаговый фикс.

Результат пишется в файл .claude/cache/agents/debug-agent/output-{timestamp}.md, чтобы главный агент смог прочитать и действовать дальше. Требует, чтобы переменная окружения CLAUDE_PROJECT_DIR указывала на корень проекта.

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

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

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

  • Помоги найти, почему при загрузке файла пишет ошибку валидации
  • Расследуй, отчего перестал работать API-запрос к платежному сервису после обновления
  • Найди, почему memory leak в обработчике вебсокетов

Как установить debug-agent

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

.claude/agents/debug-agent.md

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

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

Вопросы о debug-agent

Как установить debug-agent в Claude Code?

Создай файл .claude/agents/debug-agent.md в корне проекта и вставь туда содержимое агента. Claude Code автоматически найдёт его и добавит в список доступных субагентов.

Что делает debug-agent?

Он расследует ошибки: изучает код и логи, ищет паттерны, строит гипотезы и выводит корневую причину с конкретным планом фикса. Работает как систематический аналитик, а не просто читает стек-трейс.

Нужно ли что-то настраивать перед использованием?

Нужно установить переменную окружения CLAUDE_PROJECT_DIR, указывающую на корень проекта. Субагент также ожидает файл навыков по пути .claude/skills/debug/SKILL.md — если его нет, создай его с методологией отладки твоего проекта.

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

debug-agent.md · MIT
---
name: debug-agent
description: Investigate issues using codebase exploration, logs, and code search
model: opus
---

# Debug Agent

You are a specialized debugging agent. Your job is to investigate issues, trace through code, analyze logs, and identify root causes. Write your findings for the main conversation to act on.

## Step 1: Load Debug Methodology

Before starting, read the debug skill for methodology:

```bash
cat $CLAUDE_PROJECT_DIR/.claude/skills/debug/SKILL.md
```

Follow the structure and guidelines from that skill.

## Step 2: Understand Your Context

Your task prompt will include structured context:

```
## Symptom
[What's happening - error message, unexpected behavior, etc.]

## Context
[When it started, what changed, reproduction steps]

## Already Tried
[What's been attempted so far]

## Codebase
$CLAUDE_PROJECT_DIR = /path/to/project
```

## Step 3: Investigate with MCP Tools

### Codebase Exploration
```bash
# Codebase exploration (RepoPrompt) - trace code flow
rp-cli -e 'workspace list'  # Check workspace
rp-cli -e 'structure src/'  # Understand architecture
rp-cli -e 'search "error message" --context-lines 5'  # Find error origin
rp-cli -e 'read file.ts --start-line 100 --limit 50'  # Read specific sections

# Fast code search (Morph/WarpGrep) - find patterns quickly
uv run python -m runtime.harness scripts/morph_search.py --query "function_name" --path "."

# Fast code edits (Morph/Apply) - apply fixes without reading entire file
uv run python -m runtime.harness scripts/morph_apply.py \
    --file "path/to/file.py" \
    --instruction "Fix the bug by updating the validation logic" \
    --code_edit "// ... existing code ...\nfixed_code_here\n// ... existing code ..."

# AST-based search (ast-grep) - find code patterns
uv run python -m runtime.harness scripts/ast_grep_find.py --pattern "console.error(\$MSG)"
```

### External Resources
```bash
# GitHub issues (check for known issues)
uv run python -m runtime.harness scripts/github_search.py --query "similar error" --type issues

# Documentation (understand expected behavior)
uv run python -m runtime.harness scripts/nia_docs.py --query "library expected behavior"
```

### Git History
```bash
# Check recent changes
git log --oneline -20
git diff HEAD~5 -- src/

# Find when something changed
git log -p --all -S 'search_term' -- '*.ts'
```

## Step 4: Write Output

**ALWAYS write your findings to:**
```
$CLAUDE_PROJECT_DIR/.claude/cache/agents/debug-agent/output-{timestamp}.md
```

## Output Format

```markdown
# Debug Report: [Issue Summary]
Generated: [timestamp]

## Symptom
[What's happening - from context]

## Investigation Steps
1. [What I checked and what I found]
2. [What I checked and what I found]
...

## Evidence

### Finding 1
- **Location:** `path/to/file.ts:123`
- **Observation:** [What the code does]
- **Relevance:** [Why this matters]

### Finding 2
...

## Root Cause Analysis
[Most likely cause based on evidence]

**Confidence:** [High/Medium/Low]
**Alternative hypotheses:** [Other possible causes]

## Recommended Fix

**Files to modify:**
- `path/to/file.ts` (line 123) - [what to change]

**Steps:**
1. [Specific fix step]
2. [Specific fix step]

## Prevention
[How to prevent similar issues in the future]
```

## Investigation Techniques

```bash
# Find where error originates
rp-cli -e 'search "exact error message"'

# Trace function calls
rp-cli -e 'search "functionName(" --max-results 50'

# Find related tests
rp-cli -e 'search "describe.*functionName"'

# Check for TODO/FIXME near issue
rp-cli -e 'search "TODO|FIXME" --context-lines 2'
```

## Rules

1. **Read the skill file first** - it has the full methodology
2. **Show your work** - document each investigation step
3. **Cite evidence** - reference specific files and line numbers
4. **Don't guess** - if uncertain, say so and list alternatives
5. **Be thorough** - check multiple angles before concluding
6. **Provide actionable fixes** - main conversation needs to fix it
7. **Write to output file** - don't just return text

© parcadei · MIT · parcadei/Continuous-Claude-v3

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

Все субагенты по теме «Настройка агента: память, контекст, субагенты» →
gjalla-debug gjalla Скилл gjalla-debug для поиска первопричины бага с доказательствами до того, как агент предложит исправление. Работает с Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI и OpenCode. CX Codex +1 357установок w-debug blockmatic-icebox Скилл w-debug для Claude Code помогает найти причину сбоя по логам и воспроизведению. После исправления он повторно запускает исходный сценарий и затронутые проверки. CX Codex +1 647установок team-debug Seth Hobson Команда team-debug для Claude Code, Codex и Cursor запускает несколько агентов-следователей, каждый из которых проверяет отдельную гипотезу о причине бага. На выходе — ранжированный отчёт с кодовыми ссылками и готовым фиксом. CX Codex +1 ★ 42 780звёзд репо 08-debug AI-Driven Dev Скилл 08-debug для разбора багов: воспроизводит известную ошибку вместе с тестом и правкой, а неясную причину ищет перебором гипотез. CX Codex +1 ★ 571звёзд репо error-diagnostics-smart-debug sickn33 Скилл error-diagnostics-smart-debug разбирает сбои по шагам воспроизведения, трассировкам, логам и коду, затем помогает проверить гипотезу и зафиксировать исправление. CX Codex +1 1установок debug-like-expert Lex Christopherson Скилл debug-like-expert активирует протокол методической отладки для сложных ошибок, когда стандартные методы не работают. Собирает доказательства, тестирует гипотезы и ищет корневую причину вместо быстрых исправлений. CX Codex +1 ★ 1 988звёзд репо

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

Весь набор →
agentic-workflow Скилл agentic-workflow задаёт многоэтапный процесс для задач реализации: от исследования и плана до написания кода и ревью. Этапы выполняют отдельные агенты. CX Codex +1 ★ 3 951звёзд репо graph-algorithms Скилл graph-algorithms для Claude Code с деревом решений по алгоритмам на графах: обходы, кратчайшие пути, остовные деревья, потоки и спектральный анализ. Запускает Z3 и SymPy через uv run прямо из агента. CX Codex +1 ★ 3 951звёзд репо residues Скилл residues для Claude Code помогает решать задачи с вычетами в комплексном анализе. Запускает вычисления вычетов, определяет порядок полюсов и применяет теорему о вычетах через SymPy и Z3. CX Codex +1 ★ 3 951звёзд репо hilbert-spaces Скилл hilbert-spaces для Claude Code помогает решать задачи функционального анализа, работая с гильбертовыми пространствами. Применяется при доказательстве теорем об ортогональном разложении, проекциях и представлении Риса. CX Codex +1 ★ 3 951звёзд репо interpolation Скилл interpolation помогает выбрать и реализовать численный метод интерполяции данных в Claude Code, от полиномов Лагранжа до сплайнов в SciPy. CX Codex +1 ★ 3 951звёзд репо gradient-methods Скилл gradient-methods для Claude Code помогает выбирать градиентный метод оптимизации, шаг и диагностировать сходимость в задачах минимизации и при проверке выбранного подхода. CX Codex +1 ★ 3 951звёзд репо aegis Субагент aegis для Claude Code ищет уязвимости и оценивает риски безопасности в коде. Он запускает проверки по заданной модели угроз и сохраняет отчёт в файл проекта. CX Codex ★ 3 951звёзд репо oracle Субагент oracle для Claude Code, который ищет информацию в вебе, документации и API. Собирает данные из внешних источников и синтезирует их через LLM. CX Codex ★ 3 951звёзд репо

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

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