# Codebase Analyzer > Inspect an existing codebase and report evidence-backed structure, stack, conventions, dependencies, and architecture. Use after engineer-agent routes bounded codebase analysis. - Skill: `neplich/codebase-analyzer` (Agent Skill) - Install (CLI): `npx skillmds@latest add neplich/codebase-analyzer` - Raw SKILL.md: https://api.skillmd.com/api/skills/neplich/codebase-analyzer/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: Neplich (https://skillmd.com/u/neplich) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/neplich/codebase-analyzer --- # Codebase Analyzer Scan an existing codebase and produce a structured Project Profile. This profile serves as context for all downstream engineer skills (feature-implementor, test-writer, etc.) so they can follow existing conventions. ## Reader-Facing Writing Composition For substantial reader-facing prose, co-load `human-writing` even on direct invocation; use the same context, not a later pass. This Skill retains evidence, facts, required structure, paths, gates, and verification. Skip code-, config-, schema-, lockfile-, and data-only output. ## When to Use - Before starting any work on an existing project - When another skill needs project context but no Project Profile exists yet - When the user asks about project structure, tech stack, or conventions ## PM Handoff Entry Gate This is a downstream engineering specialist. Use it when `pm-agent` or `engineer-agent` asks for repository context, or when an equivalent confirmed workflow already needs a Project Profile. If the user directly invokes this skill for general project status, backlog, or feature naming without PM route context, return the request to `pm-agent` for classification. Use the PM-side packet definition in the plugin-local generated `../engineer-agent/_internal/_generated/shared-contracts/handoff-contract.md`. ## Step 1 — Verify project root 宿主存在 `docs/site/standards/change-map.yaml` 时，项目探索先按 pm-agent 维护的 `consumption-contract.md`（the plugin-local generated `../engineer-agent/_internal/_generated/shared-contracts/consumption-contract.md`）执行“任务落点 → change-map 反查 → 精准读取 → 关键判断回代码验证”；不存在时静默沿用当前代码探索。 Confirm you are in a valid project directory: ```bash ls -la ``` Look for project markers: `.git`, `README.md`, `package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`, `pom.xml`, `Makefile`, etc. If no project markers found, tell the user this doesn't appear to be a project directory and ask for clarification. ## Step 2 — Scan project structure ```bash find . -maxdepth 3 -type f \ ! -path '*/node_modules/*' \ ! -path '*/.git/*' \ ! -path '*/vendor/*' \ ! -path '*/dist/*' \ ! -path '*/__pycache__/*' \ ! -path '*/target/*' \ | head -100 ``` Identify: - Source code directories (`src/`, `lib/`, `app/`, `pkg/`, `internal/`, `cmd/`) - Test directories (`tests/`, `test/`, `__tests__/`, `spec/`) - Config files (lint, format, build, CI) - Documentation (`docs/`, `README`) ## Step 3 — Identify tech stack Read the primary manifest file to determine the language, runtime and package manager. Detect the framework from dependencies: - **Node.js**: next, express, fastify, nestjs, react, vue, angular, svelte - **Python**: django, flask, fastapi, streamlit - **Go**: gin, echo, fiber, chi - **Rust**: actix-web, axum, rocket Also check for TypeScript (`tsconfig.json`) and monorepo indicators (`pnpm-workspace.yaml`, `lerna.json`, `nx.json`, `turbo.json`). ## Step 4 — Extract coding conventions Check for lint and formatter config files and summarize what they enforce. Also sample 2-3 existing source files to detect: - Naming style (camelCase / snake_case / PascalCase) - Import ordering convention - Comment style and density - Error handling patterns ## Step 5 — Analyze dependencies Read the manifest file and categorize: - **Core framework** (e.g., Next.js 14, FastAPI 0.100) - **Database** (prisma, drizzle, sqlalchemy, gorm, diesel) - **Auth** (next-auth, passport, jwt libraries) - **Testing** (jest, vitest, pytest, go test, cargo test) - **Build tools** (webpack, vite, turbopack, esbuild) - **Key libraries** (anything domain-specific) ## Step 6 — Identify architecture patterns Based on directory structure and code samples, classify the architecture pattern (e.g., MVC, layered, feature-based, monorepo, serverless, microservices). ## Step 7 — Check CI/CD configuration Look for: - `.github/workflows/*.yml` (GitHub Actions) - `.gitlab-ci.yml` (GitLab CI) - `Jenkinsfile` - `.circleci/config.yml` - `Dockerfile`, `docker-compose.yml` Summarize what CI does: lint, test, build, deploy. ## Step 8 — Produce Project Profile Output the profile in this structure: ```yaml project_profile: path: name: description: tech_stack: language: framework: runtime: package_manager: typescript: monorepo: architecture: pattern: source_dirs: [list of source directories] test_dirs: [list of test directories] key_modules: [list of main modules/features] conventions: naming: linter: formatter: import_style: error_handling: dependencies: core: [framework, key libs with versions] database: auth: testing: build: ci_cd: platform: steps: [lint, test, build, deploy] config_path: docs: has_pm_docs: pm_doc_inventory: [list of docs found in docs/] has_readme: has_api_docs: feature_inventory: - candidate_feature: suggested_feature_path: evidence: routes: [] pages: [] api_endpoints: [] services: [] data_models: [] background_jobs: [] tests: [] docs: [] confidence: open_questions: [] ``` ### Building feature_inventory `feature_inventory` turns the scan into a candidate feature map for project take-over. Build it with these rules: - Group evidence by business capability a user would recognize, merging routes, pages, API endpoints, services, data models, background jobs, tests, and existing docs that serve the same capability. Do not copy code directory names as feature names; code paths are evidence only. - When evidence maps to an existing `docs/pm/**/PRD.md`, reuse that feature's `feature_path` as `suggested_feature_path`. For legacy single-level PRDs whose frontmatter has no `feature_path`, apply the feature-path-contract fallback: treat `docs/pm/{feature}/PRD.md` as `feature_path={feature}`, `parent_feature=N/A`, `feature_level=1`, and reuse that derived path instead of emitting `unresolved` or a duplicate top-level suggestion. When parent ownership or monorepo scope is unclear, set `suggested_feature_path: unresolved` and record the blocking question in `open_questions` instead of inventing a new top-level path. - Set `confidence: high` when multiple evidence categories corroborate the capability, `medium` when only one category or naming inference supports it, and `low` when the entry rests on directory names or dependency guesses. - `feature_inventory` is profiling evidence, not a naming decision. Formal `feature_path` confirmation belongs to `pm-agent:feature-catalog`, which takes this inventory as input and runs the maintainer confirmation gate. ## Edge Cases - **Empty project**: If the directory only has `.git` and maybe a README, report `status: empty` and return the request to `pm-agent` for normal classification. - **Missing handoff target**: If the target agent's plugin for a cross-agent handoff is not installed or unavailable, state the missing stage and required plugin, mark that handoff stage as blocked, and do not perform the missing agent's responsibilities yourself. - **Monorepo**: Profile the root workspace config plus each package/app that seems relevant to the user's task. Ask which sub-project to focus on if unclear. - **Multiple languages**: List all detected languages; identify the primary one by code volume. Note secondary languages (e.g., "Python backend + TypeScript frontend"). - **No CI**: Note the absence and flag as a gap. - **No linter/formatter**: Note the absence. Sample code to infer implicit conventions.