deep-codebase-analysis · diff
v1.0.0 to v1.1.1
67 added, 1 removed. Audit A to A.
---
name: deep-codebase-analysis
description: >-
Deep codebase analysis: read and analyze an entire software project's source to
understand architecture, communication, design patterns, and business flows. Use when
the user asks to analyze the overall structure of a whole codebase (exploring a new
system, understanding architecture before maintenance, or scoping a refactor). NOT for:
single-file edits, auditing one skill's SKILL.md, or reviewing a small diff — those
belong to code-review / skill-description-audit.
slug: deep-codebase-analysis
- version: 1.0.0
+ version: 1.1.1
displayName: deep-codebase-analysis
---
# Deep Codebase Analysis
## Overview
This skill enables the Agent to perform a comprehensive analysis of a software project, from high-level architecture to implementation details, helping developers quickly grasp complex systems.
## Core Capabilities
### 1. Overall Architecture Analysis
- Identify key components and organizational models (layered, microservices, modular, clean architecture, etc.).
- Map data flows and inter-module dependencies (dependency mapping).
### 2. Component Communication
- Recognize interaction mechanisms: APIs (REST, GraphQL, gRPC), Message Queues (RabbitMQ, Kafka), Event Bus, or direct function calls.
- Understand how components share memory or state.
### 3. Design Patterns
- Detect common patterns: Singleton, Factory, Observer, Dependency Injection, Strategy, etc.
- Evaluate how these patterns are applied and their consistency across the codebase.
### 4. Rules and Conventions (Coding Conventions)
- Grasp naming conventions, directory structure, and project-specific best practices.
- Check compliance with established coding standards.
### 5. Business Logic Flow
- Trace a request's journey from UI to Database and back.
- Analyze complex business rules embedded in the code.
### 6. State and Data Management
- Understand how data is stored, retrieved, and synchronized via Databases, Cache (Redis), Sessions, etc.
- Analyze schemas and entity relationships.
### 7. Error Handling and Logging
- Analyze exception handling strategies, logging, and system monitoring mechanisms.
## Workflow
1. **Scanning and Indexing**: Use search and analysis tools to build a relationship model between files.
2. **Static Analysis**: Trace function calls, inheritance, and imports to identify main entry points.
3. **Visualization**: (If supported) Create dependency diagrams or flowcharts.
4. **Contextual Inference**: Combine information from documentation, comments, and commit history to understand design intent.
5. **Verification**: Formulate hypotheses about the system and verify them by deep-diving into the source code.
## Usage Guide
When you need to analyze a codebase, start by asking the Agent:
- "Analyze the overall architecture of this project."
- "How does the processing flow work from when a user clicks 'Pay' to when it's saved in the DB?"
- "What are the main design patterns used in this project?"
+
+ ## Quick Start (helper script)
+
+ Precondition: a checkout at `/path/to/repo`.
+
+ ```bash
+ python3 scripts/analyze_structure.py /path/to/repo --depth 2
+ ```
+
+ Output excerpt (actual script behavior — prints a two-level directory tree):
+
+ ```
+ --- Project Structure: /path/to/repo ---
+ repo/
+ src/
+ api/
+ models/
+ tests/
+ package.json
+ ```
+
+ The script is a preliminary aid only; the analysis itself (architecture, patterns, flows) is done by the agent reading the source per the Workflow section. Defaults: `--depth 2`; `--exclude` already skips `node_modules`, `vendor`, `.git`, `__pycache__`, `.DS_Store`.
+
+ ## Worked Example
+
+ Ask: "Analyze the overall architecture of this project."
+
+ Observable flow: run the helper script (Quick Start) → scan/index → trace entry points → produce a report naming the architecture model, key components, communication mechanisms, and a data-flow narrative, each backed by cited source paths. Excerpt of an expected finding:
+
+ ```
+ Architecture: modular monolith
+ - Entry points: src/main.ts, src/worker.ts
+ - Communication: REST (Express) internally; Kafka for async jobs
+ - Persistence: PostgreSQL via Prisma; Redis for sessions
+ ```
+
+ ## Failure Exits
+
+ - Path does not exist or is not a directory: the script prints only the `--- Project Structure: ... ---` header with no tree under it — treat that as a wrong-path signal, tell the user the path was empty, and ask for the correct one. Do not "analyze" nothing.
+ - Empty or skeleton repo (fewer than ~10 source files): say so and analyze directly — the full workflow adds no value there.
+ - Monorepo: run the helper once per package, then analyze cross-package boundaries separately instead of treating the monorepo as one flat tree.
+ - Documentation contradicts the code: trust the code and report the contradiction as a finding — do not average the two.
+
+ ## NOT for / Anti-patterns (observable)
+
+ - NOT for reviewing a small diff or a single file — "review my last commit" belongs to `code-review`.
+ - NOT for security auditing — misconfigurations and secrets belong to `config-scan` / `secrets-scan`.
+ - Anti-pattern: summarizing the README and calling it analysis — every claim must cite a source path.
+ - Anti-pattern: reading the whole tree file-by-file before forming hypotheses — hypothesize early, then verify by deep-diving (Workflow step 5).
+ - Anti-pattern: naming patterns without evidence ("uses Factory") — name the class/file where the pattern lives.
+
+ ## Wrong → Right (FAQ)
+
+ | Wrong | Right |
+ |---|---|
+ | Running the helper on a nonexistent path and continuing | Header with no tree = wrong path; stop and ask |
+ | One flat analysis of a monorepo | Per-package structure + a separate boundary analysis |
+ | Claims sourced from docs/comments only | Verify in code; report doc/code contradictions |
+ | Reporting every design pattern found | Report the load-bearing ones and their consistency |
+
+ ## 中文速览（Quick Guide）
+
+ - **做什么**：通读整个代码库，产出架构模型、组件通信、设计模式与业务流程的分析报告，每个结论都引用源码路径佐证。
+ - **何时用**：接手新系统、维护或重构前需要整体理解代码库结构时（小 diff / 单文件评审不适用）。
+ - **核心步骤**：①扫描建索引 ②静态分析追入口与调用链 ③（可选）画依赖图 ④结合文档与提交史推断设计意图 ⑤提出假设并回源码验证。
+ - **国内可达性**：主流程离线可完成（本地源码 + 自带脚本），无境外服务依赖。
## Resources
### scripts/
- [analyze_structure.py](scripts/analyze_structure.py): A helper script to visualize project directory structure for preliminary architectural analysis. Supports excluding unnecessary directories via the `--exclude` parameter.
### references/
- [architecture_patterns.md](references/architecture_patterns.md): Reference for common architectural models and their indicators.
- [naming_conventions.md](references/naming_conventions.md): Common source code naming standards.
- [design_patterns.md](references/design_patterns.md): Catalog of common design patterns and how to identify them in code.