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

devkit.fix-debugging — команда для Claude Code

Команда devkit.fix-debugging для Claude Code пошагово находит причины ошибок и готовит точечные исправления с помощью субагентов под нужный стек.

MIT ★ 372 обновлён 2026-09-10

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

Что делает devkit.fix-debugging

Команда запускает многоэтапный разбор бага с фиксацией шагов в TodoWrite. Через параметр --lang можно указать стек: Java, Spring, TypeScript, NestJS, React, Python, AWS или general. Под каждый вариант назначаются профильные субагенты для отладки, архитектурной оценки и код-ревью.

Процесс разбит на фазы с контрольными точками. На этапе фиксации проблемы агент запрашивает детали через инструмент AskUserQuestion и останавливается — пока пользователь не ответит на вопросы об ошибке и окружении, переход к исследованию заблокирован. Затем параллельно запускаются субагенты general-debugger, которые анализируют стек-трейсы, ход выполнения и свежие коммиты в git.

Для работы команды требуются субагенты из пакетов developer-kit, поскольку передача задач через инструмент Task опирается именно на них.

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

  • локализовать скрытую причину ошибки приложения по логам и стек-трейсу
  • проверить последние коммиты git на внесённые регрессии
  • подключить профильных субагентов под TypeScript, Python или Java
  • составить минимальный план исправления бага без разрастания правок

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

  • /developer-kit:devkit.fix-debugging --lang=python TypeError: unsupported operand type(s) for +: 'int' and 'str'
  • /developer-kit:devkit.fix-debugging --lang=react форма логина не отправляет запрос после клика
  • /developer-kit:devkit.fix-debugging --lang=spring NullPointerException in UserService.findUser

Как установить devkit.fix-debugging

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

/plugin marketplace add giuseppe-trisciuoglio/developer-kit
/plugin install developer-kit@developer-kit

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

.claude/commands/devkit.fix-debugging.md

Вызов — /devkit.fix-debugging. Для всех проектов — ~/.claude/commands/

Вопросы о devkit.fix-debugging

Как установить devkit.fix-debugging в Claude Code?

Выполните команду /plugin marketplace add giuseppe-trisciuoglio/developer-kit, а затем установите пакет через /plugin install developer-kit@developer-kit. Также можно скопировать файл команды в .claude/commands/devkit.fix-debugging.md.

Какие платформы и языки поддерживает команда?

Параметр --lang поддерживает значения java, spring, typescript, ts, nestjs, react, aws, python, py и general.

Почему агент останавливает выполнение в первой фазе?

В сценарии заложен обязательный барьер через AskUserQuestion. Агент ждёт ответов о воспроизведении бага и логах, поэтому без данных от разработчика к поиску улик он не переходит.

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

devkit.fix-debugging.md · MIT
---
description: Provides guided bug fixing and debugging capability with systematic root cause analysis. Use when encountering bugs, errors, or unexpected behavior.
argument-hint: "[ --lang=java|spring|typescript|nestjs|react|python|general ] [ issue-description or error-message ]"
allowed-tools: Task, Read, Write, Edit, Bash, Grep, Glob, TodoWrite, AskUserQuestion
model: inherit
---

# Fix & Debugging
## Overview

You are helping a developer fix a bug or debug an issue. Follow a systematic approach: understand the problem, trace the
root cause, design a minimal fix, then implement and verify.

## Usage

```bash
/developer-kit:devkit.fix-debugging [--lang=java|spring|typescript|nestjs|react|python|general] [issue-description or error-message]
```

## Arguments

| Argument | Description |
|----------|-------------|
| `$ARGUMENTS` | Combined arguments passed to the command |

## Current Context

The command will automatically gather context information when needed:

- Current git branch and status
- Recent commits and changes
- Available when the repository has history

## Execution Instructions

**Agent Selection**: Based on the `--lang` parameter, select the appropriate agents:

## Integration with Sub-agents

This command leverages specialized sub-agents using the Task tool.

## Language/Framework Selection

Parse $ARGUMENTS to detect the optional `--lang` parameter:

