dev-scout（开发侦察兵）

/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

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:

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:

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:

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:

3.5 Tech Stack Detection

See references/tech-detection.md:

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

graph LR Auth --> User User --> Dashboard Billing --> User

Feature-Level Output

plans/features/{feature}/scout.md:

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

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:

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