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

technical-debt — скилл для Claude Code: аудит и установка

Скилл technical-debt для Claude Code находит технический долг в PHP/Laravel и Node/TypeScript/React, оценивает влияние и трудозатраты. Помогает составить план аудита и рефакторинга.

MIT 771 установок ★ 104 обновлён 2026-08-27

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add AsyrafHussin/agent-skills --skill technical-debt -a claude-code
Открыть на GitHub

Что делает technical-debt

technical-debt проверяет кодовую базу по 42 правилам в 10 категориях: код, безопасность, дизайн, зависимости, тесты, производительность, данные, документация, инфраструктура и процессы. Он ищет дублирование, сложные функции, уязвимые зависимости, проблемы с запросами, миграциями, тестами и конфигурацией.

Скилл определяет стек через composer.json и package.json, затем выбирает подходящие проверки. Для каждого пункта он формирует результат с описанием проблемы, местом в коде, оценкой усилий и влияния. Итогом становится реестр долга с приоритетами: критические проблемы идут первыми, а внутри приоритета сначала задачи с меньшими трудозатратами.

Область правил ограничена PHP/Laravel (MySQL) и Node/TypeScript/React, поэтому проекты на других стеках не покрываются заявленным набором проверок.

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

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

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

  • Проведи аудит технического долга во всём репозитории.
  • Проверь технический долг только в app/Services и составь список приоритетных исправлений.
  • Найди технический долг в проекте и укажи для каждой проблемы файл, трудозатраты и влияние.

Как установить technical-debt

1Через Skills CLI (Vercel)

npx skills add AsyrafHussin/agent-skills --skill technical-debt -a claude-code

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

~/.claude/skills/technical-debt/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/technical-debt/

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

Вопросы о technical-debt

Как установить technical-debt в Claude Code?

Выполните npx skills add AsyrafHussin/agent-skills --skill technical-debt -a claude-code, затем проверьте файл ~/.claude/skills/technical-debt/SKILL.md.

Что делает скилл technical-debt?

Он проводит аудит PHP/Laravel (MySQL) и Node/TypeScript/React-проектов, находит технический долг и строит приоритизированный реестр для рефакторинга.

Какие файлы нужны скиллу для определения стека?

Скилл проверяет composer.json и package.json, чтобы выбрать правила и команды для обнаруженного стека.

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

SKILL.md · MIT
---
name: technical-debt
description: Technical debt inventory, prioritization, and audit for PHP/Laravel (MySQL) and Node/TypeScript/React projects. Use when assessing code health, identifying refactoring candidates, planning debt paydown, or auditing a codebase for accumulated debt. Triggers on "audit technical debt", "find tech debt", "debt inventory", "what should we refactor first", or tasks involving code health, security debt, performance debt, data debt, observability debt, debt prioritization, or remediation planning.
license: MIT
metadata:
  author: agent-skills
  version: "1.0.0"
---

# Technical Debt

Technical debt audit and prioritization framework for **PHP/Laravel (MySQL) and Node/TypeScript/React** projects. Contains 42 rules across 10 categories covering code, security, design, dependency, test, performance, data, documentation, infrastructure, and process debt. Produces a ranked ledger (effort × impact) so teams know **what to fix first**, not just what's broken. Supports both **coding reference** and **audit mode** with PASS/FAIL/N/A output.

## Metadata

- **Version:** 1.0.0
- **Scope:** PHP / Laravel (MySQL) + Node / TypeScript / React
- **Rule Count:** 42 rules across 10 categories
- **License:** MIT

## How to Audit

When the user asks to "audit technical debt", "find tech debt", or "what should we refactor first" — run the checklist below against their codebase and produce a ranked debt ledger.

### Audit Step 1: Determine Scope

- If arguments provided (`$ARGUMENTS`): audit only those paths or modules
- If no arguments: audit the entire repository starting from the root

### Audit Step 2: Detect Project Stack

Inspect `composer.json` and `package.json` to determine which of the supported stacks (PHP/Laravel, Node/TypeScript/React, or both) is in use. Tooling commands (`composer outdated`, `npm outdated`, `phpstan`, `eslint`, `knip`, etc.) are chosen based on this detection.

