claude-sneakpeek

Use these patterns to navigate and understand unfamiliar codebases:

• Breadth-First Discovery: A three-phase approach. 1. FAN-OUT: Parallel scan of project structure, entry points, build files, and READMEs. 2. REDUCE: Synthesize an overview. 3. FAN-OUT: Deep dive into specific areas of interest.
• Feature Tracing: Follows a specific logic flow. 1. EXPLORE: Find relevant files via grep. 2. PIPELINE: Trace the flow from entry point through middleware/validation to the database layer. 3. REDUCE: Document the complete flow.
• Impact Analysis: Assesses the risk of changes. 1. EXPLORE: Find the definition/interface. 2. FAN-OUT: Find all imports, usages, and dependent tests. 3. REDUCE: Generate an impact report with risk assessment.

User Request: "How does user authentication work?"

Phase 1: EXPLORE
└─ Explore agent: Find auth-related files (grep patterns)

Phase 2: PIPELINE (Follow the flow)
├─ Explore agent: Entry point (login route/component)
├─ Explore agent: Middleware/validation layer
├─ Explore agent: Session/token handling
├─ Explore agent: Database/storage layer

Phase 3: REDUCE
└─ General-purpose agent: Document complete auth flow

Choose the model based on the complexity and required reasoning of the task. Always pass the model parameter explicitly when creating a Task.

Strategy: Use haiku for gathering, sonnet for well-defined work, and opus when you need real thinking.

# Gather info - spawn haiku wildly
Task(subagent_type="Explore", description="Find auth files", prompt="...", model="haiku", run_in_background=True)
Task(subagent_type="Explore", description="Find user routes", prompt="...", model="haiku", run_in_background=True)
Task(subagent_type="Explore", description="Find middleware", prompt="...", model="haiku", run_in_background=True)

# Clear implementation task - sonnet
Task(
    subagent_type="general-purpose",
    description="Implement login route",
    prompt="Create POST /login following the pattern in src/routes/users.ts...",
    model="sonnet",
    run_in_background=True
)

# Needs judgment and critical thinking - opus
Task(
    subagent_type="general-purpose",
    description="Design auth architecture",
    prompt="Analyze the codebase and recommend the best auth approach...",
    model="opus",
    run_in_background=True
)

When implementing new features, use the Plan-Parallel-Integrate (PIP) pattern to manage complexity and speed up development through parallelization.

1. PIPELINE (Research → Plan): Use an Explore agent to find existing patterns and a Plan agent to design the architecture.
2. FAN-OUT (Parallel Implementation): Deploy multiple agents (e.g., Agent A, B, C) to work on independent components simultaneously (e.g., database schema, middleware, routes, UI).
3. PIPELINE (Integration): Use a General-purpose agent to wire components together, add tests, and verify the end-to-end flow.

Alternatively, for full-stack features, use the Vertical Slice pattern: implement one complete flow (DB → API → UI) first before expanding via FAN-OUT.

User Request: "Add user authentication"

Phase 1: PIPELINE (Research → Plan)
├─ Explore agent: Find existing auth patterns, user models, middleware
└─ Plan agent: Design auth architecture using findings

Phase 2: FAN-OUT (Parallel Implementation)
├─ Agent A: Implement user model + database schema
├─ Agent B: Implement JWT/session middleware
├─ Agent C: Implement login/logout routes
└─ Agent D: Implement frontend auth components

Phase 3: PIPELINE (Integration)
└─ General-purpose agent: Wire components, add tests, verify flow

To perform a thorough Pull Request (PR) review, use a Multi-Dimensional Analysis pattern. This involves a two-phase orchestration:

1. FAN-OUT (Parallel analysis): Use an Explore agent to gather context, then spawn multiple general-purpose agents in parallel to analyze specific dimensions (Code Quality, Logic, Security, and Performance).
2. REDUCE (Synthesize): Use a final general-purpose agent to aggregate all findings, prioritize them, and format the final review.

For critical thinking tasks like code reviews, it is recommended to use the opus model for the analysis agents to ensure depth.

# All in single message for parallelism (opus for reviews - critical thinking)
Task(subagent_type="Explore", prompt="Fetch PR #123 details, understand context and related issues",
     model="haiku", run_in_background=True)
Task(subagent_type="general-purpose", prompt="Review code quality: patterns, readability, maintainability",
     model="opus", run_in_background=True)
Task(subagent_type="general-purpose", prompt="Review logic: correctness, edge cases, error handling",
     model="opus", run_in_background=True)
Task(subagent_type="general-purpose", prompt="Review security: injection, auth, data exposure",
     model="opus", run_in_background=True)
Task(subagent_type="general-purpose", prompt="Review performance: complexity, queries, memory",
     model="opus", run_in_background=True)

In the orchestration model, responsibilities and tool access are strictly divided to prevent agents from mismanaging the task graph.

Orchestrator Responsibilities

Orchestrators manage the high-level flow and task lifecycle. They use:

• Read (for synthesis of references, guides, and agent outputs)
• TaskCreate, TaskUpdate, TaskGet, TaskList (to manage the task graph)
• AskUserQuestion (to clarify scope)
• Task (to spawn workers)

Worker Responsibilities

Workers are specialized agents spawned to execute specific units of work. They use:

• Read, Write, Edit, Bash (for implementation and exploration)
• Glob, Grep, WebFetch, WebSearch, LSP (for discovery)
• Note: While Workers can see Task* tools, they must not use them to manage the task graph.

┌─────────────────────────────────────────────────────────────┐
│  ORCHESTRATOR uses directly:                                │
│                                                             │
│  • Read (references, guides, agent outputs for synthesis)  │
│  • TaskCreate, TaskUpdate, TaskGet, TaskList               │
│  • AskUserQuestion                                          │
│  • Task (to spawn workers)                                  │
│                                                             │
│  WORKERS use directly:                                      │
│                                                             │
│  • Read (for exploring/implementing), Write, Edit, Bash    │
│  • Glob, Grep, WebFetch, WebSearch, LSP                    │
│  • They CAN see Task* tools but shouldn't manage the graph │
└─────────────────────────────────────────────────────────────┘

Use structured patterns to document system design and evolution.

C4 Model Documentation

1. FAN-OUT: Generate documentation for different levels in parallel:
   • Context diagram: System and external actors.
   • Container diagram: Applications and data stores.
   • Component diagram: Internal components.
   • Code diagram: Critical classes/modules.
2. REDUCE: Compile into a single architecture document with diagrams.

Decision Record (ADR) Generation

1. EXPLORE: Find architectural patterns in the code.
2. FAN-OUT: Document individual decisions (e.g., database choice, framework choice). Each record should include: Context, Decision, Consequences, and Alternatives considered.

Data Flow Documentation

1. EXPLORE: Trace data through the system.
2. PIPELINE: Document ingress points, transformations, storage, and egress points.
3. REDUCE: Create a data flow diagram.