Agent-Skills.md

Agent Skills: /dev-scout - Codebase Explorer

Explore and document existing codebases at various depths

UncategorizedID: codihaus/claude-skills/dev-scout

Repository

codihaus/claude-skills
codihaus

Install this agent skill to your local

pnpm dlx add-skill https://github.com/codihaus/claude-skills/tree/HEAD/.claude/skills/dev-scout

Skill Files

Browse the full folder contents for dev-scout.

Download Skill

Loading file tree…

.claude/skills/dev-scout/SKILL.md

Skill Metadata

Name
dev-scout
Description
Explore and document existing codebases at various depths

/dev-scout - Codebase Explorer

Skill Awareness: See skills/_registry.md for all available skills.

  • Before: Use /debrief if requirements unclear
  • After: Use /dev-specs for implementation plans
  • Related: /diagram for architecture visualization

Explore and document codebases. Works at project level or per feature.

When to Use

  • Understand existing codebase before adding features
  • Document current state for team
  • Analyze specific area before implementation
  • Update scout after implementation

Usage

/dev-scout                      # Project-level, medium mode
/dev-scout deep                 # Project-level, deep mode
/dev-scout auth                 # Feature-level (plans/features/auth/)
/dev-scout deep billing         # Feature-level, deep mode
/dev-scout /path/to/code        # Custom path

Output Structure

Outputs to unified plans/ structure:

plans/
├── scout/                       # Project-level (/dev-scout)
│   ├── README.md                # Current summary
│   ├── structure.md             # File tree, tech stack
│   ├── features.md              # Existing features
│   └── history/                 # Previous snapshots
│       └── {date}.md
│
└── features/
    └── {feature}/
        ├── scout.md             # Feature-level (/dev-scout {feature})
        └── ...

Modes

| Mode | What It Does | When to Use | |------|--------------|-------------| | medium (default) | Structure, files, UI inventory | Quick overview | | deep | + API, models, logic, patterns | Before implementation |

Exploration Strategy

Parallel Directory Search

For large codebases, use parallel exploration with Task tool:

Divide codebase into logical sections:
- Agent 1: src/app/, src/pages/ (routes & pages)
- Agent 2: src/components/, src/ui/ (UI components)
- Agent 3: src/lib/, src/utils/, src/services/ (utilities)
- Agent 4: src/api/, prisma/, db/ (backend)

When to parallelize:

  • Project has 100+ files
  • Multiple distinct directories
  • Deep mode analysis

When to stay sequential:

  • Small codebases (<50 files)
  • Feature-level scout (focused area)
  • Simple structure

Priority Directories

Search high-value directories first based on task:

| Task | Priority Directories | |------|---------------------| | General overview | README, package.json, src/app/ | | Feature analysis | Feature folder, related components, API routes | | API understanding | api/, routes/, controllers/, services/ | | Data model | prisma/, models/, schema/, types/ | | UI inventory | components/, ui/, views/, pages/ |

Resilience

Handle exploration failures gracefully:

  • If a directory doesn't exist: Skip, note in coverage
  • If file read fails: Continue, mark as "unreadable"
  • If pattern returns nothing: Try alternative patterns
  • If timeout on large dir: Summarize what was found, note gap

Track coverage in output:

## Coverage
| Area | Status | Notes |
|------|--------|-------|
| src/app/ | ✓ Complete | 45 files |
| src/lib/ | ✓ Complete | 12 files |
| src/legacy/ | ⚠ Partial | Timeout after 50 files |
| docs/ | ✗ Skipped | Directory not found |

Workflow

Step 0: Check Documentation Graph

Before exploring code, check existing documentation context:

1. Read plans/docs-graph.json (if exists)
2. Find related nodes:
   - For feature scout: Find use cases, existing specs for that feature
   - For project scout: Get overview of documented features
3. Use relationships to focus exploration

How docs-graph helps:

| Scout Type | Graph Provides | |------------|----------------| | Project | List of documented features, existing UCs to validate | | Feature | Related use cases, specs, dependencies |

Example: /dev-scout auth

From docs-graph.json:
- uc-auth-001 (Login) → focus on login flow
- uc-auth-002 (Signup) → focus on registration
- [[feature-billing]] referenced → check billing integration

This context helps:

  • Focus exploration on relevant areas
  • Validate discovered features against documented UCs
  • Find integration points via graph edges

Step 0.5: Initial Assessment

Before diving in, run quick assessment:

# Option 1: Use scout-analyze script (recommended)
./scripts/scout-analyze.sh . --check

# If tools missing, ask user:
# "Missing tools: tree, scc. Install for better analysis? (--install)"

# Run full analysis
./scripts/scout-analyze.sh .

# Option 2: Manual (if script not available)
find . -type f | wc -l
ls -la && ls -d */

Determine strategy based on file count: | File Count | Strategy | |------------|----------| | <50 | Sequential, thorough | | 50-200 | Sequential, prioritized | | 200+ | Parallel exploration |

Check for existing docs:

  • README.md → Project description
  • CLAUDE.md → AI instructions, patterns
  • docs/ → Additional documentation
  • package.json / requirements.txt → Dependencies