- `--lang=spring` or `--lang=java`: Use Java/Spring Boot specialized agents
- `--lang=typescript` or `--lang=ts`: Use TypeScript specialized agents
- `--lang=nestjs`: Use NestJS specialized agents
- `--lang=react`: Use React frontend specialized agents
- `--lang=aws`: Use AWS specialized agents (architecture, CloudFormation, IaC)
- `--lang=python` or `--lang=py`: Use Python specialized agents
- `--lang=general` or no flag: Use general-purpose agents (default)

**Agent Mapping by Language:**

| Phase       | General (default)                          | Java/Spring Boot (`--lang=spring` or `--lang=java`) | TypeScript (`--lang=typescript` or `--lang=ts`)                 | NestJS (`--lang=nestjs`)                                        | React (`--lang=react`)                                     | AWS (`--lang=aws`)                                 | Python (`--lang=python` or `--lang=py`)                 |
|-------------|--------------------------------------------|-----------------------------------------------------|-----------------------------------------------------------------|-----------------------------------------------------------------|------------------------------------------------------------|----------------------------------------------------|---------------------------------------------------------|
| Debugger    | `developer-kit:general-debugger`           | `developer-kit:general-debugger`                    | `developer-kit:general-debugger`                                | `developer-kit:general-debugger`                                | `developer-kit:general-debugger`                           | `developer-kit:general-debugger`                   | `developer-kit:general-debugger`                        |
| Architect   | `developer-kit:general-software-architect` | `developer-kit-java:java-software-architect-review` | `developer-kit-typescript:typescript-software-architect-review` | `developer-kit-typescript:typescript-software-architect-review` | `developer-kit-typescript:react-software-architect-review` | `developer-kit-aws:aws-solution-architect-expert`  | `developer-kit-python:python-software-architect-expert` |
| Code Review | `developer-kit:general-code-reviewer`      | `developer-kit-java:spring-boot-code-review-expert` | `developer-kit-typescript:general-code-reviewer`                | `developer-kit-typescript:nestjs-code-review-expert`            | `developer-kit-typescript:general-code-reviewer`           | `developer-kit-aws:aws-architecture-review-expert` | `developer-kit-python:python-code-review-expert`        |

## Core Principles

- **Understand before fixing**: Never fix what you don't understand
- **Find root cause**: Symptoms can be deceiving - trace back to the real issue
- **Minimal changes**: Fix only what's broken, avoid scope creep
- **Verify completely**: Confirm the fix works and doesn't break other things
- **Use TodoWrite**: Track all progress throughout
- **Structured user interaction — NEVER SKIP**: Phases marked with **[GATE]** STOP are hard gates. You MUST call the
  AskUserQuestion tool and wait for the user's response before proceeding. Skipping these stops or proceeding without
  user input is a workflow violation. Use AskUserQuestion in Phase 1: Problem Capture, Phase 3: Root Cause Analysis,
  Phase 4: Fix Design, and Phase 7: Verification. Always use AskUserQuestion for clarifications, confirmations, and
  decisions rather than plain text questions.
- **No time estimates**: DO NOT provide or request time estimates or implementation timelines at any phase

---

## Phase 1: Problem Capture

**Goal**: Understand exactly what's wrong

**Initial issue**: $ARGUMENTS

**Actions**:

1. Create todo list with all phases
2. Gather problem details:
    - What is the exact error message or unexpected behavior?
    - When did this start happening?
    - Can you reproduce it consistently?
    - What are the reproduction steps?
    - Any recent changes that might be related?
3. **You MUST call the AskUserQuestion tool to gather all missing information in a clear, organized format**:
    - Error messages, logs, or stack traces
    - Steps to reproduce
    - Expected vs actual behavior
    - Environment details (local, staging, production)
4. ****[GATE]** STOP: Wait for the user's answers. Do NOT proceed to Phase 2 until the user has responded.**

---

## Phase 2: Evidence Collection

**Goal**: Gather all relevant information about the failure

**Actions**:

