Architecture Analyze Skill

Analyze proposed architectural changes or validate designs before implementation.

Memory location: ~/.claude/projects/<project>/memory/agents/architecture.md </IMPORTANT>

When to Use

Detecting Architectural Changes

Invoke this skill when PR/changes include:

Analysis Process

┌─────────────────────────────────────────────────────────────────┐
│                 Phase 0: Read Architecture Memory                │
│         Load existing knowledge about this codebase              │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                 Phase 1: Explore (if needed)                     │
│         Spawn Explore agent only for unknown areas               │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                 Phase 2: Analyze Module Boundaries               │
│         Where does new code belong? Proper separation?           │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                 Phase 3: Analyze Dependencies                    │
│         Direction correct? Cycles? Coupling level?               │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                 Phase 4: Assess Testability                      │
│         Isolation possible? Dependencies injectable?             │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                 Phase 5: Simplicity Check                        │
│         Over-engineered? Simpler alternative exists?             │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                 Phase 6: Generate Report                         │
│         Findings, concerns, recommendations                      │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                 Phase 7: Update Architecture Memory              │
│         Persist new knowledge for future reviews                 │
└─────────────────────────────────────────────────────────────────┘

Phase 0: Read Architecture Memory

Before exploring, check what you already know:

# Memory file location
~/.claude/projects/<project>/memory/agents/architecture.md

If memory exists:

1. Read the memory file
2. Check if relevant modules are already documented
3. Only explore areas NOT covered by memory
4. Use memory to provide context for new analysis

If memory doesn't exist:

1. Proceed to full exploration (Phase 1)
2. Create memory file after analysis

Phase 1: Explore Existing Architecture

Spawn an Explore agent with thoroughness "medium" or "very thorough":

Prompt for Explore agent:
"Analyze the existing architecture of this codebase focusing on:
1. Module/directory structure and their responsibilities
2. Key interfaces and abstract classes
3. Dependency patterns (how modules connect)
4. Factory/creation patterns used
5. How similar features were implemented before

Context: [describe the proposed changes or feature]

Return:
- Module map with responsibilities
- Key abstractions and interfaces
- Dependency graph (which modules depend on which)
- Patterns used for similar features"

What to Learn

Phase 2: Analyze Module Boundaries

Check Placement

Boundary Violations

Look for:

• Code that should be in a different module
• Module doing too many things
• Missing module that should exist
• Duplicate functionality across modules

Report Format

### Module Boundary Analysis

**Proposed location:** `src/module_name/`

**Assessment:** [Appropriate / Needs Discussion / Wrong Location]

**Findings:**
- [Finding 1]
- [Finding 2]

**Recommendation:** [Where code should go and why]

Phase 3: Analyze Dependencies

Dependency Direction

Good: High-level → Low-level
      UI → Business Logic → Data Access

Bad:  Low-level → High-level (inverted)
      Data Access → Business Logic

Check for Issues

Dependency Analysis Commands

# For C++ - find includes from changed files
grep -r "#include" <changed_files> | grep -v "test"

# For Python - find imports
grep -r "^import\|^from" <changed_files>

# Visualize with existing tools if available
# cmake --graphviz=deps.dot build/

Report Format

### Dependency Analysis

**New dependencies introduced:**
- `module_a` → `module_b` (via `InterfaceX`)
- `module_a` → `external_lib`

**Dependency direction:** [Correct / Inverted / Needs Abstraction]

**Circular dependencies:** [None found / Found: A → B → A]

**Coupling assessment:** [Low / Medium / High]

**Concerns:**
- [Concern 1]

**Recommendations:**
- [How to fix dependency issues]

Phase 4: Assess Testability

Testability Criteria

Questions to Answer

1. Can this be unit tested in isolation?
   • Are dependencies injectable?
   • Can we mock collaborators?
2. What's the mocking complexity?
   • How many mocks needed?
   • Are mocks simple or complex?
3. Are there test-hostile patterns?
   • Singletons?
   • Static methods with side effects?
   • Global state?

Report Format

### Testability Assessment

**Can be unit tested in isolation:** [Yes / Partially / No]

**Dependencies:**
| Dependency | Injectable? | Mockable? |
|------------|-------------|-----------|
| `DatabaseClient` | Yes (constructor) | Yes (interface) |
| `Logger` | No (global) | No |

