mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-03 15:43:11 +08:00
3bb4a821de
New team skill focused on structural architecture improvements (dependency cycles, coupling/cohesion, layering violations, God Classes, dead code). Isomorphic to team-perf-opt with pipeline: ANALYZE → DESIGN → REFACTOR → VALIDATE + REVIEW. Roles: coordinator, analyzer, designer, refactorer, validator, reviewer. Supports single/fan-out/independent/auto parallel modes.
114 lines
3.9 KiB
Markdown
114 lines
3.9 KiB
Markdown
# 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`:
|
|
|
|
```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 <hash>.md |
|
|
| No match | Execute subagent, cache result to <hash>.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
|
|
|
|
```json
|
|
{
|
|
"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 |
|