1. Use the Task tool to launch 2-3 general-debugger subagents in parallel with different focuses:
    - Analyze stack traces and error messages
    - Trace execution paths related to the failure
    - Check recent git changes that might have introduced the bug

   **Example Task tool usage**:

```
Task(
  description: "Analyze error and trace execution path",
  prompt: "Analyze this error: [error description]. Trace the execution path from entry point to failure. Identify the exact failure point and potential causes.",
  subagent_type: "general-debugger"
)
```

**Example agent prompts**:

- "Analyze this stack trace: [trace]. Identify the root cause and exact failure point"
- "Trace the execution flow for [feature/function] and identify where it deviates from expected behavior"
- "Check recent git changes (last 5-10 commits) for changes that could have caused [issue]"
- "Analyze the data flow for [operation] and identify where data becomes corrupted/invalid"

2. Once agents return, read all identified critical files
3. Compile evidence summary with key findings

---

## Phase 3: Root Cause Analysis

**Goal**: Identify the exact root cause of the issue

**CRITICAL**: Do not proceed to fixing until root cause is confirmed.

**Actions**:

1. Use the Task tool to launch 2 general-debugger subagents with analysis focus:
    - Deep dive into the most likely failure point
    - Verify hypothesis with code analysis

2. Synthesize findings into root cause statement:
    - **What**: Exact condition causing the failure
    - **Where**: File and line where the bug originates
    - **Why**: Underlying reason this happens
    - **When**: Conditions that trigger the bug

3. **You MUST call the AskUserQuestion tool to confirm root cause with user before proceeding**
4. ****[GATE]** STOP: Wait for user confirmation. Do NOT proceed to Phase 4 until the user has responded.**

---

## Phase 4: Fix Design

**Goal**: Design the minimal, safest fix

**DO NOT PROCEED WITHOUT ROOT CAUSE CONFIRMATION**

**Actions**:

1. Use the Task tool to launch 2-3 general-software-architect subagents in parallel with different approaches:
    - Minimal surgical fix (smallest possible change)
    - Defensive fix (adds guards and validation)
    - Comprehensive fix (addresses similar issues elsewhere)

2. Review approaches considering:
    - Risk of regression
    - Side effects on other code
    - Test coverage implications

3. Present to user:
    - Brief summary of each approach
    - Trade-offs and risks
    - **Your recommendation with reasoning**

4. **You MUST call the AskUserQuestion tool to ask user which approach they prefer**
5. ****[GATE]** STOP: Wait for the user's choice. Do NOT proceed to Phase 5 until the user has responded.**

---

## Phase 5: Implementation

**Goal**: Implement the fix

**DO NOT START WITHOUT USER APPROVAL**

**Actions**:

1. Wait for explicit user approval
2. Re-read all affected files to ensure current state
3. Implement fix following chosen approach
4. Make minimal, focused changes
5. Add or update comments explaining the fix if non-obvious
6. Update todos as you progress

---

## Phase 6: Build & Test

**Goal**: Ensure the code compiles and all tests pass

**Actions**:

1. **Compile/Build** the project:
    - Run the appropriate build command for the project
    - Maven: `mvn compile` or `mvn package -DskipTests`
    - Gradle: `./gradlew build -x test` or `./gradlew compileJava`
    - npm: `npm run build`
    - Other: Use project-specific build command

2. **Fix any compilation errors** before proceeding

3. **Run tests**:
    - Run unit tests for affected components first
    - Run full test suite if quick tests pass
    - Maven: `mvn test` or `mvn verify`
    - Gradle: `./gradlew test`
    - npm: `npm test`

4. **If tests fail**:
    - Analyze failure: Is it related to our fix or pre-existing?
    - If related to fix: Return to Phase 5 and adjust
    - If pre-existing: Document and proceed (not our scope)

5. **Confirm all green** before proceeding to verification

---

## Phase 7: Verification & Review

**Goal**: Confirm the fix is correct and doesn't introduce regressions

**Actions**:

1. Use the Task tool to launch 2 general-code-reviewer subagents:
    - Review fix for correctness and potential regressions
    - Check for similar issues that might need the same fix

