git:20260925.de695e3 to git:20260929.bb41808

---

name: analyzing-cpp-codebase

description: Analyzes C++ desktop codebase architecture, dependency graphs, framework detection, and migration assessment. Use when exploring an unfamiliar C++ project or assessing upgrade paths.

compatibility: Designed for Claude Code

metadata:

allowed-tools: Read, Grep, Glob, Bash

argument-hint: [directory-or-question]

stability: stable

---

# C++ Codebase Analysis

**Target**: $ARGUMENTS

Analyzes C++ desktop project structure, dependencies, and architecture.

Delivers actionable findings, not exhaustive documentation.

## Workflow

1. **Detect project layout** — scan for CMakeLists.txt, .pro files, src/, include/

2. **Identify framework** — determine wxWidgets, GTK3, Qt, or mixed

3. **Map dependencies** — CMake targets, find_package calls, include graph

4. **Assess architecture** — module boundaries, coupling, layering

5. **Report findings** — structured summary with actionable items

## Framework Detection

Check these indicators in order:

| Framework | CMake Signal | Include Signal | Other |

|------------|---------------------------------|-------------------------|----------------------|

| Qt | `find_package(Qt6)` / `Qt5` | `#include <QWidget>` | `.pro`, `.qrc` files |

| wxWidgets | `find_package(wxWidgets)` | `#include <wx/wx.h>` | — |

| GTK3 | `pkg_check_modules(GTK3)` | `#include <gtk/gtk.h>` | `.ui` (GtkBuilder) |

## Dependency Mapping

```bash

# List all CMake targets

grep -rn "add_library\|add_executable" CMakeLists.txt */CMakeLists.txt 2>/dev/null

# List external dependencies

grep -rn "find_package\|pkg_check_modules" CMakeLists.txt */CMakeLists.txt 2>/dev/null

# Include graph (most-included headers)

grep -rh '#include "' src/ include/ 2>/dev/null | sort | uniq -c | sort -rn | head -20

```

## Architecture Assessment

Evaluate these dimensions:

**Module Boundaries**:

- Are source files organized by feature or by layer?

- Is there a clear `src/` vs `include/` separation?

- Are GUI components isolated from business logic?

**Coupling**:

- How many cross-module includes exist?

- Are there circular dependencies?

- Is dependency injection or interface abstraction used?

**Build Structure**:

- Single CMakeLists.txt or hierarchical?

- Are libraries split into reusable targets?

- Are tests in a separate target?

## Migration Assessment

When evaluating framework upgrades (e.g., wxWidgets 3.0 to 3.2, Qt5 to Qt6):

1. **Identify version** — check CMake version constraints, include paths

2. **List deprecated APIs** — grep for known deprecated symbols

3. **Assess scope** — count affected files and call sites

4. **Estimate effort** — categorize changes as mechanical vs architectural

5. **Flag blockers** — identify removed APIs requiring redesign

## Output Format

```markdown

## Project Summary

- Framework: [detected]

- C++ standard: [detected from CMake or compiler flags]

- Build system: [CMake version / qmake]

- Modules: [count and names]

## Dependency Graph

[CMake target relationships]

## Architecture Notes

[Key observations about structure and coupling]

## Recommendations

[Prioritized, actionable items]

```

## Rules

- Report facts, not opinions — cite file paths and line numbers

- Flag risks but do not refactor without explicit request

- Keep output structured and scannable