Claude-Code-Workflow/.claude/skills/team-arch-opt/subagents/explore-subagent.md

Explore Subagent

Shared codebase exploration for discovering architecture-critical structures, dependency graphs, module boundaries, and layer organization. Results are cached to avoid redundant exploration across analyzer and refactorer roles.

Design Rationale

Codebase exploration is a read-only operation shared between analyzer (mapping structural issues) and refactorer (understanding implementation context). Caching explorations avoids redundant work when refactorer re-explores structures the analyzer already mapped.

Invocation

Called by analyzer, refactorer after needing codebase context for architecture analysis or implementation:

Task({
  subagent_type: "cli-explore-agent",
  run_in_background: false,
  description: "Explore codebase for architecture-critical structures in <target-scope>",
  prompt: `Explore the codebase to identify architecture-critical structures.

Target scope: <target-scope>
Session: <session-folder>
Focus: <exploration-focus>

Tasks:
1. Map the module structure, entry points, and layer boundaries within scope
2. Build dependency graph (import/require relationships between modules)
3. Identify architectural patterns (layering, dependency injection, event-driven, plugin architecture)
4. Note any existing abstractions, interfaces, and module boundaries
5. List key files with their roles, layer assignment, and dependency relationships

Output a structured exploration report with:
- Module map (key files, their relationships, and layer assignments)
- Dependency graph (directed edges between modules, cycle indicators)
- Layer structure (identified layers and their boundaries)
- Existing architectural patterns found
- Architecture-relevant configuration (path aliases, barrel exports, module boundaries)`
})

Cache Mechanism

Cache Index Schema

<session-folder>/explorations/cache-index.json:

{
  "entries": [
    {
      "key": "<scope-hash>",
      "scope": "<target-scope>",
      "focus": "<exploration-focus>",
      "timestamp": "<ISO-8601>",
      "result_file": "<hash>.md"
    }
  ]
}

Cache Lookup Rules

Condition	Action
Exact scope+focus match exists	Return cached result from .md
No match	Execute subagent, cache result to .md, update index
Cache file missing but index has entry	Remove stale entry, re-execute
Cache older than current session	Use cached (explorations are stable within session)

Integration with Calling Role

The calling role is responsible for:

1. Before calling: Determine target scope and exploration focus
2. Calling: Check cache first, invoke subagent only on cache miss
3. After calling:

Result	Action
Exploration successful	Use findings to inform analysis/implementation
Exploration partial	Use available findings, note gaps
Exploration failed	Proceed without exploration context, use direct file reading

Output Schema

{
  "scope": "<target-scope>",
  "module_map": [
    { "file": "<path>", "role": "<description>", "layer": "<presentation|domain|data|infra>", "dependency_graph": { "imports": ["<path>"], "imported_by": ["<path>"] } }
  ],
  "dependency_graph": {
    "nodes": ["<module-path>"],
    "edges": [{ "from": "<path>", "to": "<path>", "type": "<import|re-export|dynamic>" }],
    "cycles": [["<path-a>", "<path-b>", "<path-a>"]]
  },
  "layer_structure": [
    { "layer": "<name>", "modules": ["<path>"], "violations": ["<description>"] }
  ],
  "existing_patterns": [
    { "type": "<pattern>", "location": "<file:line>", "description": "<what>" }
  ],
  "investigation_targets": ["<file-or-pattern>"]
}

Error Handling

Scenario	Resolution
Single exploration angle fails	Continue with partial results
All exploration fails	Return basic result from direct file listing
Target scope not found	Return error immediately
Cache corrupt	Clear cache-index.json, re-execute