### Audit Step 3: Run Debt Checklist

Work through every item below. For each, output:
- **PASS** — brief confirmation of what was verified
- **FAIL** — exact `file:line` (or command output), description of the debt, **effort estimate** (S/M/L), and **impact** (LOW/MED/HIGH/CRITICAL)
- **N/A** — if the check does not apply to this project

#### Code Debt
- [ ] No duplicated blocks > 30 lines across files
- [ ] No function exceeds 50 lines or cyclomatic complexity > 10
- [ ] No class exceeds 300 lines or has > 15 public methods (god class)
- [ ] No unreachable code, unused exports, or commented-out blocks left in source
- [ ] No magic numbers or unexplained string literals in business logic
- [ ] No function exceeds 4 parameters (use a parameter object)

#### Security Debt
- [ ] No secrets, API keys, or credentials committed to source (or git history)
- [ ] Every public endpoint validates input via a schema / FormRequest / DTO
- [ ] Passwords hashed with bcrypt or argon2id; no MD5/SHA-1
- [ ] Sessions have a bounded lifetime; auth-sensitive endpoints rate-limited
- [ ] Security headers present (CSP, HSTS, X-Content-Type-Options, Referrer-Policy)
- [ ] Authorization (not just authentication) enforced on every protected route

#### Design Debt
- [ ] No circular dependencies between modules/packages
- [ ] Layers respect direction (UI → service → repository, never reversed)
- [ ] No "shotgun surgery" patterns (one change forcing edits in 5+ files)
- [ ] Abstractions hide implementation details (no leaking framework types across boundaries)

#### Dependency Debt
- [ ] No dependencies more than 2 major versions behind
- [ ] No abandoned/unmaintained packages (no release in > 24 months)
- [ ] No known CVEs reported by `npm audit` / `composer audit` at HIGH or CRITICAL
- [ ] No unused dependencies in `package.json` / `composer.json`

#### Test Debt
- [ ] Critical paths have integration test coverage
- [ ] No skipped/disabled tests without linked issue or removal date
- [ ] No known flaky tests left in main branch
- [ ] Test suite runs in under 10 minutes (or has explicit budget documented)

#### Performance Debt
- [ ] No N+1 query patterns on list endpoints (query count constant per request)
- [ ] No list endpoint returns an unbounded result set (pagination present)
- [ ] Frontend initial bundle within budget (~200 KB gzip); route-level code splitting in place
- [ ] Expensive read paths (aggregations, external APIs, static configs) are cached at a sensible layer

#### Data Debt
- [ ] Migrations are the only source of schema changes; production matches migration history
- [ ] All foreign-key and frequently-queried columns are indexed
- [ ] No orphaned child records; FK constraints enforced

#### Documentation Debt
- [ ] README reflects current setup and dev workflow
- [ ] No stale comments contradicting the code they describe
- [ ] Public APIs / exported modules have docblocks or type hints

#### Infrastructure Debt
- [ ] Runtime versions (Node, PHP) are on supported (non-EOL) releases
- [ ] No deprecated framework APIs in use (e.g., Laravel `Route::get()` deprecations)
- [ ] Build runs cleanly with zero warnings
- [ ] Secrets stored in a manager (Vault / Doppler / cloud SM); no long-lived shared credentials
- [ ] Structured logs, error tracking, p95 latency dashboards, and SLO-based alerts in place

#### Process Debt
- [ ] No `TODO`/`FIXME`/`HACK` comments older than 6 months without owner or ticket
- [ ] No `@deprecated` markers without a removal date or replacement
- [ ] Debt is tracked somewhere visible (issue tracker label, debt register, ADR)
- [ ] Every path has an owner (CODEOWNERS file present and current)
- [ ] No feature flags at 100% rollout for more than 6 weeks without a removal plan

### Audit Step 4: Build the Debt Ledger

End the audit with a prioritized table:

```
## Technical Debt Ledger

| # | Category | Item | File / Location | Effort | Impact | Priority |
|---|----------|------|-----------------|--------|--------|----------|
| 1 | deps | jQuery 1.12 (8y old, 3 CVEs) | package.json:14 | L | CRITICAL | P0 |
| 2 | code | OrderService god class (820 lines) | app/Services/OrderService.php | M | HIGH | P1 |
| 3 | test | 12 disabled tests in auth/ | tests/Feature/Auth/* | S | HIGH | P1 |
...

## Summary
- **PASS:** X checks
- **FAIL:** Y checks
- **N/A:** Z checks
- **Top 3 to pay down first:** (list highest-priority items with rationale)
```

**Priority formula:** `P0 = CRITICAL impact`, `P1 = HIGH impact`, `P2 = MED`, `P3 = LOW`. Within a priority, sort by ascending effort (cheap wins first).

**Effort scale:**
- **S** = under a day
- **M** = 1–5 days
- **L** = more than a week (likely needs to be broken down)

---

## When to Apply

Reference these guidelines when:
- Running a tech-debt audit on a codebase
- Planning a refactoring sprint or debt-paydown initiative
- Reviewing a PR that introduces shortcuts (and deciding whether to accept them)
- Building a debt register or backlog category in your issue tracker
- Justifying engineering investment to non-engineering stakeholders
- Onboarding to a new codebase and assessing its health
- Writing an ADR (architecture decision record) for a debt-related decision

## Step 1: Detect Project Stack

**Always detect the stack before running tooling.** This skill targets PHP / Laravel (with MySQL) and Node / TypeScript / React projects; detection commands below assume one or both are present.

| Signal | Stack | Tooling |
|--------|-------|---------|
| `composer.json` present | PHP / Laravel | `composer outdated`, `composer audit`, `phpstan`, `phpcs`, `phpmd`, `deptrac` |
| `package.json` present | Node / JS / TS / React | `npm outdated`, `npm audit`, `eslint`, `tsc --noEmit`, `knip`, `madge` |
| MySQL connection available | Database | `EXPLAIN`, `sys.schema_tables_with_full_table_scans`, `sys.schema_unused_indexes`, `sys.statement_analysis` |
| any repo | Secrets scan | `gitleaks git`, `trufflehog` |

If both stacks are present (e.g., Laravel + Inertia + React), run audits for each.

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Code Debt | CRITICAL | `code-` |
| 2 | Security Debt | CRITICAL | `security-` |
| 3 | Design Debt | HIGH | `design-` |
| 4 | Dependency Debt | HIGH | `deps-` |
| 5 | Test Debt | HIGH | `test-` |
| 6 | Performance Debt | HIGH | `perf-` |
| 7 | Data Debt | HIGH | `data-` |
| 8 | Documentation Debt | MEDIUM | `docs-` |
| 9 | Infrastructure Debt | MEDIUM | `infra-` |
| 10 | Process Debt | MEDIUM | `process-` |

## Quick Reference

### 1. Code Debt (CRITICAL)

- `code-duplication` — Detect and consolidate duplicated logic
- `code-complexity` — Cyclomatic and cognitive complexity thresholds
- `code-long-functions` — Function and method length limits
- `code-god-classes` — Class size and responsibility limits
- `code-dead-code` — Unused code, unreachable branches, commented blocks
- `code-magic-numbers` — Hardcoded literals in business logic
- `code-long-parameter-lists` — Functions with too many positional params

### 2. Security Debt (CRITICAL)

- `security-secrets-in-code` — API keys, passwords, tokens in source / history
- `security-input-validation` — Endpoints accepting untrusted input without schemas
- `security-auth-hardening` — Outdated auth, missing MFA, missing security headers

### 3. Design Debt (HIGH)

- `design-tight-coupling` — Excessive direct dependencies between modules
- `design-circular-deps` — Cyclic imports / requires
- `design-leaky-abstractions` — Framework types crossing layer boundaries
- `design-shotgun-surgery` — Changes that touch many files at once

### 4. Dependency Debt (HIGH)

