Discover and document how the codebase works - patterns, rules, and team conventions. Use when: (1) Before implementation to understand existing code, (2) Onboarding to a new codebase, (3) Documenting team patterns and architecture, (4) Understanding how a specific feature is implemented
/dev-scout # Project-level, medium mode
/dev-scout deep # Project-level, deep mode
/dev-scout auth # Feature-level
/dev-scout deep billing # Feature-level, deep mode
Prerequisite: MUST have tech-context.md first (patterns already documented)
Answers:
How does THIS feature work? (not patterns - those are in tech-context.md)
Where are the key files for this feature?
How to extend this feature?
What to watch out for?
Does NOT repeat:
Project-wide patterns (already in tech-context.md)
Tech stack info (already documented)
Code conventions (already documented)
Expected Outcome
Project-Level: tech-context.md (~150-200 lines)
Answers: How does this project work?
For new developers, provide:
Patterns - How we make API calls, access data, structure code (with file/location references)
Conventions - Team standards for naming, formatting, git workflow
Stack - Tech choices and why
All existing features - Complete list (important: don't miss any!)
Format: Overview + location reference, NOT do/don't lists
Example:
### API Communication
**Pattern:** All API calls go through `lib/api/client.ts` wrapper
**Location:** See `lib/api/client.ts` for implementation
**Usage:** Import `apiClient` and call methods
NOT:
✅ DO: Use apiClient
❌ DON'T: Use fetch directly
Feature-Level: codebase-context.md
Answers: How does THIS already-implemented feature work?
Purpose: Document existing implementation for understanding/extending, NOT create specs
Prerequisite: MUST have tech-context.md first
Captures:
How this feature uses the patterns (reference tech-context.md)
Where key files are (locations, entry points)
How it currently works (flow, architecture)
How to extend it (what to modify where)
Does NOT:
Create implementation specs (this is for EXISTING code)
Document existing code: How it works NOW, where files are, how to extend
Output:codebase-context.md describing current implementation
Pattern Discovery Rules
Sample, don't exhaust - Read 2-3 representative files, not all
Find abstractions - Wrappers, base classes, shared utilities
Capture with example - Show the pattern in action
Ask "what's the rule?" - Not "what files exist?"
Strategy by Codebase Size
Size
Strategy
Small (<100 files)
Sequential discovery
Medium (100-500)
Parallel by concern (API, data, UI, conventions)
Large (500+)
Use /utils/gemini first, then focused Claude analysis
Version Management
When tech-context.md exists:
Move current to history/tech-context-{date}.md
Note what changed (pattern changes, not file changes)
When feature scout requested:
Check tech-context.md exists first
If not, run project-level scout first
Output Template
See references/output-template.md for structure.
Tools
Tool
Purpose
Read
Docs, configs, sample files
Glob
Find patterns (wrappers, configs)
Grep
Search code patterns
Bash
Git history for conventions
Task
Parallel pattern discovery
Context7
Library patterns
Large Codebase Strategy
For 500+ files, use /utils/gemini:
Gemini scans full codebase (1M context)
Claude reads Gemini output
Claude deep dives on key patterns identified
Creates pattern-focused scout
Anti-Patterns
General:
❌ Listing every file in a directory
❌ Counting components/routes
❌ Including full file trees
❌ Documenting file locations (use Glob instead)
❌ Reading every file (sample instead)