code-archaeologist

KO | EN

gitlite — search

#javascript #python #hacktoberfest #typescript #golang #go #deep-learning #nodejs #macos #java #awesome-list #pytorch #mcp #open-source

code-archaeologist

(★ 10)

A production-ready skill system that gives Claude Code deep understanding of codebase evolution.

code-archaeologist Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Code Archaeologist - Claude Code Skill

[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://raw.githubusercontent.com/udaybandaru/code-archaeologist/main/LICENSE)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org)
[![Status](https://img.shields.io/badge/status-production--ready-brightgreen)](https://raw.githubusercontent.com/udaybandaru/code-archaeologist/main/FINAL_SYSTEM_OVERVIEW.md)

A production-ready skill system that gives Claude Code **deep understanding of codebase evolution** through 10 integrated analysis capabilities.

> **📊 [Read the Complete System Overview](FINAL_SYSTEM_OVERVIEW.md)** - Full architecture, integration guide, and value proposition

## Quick Start

```bash
# From any git repository
python3 .claude/skills/code_archaeologist/skill.py suggest
python3 .claude/skills/code_archaeologist/skill.py smart src/
```

Want a design doc with historical context?
```bash
python3 .claude/skills/code_archaeologist/skill.py design src/ \
  --feature "Feature Name" \
  --description "What it does"
```

## What This System Does

Transform Claude Code from a reactive editor into a **proactive development intelligence platform**:

- **Understands** codebase evolution deeply (10 analysis skills)
- **Learns** from past successes and failures (git history analysis)
- **Recommends** patterns and approaches (14 architectural patterns)
- **Prevents** technical debt and mistakes (risk assessment + design intelligence)
- **Accelerates** development (2-4 hours of research → 20 seconds)

**The Result**: 10-20x faster research with higher quality, consistency, and safety.

## Who This Is For

- Teams with fast‑moving codebases and high churn
- Engineers refactoring legacy or high‑risk areas
- New contributors needing historical context fast

## 🎯 Intelligent Commit Weighting (NEW!)

The system now **automatically distinguishes between meaningful PR commits and dev loop noise**:

- **Squashed PR commits** (weight: 1.0) - Reviewed, merged features/fixes
- **Regular commits** (weight: 0.5) - Meaningful changes, not reviewed
- **Dev loop commits** (weight: 0.1) - WIP, debugging, typo fixes

**Impact**:
- 35% noise reduction in analysis
- Hotspots now reflect real problems, not WIP churn
- Risk assessment based on meaningful changes
- One PR commit = 10 WIP commits in significance

**Example**: A function modified 10× in WIP commits gets score 1.0, while one modified 10× in PR commits gets score 10.0. This makes hotspot detection 10× more accurate.

See [COMMIT_WEIGHTING.md](COMMIT_WEIGHTING.md) for complete documentation.

## Why This Skill?

Most coding assistants treat codebases as static snapshots. They can read the current code but don't understand:
- **Why** the code is structured a certain way
- What **alternatives** were tried and abandoned
- How components **evolved** over time
- Where **technical debt** came from
- What **patterns** are mandatory vs optional
- What **risks** exist in specific areas

This skill gives Claude Code the ability to think like a **tenured senior engineer** who has lived through the entire project evolution
## Features

### 1. Folder Evolution Analysis
Understand how a folder/component evolved over time:
- Creation story and initial purpose
- Key milestones and architectural decisions
- Significant changes and refactors
- Current activity level and contributors

### 2. Smart Folder Discovery
Automatically identify the most interesting folders to analyze:
- Active development areas
- Core components with rich history
- Critical infrastructure (auth, db, caching)
- Legacy code needing attention

### 3. Historical Context for Questions
Get targeted historical information to answer specific questions:
- "Why was this implemented this way?"
- "What alternatives were considered?"
- "When did this pattern emerge?"

### 4. Folder Comparison
Compare the evolution of two components:
- Age and maturity differences
- Activity levels and contributor engagement
- Architectural evolution patterns

### 5. File-Level Function Evolution (NEW!)
Analyze how individual functions evolved within a file:
- **Hotspots**: Most frequently modified functions (unstable/bug-prone)
- **Complexity Growth**: Functions that grew significantly (code smells)
- **Function Coupling**: Functions that change together (tight dependencies)
- **Function Lifecycle**: When functions were added, modified, removed
- **Specific Function History**: Complete timeline for any function

**Why this matters**: Folder analysis tells you "this module changed a lot", but file analysis tells you "the `handle_streaming()` function has 47 modifications and grew from 20 to 150 lines - it's a complexity hotspot".

See [FILE_LEVEL_ANALYSIS.md](FILE_LEVEL_ANALYSIS.md) for complete documentation.

### 6. Adaptive Intelligence
Smart analysis that adapts to project characteristics:
- Dynamic commit limits based on project age and activity
- Dependency-based risk scoring (CRITICAL/HIGH/MEDIUM/LOW)
- Context condensation for large histories
- User prompts when uncertain

### 7. Counterfactual Analysis
Prove the value of historical context by simulating what would go wrong without it:
- Compare naive approach vs informed approach
- Identify specific mistakes that would be made
- Quantify value in points and monetary terms
- Show time savings and success rate improvements

See [COUNTERFACTUAL_VALUE.md](COUNTERFACTUAL_VALUE.md) for complete documentation.

### 8. Dependency Evolution Graph (NEW!)
Track how imports and dependencies changed over time:
- **File-Level**: When each import was added/removed, import churn
- **Folder-Level**: Circular dependencies, god objects, fan-in/fan-out metrics

**Why this matters**: Detect unstable dependencies, identify refactoring targets, prevent circular dependencies.

See [DEPENDENCY_AND_PATTERNS.md](DEPENDENCY_AND_PATTERNS.md) for complete documentation.

### 9. Architectural Pattern Detector (NEW!)
Identify and track architectural patterns across the codebase:
- **File-Level**: When patterns were introduced, dominant patterns
- **Folder-Level**: Pattern adoption %, consistency score, pattern violations

**Detects 14 patterns**: Retry, Async, Error Handling, Logging, Caching, Dependency Injection, Decorators, Context Managers, Singleton, Factory, Observer, Validation, Rate Limiting, Circuit Breaker

**Why this matters**: Ensure new code follows established conventions, identify files missing common patterns, enforce architectural consistency.

See [DEPENDENCY_AND_PATTERNS.md](DEPENDENCY_AND_PATTERNS.md) for complete documentation.

**Why this matters**: Automate 2-4 hours of manual research into 20 seconds. Find similar implementations, learn from past attempts, access best practices.

### 10. Design Intelligence (NEW!)
Generate complete design doc templates based on historical intelligence:
- **Historical context**: Reverts, activity, risk factors
- **Pattern requirements**: Mandatory patterns (>50% adoption)
- **Architectural constraints**: God objects, circular deps to avoid
- **Similar features**: Prior art and local references
- **Risk assessment**: What could fail + mitigation strategies
- **Implementation recommendations**: Specific, actionable steps

**Why this matters**: Design docs generated in 30 seconds instead of 2-4 hours. Includes all context, patterns, and risks automatically.

## Proactive Integration

This skill is designed to be used **proactively** by Claude Code BEFORE making changes:

**Modifying Code** → Automatically analyze function evolution + dependencies + patterns + risk
**Adding Feature** → Automatically generate a design doc with historical intelligence
**Creating Module** → Automatically analyze similar modules + extract consensus patterns

See [CLAUDE_CODE_INTEGRATION.md](CLAUDE_CODE_INTEGRATION.md) for complete integration guide.

## Installation

The skill is already installed in this repository at:
```
.claude/skills/code_archaeologist/
```

## Usage

### Command Line

```bash
# Discover interesting folders
python3 .claude/skills/code_archaeologist/skill.py suggest

# Analyze a specific folder
python3 .claude/skills/code_archaeologist/skill.py analyze <folder>

# Get compact analysis
python3 .claude/skills/code_archaeologist/skill.py analyze <folder> --format compact

# Get historical context for a question
python3 .claude/skills/code_archaeologist/skill.py context <folder> \
  --question "Why was authentication implemented this way?"

# Compare two folders
python3 .claude/skills/code_archaeologist/skill.py compare \
  <folder> --path2 <folder>/db

# Discover all folders (categorized)
python3 .claude/skills/code_archaeologist/skill.py discover

# Analyze a specific file (function-level)
python3 .claude/skills/code_archaeologist/skill.py file <folder>/main.py

# Analyze a specific function within a file
python3 .claude/skills/code_archaeologist/skill.py file <folder>.py --function route_request

# Smart adaptive analysis (combines all features)
python3 .claude/skills/code_archaeologist/skill.py smart <folder>/hooks

# Counterfactual analysis (what would go wrong without history?)
python3 .claude/skills/code_archaeologist/skill.py counterfactual <folder>/hooks \
  --commit <hash> --problem "Fix rate limiting"

# Dependency evolution (file-level import history)
python3 .claude/skills/code_archaeologist/skill.py dependencies <folder>/main.py

# Dependency graph (folder-level circular deps, god objects)
python3 .claude/skills/code_archaeologist/skill.py dep-graph <folder>

# Pattern evolution (file-level pattern introduction timeline)
python3 .claude/skills/code_archaeologist/skill.py patterns <folder>/main.py

# Pattern adoption (folder-level consistency and violations)
python3 .claude/skills/code_archaeologist/skill.py pattern-adoption <folder>

# Design doc generation (historical intelligence)
python3 .claude/skills/code_archaeologist/skill.py design <folder> \
  --feature "OAuth 2.0 Authentication" \
  --description "Add OAuth 2.0 authentication support for enterprise customers"
```

### With Claude Code

This skill is designed to be invoked by Claude Code when you ask questions about code history:

**User**: "Can you explain the history of the authentication system in <folder>?"

**Claude Code**:
1. Recognizes this is a historical question
2. Invokes the history analyzer skill
3. Gets comprehensive timeline and context
4. Synthesizes answer with citations

**User**: "Why was the router implemented this way?"

**Claude Code**:
1. Analyzes `<folder>/` history
2. Identifies key architectural decisions
3. Explains rationale with commit references

**User**: "I need to refactor the caching layer. What should I know?"

**Claude Code**:
1. Analyzes `<folder>/caching/` evolution
2. Shows what approaches were tried before
3. Identifies current pain points from recent commits
4. Suggests refactoring strategy informed by history

**User**: "I want to modify the handle_streaming function in router.py"

**Claude Code**:
1. Runs file-level analysis on `<folder>.py`
2. Checks if `handle_streaming` is a hotspot (high modification count)
3. Shows function's modification history
4. Warns if function has high coupling or complexity growth
5. Recommends testing strategy based on function's risk profile

### When to Use File-Level vs Folder-Level

**Folder-Level** (`analyze`, `smart`, `context`):
- Understanding module/component architecture
- Assessing overall risk of an area
- Finding related commits across multiple files
- Understanding feature evolution

**File-Level** (`file`):
- Before modifying a specific function
- Identifying complexity hotspots within a file
- Understanding function coupling (what changes together)
- Finding which functions are bug-prone

**Both**:
- Start with folder-level for big picture
- Drill down to file-level for specific changes

### Proactive Integration (The Real Power)

These skills should be used **automatically by Claude Code BEFORE making changes**:

```
User: "Fix the streaming timeout in router.py"

Claude Code (automatically runs):
1. Function Evolution → Is handle_streaming() a hotspot?
2. Dependencies → What does it import? Any churn?
3. Patterns → What patterns must I follow?
4. Dep-graph → What depends on this? Blast radius?
5. Risk Assessment → Combine all signals

Claude: "⚠️ HIGH RISK modification detected:
- handle_streaming() modified 47 times (hotspot)
- 12 files depend on router.py (god object)
- Must follow: async (68×), error handling (52×), logging (41×)
- Recommended: Feature flag + test all 12 dependents

Proceeding with history-informed implementation..."

[Claude then implements fix following ALL discovered patterns]
```

See [CLAUDE_CODE_INTEGRATION.md](CLAUDE_CODE_INTEGRATION.md) for complete integration guide.

## Output Formats

### Markdown (Default)
Full detailed timeline with:
- Summary statistics
- Evolution narrative
- Key milestones with commit hashes
- Top contributors
- Activity over time

### Compact
Quick summary format:
- Basic stats in one line
- Creation info
- Top 3 recent changes

### JSON
Structured data for programmatic use:
- All timeline data
- Commit metadata
- Statistical analysis

## How It Works

### 1. Git History Mining
- Extracts commits for specified folders
- Parses commit messages for PR numbers
- Tracks file changes over time

### 2. Significance Detection
Identifies important commits based on:
- Keywords: feat, fix, refactor, breaking, security
- PR association
- Number of files changed
- Commit message patterns

### 3. Timeline Clustering
Groups related commits into meaningful milestones:
- Time-based clustering (60-day windows)
- Significance scoring
- Evolution phase identification

### 4. Context Synthesis
Generates narrative explanations:
- "Why" behind decisions
- Evolution patterns
- Current state assessment
- Technical debt indicators

## Architecture

```
.claude/skills/code_archaeologist/
├── skill.py              # Main skill interface
├── git_utils.py          # Git history extraction
├── timeline_generator.py # Timeline creation and formatting
├── folder_discovery.py   # Smart folder finding
└── README.md            # This file
```

### Core Components

**git_utils.py**
- `get_folder_commits()` - Extract commit history
- `get_commit_details()` - Detailed commit info
- `identify_significant_commits()` - Smart filtering
- `cluster_commits_by_time()` - Timeline grouping
- `get_folder_structure()` - Repo topology

**timeline_generator.py**
- `generate_folder_timeline()` - Main timeline generator
- `format_timeline_markdown()` - Pretty output
- `_create_milestones()` - Milestone extraction
- `_analyze_commit_frequency()` - Activity patterns

**folder_discovery.py**
- `discover_folders()` - Find all folders
- `categorize_folders()` - Smart categorization
- `get_folder_suggestions()` - Prioritized recommendations
- `_calculate_relevance_score()` - Ranking algorithm

## Use Cases

### 1. Understanding Legacy Code
**Scenario**: New developer joins, needs to understand auth system

```bash
python3 skill.py context <folder> \
  --question "How did the authentication system evolve?"
```

**Result**: Complete narrative from initial JWT implementation through SSO integration and security fixes.

### 2. Pre-Refactoring Research
**Scenario**: Planning to refactor the router

```bash
python3 skill.py analyze <folder>
```

**Result**: See what approaches were tried, why current design was chosen, what pain points led to changes.

### 3. Architecture Review
**Scenario**: Understanding system architecture

```bash
python3 skill.py suggest
```

**Result**: Prioritized list of core components with context about their role and evolution.

### 4. Comparative Analysis
**Scenario**: Deciding between two implementation approaches

```bash
python3 skill.py compare <folder>/caching --path2 <folder>
```

**Result**: See how similar components evolved, learn from their different trajectories.

## Integration with Claude Code

Claude Code can automatically invoke this skill when:

1. **User asks historical questions**
   - "Why is X implemented this way?"
   - "How did Y evolve?"
   - "What's the history of Z?"

2. **User requests refactoring**
   - Automatically checks history to understand constraints
   - Identifies past failed attempts
   - Suggests approach based on evolution

3. **User debugs issues**
   - Finds when behavior changed
   - Identifies related fixes in history
   - Shows commit introducing the pattern

## Extending This Skill

### Adding New Commands

```python
# skill.py
def analyze_contributor_impact(self, author: str) -> str:
    """Show how a specific person shaped the codebase."""
    # Find all their commits
    # Identify their major contributions
    # Show their architectural influence
    pass
```

## Configuration

### Exclude Patterns
Edit `folder_discovery.py` to exclude specific folders:

```python
exclude_patterns = [
    '__pycache__',
    'test',
    'docs',
    'examples'
]
```

### Significance Keywords
Customize what makes a commit "significant" in `git_utils.py`:

```python
keywords = [
    'feat', 'feature', 'add',
    'fix', 'bug',
    'refactor', 'breaking',
    'security', 'performance'
]
```

### Time Windows
Adjust clustering window in `timeline_generator.py`:

```python
clusters = cluster_commits_by_time(
    commits,
    days_gap=60  # Adjust this
)
```

## Troubleshooting

### "No commits found"
- Ensure you're in a git repository
- Check folder path is correct
- Try increasing `--since` date range

### Slow performance
- Reduce `max_commits` in code
- Use `--format compact` for faster output
- Limit `--depth` in discovery

### Missing milestones
- Adjust significance scoring in `git_utils.py`
- Lower minimum commit threshold
- Check commit message patterns

## Performance

- **Small folders** (< 100 commits): < 1 second
- **Medium folders** (100-500 commits): 2-5 seconds
- **Large folders** (> 500 commits): 5-10 seconds
- **Full repo discovery**: 10-30 seconds

Optimizations:
- Commits are capped at 500 by default
- Only significant commits are analyzed in detail
- Folder discovery caches results

## Future Enhancements

1. **Semantic Search**: Find similar architectural patterns across time
2. **Contributor Network Analysis**: Understand collaboration patterns
3. **Technical Debt Detection**: Identify accumulated complexity
4. **Predictive Analytics**: Forecast areas needing attention
5. **Integration with CI/CD**: Link to build failures and performance metrics

## Contributing

See `CONTRIBUTING.md` for setup, style, and pull request guidelines.

## Code of Conduct

See `CODE_OF_CONDUCT.md`.

## License

MIT License. See `LICENSE`.

## Example Output

Key features demonstrated:
- 📁 Folder identification
- 🔥 Activity indicators
- 🎬 Creation history
- 📈 Evolution timeline
- 👥 Contributor analysis
- 🔗 PR/commit linking

---

**Built by udaybandaru** | Making AI understand code history | 2025

code-archaeologist

code-archaeologist Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

code-archaeologist

code-archaeologist Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README