repository-analyzer by jackspace/claudeskillz
npx skills add https://github.com/jackspace/claudeskillz --skill repository-analyzer通过自动扫描结构、检测技术栈、映射依赖关系并生成全面文档,快速理解不熟悉的代码库。
对于 SDAM 用户:创建可供后续参考的代码库结构外部文档。对于 ADHD 用户:无需手动探索即可获得即时概览 - 节省数小时的上下文切换时间。对于所有用户:在几分钟而非数天内熟悉新项目。
步骤 1:获取目录结构
# 使用文件系统工具映射结构
tree -L 3 -I 'node_modules|.git|dist|build'
步骤 2:按类型统计文件
# 识别使用的语言
find . -type f -name "*.js" | wc -l
find . -type f -name "*.py" | wc -l
find . -type f -name "*.go" | wc -l
# 等等...
步骤 3:测量代码库大小
# 统计代码行数
cloc . --exclude-dir=node_modules,.git,dist,build
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
语言:JavaScript、TypeScript、Python、Go、Rust、Java 等。
框架:
检测方法:
const detectFramework = async () => {
// 检查 package.json
const packageJson = await readFile('package.json');
const dependencies = packageJson.dependencies || {};
if ('react' in dependencies) return 'React';
if ('vue' in dependencies) return 'Vue';
if ('express' in dependencies) return 'Express';
// 检查 requirements.txt
const requirements = await readFile('requirements.txt');
if (requirements.includes('fastapi')) return 'FastAPI';
if (requirements.includes('django')) return 'Django';
// 检查 go.mod
const goMod = await readFile('go.mod');
if (goMod.includes('gin-gonic')) return 'Gin';
return 'Unknown';
};
对于 Node.js:
# 读取 package.json
cat package.json | jq '.dependencies'
cat package.json | jq '.devDependencies'
# 检查过时的包
npm outdated
对于 Python:
# 读取 requirements.txt 或 pyproject.toml
cat requirements.txt
# 检查过时的包
pip list --outdated
对于 Go:
# 读取 go.mod
cat go.mod
# 检查过时的模块
go list -u -m all
要检测的常见模式:
models/、views/、controllers/api/、services/、repositories/features/auth/、features/users/domain/、application/、infrastructure/services/ 目录下的多个服务检测逻辑:
const detectArchitecture = (structure) => {
if (structure.includes('models') && structure.includes('views') && structure.includes('controllers')) {
return 'MVC Pattern';
}
if (structure.includes('features')) {
return 'Feature-based Architecture';
}
if (structure.includes('domain') && structure.includes('application')) {
return 'Domain-Driven Design';
}
if (structure.includes('services') && structure.includes('api-gateway')) {
return 'Microservices Architecture';
}
return 'Custom Architecture';
};
搜索指标:
# 查找 TODOs
grep -r "TODO" --include="*.js" --include="*.py" --include="*.go"
# 查找 FIXMEs
grep -r "FIXME" --include="*.js" --include="*.py" --include="*.go"
# 查找 HACKs
grep -r "HACK" --include="*.js" --include="*.py" --include="*.go"
# 查找已弃用的代码
grep -r "@deprecated" --include="*.js" --include="*.ts"
复杂度分析:
// 识别长函数(潜在的代码重构目标)
const analyzeFunctions = () => {
// 函数 > 50 行 = 高复杂度
// 函数 > 100 行 = 非常高复杂度
// 圈复杂度 > 10 = 需要重构
};
输出格式:
# {项目名称} - 仓库分析
**生成时间:** {时间戳}
**分析者:** Claude 代码仓库分析器
---
## 📊 概览
**主要语言:** {语言}
**框架:** {框架}
**架构:** {架构模式}
**总文件数:** {数量}
**代码行数:** {LOC}
**最后更新:** {git 日志日期}
---
## 📁 目录结构
project/
├── src/
│ ├── components/
│ ├── services/
│ └── utils/
├── tests/
└── docs/
---
## 🛠 技术栈
### 前端
- React 18.2.0
- TypeScript 5.0
- Tailwind CSS 3.3
### 后端
- Node.js 18
- Express 4.18
- PostgreSQL 15
### DevOps
- Docker
- GitHub Actions
- Jest 用于测试
---
## 📦 依赖项
### 生产环境 (12 个包)
- express: 4.18.2
- pg: 8.11.0
- jsonwebtoken: 9.0.0
- ...
### 开发环境 (8 个包)
- typescript: 5.0.4
- jest: 29.5.0
- eslint: 8.40.0
- ...
### ⚠️ 已过时 (3 个包)
- express: 4.18.2 → 4.19.0 (有次要更新可用)
- jest: 29.5.0 → 29.7.0 (有补丁更新可用)
---
## 🏗 架构
**模式:** 分层架构
**层级:**
1. **API 层** (`src/api/`): REST 端点,请求验证
2. **服务层** (`src/services/`): 业务逻辑
3. **仓库层** (`src/repositories/`): 数据库访问
4. **模型** (`src/models/`): 数据结构
**数据流:**
Client → API → Service → Repository → Database
---
## 🔍 代码质量
**指标:**
- 平均函数长度:25 行
- 圈复杂度:3.2 (低)
- 测试覆盖率:78%
- TypeScript 严格模式:✅ 已启用
**优势:**
- ✅ 结构良好的代码库
- ✅ 良好的测试覆盖率
- ✅ 使用 TypeScript 实现类型安全
**待改进之处:**
- ⚠️ 发现 12 个 TODO (见技术债务部分)
- ⚠️ 3 个过时的依赖项
- ⚠️ `/utils` 中缺少文档
---
## 🐛 技术债务
### 高优先级 (3)
- **FIXME** 在 `src/services/auth.js:42`:JWT 刷新令牌轮换未实现
- **TODO** 在 `src/api/users.js:78`:添加速率限制
- **HACK** 在 `src/utils/cache.js:23`:使用 setTimeout 而非正确的缓存过期机制
### 中优先级 (5)
- **TODO** 在 `src/components/Dashboard.jsx:15`:优化重新渲染
- **TODO** 在 `tests/integration/api.test.js:100`:添加更多边界情况
- ...
### 低优先级 (4)
- **TODO** 在 `README.md:50`:更新安装说明
- ...
---
## 🚀 入口点
**主应用:**
- `src/index.js` - 服务器入口点
- `src/client/index.jsx` - 客户端入口点
**开发:**
- `npm run dev` - 启动开发服务器
- `npm test` - 运行测试
- `npm run build` - 生产环境构建
**配置:**
- `.env.example` - 环境变量
- `tsconfig.json` - TypeScript 配置
- `jest.config.js` - 测试配置
---
## 📋 常见任务
**添加新功能:**
1. 在 `src/components/` 中创建组件
2. 在 `src/services/` 中添加服务逻辑
3. 在 `src/api/` 中创建 API 端点
4. 在 `tests/` 中编写测试
**数据库变更:**
1. 在 `migrations/` 中创建迁移
2. 在 `src/models/` 中更新模型
3. 运行 `npm run migrate`
---
## 🔗 集成点
**外部服务:**
- PostgreSQL 数据库 (端口 5432)
- Redis 缓存 (端口 6379)
- SendGrid API (邮件)
- Stripe API (支付)
**API 端点:**
- `GET /api/users` - 列出用户
- `POST /api/auth/login` - 身份验证
- `GET /api/dashboard` - 仪表板数据
---
## 📚 附加资源
- [架构图](./docs/architecture.png)
- [API 文档](./docs/api.md)
- [开发指南](./docs/development.md)
---
**后续步骤:**
1. 处理高优先级技术债务
2. 更新过时的依赖项
3. 将测试覆盖率提高到 85% 以上
4. 记录工具函数
查看 patterns.md 获取架构模式库,以及 examples.md 获取分析示例。
# 查找变更最频繁的文件(热点)
git log --pretty=format: --name-only | sort | uniq -c | sort -rg | head -10
# 查找主要贡献者
git shortlog -sn
# 近期活动
git log --oneline --since="30 days ago" --no-merges
# 使用复杂度工具
npx eslint src/ --format json | jq '.[] | select(.messages[].ruleId == "complexity")'
# 或手动分析
# 函数 > 50 行 = 重构候选
# 文件 > 500 行 = 拆分候选
# 检查漏洞
npm audit
pip-audit # 用于 Python
go mod tidy && go list -m all # 用于 Go
保存仓库概览:
remember: Analyzed ProjectX repository
Type: CONTEXT
Tags: repository, architecture, nodejs, react
Content: ProjectX uses React + Express, layered architecture,
12 high-priority TODOs, 78% test coverage
如果分析发现常见问题:
Invoke error-debugger for:
- Deprecated dependencies
- Security vulnerabilities
- Common antipatterns detected
生成可视化:
Create dependency graph visualization
→ browser-app-creator generates interactive HTML chart
在交付文档之前,请验证:
格式:Markdown 文件保存到 ~/.claude-artifacts/analysis-{project}-{timestamp}.md (Linux/macOS) 或 %USERPROFILE%\.claude-artifacts\analysis-{project}-{timestamp}.md (Windows)
通知用户:
✅ **{项目名称} 分析** 完成!
**摘要:**
- {LOC} 行代码,分布在 {file_count} 个文件中
- 主要技术栈:{stack}
- 架构:{pattern}
- 发现 {todo_count} 个 TODO
**文档保存至:** {filepath}
**主要发现:**
1. {finding_1}
2. {finding_2}
3. {finding_3}
**推荐操作:**
- {action_1}
- {action_2}
用户加入不熟悉的项目 → 分析器在几分钟内提供完整概览
用户需要评估遗留代码 → 分析器识别所有 TODO/FIXME/HACK
用户想要检查过时的包 → 分析器列出所有带有版本的过时依赖项
用户需要记录现有项目 → 分析器生成全面的架构文档
✅ 完整的代码库结构已映射 ✅ 所有技术栈已正确识别 ✅ 依赖项已按版本编目 ✅ 架构模式已检测 ✅ 技术债务已暴露 ✅ 文档在 <2 分钟内生成 ✅ Markdown 输出已保存到工件 ✅ 提供了可操作的建议
~/.claude-artifacts/analysis-{project}-{timestamp}.md%USERPROFILE%\.claude-artifacts\analysis-{project}-{timestamp}.mdWeekly Installs
104
Repository
GitHub Stars
10
First Seen
Jan 24, 2026
Security Audits
Installed on
opencode94
codex89
cursor88
gemini-cli87
github-copilot77
kimi-cli73
Quickly understand unfamiliar codebases by automatically scanning structure, detecting technologies, mapping dependencies, and generating comprehensive documentation.
For SDAM users : Creates external documentation of codebase structure you can reference later. For ADHD users : Instant overview without manual exploration - saves hours of context-switching. For all users : Onboard to new projects in minutes instead of days.
Step 1: Get directory structure
# Use filesystem tools to map structure
tree -L 3 -I 'node_modules|.git|dist|build'
Step 2: Count files by type
# Identify languages used
find . -type f -name "*.js" | wc -l
find . -type f -name "*.py" | wc -l
find . -type f -name "*.go" | wc -l
# etc...
Step 3: Measure codebase size
# Count lines of code
cloc . --exclude-dir=node_modules,.git,dist,build
Languages : JavaScript, TypeScript, Python, Go, Rust, Java, etc.
Frameworks :
Detection methods :
const detectFramework = async () => {
// Check package.json
const packageJson = await readFile('package.json');
const dependencies = packageJson.dependencies || {};
if ('react' in dependencies) return 'React';
if ('vue' in dependencies) return 'Vue';
if ('express' in dependencies) return 'Express';
// Check requirements.txt
const requirements = await readFile('requirements.txt');
if (requirements.includes('fastapi')) return 'FastAPI';
if (requirements.includes('django')) return 'Django';
// Check go.mod
const goMod = await readFile('go.mod');
if (goMod.includes('gin-gonic')) return 'Gin';
return 'Unknown';
};
For Node.js :
# Read package.json
cat package.json | jq '.dependencies'
cat package.json | jq '.devDependencies'
# Check for outdated packages
npm outdated
For Python :
# Read requirements.txt or pyproject.toml
cat requirements.txt
# Check for outdated packages
pip list --outdated
For Go :
# Read go.mod
cat go.mod
# Check for outdated modules
go list -u -m all
Common patterns to detect :
models/, views/, controllers/api/, services/, repositories/features/auth/, features/users/domain/, application/, Detection logic :
const detectArchitecture = (structure) => {
if (structure.includes('models') && structure.includes('views') && structure.includes('controllers')) {
return 'MVC Pattern';
}
if (structure.includes('features')) {
return 'Feature-based Architecture';
}
if (structure.includes('domain') && structure.includes('application')) {
return 'Domain-Driven Design';
}
if (structure.includes('services') && structure.includes('api-gateway')) {
return 'Microservices Architecture';
}
return 'Custom Architecture';
};
Search for indicators :
# Find TODOs
grep -r "TODO" --include="*.js" --include="*.py" --include="*.go"
# Find FIXMEs
grep -r "FIXME" --include="*.js" --include="*.py" --include="*.go"
# Find HACKs
grep -r "HACK" --include="*.js" --include="*.py" --include="*.go"
# Find deprecated code
grep -r "@deprecated" --include="*.js" --include="*.ts"
Complexity analysis :
// Identify long functions (potential refactor targets)
const analyzeFunctions = () => {
// Functions > 50 lines = high complexity
// Functions > 100 lines = very high complexity
// Cyclomatic complexity > 10 = needs refactoring
};
Output format :
# {Project Name} - Repository Analysis
**Generated:** {timestamp}
**Analyzed by:** Claude Code Repository Analyzer
---
## 📊 Overview
**Primary Language:** {language}
**Framework:** {framework}
**Architecture:** {architecture pattern}
**Total Files:** {count}
**Lines of Code:** {LOC}
**Last Updated:** {git log date}
---
## 📁 Directory Structure
project/ ├── src/ │ ├── components/ │ ├── services/ │ └── utils/ ├── tests/ └── docs/
---
## 🛠 Technologies
### Frontend
- React 18.2.0
- TypeScript 5.0
- Tailwind CSS 3.3
### Backend
- Node.js 18
- Express 4.18
- PostgreSQL 15
### DevOps
- Docker
- GitHub Actions
- Jest for testing
---
## 📦 Dependencies
### Production (12 packages)
- express: 4.18.2
- pg: 8.11.0
- jsonwebtoken: 9.0.0
- ...
### Development (8 packages)
- typescript: 5.0.4
- jest: 29.5.0
- eslint: 8.40.0
- ...
### ⚠️ Outdated (3 packages)
- express: 4.18.2 → 4.19.0 (minor update available)
- jest: 29.5.0 → 29.7.0 (patch updates available)
---
## 🏗 Architecture
**Pattern:** Layered Architecture
**Layers:**
1. **API Layer** (`src/api/`): REST endpoints, request validation
2. **Service Layer** (`src/services/`): Business logic
3. **Repository Layer** (`src/repositories/`): Database access
4. **Models** (`src/models/`): Data structures
**Data Flow:**
Client → API → Service → Repository → Database
---
## 🔍 Code Quality
**Metrics:**
- Average function length: 25 lines
- Cyclomatic complexity: 3.2 (low)
- Test coverage: 78%
- TypeScript strict mode: ✅ Enabled
**Strengths:**
- ✅ Well-structured codebase
- ✅ Good test coverage
- ✅ Type-safe with TypeScript
**Areas for Improvement:**
- ⚠️ 12 TODOs found (see Technical Debt section)
- ⚠️ 3 outdated dependencies
- ⚠️ Missing documentation in `/utils`
---
## 🐛 Technical Debt
### High Priority (3)
- **FIXME** in `src/services/auth.js:42`: JWT refresh token rotation not implemented
- **TODO** in `src/api/users.js:78`: Add rate limiting
- **HACK** in `src/utils/cache.js:23`: Using setTimeout instead of proper cache expiry
### Medium Priority (5)
- **TODO** in `src/components/Dashboard.jsx:15`: Optimize re-renders
- **TODO** in `tests/integration/api.test.js:100`: Add more edge cases
- ...
### Low Priority (4)
- **TODO** in `README.md:50`: Update installation instructions
- ...
---
## 🚀 Entry Points
**Main Application:**
- `src/index.js` - Server entry point
- `src/client/index.jsx` - Client entry point
**Development:**
- `npm run dev` - Start dev server
- `npm test` - Run tests
- `npm run build` - Production build
**Configuration:**
- `.env.example` - Environment variables
- `tsconfig.json` - TypeScript config
- `jest.config.js` - Test configuration
---
## 📋 Common Tasks
**Adding a new feature:**
1. Create component in `src/components/`
2. Add service logic in `src/services/`
3. Create API endpoint in `src/api/`
4. Write tests in `tests/`
**Database changes:**
1. Create migration in `migrations/`
2. Update models in `src/models/`
3. Run `npm run migrate`
---
## 🔗 Integration Points
**External Services:**
- PostgreSQL database (port 5432)
- Redis cache (port 6379)
- SendGrid API (email)
- Stripe API (payments)
**API Endpoints:**
- `GET /api/users` - List users
- `POST /api/auth/login` - Authentication
- `GET /api/dashboard` - Dashboard data
---
## 📚 Additional Resources
- [Architecture Diagram](./docs/architecture.png)
- [API Documentation](./docs/api.md)
- [Development Guide](./docs/development.md)
---
**Next Steps:**
1. Address high-priority technical debt
2. Update outdated dependencies
3. Increase test coverage to 85%+
4. Document utility functions
See patterns.md for architecture pattern library and examples.md for analysis examples.
# Find most changed files (hotspots)
git log --pretty=format: --name-only | sort | uniq -c | sort -rg | head -10
# Find largest contributors
git shortlog -sn
# Recent activity
git log --oneline --since="30 days ago" --no-merges
# Using complexity tools
npx eslint src/ --format json | jq '.[] | select(.messages[].ruleId == "complexity")'
# Or manual analysis
# Functions > 50 lines = candidate for refactoring
# Files > 500 lines = candidate for splitting
# Check for vulnerabilities
npm audit
pip-audit # for Python
go mod tidy && go list -m all # for Go
Save repository overview:
remember: Analyzed ProjectX repository
Type: CONTEXT
Tags: repository, architecture, nodejs, react
Content: ProjectX uses React + Express, layered architecture,
12 high-priority TODOs, 78% test coverage
If analysis finds common issues:
Invoke error-debugger for:
- Deprecated dependencies
- Security vulnerabilities
- Common antipatterns detected
Generate visualization:
Create dependency graph visualization
→ browser-app-creator generates interactive HTML chart
Before delivering documentation, verify:
Format : Markdown file saved to ~/.claude-artifacts/analysis-{project}-{timestamp}.md (Linux/macOS) or %USERPROFILE%\.claude-artifacts\analysis-{project}-{timestamp}.md (Windows)
Notify user :
✅ **{Project Name} Analysis** complete!
**Summary:**
- {LOC} lines of code across {file_count} files
- Primary stack: {stack}
- Architecture: {pattern}
- {todo_count} TODOs found
**Documentation saved to:** {filepath}
**Key findings:**
1. {finding_1}
2. {finding_2}
3. {finding_3}
**Recommended actions:**
- {action_1}
- {action_2}
User joins unfamiliar project → analyzer provides complete overview in minutes
User needs to evaluate legacy code → analyzer identifies all TODOs/FIXMEs/HACKs
User wants to check outdated packages → analyzer lists all outdated dependencies with versions
User needs to document existing project → analyzer generates comprehensive architecture docs
✅ Complete codebase structure mapped ✅ All technologies identified correctly ✅ Dependencies catalogued with versions ✅ Architecture pattern detected ✅ Technical debt surfaced ✅ Documentation generated in <2 minutes ✅ Markdown output saved to artifacts ✅ Actionable recommendations provided
~/.claude-artifacts/analysis-{project}-{timestamp}.md%USERPROFILE%\.claude-artifacts\analysis-{project}-{timestamp}.mdWeekly Installs
104
Repository
GitHub Stars
10
First Seen
Jan 24, 2026
Security Audits
Gen Agent Trust HubFailSocketPassSnykPass
Installed on
opencode94
codex89
cursor88
gemini-cli87
github-copilot77
kimi-cli73
agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试
157,400 周安装
Clerk Webhooks 完整指南:Next.js 用户认证事件实时同步与集成
3,100 周安装
能力进化器 - OpenClaw智能体自主代码进化与自我修复工具
3,200 周安装
Orderly Network 入门指南:全链订单簿交易基础设施与AI智能体开发工具
3,200 周安装
LangChain深度代理框架deep-agents-core:任务规划、子代理与长期记忆的AI代理开发
3,300 周安装
Vercel React 最佳实践指南:45条性能优化规则与代码示例
3,200 周安装
Ralphmode权限配置文件 - 跨平台自动化工作流安全解决方案
3,200 周安装
infrastructure/services/ directory