tech-debt-analyzer by ailabs-393/ai-labs-claude-skills
npx skills add https://github.com/ailabs-393/ai-labs-claude-skills --skill tech-debt-analyzer系统性地识别、分析、记录和跟踪 JavaScript/TypeScript 代码库中的技术债务。此技能提供自动化分析工具、全面的债务分类框架和文档模板,以维护技术债务登记册。
运行自动化脚本以检测整个代码库中的技术债务指标。
使用自动化检测器识别代码质量问题:
python3 scripts/detect_code_smells.py src --output markdown
该脚本分析:
any 类型输出示例:
# 技术债务分析报告
**已分析文件:** 127
**总行数:** 15,432
**总问题数:** 89
### 按严重程度分类的问题
- 高:23
- 中:41
- 低:25
## 大型文件 (12 个问题)
### 高优先级
- src/components/Dashboard.tsx (847 行):文件过大
- src/services/DataProcessor.ts (623 行):文件过大
...
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
检查依赖项中的债务指标:
python3 scripts/analyze_dependencies.py package.json
该脚本识别:
输出示例:
# 依赖分析报告
**包:** expense-tracker
**依赖项:** 24
**开发依赖项:** 18
**总问题数:** 7
## 已弃用/过时的包 (3)
### request [高]
使用已弃用的包 - 请改用 axios、node-fetch 或 got
- 当前版本:^2.88.0
## 重复功能 (2)
### HTTP 客户端 [中]
多个 HTTP 客户端包:axios, node-fetch
通过手动审查来补充自动化分析,以处理需要人工判断的问题。
架构债务:
测试债务:
文档债务:
性能债务:
安全债务:
使用标准化的债务类别来组织发现的问题。
有关以下内容的详细信息,请参阅 references/debt_categories.md:
根据影响和紧迫性分配严重性:
严重:
高:
中:
低:
| 影响 / 工作量 | 低工作量 | 中等工作量 | 高工作量 |
|---|---|---|---|
| 高影响 | 优先处理 | 其次处理 | 计划并处理 |
| 中等影响 | 其次处理 | 计划并处理 | 考虑 |
| 低影响 | 快速解决 | 考虑 | 避免 |
创建全面的技术债务文档。
使用提供的模板来维护债务登记册:
模板位置: assets/DEBT_REGISTER_TEMPLATE.md
结构:
## DEBT-001: 复杂的 UserService,共 847 行
**类别:** 代码质量
**严重性:** 高
**位置:** src/services/UserService.ts
**描述:**
UserService 已增长到 847 行,承担了多种职责,
包括认证、配置文件管理和通知处理。
**影响:**
- 业务:使功能开发速度降低 30%
- 技术:难以测试,错误率高
- 风险:更改经常破坏不相关的功能
**建议解决方案:**
拆分为独立服务:
- AuthenticationService
- UserProfileService
- NotificationService
**工作量估算:** 3 天
**优先级理由:** 高变更区域阻碍新功能
**目标解决时间:** 冲刺 24
登记册部分:
使用 ADR 记录重大技术决策,以防止未来产生债务。
模板位置: assets/ADR_TEMPLATE.md
何时创建 ADR:
示例:
# ADR-003: 从 Moment.js 迁移到 date-fns
**状态:** 已接受
**日期:** 2024-01-15
## 背景
Moment.js 已弃用,并使打包体积增加 67KB。
团队需要一个支持 tree-shaking 的现代日期库。
## 决策
迁移到 date-fns 进行日期操作。
## 后果
- 积极:减少打包体积 60KB,现代 API,积极维护
- 消极:迁移工作量,团队学习曲线
- 技术债务:无 - 这解决了现有的依赖债务
制定可操作的计划来解决技术债务。
推荐分配:
随时间监控债务减少情况:
要跟踪的指标:
实施实践以最小化新的技术债务。
在批准 PR 之前,验证:
代码检查和格式化:
{
"rules": {
"complexity": ["error", 10],
"max-lines-per-function": ["error", 50],
"max-params": ["error", 5],
"max-depth": ["error", 4],
"no-console": "warn"
}
}
必需检查项:
每周:
每月:
每季度:
根据情况遵循此工作流:
开始新的分析? → 运行自动化脚本 (detect_code_smells.py, analyze_dependencies.py) → 审查输出中的高严重性问题 → 对脚本无法检测的领域进行手动审查 → 转到文档步骤
记录发现? → 将 DEBT_REGISTER_TEMPLATE.md 复制到项目根目录 → 添加每个债务项及其完整详细信息 → 按类型分类并分配严重性 → 估算工作量并确定优先级 → 转到规划步骤
规划债务减少? → 按优先级矩阵 (影响/工作量) 排序 → 分配冲刺容量 (推荐 20%) → 为最高优先级项创建工单 → 安排定期审查
做出架构决策? → 复制 ADR_TEMPLATE.md → 记录背景、选项和决策 → 识别可能产生的任何债务 → 如果适用,添加到债务登记册
预防新债务? → 实施代码审查清单 → 配置自动化代码检查/测试 → 设置定期维护计划 → 随时间监控指标
目的: 自动化代码质量分析
用法:
python3 scripts/detect_code_smells.py [src-dir] [--output json|markdown]
检测:
输出: Markdown 报告或用于程序化处理的 JSON
目的: 依赖项健康分析
用法:
python3 scripts/analyze_dependencies.py [package.json-path]
检测:
输出: 带有建议的 Markdown 报告
技术债务类型的综合指南,包含:
在以下情况下加载此参考:
完整的技术债务登记册模板,包括:
使用此模板来:
架构决策记录模板,包括:
使用此模板来:
从分析到解决的完整工作流:
第 1 周:分析
# 运行自动化分析
python3 scripts/detect_code_smells.py src --output markdown > debt_analysis.md
python3 scripts/analyze_dependencies.py package.json >> debt_analysis.md
# 关键领域的手动审查
# - 认证逻辑
# - 支付处理
# - 数据模型
第 1-2 周:文档
# 从模板创建债务登记册
cp assets/DEBT_REGISTER_TEMPLATE.md TECHNICAL_DEBT.md
# 将发现添加到登记册,包括:
# - 类别和严重性
# - 影响评估
# - 工作量估算
# - 优先级分配
第 2 周:优先级排序
# 团队评审会议
# - 审查所有高/严重项
# - 讨论快速胜利 (高影响,低工作量)
# - 分配冲刺容量
# - 为前 5 项创建工单
第 3-6 周:修复
# 冲刺工作
# - 每个冲刺修复 2-3 个债务项
# - 解决项时更新债务登记册
# - 为重大重构决策创建 ADR
# - 监控指标
每月:审查
# 趋势分析
# - 总债务 (应减少)
# - 新增债务率 (应较低)
# - 最旧项的存在时间 (应减少)
# - 受影响最严重的类别
# 根据趋势调整策略
跟踪这些指标以衡量债务减少的有效性:
数量指标:
质量指标:
速度指标:
业务指标:
每周安装次数
66
仓库
GitHub 星标数
322
首次出现
2026 年 1 月 23 日
安全审计
安装于
opencode55
codex48
claude-code48
gemini-cli46
cursor46
github-copilot39
Systematically identify, analyze, document, and track technical debt in JavaScript/TypeScript codebases. This skill provides automated analysis tools, comprehensive debt categorization frameworks, and documentation templates to maintain a technical debt register.
Run automated scripts to detect technical debt indicators across the codebase.
Identify code quality issues using the automated detector:
python3 scripts/detect_code_smells.py src --output markdown
The script analyzes:
any type in TypeScriptOutput Example:
# Technical Debt Analysis Report
**Files Analyzed:** 127
**Total Lines:** 15,432
**Total Issues:** 89
### Issues by Severity
- HIGH: 23
- MEDIUM: 41
- LOW: 25
## Large Files (12 issues)
### High Priority
- src/components/Dashboard.tsx (847 lines): File too large
- src/services/DataProcessor.ts (623 lines): File too large
...
Examine dependencies for debt indicators:
python3 scripts/analyze_dependencies.py package.json
The script identifies:
Output Example:
# Dependency Analysis Report
**Package:** expense-tracker
**Dependencies:** 24
**Dev Dependencies:** 18
**Total Issues:** 7
## Deprecated/Outdated Packages (3)
### request [HIGH]
Using deprecated package - use axios, node-fetch, or got instead
- Current version: ^2.88.0
## Duplicate Functionality (2)
### HTTP client [MEDIUM]
Multiple packages for HTTP client: axios, node-fetch
Complement automated analysis with manual review for issues that require human judgment.
Architectural Debt:
Test Debt:
Documentation Debt:
Performance Debt:
Security Debt:
Organize findings using the standardized debt categories.
Refer to references/debt_categories.md for comprehensive details on:
Assign severity based on impact and urgency:
Critical:
High:
Medium:
Low:
| Impact / Effort | Low Effort | Medium Effort | High Effort |
|---|---|---|---|
| High Impact | Do First | Do Second | Plan & Do |
| Medium Impact | Do Second | Plan & Do | Consider |
| Low Impact | Quick Win | Consider | Avoid |
Create comprehensive documentation of technical debt.
Use the provided template to maintain a debt register:
Template Location: assets/DEBT_REGISTER_TEMPLATE.md
Structure:
## DEBT-001: Complex UserService with 847 lines
**Category:** Code Quality
**Severity:** High
**Location:** src/services/UserService.ts
**Description:**
UserService has grown to 847 lines with multiple responsibilities
including authentication, profile management, and notification handling.
**Impact:**
- Business: Slows down feature development by 30%
- Technical: Difficult to test, high bug rate
- Risk: Changes frequently break unrelated functionality
**Proposed Solution:**
Split into separate services:
- AuthenticationService
- UserProfileService
- NotificationService
**Effort Estimate:** 3 days
**Priority Justification:** High churn area blocking new features
**Target Resolution:** Sprint 24
Register Sections:
Document major technical decisions using ADRs to prevent future debt.
Template Location: assets/ADR_TEMPLATE.md
When to Create ADRs:
Example:
# ADR-003: Migrate from Moment.js to date-fns
**Status:** Accepted
**Date:** 2024-01-15
## Context
Moment.js is deprecated and increases bundle size by 67KB.
Team needs a modern date library with tree-shaking support.
## Decision
Migrate to date-fns for date manipulation.
## Consequences
- Positive: Reduce bundle by 60KB, modern API, active maintenance
- Negative: Migration effort, learning curve for team
- Technical Debt: None - this resolves existing dependency debt
Create actionable plans to address technical debt.
Recommended Allocation:
Monitor debt reduction over time:
Metrics to Track:
Implement practices to minimize new technical debt.
Before approving PRs, verify:
Linting and Formatting:
{
"rules": {
"complexity": ["error", 10],
"max-lines-per-function": ["error", 50],
"max-params": ["error", 5],
"max-depth": ["error", 4],
"no-console": "warn"
}
}
Required Checks:
Weekly:
Monthly:
Quarterly:
Follow this workflow based on the situation:
Starting a new analysis? → Run automated scripts (detect_code_smells.py, analyze_dependencies.py) → Review output for high-severity issues → Conduct manual review for areas scripts can't detect → Go to documentation step
Documenting findings? → Copy DEBT_REGISTER_TEMPLATE.md to project root → Add each debt item with full details → Categorize by type and assign severity → Estimate effort and prioritize → Go to planning step
Planning debt reduction? → Sort by priority matrix (impact/effort) → Allocate sprint capacity (20% recommended) → Create tickets for top priority items → Schedule regular reviews
Making architectural decisions? → Copy ADR_TEMPLATE.md → Document context, options, and decision → Identify any debt being incurred → Add to debt register if applicable
Preventing new debt? → Implement code review checklist → Configure automated linting/testing → Set up regular maintenance schedule → Monitor metrics over time
Purpose: Automated code quality analysis
Usage:
python3 scripts/detect_code_smells.py [src-dir] [--output json|markdown]
Detects:
Output: Markdown report or JSON for programmatic processing
Purpose: Dependency health analysis
Usage:
python3 scripts/analyze_dependencies.py [package.json-path]
Detects:
Output: Markdown report with recommendations
Comprehensive guide to technical debt types with:
Load this reference when:
Complete technical debt register template including:
Use this template to:
Architecture Decision Record template including:
Use this template to:
Complete workflow from analysis to resolution:
Week 1: Analysis
# Run automated analysis
python3 scripts/detect_code_smells.py src --output markdown > debt_analysis.md
python3 scripts/analyze_dependencies.py package.json >> debt_analysis.md
# Manual review of critical areas
# - Authentication logic
# - Payment processing
# - Data models
Week 1-2: Documentation
# Create debt register from template
cp assets/DEBT_REGISTER_TEMPLATE.md TECHNICAL_DEBT.md
# Add findings to register with:
# - Category and severity
# - Impact assessment
# - Effort estimation
# - Priority assignment
Week 2: Prioritization
# Team review session
# - Review all high/critical items
# - Discuss quick wins (high impact, low effort)
# - Allocate sprint capacity
# - Create tickets for top 5 items
Weeks 3-6: Remediation
# Sprint work
# - Fix 2-3 debt items per sprint
# - Update debt register as items resolved
# - Create ADRs for major refactoring decisions
# - Monitor metrics
Monthly: Review
# Trend analysis
# - Total debt (should decrease)
# - New debt rate (should be low)
# - Age of oldest items (should decrease)
# - Categories most affected
# Adjust strategy based on trends
Track these metrics to measure debt reduction effectiveness:
Quantity Metrics:
Quality Metrics:
Velocity Metrics:
Business Metrics:
Weekly Installs
66
Repository
GitHub Stars
322
First Seen
Jan 23, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode55
codex48
claude-code48
gemini-cli46
cursor46
github-copilot39
Skills CLI 使用指南:AI Agent 技能包管理器安装与管理教程
46,600 周安装