sourceatlas

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# 🗺️ SourceAtlas

> 🌐 [sourceatlas.io](https://sourceatlas.io) | **English** | [繁體中文](https://github.com/lis186/sourceatlas/blob/HEAD/README.zh-TW.md)

**Get project overview in ~3 minutes by scanning <5% of files**

A set of AI-powered slash commands for [Claude Code](https://claude.ai/code) that help you understand any codebase quickly.

[![Version](https://img.shields.io/badge/version-v2.13.1-blue)](https://github.com/lis186/SourceAtlas/releases)
[![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)

![Command Menu](https://github.com/lis186/sourceatlas/raw/HEAD/docs/images/atlas-command-menu.png)

---

## Have You Ever...

- Spent **3 days** on a new project and still don't understand the architecture?
- Wanted to change one line, but **afraid it might break everything**?
- Asked a colleague "how do I write this", and got "just look at file XXX"?
- Needed to upgrade iOS 16 → 17, but had **no idea how much work** it would take?

**SourceAtlas solves these in minutes, not days.**

---

## Before & After

| Task | Before | After |
|------|--------|-------|
| Understand project architecture | 2-3 days | **~3-15 minutes** ✓ |
| Find API implementation examples | Ask colleagues / random searching | **~seconds** |
| Analyze impact of code changes | Manual tracking, hope for the best | **~1-2 minutes** |
| Plan framework upgrade | Weeks of research | **~15-30 minutes** |
| Find code hotspots & experts | Ask around | **~5-10 minutes** |

<sub>✓ = benchmarked on 5 open-source projects. Others are estimates based on usage.</sub>

---

## How It Works

SourceAtlas uses **information theory** to prioritize high-entropy files (configs, READMEs, models) over implementation details. By scanning <5% of files, it achieves 70-80% understanding depth in minutes instead of days.

![Flow Diagram Example](https://github.com/lis186/sourceatlas/raw/HEAD/docs/images/atlas-flow-diagram.png)

---

## Core Commands

### 1. "I just joined the project, where do I start?"

```bash
/sourceatlas:overview
```

**In ~3 minutes, get**: Tech stack, architecture patterns, project scale, code quality signals

**Example output**: Detects Swift 5.10 + MVVM + Coordinator, 12K files, test coverage level

---

### 2. "I want to write an API, how does this project do it?"

```bash
/sourceatlas:pattern "api endpoint"
/sourceatlas:pattern "authentication"
/sourceatlas:pattern "database query"
```

**In 0.1-30 seconds, get**: 2-3 best example files with exact line numbers + implementation guide

**Example output**: Returns `UserAPI.swift:45` with matching test file and implementation guide

**221 patterns supported**: MVVM, Networking, Core Data, React Hooks, Next.js API, Jetpack Compose, Vue Composable, FastAPI, Rails Controller...

---

### 3. "I want to change this file, what else will break?"

```bash
/sourceatlas:impact "src/api/users.ts"
/sourceatlas:impact api "/api/users/{id}"
```

**In 1-2 minutes, get**: All dependents, Breaking Change risks, test coverage, migration steps

**Example output**: Lists 23 dependent files, identifies 5 breaking change risks

---

### 4. "Who knows this code best? What's the danger zone?"

```bash
/sourceatlas:history
/sourceatlas:history src/
```

**In 5-10 minutes, get**: Hotspots (files that change constantly), Hidden Coupling, Knowledge Distribution

**Example output**: Shows `PaymentService.swift` with 47 changes, flags single-contributor bus factor risk

---

### 5. "How does the login flow actually work?"

```bash
/sourceatlas:flow "user login"
/sourceatlas:flow "checkout process"
```

**In 3-5 minutes, get**: Entry points, complete execution path, boundary identification (API/DB/Auth/Payment)

**Example output**: Traces `LoginViewController` → `AuthService` → `APIClient` → `TokenManager`

---

### 6. "We need to upgrade to iOS 17, how much work is that?"

```bash
/sourceatlas:deps "iOS 16 → 17"
/sourceatlas:deps "React 17 → 18"
/sourceatlas:deps "Python 3.11 → 3.12"
```

**In 15-30 minutes, get**: Deprecated APIs, version checks to remove, third-party compatibility, effort estimate

**Example output**: Migration checklist with removable version checks, deprecated APIs, effort estimate

---

## Benchmark Results

**Tested on 5 open-source projects**: Firefox iOS, Discourse, Cal.com, Prefect, Thunderbird

| Command | Key Metric | Result | Report |
|---------|-----------|--------|--------|
| `overview` | Overall Accuracy | 93% (56/60) | [✓](https://github.com/lis186/sourceatlas/blob/HEAD/dev-notes/2025-12/2025-12-21-overview-e2e-verification.md) |
| `pattern` | Search Precision | 98.6% (7/7 cases) | [✓](https://github.com/lis186/sourceatlas/blob/HEAD/dev-notes/2025-12/2025-12-21-pattern-e2e-verification.md) |
| `impact` | Internal Consistency | 100% (5/5 projects) | [✓](https://github.com/lis186/sourceatlas/blob/HEAD/dev-notes/2025-12/2025-12-21-impact-e2e-verification.md) |
| `flow` | Entry Point Detection | 100% (5/5 projects) | [✓](https://github.com/lis186/sourceatlas/blob/HEAD/dev-notes/2025-12/2025-12-21-flow-e2e-verification.md) |
| `deps` | Mode Detection | 100% (2/2 cases) | [✓](https://github.com/lis186/sourceatlas/blob/HEAD/dev-notes/2025-12/2025-12-21-deps-e2e-verification.md) |
| `history` | Hotspots Detection | 100% (Top 10) | [✓](https://github.com/lis186/sourceatlas/blob/HEAD/dev-notes/2025-12/2025-12-21-history-e2e-verification.md) |

<sub>All E2E verified on 2025-12-21. Languages tested: Swift, Ruby, Python, TypeScript, Kotlin. Click ✓ for detailed reports.</sub>

---

## Quick Start (2 minutes)

### Requirements

- **Claude Code** 1.0.33+ ([Get it here](https://claude.ai/code))
- **Git** 2.0+
- **macOS 12+** or **Linux**

### Installation

**Option A: Plugin Marketplace (Recommended)**
```bash
# In Claude Code:
/plugin marketplace add lis186/SourceAtlas
/plugin install sourceatlas@lis186-SourceAtlas
```

**Option B: Quick Local Testing**
```bash
git clone https://github.com/lis186/SourceAtlas.git
claude --plugin-dir ./SourceAtlas/plugin
```

> ⚠️ **Known Issue**: If you install with `--scope project` in one repo, you may get "already installed" errors in other repos. This is a [Claude Code bug](https://github.com/anthropics/claude-code/issues/14202). **Workaround**: Use default user scope (no `--scope` flag) or `--scope user`.

**Option C: Via OpenSkills (For Cursor, Gemini CLI, Aider)**

SourceAtlas also works with non-Claude Code AI agents via [OpenSkills](https://github.com/numman-ali/openskills).

**Prerequisites**: Node.js 18+

**Quick Install**:
```bash
npm i -g openskills
cd your-project
openskills install lis186/SourceAtlas
touch AGENTS.md && openskills sync -y
```

**Using with Cursor**:

After installation, open Cursor's AI Chat (Cmd+L) and ask naturally:

| You Ask | What Happens |
|---------|--------------|
| "Help me understand this codebase" | Runs `openskills read overview` → Architecture analysis |
| "How do I add an API endpoint here?" | Runs `openskills read pattern` → Shows existing patterns |
| "What files are affected if I change UserService?" | Runs `openskills read impact` → Dependency analysis |
| "Trace the login flow" | Runs `openskills read flow` → Execution path |

> **Tip**: If Cursor doesn't auto-detect skills, explicitly ask: *"Use `openskills read overview` to analyze this project"*

**Verify Installation**:
```bash
openskills list | grep overview
# Should see: overview    (project)   Get project overview...
```

**Troubleshooting**:
- **"SKILL.md not found"** → Use `openskills install lis186/SourceAtlas` (repo root path)
- **Skills not appearing** → Run `openskills sync -y` to regenerate AGENTS.md

See [plugin/README.md](https://github.com/lis186/sourceatlas/blob/HEAD/plugin/README.md#method-2-via-openskills-for-cursor-gemini-cli-aider-windsurf) for detailed instructions.

### First Use

```bash
cd ~/projects/any-project
/sourceatlas:overview  # Start understanding
```

![Overview Output Example](https://github.com/lis186/sourceatlas/raw/HEAD/docs/images/atlas-overview-output.png)

With **Agent Skills**, Claude automatically suggests the right analysis based on your questions — no commands to memorize!

---

## All 8 Commands

| Command | Problem It Solves | Time |
|---------|------------------|------|
| `/sourceatlas:overview` | New to project, need the big picture | ~3-15 min ✓ |
| `/sourceatlas:pattern "X"` | Need to implement X, want examples | ~seconds ✓ |
| `/sourceatlas:impact "file"` | About to change code, worried about side effects | ~1-2 min |
| `/sourceatlas:history` | Need to find hotspots and experts | ~5-10 min |
| `/sourceatlas:flow "feature"` | Need to understand a feature's execution path | ~3-5 min |
| `/sourceatlas:deps "upgrade"` | Planning framework/SDK upgrade | ~15-30 min |
| `/sourceatlas:list` | Check what analyses are cached | instant |
| `/sourceatlas:reset` | Clear outdated cache | instant |

<sub>✓ = benchmarked. Times without ✓ are estimates.</sub>

---

## Supported Languages

| Language | Patterns | Example Patterns |
|----------|----------|------------------|
| **Swift/iOS** | 34 | MVVM, Coordinator, Core Data, SwiftUI, Combine |
| **TypeScript/React/Vue** | 50 | Hooks, Next.js, Zustand, Pinia, tRPC |
| **Kotlin/Android** | 31 | ViewModel, Room, Compose, Hilt, MVI |
| **Python** | 26 | Django, FastAPI, Flask, Celery, SQLAlchemy |
| **Ruby/Rails** | 26 | ActiveRecord, Controller, Service, Job |
| **Go** | 26 | Handler, Service, Middleware, Repository |
| **Rust** | 28 | Handler, Service, Middleware, Async Runtime |

**Total: 221 patterns**

---

## Limitations

| Limitation | Details |
|------------|---------|
| **Benchmark scope** | 6 commands tested (`overview`, `pattern`, `flow`, `impact`, `deps`, `history`) |
| **Tech Stack detection** | May miss secondary languages (e.g., React in a Python project) |
| **Architecture detection** | May miss secondary patterns (e.g., MVI in Clean Architecture) |
| **Best for mature projects** | Works best with README, config files; limited for undocumented legacy code |
| **Language coverage** | 7 languages supported; non-mainstream languages need manual verification |

---

## When NOT to Use

| Situation | Why | Alternative |
|-----------|-----|-------------|
| Small projects (<2K LOC) | Reading directly is faster | Just read the code |
| Need 100% precision | AI has ~93% accuracy | Use static analysis tools |
| Highly sensitive code | Code sent to Claude API | Check your compliance policy |
| Offline environment | Requires API connection | Use local tools |

---

## Privacy & Cost

| Aspect | Details |
|--------|---------|
| **Data Privacy** | Code is sent to Claude API for analysis. SourceAtlas itself stores nothing. Check your organization's AI policy. |
| **Token Usage** | ~50-100k tokens per analysis (~$0.15-0.30 USD with Sonnet) |
| **Local Processing** | Git history analysis (code-maat) runs locally. AST search (ast-grep) runs locally. |

---

## Save & Share Analyses

All commands support `--save`:

```bash
/sourceatlas:overview --save          # → .sourceatlas/overview.yaml
/sourceatlas:pattern "api" --save     # → .sourceatlas/patterns/api.md
/sourceatlas:history --save           # → .sourceatlas/history.md
```

**Benefits**:
- New team members can read existing analyses
- Avoid re-running expensive analyses
- Track how the codebase evolves

**Manage cache**:
```bash
/sourceatlas:list   # View all cached analyses
/sourceatlas:reset  # Clear all or specific caches
```

---

## Documentation

| Document | Description |
|----------|-------------|
| [Usage Guide](https://github.com/lis186/sourceatlas/blob/HEAD/USAGE_GUIDE.md) | Complete command reference, all 221 patterns |
| [Case Studies](https://github.com/lis186/sourceatlas/tree/HEAD/docs/case-studies/) | 7 framework analyses (Gin, TCA, FastAPI, tRPC, etc.) |
| [Plugin Guide](https://github.com/lis186/sourceatlas/blob/HEAD/plugin/README.md) | Plugin installation and features |
| [Analysis Constitution](https://github.com/lis186/sourceatlas/blob/HEAD/ANALYSIS_CONSTITUTION.md) | Quality principles all analyses follow |
| [CLAUDE.md](https://github.com/lis186/sourceatlas/blob/HEAD/CLAUDE.md) | Developer guide, architecture |

---

## Feedback & Contributions

- **Report Issues**: [GitHub Issues](https://github.com/lis186/SourceAtlas/issues)
- **Contribute Code**: PRs welcome

---

## Acknowledgments

SourceAtlas is built with these excellent tools:

| Tool | Purpose | Link |
|------|---------|------|
| **ast-grep** | AST-based code search for `pattern` and `deps` commands | [GitHub](https://github.com/ast-grep/ast-grep) |
| **code-maat** | Git history analysis for `history` command | [GitHub](https://github.com/adamtornhill/code-maat) |
| **Claude Code** | AI-powered code assistant | [claude.ai/code](https://claude.ai/code) |

---

**SourceAtlas** — Understand any codebase in minutes, not days.

v2.13.1 | MIT License | Made with Claude Code

🗺️ SourceAtlas

🌐 sourceatlas.io | English | 繁體中文

Get project overview in ~3 minutes by scanning <5% of files

A set of AI-powered slash commands for Claude Code that help you understand any codebase quickly.

Have You Ever...

Spent 3 days on a new project and still don't understand the architecture?
Wanted to change one line, but afraid it might break everything?
Asked a colleague "how do I write this", and got "just look at file XXX"?
Needed to upgrade iOS 16 → 17, but had no idea how much work it would take?

SourceAtlas solves these in minutes, not days.

Before & After

Task	Before	After
Understand project architecture	2-3 days	~3-15 minutes ✓
Find API implementation examples	Ask colleagues / random searching	~seconds
Analyze impact of code changes	Manual tracking, hope for the best	~1-2 minutes
Plan framework upgrade	Weeks of research	~15-30 minutes
Find code hotspots & experts	Ask around	~5-10 minutes

_{✓ = benchmarked on 5 open-source projects. Others are estimates based on usage.}

How It Works

SourceAtlas uses information theory to prioritize high-entropy files (configs, READMEs, models) over implementation details. By scanning <5% of files, it achieves 70-80% understanding depth in minutes instead of days.

Flow Diagram Example

Core Commands

1. "I just joined the project, where do I start?"

/sourceatlas:overview

In ~3 minutes, get: Tech stack, architecture patterns, project scale, code quality signals

Example output: Detects Swift 5.10 + MVVM + Coordinator, 12K files, test coverage level

2. "I want to write an API, how does this project do it?"

/sourceatlas:pattern "api endpoint"
/sourceatlas:pattern "authentication"
/sourceatlas:pattern "database query"

In 0.1-30 seconds, get: 2-3 best example files with exact line numbers + implementation guide

Example output: Returns UserAPI.swift:45 with matching test file and implementation guide

221 patterns supported: MVVM, Networking, Core Data, React Hooks, Next.js API, Jetpack Compose, Vue Composable, FastAPI, Rails Controller...

3. "I want to change this file, what else will break?"

/sourceatlas:impact "src/api/users.ts"
/sourceatlas:impact api "/api/users/{id}"

In 1-2 minutes, get: All dependents, Breaking Change risks, test coverage, migration steps

Example output: Lists 23 dependent files, identifies 5 breaking change risks

4. "Who knows this code best? What's the danger zone?"

/sourceatlas:history
/sourceatlas:history src/

In 5-10 minutes, get: Hotspots (files that change constantly), Hidden Coupling, Knowledge Distribution

Example output: Shows PaymentService.swift with 47 changes, flags single-contributor bus factor risk

5. "How does the login flow actually work?"

/sourceatlas:flow "user login"
/sourceatlas:flow "checkout process"

In 3-5 minutes, get: Entry points, complete execution path, boundary identification (API/DB/Auth/Payment)

Example output: Traces LoginViewController → AuthService → APIClient → TokenManager

6. "We need to upgrade to iOS 17, how much work is that?"

/sourceatlas:deps "iOS 16 → 17"
/sourceatlas:deps "React 17 → 18"
/sourceatlas:deps "Python 3.11 → 3.12"

In 15-30 minutes, get: Deprecated APIs, version checks to remove, third-party compatibility, effort estimate

Example output: Migration checklist with removable version checks, deprecated APIs, effort estimate

Benchmark Results

Tested on 5 open-source projects: Firefox iOS, Discourse, Cal.com, Prefect, Thunderbird

Command	Key Metric	Result	Report
`overview`	Overall Accuracy	93% (56/60)	✓
`pattern`	Search Precision	98.6% (7/7 cases)	✓
`impact`	Internal Consistency	100% (5/5 projects)	✓
`flow`	Entry Point Detection	100% (5/5 projects)	✓
`deps`	Mode Detection	100% (2/2 cases)	✓
`history`	Hotspots Detection	100% (Top 10)	✓

_{All E2E verified on 2025-12-21. Languages tested: Swift, Ruby, Python, TypeScript, Kotlin. Click ✓ for detailed reports.}

Quick Start (2 minutes)

Requirements

Claude Code 1.0.33+ (Get it here)
Git 2.0+
macOS 12+ or Linux

Installation

Option A: Plugin Marketplace (Recommended)

# In Claude Code:
/plugin marketplace add lis186/SourceAtlas
/plugin install sourceatlas@lis186-SourceAtlas

Option B: Quick Local Testing

git clone https://github.com/lis186/SourceAtlas.git
claude --plugin-dir ./SourceAtlas/plugin

⚠️ Known Issue: If you install with --scope project in one repo, you may get "already installed" errors in other repos. This is a Claude Code bug. Workaround: Use default user scope (no --scope flag) or --scope user.

Option C: Via OpenSkills (For Cursor, Gemini CLI, Aider)

SourceAtlas also works with non-Claude Code AI agents via OpenSkills.

Prerequisites: Node.js 18+

Quick Install:

npm i -g openskills
cd your-project
openskills install lis186/SourceAtlas
touch AGENTS.md && openskills sync -y

Using with Cursor:

After installation, open Cursor's AI Chat (Cmd+L) and ask naturally:

You Ask	What Happens
"Help me understand this codebase"	Runs `openskills read overview` → Architecture analysis
"How do I add an API endpoint here?"	Runs `openskills read pattern` → Shows existing patterns
"What files are affected if I change UserService?"	Runs `openskills read impact` → Dependency analysis
"Trace the login flow"	Runs `openskills read flow` → Execution path

Tip: If Cursor doesn't auto-detect skills, explicitly ask: "Use openskills read overview to analyze this project"

Verify Installation:

openskills list | grep overview
# Should see: overview    (project)   Get project overview...

Troubleshooting:

"SKILL.md not found" → Use openskills install lis186/SourceAtlas (repo root path)
Skills not appearing → Run openskills sync -y to regenerate AGENTS.md

See plugin/README.md for detailed instructions.

First Use

cd ~/projects/any-project
/sourceatlas:overview  # Start understanding

Overview Output Example

With Agent Skills, Claude automatically suggests the right analysis based on your questions — no commands to memorize!

All 8 Commands

Command	Problem It Solves	Time
`/sourceatlas:overview`	New to project, need the big picture	~3-15 min ✓
`/sourceatlas:pattern "X"`	Need to implement X, want examples	~seconds ✓
`/sourceatlas:impact "file"`	About to change code, worried about side effects	~1-2 min
`/sourceatlas:history`	Need to find hotspots and experts	~5-10 min
`/sourceatlas:flow "feature"`	Need to understand a feature's execution path	~3-5 min
`/sourceatlas:deps "upgrade"`	Planning framework/SDK upgrade	~15-30 min
`/sourceatlas:list`	Check what analyses are cached	instant
`/sourceatlas:reset`	Clear outdated cache	instant

_{✓ = benchmarked. Times without ✓ are estimates.}

Supported Languages

Language	Patterns	Example Patterns
Swift/iOS	34	MVVM, Coordinator, Core Data, SwiftUI, Combine
TypeScript/React/Vue	50	Hooks, Next.js, Zustand, Pinia, tRPC
Kotlin/Android	31	ViewModel, Room, Compose, Hilt, MVI
Python	26	Django, FastAPI, Flask, Celery, SQLAlchemy
Ruby/Rails	26	ActiveRecord, Controller, Service, Job
Go	26	Handler, Service, Middleware, Repository
Rust	28	Handler, Service, Middleware, Async Runtime

Total: 221 patterns

Limitations

Limitation	Details
Benchmark scope	6 commands tested (`overview`, `pattern`, `flow`, `impact`, `deps`, `history`)
Tech Stack detection	May miss secondary languages (e.g., React in a Python project)
Architecture detection	May miss secondary patterns (e.g., MVI in Clean Architecture)
Best for mature projects	Works best with README, config files; limited for undocumented legacy code
Language coverage	7 languages supported; non-mainstream languages need manual verification

When NOT to Use

Situation	Why	Alternative
Small projects (<2K LOC)	Reading directly is faster	Just read the code
Need 100% precision	AI has ~93% accuracy	Use static analysis tools
Highly sensitive code	Code sent to Claude API	Check your compliance policy
Offline environment	Requires API connection	Use local tools

Privacy & Cost

Aspect	Details
Data Privacy	Code is sent to Claude API for analysis. SourceAtlas itself stores nothing. Check your organization's AI policy.
Token Usage	~~50-100k tokens per analysis (~~$0.15-0.30 USD with Sonnet)
Local Processing	Git history analysis (code-maat) runs locally. AST search (ast-grep) runs locally.

Save & Share Analyses

All commands support --save:

/sourceatlas:overview --save          # → .sourceatlas/overview.yaml
/sourceatlas:pattern "api" --save     # → .sourceatlas/patterns/api.md
/sourceatlas:history --save           # → .sourceatlas/history.md

Benefits:

New team members can read existing analyses
Avoid re-running expensive analyses
Track how the codebase evolves

Manage cache:

/sourceatlas:list   # View all cached analyses
/sourceatlas:reset  # Clear all or specific caches

Documentation

Document	Description
Usage Guide	Complete command reference, all 221 patterns
Case Studies	7 framework analyses (Gin, TCA, FastAPI, tRPC, etc.)
Plugin Guide	Plugin installation and features
Analysis Constitution	Quality principles all analyses follow
CLAUDE.md	Developer guide, architecture

Feedback & Contributions

Report Issues: GitHub Issues
Contribute Code: PRs welcome

Acknowledgments

SourceAtlas is built with these excellent tools:

Tool	Purpose	Link
ast-grep	AST-based code search for `pattern` and `deps` commands	GitHub
code-maat	Git history analysis for `history` command	GitHub
Claude Code	AI-powered code assistant	claude.ai/code

SourceAtlas — Understand any codebase in minutes, not days.

v2.13.1 | MIT License | Made with Claude Code