Step 1: Determine Scope

Project-level (/dev-scout):

  • Scans entire codebase
  • Outputs to plans/scout/
  • Creates history snapshot if scout exists

Feature-level (/dev-scout auth):

  • Scans specific area only
  • Outputs to plans/features/auth/scout.md
  • Links to BRD use cases

Step 2: Check for Existing Scout

If plans/scout/ exists:

  1. Move current README.md to history/{date}.md
  2. Create fresh analysis
  3. Note what changed since last scout

If first scout:

  1. Create plans/scout/ folder
  2. Generate initial analysis

Step 3: Medium Mode Analysis

3.1 Documentation Check

Patterns:
- README.md, CLAUDE.md
- docs/**/*.md
- package.json, requirements.txt

Extract:

  • App description
  • Tech stack
  • Setup instructions

3.2 File Structure Scan

Get folder tree (depth 3):
- /src, /app, /pages
- /components, /views
- /lib, /utils
- /api, /server

3.3 Frontend File Inventory

See references/file-patterns.md:

Include: **/*.vue, **/*.tsx, **/*.jsx
Exclude: node_modules/**, dist/**

Group by:

  • Pages/Routes → Screens
  • Components → UI inventory
  • Views → Layouts

3.4 Feature Inference

See references/feature-patterns.md:

| Pattern | Feature | |---------|---------| | auth/, login.* | Authentication | | payment/, checkout/ | Payments | | dashboard/ | Dashboard |

3.5 Tech Stack Detection

See references/tech-detection.md:

| File | Tech | |------|------| | next.config.* | Next.js | | prisma/schema.prisma | Prisma |

Step 4: Deep Mode Analysis (if requested)

Additional to medium mode:

4.1 API Analysis

Patterns:
- **/api/**/*.ts
- **/routes/**/*.ts

Document:

  • Endpoints (method, path)
  • Authentication requirements
  • Patterns used

4.2 Data Model Analysis

Patterns:
- prisma/schema.prisma
- **/models/**/*.ts

Document:

  • Entities
  • Relationships
  • Key fields

4.3 Code Pattern Identification

Read representative files for:

  • State management
  • API client patterns
  • Authentication flow
  • Error handling

4.4 Project Conventions Detection

Code Style (read from config or infer from code):

Check for configs:
- .eslintrc.* → Linting rules
- .prettierrc.* → Formatting
- tsconfig.json → TypeScript strictness
- .editorconfig → Tabs/spaces, line endings

Infer from code (sample 3-5 files):
- Naming: camelCase, PascalCase, snake_case
- File naming: Component.tsx vs component.tsx
- Import style: absolute (@/) vs relative (./)
- Quote style: single vs double
- Semicolons: yes/no

Git Conventions (read from history):

# Check commit style
git log --oneline -20