- `deps-outdated-versions` — Major versions behind on dependencies
- `deps-abandoned-packages` — Unmaintained / abandoned libraries
- `deps-security-advisories` — Known CVEs in installed dependencies
- `deps-unused-deps` — Declared but unused packages

### 5. Test Debt (HIGH)

- `test-coverage-gaps` — Critical paths without tests
- `test-flaky-tests` — Tests with non-deterministic outcomes
- `test-disabled-tests` — Skipped tests left in the suite
- `test-slow-tests` — Tests blocking fast feedback

### 6. Performance Debt (HIGH)

- `perf-n-plus-one` — Linear request → quadratic database load
- `perf-missing-pagination` — Unbounded result sets
- `perf-bundle-bloat` — Heavy / unsplit frontend bundles
- `perf-no-caching` — Missing cache layers on read-heavy paths

### 7. Data Debt (HIGH)

- `data-schema-drift` — Production schema diverges from migrations
- `data-missing-indexes` — Hot queries doing sequential scans
- `data-orphaned-records` — Referential integrity gaps

### 8. Documentation Debt (MEDIUM)

- `docs-stale-comments` — Comments contradicting current behavior
- `docs-outdated-architecture` — README/architecture docs out of date
- `docs-undocumented-api` — Public APIs without docblocks or types

### 9. Infrastructure Debt (MEDIUM)

- `infra-runtime-versions` — EOL or near-EOL language/runtime versions
- `infra-deprecated-apis` — Framework deprecations still in use
- `infra-build-warnings` — Build/compile warnings ignored
- `infra-secrets-management` — Long-lived credentials, plain env files, leaked logs
- `infra-monitoring-gaps` — Missing logs, metrics, traces, alerts, or SLOs

### 10. Process Debt (MEDIUM)

- `process-todo-fixme-aging` — Aging TODO/FIXME/HACK comments
- `process-deprecated-markers` — `@deprecated` without removal plan
- `process-debt-tracking` — Debt visible in a register / backlog
- `process-ownership-gaps` — Code without an owning team (CODEOWNERS)
- `process-feature-flags-lingering` — Stale feature flags polluting code paths

## Essential Patterns

### Debt Ledger Output Format

```
| # | Category | Item                          | Location              | Effort | Impact   | Priority |
|---|----------|-------------------------------|-----------------------|--------|----------|----------|
| 1 | deps     | guzzle 6.x (5y behind)        | composer.json:18      | M      | HIGH     | P1       |
| 2 | code     | InvoiceService dup logic      | app/Services/Invoice* | S      | MEDIUM   | P2       |
| 3 | test     | 8 skipped tests in checkout/  | tests/Feature/Checkout| S      | HIGH     | P1       |
```

### Effort × Impact Prioritization

```
              LOW       MEDIUM    HIGH      CRITICAL
S (<1d)   →   P3        P2        P1        P0
M (1-5d)  →   P3        P2        P1        P0
L (>1w)   →   P3        P3        P2        P1   (break down)
```

Cheap + high-impact items go first. Expensive items always get broken down before scheduling.

### Tooling Cheatsheet

```bash
# PHP / Laravel
composer outdated --direct          # list outdated direct deps
composer audit                      # known CVEs
vendor/bin/phpstan analyse          # static analysis
vendor/bin/phpmd app text cleancode # mess detector

# Node / TS
npm outdated                        # list outdated deps
npm audit                           # known CVEs
npx depcheck                        # unused deps
npx tsc --noEmit                    # type errors
npx eslint . --max-warnings 0       # lint warnings

# Cross-language
git log --since="6 months ago" --diff-filter=A -p | grep -E "TODO|FIXME|HACK"
cloc .                              # lines of code per language
```

## How to Use

Read individual rule files for detailed explanations and code examples:

```
rules/code-duplication.md
rules/design-circular-deps.md
rules/deps-outdated-versions.md
rules/test-flaky-tests.md
rules/process-todo-fixme-aging.md
```

Each rule file contains:
- YAML frontmatter with metadata (title, impact, tags)
- Brief explanation of why it matters
- How to detect (commands / patterns)
- Incorrect example with explanation
- Correct example or remediation strategy