2. **Use the AskUserQuestion tool to confirm with user**:
    - Does the fix resolve the original issue?
    - Any unexpected behavior observed?
    - Should we add tests to prevent regression?

3. **Wait for user feedback before finalizing**

3. If regression tests needed:
    - Propose test cases that would catch this bug
    - **Use AskUserQuestion to ask if user wants to implement the tests**
    - Implement tests if user approves
    - Run tests again to confirm new tests pass

---

## Phase 8: Summary

**Goal**: Document what was fixed and learned

**Actions**:

1. Mark all todos complete
2. Summarize:
    - **Problem**: What was broken
    - **Root Cause**: Why it was broken
    - **Fix**: What was changed
    - **Files Modified**: List of changes
    - **Tests Added**: If any
    - **Prevention**: How to avoid similar issues

---

### General Agents (default, or `--lang=general`)

- **Debugger**: `developer-kit:general-debugger`
- **Software Architect**: `developer-kit:general-software-architect`
- **Code Reviewer**: `developer-kit:general-code-reviewer`

### Java/Spring Boot Agents (`--lang=spring` or `--lang=java`)

- **Debugger**: `developer-kit:general-debugger`
- **Software Architect**: `developer-kit-java:java-software-architect-review`
- **Code Reviewer**: `developer-kit-java:spring-boot-code-review-expert`

### TypeScript Agents (`--lang=typescript` or `--lang=ts`)

- **Debugger**: `developer-kit:general-debugger`
- **Software Architect**: `developer-kit-typescript:typescript-software-architect-review`
- **Code Reviewer**: `developer-kit:general-code-reviewer`

### NestJS Agents (`--lang=nestjs`)

- **Debugger**: `developer-kit:general-debugger`
- **Software Architect**: `developer-kit-typescript:typescript-software-architect-review`
- **Code Reviewer**: `developer-kit-typescript:nestjs-code-review-expert`

### React Agents (`--lang=react`)

- **Debugger**: `developer-kit:general-debugger`
- **Software Architect**: `developer-kit-typescript:react-software-architect-review`
- **Code Reviewer**: `developer-kit-typescript:general-code-reviewer`

### Python Agents (`--lang=python` or `--lang=py`)

- **Debugger**: `developer-kit:general-debugger`
- **Software Architect**: `developer-kit-python:python-software-architect-expert`
- **Code Reviewer**: `developer-kit-python:python-code-review-expert`
- **Security Expert**: `developer-kit-python:python-security-expert`

### AWS Agents (`--lang=aws`)

- **Debugger**: `developer-kit-aws:aws-architecture-review-expert`
- **Software Architect**: `developer-kit-aws:aws-solution-architect-expert`
- **Code Reviewer**: `developer-kit-aws:aws-architecture-review-expert`
- **CloudFormation Expert**: `developer-kit-aws:aws-cloudformation-devops-expert`

**Fallback**: If specialized agents are not available, fall back to `general-purpose` agent.

1. **general-debugger** - Analyzes errors, traces execution, finds root cause
2. **general-software-architect** / **java-software-architect-review** / **typescript-software-architect-review** -
   Designs fix approaches with trade-offs
3. **general-code-reviewer** / **spring-boot-code-review-expert** / **nestjs-code-review-expert** - Reviews fix for
   quality and regressions

### Agent Selection Pattern