Detect patterns:
- Conventional commits? (feat:, fix:, chore:)
- Emoji commits? (✨, 🐛, 🔧)
- Ticket refs? (JIRA-123, #123)
- Simple messages? (no pattern)

# Check branch naming
git branch -a | head -20

Detect patterns:
- feature/*, bugfix/*, hotfix/*
- feat/*, fix/*
- username/feature-name
- No pattern

Project Conventions:

Check for:
- CLAUDE.md → AI instructions (HIGH VALUE)
- CONTRIBUTING.md → Team guidelines
- .github/PULL_REQUEST_TEMPLATE.md → PR format
- .github/ISSUE_TEMPLATE/* → Issue format

Document:
- How to name files
- How to structure components
- How to write tests
- PR/commit requirements

Step 5: Generate Output

Project-Level Output

plans/scout/README.md:

# Codebase Analysis

> **Last Updated**: {date}
> **Mode**: Medium | Deep
> **Previous**: [→ history/]

## Summary
{Brief description of the app}

## Tech Stack
| Layer | Technology |
|-------|------------|
| Frontend | {framework} |
| Backend | {framework} |
| Database | {db} |
| Auth | {method} |

## Conventions (deep mode)

### Code Style
| Aspect | Convention |
|--------|------------|
| Naming | camelCase (variables), PascalCase (components) |
| File naming | kebab-case.tsx |
| Imports | Absolute (@/lib/*) |
| Quotes | Single |
| Semicolons | No |

### Git Conventions
| Aspect | Convention |
|--------|------------|
| Commits | Conventional (feat:, fix:, chore:) |
| Branches | feature/*, bugfix/* |
| PR template | Yes (.github/PULL_REQUEST_TEMPLATE.md) |

### Project Rules
{From CLAUDE.md or CONTRIBUTING.md}
- {Rule 1}
- {Rule 2}

## Structure Overview

src/ ├── app/ # {description} ├── components/ # {description} └── lib/ # {description}


## Existing Features
| Feature | Evidence | Confidence |
|---------|----------|------------|
| Auth | `app/auth/`, `LoginForm.tsx` | High |
| Dashboard | `app/dashboard/` | High |

## Pages/Routes
| Path | File | Description |
|------|------|-------------|
| / | `app/page.tsx` | Home |
| /login | `app/login/page.tsx` | Login |

## Components ({count})
{List key components}

## API Endpoints (deep mode)
| Method | Path | Handler |
|--------|------|---------|
| GET | /api/users | users.list |

## Integration Points
{How to connect new features}

## Coverage
| Area | Status | Files | Notes |
|------|--------|-------|-------|
| src/app/ | ✓ | 45 | Routes, pages |
| src/components/ | ✓ | 32 | UI components |
| src/lib/ | ✓ | 8 | Utilities |

## Gaps / Unresolved
- {Any areas not fully explored}
- {Questions for follow-up}

## Notes
{Observations, potential issues}

plans/scout/structure.md:

# File Structure

## Directory Tree

{full tree output}


## Key Directories
| Directory | Purpose | File Count |
|-----------|---------|------------|

## Config Files
| File | Purpose |
|------|---------|

plans/scout/features.md:

# Existing Features

## Feature Inventory

### {Feature 1}
- **Status**: Complete | Partial | Planned
- **Files**: {list}
- **Depends on**: {other features}

### {Feature 2}
...

## Feature Relationships
```mermaid
graph LR
    Auth --> User
    User --> Dashboard
    Billing --> User


#### Feature-Level Output

**plans/features/{feature}/scout.md:**
```markdown
# {Feature} - Scout Analysis

> **Date**: {date}
> **Mode**: Medium | Deep
> **Feature**: [[feature-{feature}]]
> **Related UCs**: [[uc-{group}-001]], [[uc-{group}-002]]

## Summary
{What this feature does currently}

## Files
| File | Purpose |
|------|---------|
| {path} | {description} |

## Current Implementation
{How it works}

## API Endpoints (if applicable)
| Method | Path | Description |
|--------|------|-------------|

## Data Models (if applicable)
| Model | Fields | Relations |
|-------|--------|-----------|

## Integration Points
{How to extend or modify}

## For Implementation
- Entry point: {file}
- Key patterns: {patterns used}
- Dependencies: {what to be aware of}

Step 6: Update History (project-level)

If updating existing scout:

  1. Move current to history/{date}.md
  2. In new README.md, add:
## Changes Since Last Scout
- Added: {new files/features}
- Modified: {changed areas}
- Removed: {deleted items}

Tools Used

| Tool | Purpose | |------|---------| | Task | Parallel exploration (Explore agents) | | Glob | Find files by pattern | | Grep | Search code patterns | | Read | Read file contents | | Bash | Directory listing, file counts | | Write | Output files |

Parallel Exploration Example

For large codebases (200+ files), spawn parallel agents:

Task 1 (Explore): "Search src/app/ and src/pages/ for route definitions, page components. List files with brief purpose."

Task 2 (Explore): "Search src/components/ for UI components. Group by type (forms, buttons, layouts, etc.)."

Task 3 (Explore): "Search src/lib/, src/utils/, src/services/ for utilities. Identify patterns, shared logic."

Task 4 (Explore): "Search api/, prisma/, db/ for backend code. Document endpoints, models."

Synthesize results from all agents into unified scout output.

Tips

General:

  • Run project-level scout first for overview
  • Use feature-level before /dev-specs
  • Update scout after major implementations
  • History helps track codebase evolution

For large codebases:

  • Start with Step 0 assessment to choose strategy
  • Parallelize with 3-5 agents max (diminishing returns beyond)
  • Focus deep analysis on areas relevant to task
  • Accept partial coverage if codebase is huge - note gaps

For monorepos:

  • Treat each package/app as separate scout target
  • Document inter-package dependencies
  • Use feature-level scout for specific packages

Quality over speed:

  • Better to have thorough analysis of key areas than shallow scan of everything
  • Flag uncertainties rather than guessing
  • Include "Gaps / Unresolved" section honestly

Scripts

scout-analyze.sh

Quick codebase analysis with optional tool installation:

# Check available tools
./scripts/scout-analyze.sh . --check

# Run analysis with available tools
./scripts/scout-analyze.sh /path/to/code

# Auto-install missing tools and analyze
./scripts/scout-analyze.sh . --install

# Output as JSON (for parsing)
./scripts/scout-analyze.sh . --json

Tools checked: | Tool | Purpose | Fallback | |------|---------|----------| | tree | Visual directory structure | find -type d | | scc | Code stats (fast, accurate) | wc -l | | jq | Parse JSON configs | grep | | rg | Fast search | grep -r |

Output includes:

  • File/directory counts
  • Directory structure (depth 2)
  • Code statistics by language
  • Top file extensions
  • Dependencies (package.json, requirements.txt, go.mod)
  • Git activity (recent commits, active files, contributors)
  • Config files detected

Usage in workflow:

  1. Run ./scripts/scout-analyze.sh . --check in Step 0
  2. Offer user to install missing tools
  3. Run full analysis to inform exploration strategy

References

  • references/file-patterns.md - Search patterns
  • references/feature-patterns.md - Feature inference
  • references/tech-detection.md - Tech stack detection