## References

- [Martin Fowler — Technical Debt Quadrant](https://martinfowler.com/bliki/TechnicalDebtQuadrant.html)
- [Ward Cunningham — The Debt Metaphor](https://www.youtube.com/watch?v=pqeJFYwnkjE)
- [SonarQube — Technical Debt Model](https://docs.sonarsource.com/sonarqube/latest/user-guide/metric-definitions/)
- [OWASP Dependency-Check](https://owasp.org/www-project-dependency-check/)
- [Snyk Open Source Vulnerability Database](https://security.snyk.io/)

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`

© agent-skills · MIT · AsyrafHussin/agent-skills

Похожие скиллы

Все скиллы по теме «Код-ревью и рефакторинг» →
remove-technical-debt wondelai Скилл remove-technical-debt для Claude Code и Codex помогает поэтапно выплачивать технический долг в легаси-проектах без переписывания с нуля. Он ведёт через восемь фаз с фиксацией решений в папке docs/. CX Codex +1 2 600установок technical-debt-manager davila7 Субагент technical-debt-manager находит архитектурные проблемы и дыры в тестах. Помогает составить план рефакторинга перед спринтом. CX Codex 857установок Technical Debt Remediation Plan официальный github Technical Debt Remediation Plan — субагент GitHub Copilot для пошагового планирования устранения техдолга. Анализирует TODO и устаревшие зависимости, не меняя файлы проекта. CX Codex +1 ★ 41 430звёзд репо tech-debt-analyzer ailabs-393 Скилл tech-debt-analyzer находит техдолг в проектах на JavaScript и TypeScript с помощью скриптов на Python, а затем помогает оформить реестр проблем и записи архитектурных решений. CX Codex +1 991установок code-auditor mhattingpete Скилл code-auditor для Claude Code разбирает репозиторий по шести направлениям: архитектура, качество кода, безопасность, производительность, тесты и поддерживаемость. Выявляет, что в кодовой базе болит. CX Codex +1 344установок technical-debt-assessment aj-geddes Скилл technical-debt-assessment помогает оцифровать техдолг, оценить трудозатраты на правки и расставить приоритеты перед рефакторингом или планированием спринта. CX Codex +1 511установок

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

Весь набор →
e2e-playwright-testing Скилл e2e-playwright-testing для Claude Code помогает писать и проверять сквозные тесты в Playwright. Активируется при работе с браузерными сценариями, формами и файлами в tests/e2e/. CX Codex +1 880установок code-slop Скилл code-slop находит паттерны сгенерированного ИИ кода в PHP/Laravel и TypeScript/React. Помогает при ревью пулреквестов отсеять избыточные обёртки, пустые тесты и очевидные комментарии. CX Codex +1 862установок state-management Скилл state-management для Claude Code помогает настраивать загрузку данных, кэширование и клиентское состояние через React Query и Zustand. Активируется при работе с useQuery, useMutation и хранилищами Zustand. CX Codex +1 849установок seo-best-practices Скилл seo-best-practices проверяет SEO веб-приложений и помогает внедрять метатеги, JSON-LD, sitemap, Open Graph и настройки Core Web Vitals. CX Codex +1 797установок laravel-queues Скилл laravel-queues помогает проектировать асинхронные задачи, настраивать Horizon, отлаживать застрявшие джобы и проверять здоровье очереди в Laravel 13. CX Codex +1 770установок prd-writing Скилл prd-writing для Claude Code помогает составить продуктовые требования: проводит агента через 6 этапов сбора контекста до кодинга и использует шаблон на 12 разделов. CX Codex +1 722установок project-docs Скилл project-docs ведёт документацию проекта от создания до уборки: раскладывает файлы по папкам, проверяет свежесть и вычищает мусор, оставшийся от ИИ. CX Codex +1 721установок laravel-ai-sdk Скилл laravel-ai-sdk с 17 правилами для пакета laravel/ai. Помогает проектировать агентов, генерировать медиа и настраивать RAG в проектах на Laravel 13. CX Codex +1 721установок

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

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