Codebase Architecture Analyze & Extract
Transform an opaque codebase into durable architecture documentation. This is the analysis / extract half of the reimplementation playbook (see playbook-chain.md and vault comparisons/codebase-analysis-reimplementation-skills.md).
Mandatory skill load
Before writing durable extracts, invoke skill codebase-design (load glossary + principles). Use its terms exactly — module, interface, depth, seam, adapter, leverage, locality — in every extract.
C4 vs design vocabulary: C4 Component is a diagram level only. Extract files and design prose use module / seam cluster. See c4-evidence.md.
Output routing (mandatory)
Before writing files, resolve the extract root per output-routing.md:
- Explicit
--save / path from user
- Else if SkillWiki vault and
projects/{slug}/ exists (slug algorithm in output-routing) → {WIKI}/projects/{slug}/architecture/
- Else →
{TARGET_REPO}/docs/architecture/
--ephemeral → terminal only
Announce the resolved output root to the user before bulk writes.
Pin source commit/tag in every file header. Plugin version: read .claude-plugin/plugin.json → version (see output-routing). Prefer numbered extract set:
| File |
Content |
00-reimplementation-blueprint.md |
E2E flow + milestone plan + verify commands |
01-topology.md |
Tree, stack, entry points, deps, scope, observed vs inferred; short C4 overview may live here |
02-module-{name}.md, 03-module-{name}.md, … |
Sequential major module / seam cluster specs (start at 02) |
04-adrs.md or adrs/ADR-*.md |
Optional when ADR register is large; else ADRs section in 01/00 |
05-tech-debt.md |
Optional when debt register is large |
08-*.md / 09-*.md |
Optional layer inventories |
Workflow
Phase 0 — Target, scope & pin
- Identify target repo (cwd or user path).
- Record: remote,
git describe --tags --always, short SHA, package/UI versions if they differ.
- State scope (repo-only / monorepo slice / service-in-platform / partial). See c4-evidence.md.
- Resolve output root (above). Announce path before bulk writes.
- Optional pack: repomix / code2prompt when the tree is large.
Phase 1 — Reconnaissance
- Stack: language, frameworks, build, storage, external integrations.
- Directory tree and roles.
- Entry points: main app, routers, workers, CLI, schedulers.
- Config: manifests, env templates, CI, compose/IaC.
Write 01-topology.md early. Separate Observed vs Inferred bullets.
Phase 2 — Structural analysis
For each major module (design vocabulary):
- Purpose, location, public interface, dependencies, dependents, key files
- Dependency graph (Mermaid); flag cycles and layer leaks
- Data flows: request path, events, background jobs (sequence diagrams)
Phase 3 — Pattern recognition
Document structural patterns (layered, hexagonal, event-driven, …), design patterns in use, data patterns (repository, CQRS, …). Note deviations from textbook form with file evidence.
Phase 4 — C4 + decisions + debt
- C4: Context → Container → Component (Code sparingly). Label diagram levels as C4; map internals to modules. Prefer embedding a short C4 overview in
01-topology.md; use a separate file only if large.
- ADRs for load-bearing decisions found in code (status: Discovered | Active | …) →
04-adrs.md / adrs/ or a section in 00/01.
- Tech debt register: code / architecture / dependency / docs / infra →
05-tech-debt.md or a section in 00/01.
Phase 5 — Reimplementation extract (when goal is rebuild or full playbook)
Produce:
- Architecture overview + NFR
- Module / seam-cluster specs: interface contracts, state, errors, config, deps
- Data model / schema notes
- Integration points (HTTP/gRPC/events, auth, quotas)
- Testing strategy at highest stable seams
00-reimplementation-blueprint.md with bottom-up milestones and verify commands
Phase 6 — Closeout
- Link extracts with relative paths or wikilinks (wiki mode).
- Ensure topology or blueprint includes Open questions and Assumptions and inferences.
- If wiki project: run
skillwiki project-index --project {slug} --apply when available.
- Report: output root, file list, source pin, known gaps vs HEAD, suggested next skill (
improve-codebase-architecture / architecture-to-spec / external migrate).
Interactive vs batch
- Default (full extract): run phases 1–5 without waiting when user asked to analyze/extract/document.
- Exploratory: after Phase 1, summarize and ask which areas to deepen before Phase 2–5.
- Ask only high-value questions when code cannot answer (see c4-evidence.md).
Alignment with related skills
| Need |
Skill |
| Deep-module language |
codebase-design (load first) |
| Find shallow clusters to refactor |
improve-codebase-architecture |
| Turn analysis into PRD |
architecture-to-spec |
| Batched multi-file rewrite |
external codebase-migrate (not bundled) |
| External GitHub / freshness evidence |
deep-research / PavedPath |
| Full chain chooser |
codebase-architecture router |
Guardrails
- Evidence over assertion: every structural claim cites paths or symbols; mark inferences.
- Don't invent a wiki project; fall back to
docs/architecture/.
- Don't put improve-architecture HTML into wiki/docs (temp only).
- Prefer repo-relative paths in durable docs.
- Redact secrets from extracts.
1---2name: codebase-architecture-analyze3description: Analyze architecture into C4, ADRs, debt, and reimplementation maps. Use when documenting or reverse-engineering a repo.4---56# Codebase Architecture Analyze & Extract78Transform an opaque codebase into durable architecture documentation. This is the **analysis / extract** half of the reimplementation playbook (see [playbook-chain.md](../../references/playbook-chain.md) and vault `comparisons/codebase-analysis-reimplementation-skills.md`).910## Mandatory skill load1112Before writing durable extracts, **invoke skill `codebase-design`** (load glossary + principles). Use its terms exactly — module, interface, depth, seam, adapter, leverage, locality — in every extract.1314**C4 vs design vocabulary:** C4 *Component* is a diagram level only. Extract files and design prose use **module** / **seam cluster**. See [c4-evidence.md](../../references/c4-evidence.md).1516## Output routing (mandatory)1718Before writing files, resolve the extract root per [output-routing.md](../../references/output-routing.md):19201. Explicit `--save` / path from user212. Else if SkillWiki vault **and** `projects/{slug}/` exists (slug algorithm in output-routing) → **`{WIKI}/projects/{slug}/architecture/`**223. Else → **`{TARGET_REPO}/docs/architecture/`**234. `--ephemeral` → terminal only2425Announce the resolved output root to the user before bulk writes.2627Pin source commit/tag in every file header. Plugin version: read `.claude-plugin/plugin.json` → `version` (see output-routing). Prefer numbered extract set:2829| File | Content |30|------|---------|31| `00-reimplementation-blueprint.md` | E2E flow + milestone plan + verify commands |32| `01-topology.md` | Tree, stack, entry points, deps, **scope**, observed vs inferred; short C4 overview may live here |33| `02-module-{name}.md`, `03-module-{name}.md`, … | Sequential major module / seam cluster specs (start at `02`) |34| `04-adrs.md` or `adrs/ADR-*.md` | Optional when ADR register is large; else ADRs section in `01`/`00` |35| `05-tech-debt.md` | Optional when debt register is large |36| `08-*.md` / `09-*.md` | Optional layer inventories |3738## Workflow3940### Phase 0 — Target, scope & pin41421. Identify target repo (cwd or user path).432. Record: remote, `git describe --tags --always`, short SHA, package/UI versions if they differ.443. State **scope** (repo-only / monorepo slice / service-in-platform / partial). See [c4-evidence.md](../../references/c4-evidence.md).454. Resolve output root (above). Announce path before bulk writes.465. Optional pack: repomix / code2prompt when the tree is large.4748### Phase 1 — Reconnaissance49501. Stack: language, frameworks, build, storage, external integrations.512. Directory tree and roles.523. Entry points: main app, routers, workers, CLI, schedulers.534. Config: manifests, env templates, CI, compose/IaC.5455Write `01-topology.md` early. Separate **Observed** vs **Inferred** bullets.5657### Phase 2 — Structural analysis5859For each major **module** (design vocabulary):6061- Purpose, location, public **interface**, dependencies, dependents, key files62- Dependency graph (Mermaid); flag cycles and layer leaks63- Data flows: request path, events, background jobs (sequence diagrams)6465### Phase 3 — Pattern recognition6667Document structural patterns (layered, hexagonal, event-driven, …), design patterns in use, data patterns (repository, CQRS, …). Note deviations from textbook form with file evidence.6869### Phase 4 — C4 + decisions + debt7071- C4: Context → Container → Component (Code sparingly). Label diagram levels as C4; map internals to **modules**. Prefer embedding a short C4 overview in `01-topology.md`; use a separate file only if large.72- ADRs for load-bearing decisions found in code (status: Discovered | Active | …) → `04-adrs.md` / `adrs/` or a section in `00`/`01`.73- Tech debt register: code / architecture / dependency / docs / infra → `05-tech-debt.md` or a section in `00`/`01`.7475### Phase 5 — Reimplementation extract (when goal is rebuild or full playbook)7677Produce:78791. Architecture overview + NFR802. **Module / seam-cluster specs**: interface contracts, state, errors, config, deps813. Data model / schema notes824. Integration points (HTTP/gRPC/events, auth, quotas)835. Testing strategy at highest stable **seams**846. `00-reimplementation-blueprint.md` with bottom-up milestones and verify commands8586### Phase 6 — Closeout87881. Link extracts with relative paths or wikilinks (wiki mode).892. Ensure topology or blueprint includes **Open questions** and **Assumptions and inferences**.903. If wiki project: run `skillwiki project-index --project {slug} --apply` when available.914. Report: output root, file list, source pin, known gaps vs HEAD, suggested next skill (`improve-codebase-architecture` / `architecture-to-spec` / external migrate).9293## Interactive vs batch9495- **Default (full extract):** run phases 1–5 without waiting when user asked to analyze/extract/document.96- **Exploratory:** after Phase 1, summarize and ask which areas to deepen before Phase 2–5.97- Ask only high-value questions when code cannot answer (see [c4-evidence.md](../../references/c4-evidence.md)).9899## Alignment with related skills100101| Need | Skill |102|------|--------|103| Deep-module language | `codebase-design` (load first) |104| Find shallow clusters to refactor | `improve-codebase-architecture` |105| Turn analysis into PRD | `architecture-to-spec` |106| Batched multi-file rewrite | external `codebase-migrate` (not bundled) |107| External GitHub / freshness evidence | `deep-research` / PavedPath |108| Full chain chooser | `codebase-architecture` router |109110## Guardrails111112- Evidence over assertion: every structural claim cites paths or symbols; mark inferences.113- Don't invent a wiki project; fall back to `docs/architecture/`.114- Don't put improve-architecture HTML into wiki/docs (temp only).115- Prefer repo-relative paths in durable docs.116- Redact secrets from extracts.
karlorz