```
// General agents (default)
Task(
  description: "Brief task description",
  prompt: "Detailed prompt for the sub-agent",
  subagent_type: "developer-kit:general-debugger"
)

// Java/Spring Boot agents (when --lang=spring or --lang=java)
Task(
  description: "Brief task description",
  prompt: "Detailed prompt for the sub-agent",
  subagent_type: "developer-kit-java:java-software-architect-review"
)

// TypeScript agents (when --lang=typescript or --lang=ts)
Task(
  description: "Brief task description",
  prompt: "Detailed prompt for the sub-agent",
  subagent_type: "developer-kit-typescript:typescript-software-architect-review"
)

// NestJS agents (when --lang=nestjs)
Task(
  description: "Brief task description",
  prompt: "Detailed prompt for the sub-agent",
  subagent_type: "developer-kit-typescript:nestjs-code-review-expert"
)

// React agents (when --lang=react)
Task(
  description: "Brief task description",
  prompt: "Detailed prompt for the sub-agent",
  subagent_type: "developer-kit-typescript:react-frontend-development-expert"
)

// Python agents (when --lang=python or --lang=py)
Task(
  description: "Analyze Python error and trace execution",
  prompt: "Analyze this Python error and identify the root cause",
  subagent_type: "developer-kit:general-debugger"
)

Task(
  description: "Review Python architecture",
  prompt: "Review the Python architecture using Clean Architecture and DDD principles",
  subagent_type: "developer-kit-python:python-software-architect-expert"
)

Task(
  description: "Review Python code quality",
  prompt: "Review Python code for quality, Pythonic patterns, and best practices",
  subagent_type: "developer-kit-python:python-code-review-expert"
)

// AWS agents (when --lang=aws)
Task(
  description: "Debug AWS infrastructure issue",
  prompt: "Analyze CloudFormation template and AWS resources to identify the root cause",
  subagent_type: "developer-kit-aws:aws-architecture-review-expert"
)

Task(
  description: "Fix CloudFormation template",
  prompt: "Review and fix the CloudFormation template issues",
  subagent_type: "developer-kit-aws:aws-cloudformation-devops-expert"
)

Task(
  description: "Redesign AWS architecture",
  prompt: "Propose architectural fixes following AWS best practices",
  subagent_type: "developer-kit-aws:aws-solution-architect-expert"
)
```

### Important Notes

- Each sub-agent operates with its own context window
- Multiple sub-agents can be launched in parallel for different perspectives
- The main Claude maintains control and coordination of the overall process

## Todo Management

Throughout the process, maintain a todo list like:

```
[ ] Phase 1: Problem Capture
[ ] Phase 2: Evidence Collection
[ ] Phase 3: Root Cause Analysis
[ ] Phase 4: Fix Design
[ ] Phase 5: Implementation
[ ] Phase 6: Build & Test
[ ] Phase 7: Verification & Review
[ ] Phase 8: Summary
```

Update the status as you progress through each phase.

---

## Quick Debug Mode

For simple issues, you can skip some phases:

**When to use quick mode**:

- Error message clearly points to the issue
- Recent, obvious change caused the bug
- Simple typo or configuration error

**Quick mode flow**:

1. Phase 1: Problem Capture (simplified)
2. Phase 3: Root Cause Analysis (focused)
3. Phase 5: Implementation
4. Phase 6: Build & Test
5. Phase 8: Summary

Tell the user: "This appears to be a straightforward issue. Would you like to proceed with quick debug mode?"

---

**Note**: This command follows a systematic debugging approach to ensure bugs are fixed correctly the first time, with
minimal risk of regression.

---

## Examples

```bash
# With error message (general agents)
/developer-kit:devkit.fix-debugging NullPointerException in UserService.getUserProfile()

# With bug description
/developer-kit:devkit.fix-debugging Users are seeing stale data after profile update

# Java/Spring Boot debugging
/developer-kit:devkit.fix-debugging --lang=spring Bean injection failing in OrderService

# TypeScript debugging
/developer-kit:devkit.fix-debugging --lang=typescript Type error in async handler

# NestJS debugging
/developer-kit:devkit.fix-debugging --lang=nestjs Dependency injection circular reference in AuthModule

# React debugging
/developer-kit:devkit.fix-debugging --lang=react Component not re-rendering after state update

# Python debugging
/developer-kit:devkit.fix-debugging --lang=python TypeError in async FastAPI endpoint handler

# Python debugging
/developer-kit:devkit.fix-debugging --lang=py Import circular dependency in Django models

# AWS infrastructure debugging
/developer-kit:devkit.fix-debugging --lang=aws CloudFormation stack creation failing with IAM error

# AWS architecture issues
/developer-kit:devkit.fix-debugging --lang=aws Lambda function timeout causing API Gateway 504 errors

# With test failure
/developer-kit:devkit.fix-debugging Test UserServiceTest.testGetProfile is failing intermittently

# With performance issue
/developer-kit:devkit.fix-debugging API response time increased from 50ms to 2s after last deploy

# With production issue
/developer-kit:devkit.fix-debugging Production errors: "Connection pool exhausted" every 2 hours
```

