analyzing-cpp-codebase

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

# 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

## 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