**Mocking complexity:** [Low / Medium / High]
- Mocks needed: [count]
- Complex mocks: [list]

**Test-hostile patterns found:**
- [Pattern and location]

**Recommendations:**
- [How to improve testability]

Phase 5: Simplicity Check

Over-Engineering Signals

Questions to Ask

1. What's the simplest solution that works?
   • Can this be a function instead of a class?
   • Can this be one class instead of three?
2. Is the abstraction earning its keep?
   • Does the interface have multiple implementations?
   • Will it realistically be extended?
3. YAGNI check
   • Is this solving a current problem or a hypothetical one?
   • What's the cost of adding this later if needed?

Simpler Alternatives

For each abstraction/pattern, consider:

Report Format

### Simplicity Check

**Over-engineering concerns:**
- [Concern 1: what and why]
- [Concern 2: what and why]

**Simpler alternatives:**

| Current Approach | Simpler Alternative | Recommendation |
|------------------|---------------------|----------------|
| [What's proposed] | [Simpler option] | [Keep / Simplify] |

**YAGNI violations:**
- [Code that solves hypothetical problems]

**Verdict:** [Appropriate complexity / Over-engineered / Under-engineered]

Phase 6: Generate Report

Full Architecture Review Report

# Architecture Review

## Summary

**Scope:** [PR #X / Feature Y planning]

**Verdict:** [Approve / Concerns / Needs Rework]

**Key findings:**
- [1-3 bullet summary]

---

## 1. Existing Architecture Context

[Summary from Explore agent]

- **Relevant modules:** [list]
- **Key interfaces:** [list]
- **Patterns used:** [list]

---

## 2. Module Boundaries

**Assessment:** [Appropriate / Needs Discussion / Wrong Location]

[Details from Phase 2]

---

## 3. Dependencies

**Assessment:** [Clean / Minor Issues / Major Issues]

[Details from Phase 3]

---

## 4. Testability

**Assessment:** [Good / Acceptable / Poor]

[Details from Phase 4]

---

## 5. Simplicity

**Assessment:** [Appropriate / Over-engineered / Under-engineered]

[Details from Phase 5]

---

## Recommendations

### Must Address (Blocking)

1. [Critical architectural issue]

### Should Address (Non-blocking)

1. [Important improvement]

### Consider (Optional)

1. [Nice-to-have suggestion]

---

## Questions for Author

- [Clarifying questions about design decisions]

Phase 7: Update Architecture Memory

After completing analysis, update your memory:

# Architecture Memory

## Project: [project name]
Last updated: [date]

## Module Map
<!-- List all discovered modules and their responsibilities -->

| Module | Responsibility | Key Files |
|--------|----------------|-----------|
| src/core/ | Core business logic | core.cpp, engine.cpp |
| src/api/ | External API layer | handler.cpp, router.cpp |

## Key Interfaces
<!-- Important abstractions that define boundaries -->

- `IProcessor` - Main processing interface (src/core/processor.h)
- `IStorage` - Storage abstraction (src/storage/storage.h)

## Dependency Patterns
<!-- How modules connect to each other -->

api/ → core/ → storage/ ↘ utils/

## Architectural Decisions
<!-- Design choices and their rationale -->

- **Why X instead of Y**: [reason]
- **Pattern used for Z**: [pattern and why]

## Known Issues
<!-- Architectural debt or areas needing improvement -->

- Circular dependency between X and Y
- Core module is getting too large

Memory update rules:

1. Only add confirmed patterns (not speculation)
2. Update existing entries if they change
3. Remove outdated information
4. Keep memory concise and useful

Integration with Other Skills

From pr-review

pr-review detects architectural changes:
  → Invoke architecture-analyze
  → Include architecture report in PR review
  → Architectural issues become "Must Fix" items
  → Memory is updated with new architectural knowledge

From planning-feature

planning-feature validates design:
  → Invoke architecture-analyze with proposed design
  → Catch issues before coding starts
  → Adjust plan based on findings
  → Memory helps understand existing architecture faster

Quick Architecture Checklist

For fast reviews, at minimum verify:

• Code is in the appropriate module
• No circular dependencies introduced
• Dependencies go in the right direction (high → low level)
• New code can be unit tested
• No obvious over-engineering

References

• Clean Architecture - Robert C. Martin
• SOLID Principles
• YAGNI