Expert Navigator Guide

Your generalist agent for navigating complex software engineering challenges — providing expert-level guidance on technology selection, system design, debugging strategies, and best practices across the full development lifecycle.

When to Use This Agent

Choose Expert Navigator Guide when:

• Seeking expert guidance on unfamiliar technology decisions
• Navigating complex engineering problems that span multiple domains
• Getting recommendations on tools, libraries, and approaches for specific scenarios
• Understanding trade-offs between different technical approaches
• Onboarding to a new technology stack or codebase

Consider alternatives when:

• You need deep expertise in one specific technology — use a domain specialist agent
• You need actual code implementation — use a developer agent
• You need infrastructure or deployment — use a DevOps agent

Quick Start

Copy
# .claude/agents/expert-navigator.yml
name: Expert Navigator Guide
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Expert generalist agent for navigating technology decisions, system design, and engineering best practices

Example invocation:

claude "We're building a real-time analytics dashboard. Help us navigate the technology choices — should we use WebSockets vs SSE, what database for time-series data, and how to handle 10K concurrent users"

Core Concepts

Technology Decision Matrix

Factor	Weight	Question
Team Expertise	High	Does the team know this technology?
Community & Ecosystem	High	Is there active community support?
Scalability	Medium-High	Will it handle 10x growth?
Operational Cost	Medium	What's the total cost of ownership?
Learning Curve	Medium	How quickly can the team get productive?
Lock-in Risk	Low-Medium	How hard is it to switch later?

Navigation Framework

Problem Space                    Solution Space
┌─────────────┐                 ┌─────────────┐
│ Requirements │───Analyze───→  │ Options      │
│ Constraints  │                │ Trade-offs   │
│ Context      │                │ Risks        │
└─────────────┘                 └─────────────┘
       │                              │
       └────── Evaluate ──────────────┘
                   │
            ┌──────┴──────┐
            │ Recommended  │
            │ Approach     │
            └─────────────┘

Configuration

Parameter	Description	Default
guidance_depth	Detail level (overview, detailed, exhaustive)	detailed
focus_areas	Priority domains (backend, frontend, data, infra, all)	all
risk_tolerance	Comfort with new tech (conservative, balanced, progressive)	balanced
team_context	Team size and skill level	provided per question
decision_style	Output style (options-list, recommendation, comparison)	recommendation

Best Practices

1. Anchor decisions to specific, measurable requirements. "We need a fast database" is too vague to navigate. "We need sub-10ms reads for 100K queries/sec with 30-day data retention" eliminates most options and makes the decision tractable.

2. Evaluate build-vs-buy for every significant component. Before building a custom solution, check if a managed service or open-source tool solves 80% of the problem. Custom code is a liability — every line needs maintenance, testing, and operational support.

3. Prototype the riskiest assumption first. If the entire architecture depends on "we can process events in under 50ms," validate that assumption with a prototype before building the rest of the system. Failing fast on the critical assumption saves months of wasted effort.

4. Consider the second-year cost, not just the first-month setup. Technologies that are easy to start with (Firebase, Heroku) may become expensive or limiting at scale. Technologies that require upfront investment (Kubernetes, custom infrastructure) may pay off at scale. Model costs at 1x, 5x, and 10x your expected scale.

5. Prefer boring technology for critical paths. Novel technologies are exciting but risky for core infrastructure. PostgreSQL, Redis, and Linux have decades of battle-testing. Use novel tech for non-critical features where failure is cheap and learning is valuable.

Common Issues

Analysis paralysis from too many valid options. When 5 databases all "work," the decision stalls. Set time-boxed evaluation criteria, score each option against them, and pick the highest-scoring option. Perfect is the enemy of shipped.

Technology choice driven by resume-building rather than project needs. Kubernetes for a side project, microservices for a 2-person team. Match technology complexity to organizational capacity. If the team can't operate it, it's the wrong choice regardless of its technical merits.

Recommendations change based on who you ask. Every expert has preferences. Focus on requirements and trade-offs rather than opinions. Document why you chose option A over B and C, so the decision can be re-evaluated when context changes.