© Giuseppe Trisciuoglio · MIT · giuseppe-trisciuoglio/developer-kit

Похожие слэш-команды

Все слэш-команды по теме «Тесты и QA» →
quick-fix CloudAI-X Команда quick-fix для быстрого исправления ошибок линтера, типов и простых багов. Находит проблему, применяет минимальную правку, запускает проверку. CX Codex +1 ★ 1 424звёзд репо java-debugging официальный github Скилл java-debugging для GitHub Copilot ведёт агента по методике поиска причины бага в Java: воспроизвести, сузить, проверить гипотезу, подключить отладчик. Использует логи и логпоинты вместо брейкпоинтов. CX Codex +1 1установок debugging-streamlit streamlit Скилл debugging-streamlit запускает отладку приложений и компонентов Streamlit через команду make debug с горячей перезагрузкой, сбором логов и скриншотами через Playwright. CX Codex +1 502установок Debugging pluginagentmarketplace Скилл Debugging разбирает отладку Python по шагам: pdb, точки останова в IDE, logging, профилирование и чтение traceback — с командами и примерами. CX Codex +1 233установок systematic-debugging Jesse Vincent Скилл systematic-debugging для Claude Code и Codex блокирует фиксы до завершения анализа первопричины. Включается при падении тестов, баге или неожиданном поведении. CX Codex +1 306 118установок debugging-and-error-recovery addyosmani Скилл debugging-and-error-recovery для Claude Code помогает найти первопричину сбоя и проверить исправление. Он включается при падении тестов, ошибках сборки и неожиданном поведении кода. CX Codex +1 79 600установок

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

Весь набор →
clean-architecture Скилл clean-architecture раскладывает PHP-проект на слои Domain, Application, Adapter и Infrastructure и даёт шаблоны сущностей, value objects и портов без привязки к Symfony. CX Codex +1 ★ 372звёзд репо speckit.optimize Команда speckit.optimize анализирует tasks.md, находит скрытые зависимости и строит план параллельного выполнения задач до запуска реализации. CX Codex +1 ★ 372звёзд репо aws-cloudformation-devops-expert Субагент aws-cloudformation-devops-expert для Claude Code создаёт и проверяет шаблоны CloudFormation, связывает стеки и готовит автоматизацию развёртывания AWS. Работает с задачами Infrastructure as Code и CI/CD. CX Codex ★ 372звёзд репо react-software-architect-review Субагент react-software-architect-review для Claude Code разбирает архитектуру React-приложения: компоненты, состояние, поток данных и производительность. Помогает пересмотреть структуру проекта на React 19 или Next.js. CX Codex ★ 372звёзд репо php-refactor-expert Субагент php-refactor-expert разбирает PHP-код и предлагает рефакторинг с сохранением поведения. Запускайте его после реализации функции или когда код трудно читать и поддерживать. CX Codex ★ 372звёзд репо java-tutorial-engineer Субагент java-tutorial-engineer пишет пошаговые учебные материалы по Java: от базового Spring Boot до интеграции с LangChain4j. Встраивает примеры кода, упражнения и траектории обучения в проект. CX Codex ★ 372звёзд репо devkit.java.dependency-audit Команда devkit.java.dependency-audit проверяет зависимости Java на Maven и Gradle: находит уязвимости по базам CVE, выявляет несовместимые лицензии и оценивает риски в цепочке поставок перед релизом. CX Codex +1 ★ 372звёзд репо php-security-expert Субагент php-security-expert для Claude Code проверяет безопасность PHP-приложений. Подключается для аудита, настройки DevSecOps или внедрения требований безопасности в Laravel и Symfony. CX Codex ★ 372звёзд репо

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

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