Skip to content

dvy1987/agent-loom / .agents/skills/codebase-understanding

codebase-understanding

Verified

Quickly understand an unfamiliar codebase or project by mapping its architecture, identifying key components and data flows, and surfacing complexity hotspots. Load when the user asks to understand a repo, explain how something works, map the architecture, onboard to a codebase, or explore how components connect. Also triggers on "walk me through this codebase", "how does this project work", "explain the architecture", "what does this repo do", "show me the structure", "onboard me", or any request to build a mental model of a codebase before making changes.

FileKindSize
SKILL.mdskill md8.1 KB
references/examples.mdmarkdown3.2 KB

references/examples.md

View on GitHub
# Codebase Understanding — Full Worked Examples

Skill: `codebase-understanding` | Enriched from SKILL.md (improve-skills pass, SKIP_RESEARCH).

## Example 1 — Documented workflow

**Input:** Help me understand this repo before I start working on it.

**Output:**
```
[Scanned root: Next.js app with Prisma ORM, 3 main directories]

## Architecture Overview
Tech stack: TypeScript, Next.js 14, Prisma, PostgreSQL, Tailwind
Entry points: `src/app/layout.tsx` (UI), `src/app/api/` (API routes)
Layers: UI (src/app/), API (src/app/api/), Services (src/lib/), DB (prisma/)

## Key Flows
1. User signup: `app/signup/page.tsx` → `api/auth/register/route.ts` → `lib/auth.ts` → Prisma → DB
2. Dashboard load: `app/dashboard/page.tsx` → `api/projects/route.ts` → `lib/projects.ts` → DB

## Component Map
| Component | Path | Responsibility | Dependencies |
|-----------|------|----------------|--------------|
| Auth | src/lib/auth.ts | JWT + session management | prisma, jose |
| Projects | src/lib/projects.ts | CRUD for projects | prisma |

## Hotspots
- `src/lib/auth.ts:45-120` — 75-line function handling both login and registration
- `prisma/schema.prisma` — 3 TODO comments for missing indexes

## Recommendations
- Split auth.ts login/register into separate functions before adding features
- Add the missing DB indexes flagged in the schema

Want me to deep-dive into any of these components?
```

## Example 2 — Documented workflow

**Input:** How does the payment flow work in this codebase?

**Output:**
```
[Searched for payment/billing/stripe across the codebase]

## Key Flow: Payment Processing
`app/billing/page.tsx` → `api/billing/checkout/route.ts` → `lib/stripe.ts` → Stripe API → webhook at `api/webhooks/stripe/route.ts` → `lib/subscriptions.ts` → DB

## Component Map
| Component | Path | Responsibility | Dependencies |
|-----------|------|----------------|--------------|
| Checkout | api/billing/checkout/ | Creates Stripe session | stripe, lib/stripe |
| Webhook | api/webhooks/stripe/ | Handles payment events | stripe, lib/subscriptions |
| Subscriptions | lib/subscriptions.ts | Updates user plan in DB | prisma |

## Hotspots
- `lib/stripe.ts:30` — Stripe secret key loaded from env, verified
- `api/webhooks/stripe/route.ts:15` — Webhook signature verification present

Want me to trace another flow or go deeper on any component?
```

## Example 3 — Step-by-step execution

**Input:** "Run `codebase-understanding` on [concrete task]"

**Agent actions:**
1. Query knowledge graph (if present)
2. Scope the Request
3. Scan Project Structure
4. Map Architecture
5. Trace Key Flows
6. Surface Hotspots and Risks
7. Deliver the Mental Model

## Example 4 — Gotcha application

**Input:** Task hits a non-obvious edge case

**Apply:**
- Directory names like `utils/` or `helpers/` reveal nothing about responsibility — always read the files inside.
- Monorepos have multiple entry points — check for workspace configs (`pnpm-workspace.yaml`, `lerna.json`, Cargo workspace).
- Generated files (build output, lockfiles, compiled assets) pollute architecture maps — identify and exclude them early.
- A `README.md` may be outdated — cross-reference claims against actual file structure.

---

See `SKILL.md` for hard rules and verification checklist.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 319kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall