repository-analyzer

仓库分析器

用途

通过自动扫描结构、检测技术栈、梳理依赖关系并生成全面文档，快速了解陌生代码库。

面向 SDAM 用户：创建代码库结构的外部文档，供日后参考。 面向 ADHD 用户：无需手动探索即可快速掌握概况，节省数小时的上下文切换时间。 面向所有用户：只需几分钟而不是几天，即可熟悉新项目。

激活条件

• 用户说：“分析仓库”“了解代码库”“编写项目文档”
• 用户请求：“这个仓库里有什么”“它是如何工作的”“代码库概览”
• 熟悉新项目的场景
• 技术债评估请求

核心工作流

1. 扫描仓库结构

步骤 1：获取目录结构

# Use filesystem tools to map structure
tree -L 3 -I 'node_modules|.git|dist|build'

步骤 2：按类型统计文件

# 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...

步骤 3：测量代码库规模

# Count lines of code
cloc . --exclude-dir=node_modules,.git,dist,build

2. 检测技术栈

语言：JavaScript、TypeScript、Python、Go、Rust、Java 等。

框架：

• 前端：React、Vue、Angular、Svelte
• 后端：Express、FastAPI、Django、Rails
• 移动端：React Native、Flutter
• 桌面端：Electron、Tauri

检测方法：

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';
};

3. 梳理依赖关系

对于 Node.js：

# Read package.json
cat package.json | jq '.dependencies'
cat package.json | jq '.devDependencies'

# Check for outdated packages
npm outdated

对于 Python：

# Read requirements.txt or pyproject.toml
cat requirements.txt

# Check for outdated packages
pip list --outdated

对于 Go：

# Read go.mod
cat go.mod

# Check for outdated modules
go list -u -m all

4. 识别架构模式

常见的检测模式：

• MVC（模型-视图-控制器）：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';
};

5. 提取技术债

搜索相关标记：

# 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"

复杂度分析：

// Identify long functions (potential refactor targets)
const analyzeFunctions = () => {
  // Functions > 50 lines = high complexity
  // Functions > 100 lines = very high complexity
  // Cyclomatic complexity > 10 = needs refactoring
};

6. 生成文档

输出格式：

# {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:**

客户端 → API → 服务 → 仓库 → 数据库

---

## 🔍 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

架构模式库请参阅 patterns.md，分析示例请参阅 examples.md。

高级分析功能

Git 历史分析

# 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

与其他技能集成

上下文管理器

保存仓库概览：

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 格式正确

输出交付

格式：将 Markdown 文件保存到 ~/.claude-artifacts/analysis-{project}-{timestamp}.md（Linux/macOS）或 %USERPROFILE%\.claude-artifacts\analysis-{project}-{timestamp}.md（Windows）

通知用户：

✅ **{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}

常见分析场景

熟悉新项目

用户加入陌生项目 → 分析器在几分钟内提供完整概览

技术债评估

用户需要评估遗留代码 → 分析器识别所有 TODO/FIXME/HACK 标记

依赖项审计

用户想检查过时的软件包 → 分析器列出所有过时依赖项及其版本

架构文档

用户需要记录现有项目 → 分析器生成全面的架构文档

成功标准

✅ 完整梳理代码库结构 ✅ 正确识别所有技术栈 ✅ 汇总依赖项及其版本 ✅ 检测到架构模式 ✅ 找出技术债 ✅ 在 2 分钟内生成文档 ✅ 将 Markdown 输出保存到制品目录 ✅ 提供可执行的建议

附加资源

• 模式库 - 常见架构模式
• 分析示例 - 真实世界的代码仓库分析

快速参考

触发短语

• “分析代码仓库”
• “了解代码库”
• “编写项目文档”
• “这个代码仓库里有什么”
• “代码库概览”
• “技术债务报告”

输出位置

• Linux/macOS：~/.claude-artifacts/analysis-{project}-{timestamp}.md
• Windows：%USERPROFILE%\.claude-artifacts\analysis-{project}-{timestamp}.md

分析深度选项

• 快速（<1 分钟）：仅分析结构和语言
• 标准（1-2 分钟）：+ 依赖项 + 模式
• 深入（3-5 分钟）：+ Git 历史 + 复杂度指标 + 安全审计