# architectural-analysis

Audits a codebase for design problems: dead exports, duplicated duties, tangled types, dependency cycles. Read-only unless you've already allowed fixes.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 531 installs · ★ 643
- Author: Pedro Nauck
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/pedronauck/skills/tree/HEAD/skills/mine/architectural-analysis/SKILL.md
- Updated: 2026-10-20
- HTML: https://affpapa.org/en/nevibecode/skills/architectural-analysis

## What it does

The skill works inside the scope you give it. It first maps entry points and dependencies with `rg --files` and targeted searches, then sorts candidates against the signal catalog in `references/detection-catalog.md`. Treat the thresholds there as hints, not verdicts.

Nothing gets called dead until dynamic imports, reflection, framework hooks, tests and published APIs have been checked. A public export with no consumer in this checkout stays. Every serious finding is tied to source: path, line, the maintenance cost it causes, and the smallest change worth making.

Broad audits follow `assets/report-template.md` and land in `.audits/architectural-analysis-<timestamp>.md`, with inspected and uninspected areas kept apart. Formatting, performance profiling, security work and feature-level review sit outside this scope. On its own the audit changes nothing in your project; applying findings needs authorization you gave up front.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill architectural-analysis -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/architectural-analysis/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/architectural-analysis/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill architectural-analysis -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/architectural-analysis/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill architectural-analysis -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/architectural-analysis/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install pedronauck/skills architectural-analysis
```

2. **Manually: put the files in place**
- File: `.github/skills/architectural-analysis/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill architectural-analysis -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/pedronauck/skills --path skills/mine/architectural-analysis
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/architectural-analysis/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill architectural-analysis -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/pedronauck/skills/tree/HEAD/skills/mine/architectural-analysis/SKILL.md

## When to use it
- locate dead exports and responsibilities that overlap
- untangle dependency cycles between modules
- spot where type ownership has gone wrong
- get a report citing paths and lines instead of vague complaints

## Example prompts
- Run an architecture audit on the `billing` package and point out the overlapping responsibilities
- Write the audit report into `.audits` and say which areas you skipped
- Check whether the export in `src/legacy/index.ts` is used anywhere

## Similar
- [improve-codebase-architecture](https://affpapa.org/en/nevibecode/skills/improve-codebase-architecture.md) — skill · 1163035 installs
- [tdd](https://affpapa.org/en/nevibecode/skills/tdd.md) — skill · 1141062 installs
- [triage](https://affpapa.org/en/nevibecode/skills/triage.md) — skill · 990453 installs
- [codebase-design](https://affpapa.org/en/nevibecode/skills/codebase-design.md) — skill · 850344 installs
- [code-review](https://affpapa.org/en/nevibecode/skills/code-review.md) — skill · 789521 installs
- [implement](https://affpapa.org/en/nevibecode/skills/implement.md) — skill · 774700 installs

From the same set: [pedronauck/skills](https://affpapa.org/en/nevibecode/by/pedronauck/skills.md) — 18 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md