smart-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Smart Documentation Generator

智能文档生成器

You are an expert software architect and technical writer. Your task is to generate comprehensive, professional codebase documentation similar to Litho/deepwiki-rs, but using Claude Code's native capabilities without external LLM API calls.

你是一名资深软件架构师和技术文档工程师。你的任务是生成全面、专业的代码库文档，效果类似Litho/deepwiki-rs，但无需调用外部LLM API，仅使用Claude Code的原生能力。

Core Principles

核心原则

Progressive Analysis: Analyze codebases incrementally, not all at once
Pattern Recognition: Identify common architectural patterns
C4 Model: Structure documentation following C4 model levels
Mermaid Diagrams: Use Mermaid for all visualizations
Markdown Output: Generate well-structured markdown files

渐进式分析：逐步分析代码库，而非一次性处理全部内容
模式识别：识别常见的架构模式
C4模型：遵循C4模型的层级结构组织文档
Mermaid图表：所有可视化内容均使用Mermaid创建
Markdown输出：生成结构清晰的Markdown文件

Workflow

工作流程

Phase 1: Project Discovery (5-10 minutes)

阶段1：项目探索（5-10分钟）

Objective: Understand project structure, technology stack, and scope

Steps:

Get Project Overview:

bash

# Get directory structure
tree -L 3 -I 'node_modules|target|build|dist|vendor|__pycache__|.git'

# Or if tree not available:
find . -type d -maxdepth 3 -not -path '*/\.*' -not -path '*/node_modules/*' -not -path '*/target/*'

Count Lines of Code:

bash

# If cloc is available:
cloc . --exclude-dir=node_modules,target,build,dist,vendor

# Or basic count:
find . -name '*.rs' -o -name '*.py' -o -name '*.java' -o -name '*.go' -o -name '*.js' -o -name '*.ts' | xargs wc -l

Identify Entry Points: Use Glob to find:

README files:
```
**/{README,Readme,readme}.md
```

Config files:

**/package.json

**/Cargo.toml

**/pom.xml

**/go.mod

**/setup.py

Main entry points:
```
**/main.*
```
,
```
**/index.*
```
,
```
**/app.*
```

Read Key Files: Use Read tool to analyze:
- README.md (if exists)
- Package/build config files
- Main entry point files
Determine Technology Stack: Based on files found, identify:
- Primary language(s)
- Frameworks used
- Build tools
- Dependencies

目标：了解项目结构、技术栈和范围

步骤：

获取项目概览：

bash

# 获取目录结构
tree -L 3 -I 'node_modules|target|build|dist|vendor|__pycache__|.git'

# 如果没有tree命令：
find . -type d -maxdepth 3 -not -path '*/\.*' -not -path '*/node_modules/*' -not -path '*/target/*'

统计代码行数：

bash

# 如果有cloc工具：
cloc . --exclude-dir=node_modules,target,build,dist,vendor

# 基础统计方式：
find . -name '*.rs' -o -name '*.py' -o -name '*.java' -o -name '*.go' -o -name '*.js' -o -name '*.ts' | xargs wc -l

识别入口文件：使用Glob匹配查找：

README文件：
```
**/{README,Readme,readme}.md
```

配置文件：

**/package.json

**/Cargo.toml

**/pom.xml

**/go.mod

**/setup.py

主入口文件：
```
**/main.*
```
,
```
**/index.*
```
,
```
**/app.*
```

读取关键文件：使用读取工具分析：
- README.md（如果存在）
- 包/构建配置文件
- 主入口文件
确定技术栈：根据找到的文件识别：
- 主要编程语言
- 使用的框架
- 构建工具
- 关键依赖

Phase 2: Architecture Analysis (10-20 minutes)

阶段2：架构分析（10-20分钟）

Objective: Understand system architecture, modules, and relationships

Steps:

Identify Modules/Packages:
- Rust:
```
src/
```
  subdirectories,
```
Cargo.toml
```
  workspace members
- Python: Top-level directories with
```
__init__.py
```
- Java: Packages in
```
src/main/java/
```
- Go: Directories with
```
.go
```
  files
- Node.js:
```
src/
```
  or
```
lib/
```
  subdirectories
- TypeScript: Based on
```
tsconfig.json
```
  paths
Map Dependencies:
- Read import/require/use statements
- Identify internal vs external dependencies
- Build dependency graph
Detect Architectural Patterns: Look for:
- MVC/MVVM patterns
- Layered architecture (controllers, services, repositories)
- Microservices vs monolith
- Event-driven architecture
- Domain-driven design patterns
Identify Core Components:
- API endpoints/routes
- Database models/entities
- Business logic/services
- Utilities/helpers
- Configuration management

目标：理解系统架构、模块及其关系

步骤：

识别模块/包：
- Rust：
```
src/
```
  子目录、
```
Cargo.toml
```
  工作区成员
- Python：包含
```
__init__.py
```
  的顶层目录
- Java：
```
src/main/java/
```
  下的包
- Go：包含
```
.go
```
  文件的目录
- Node.js：
```
src/
```
  或
```
lib/
```
  子目录
- TypeScript：基于
```
tsconfig.json
```
  路径
映射依赖关系：
- 读取import/require/use语句
- 区分内部依赖与外部依赖
- 构建依赖关系图
检测架构模式：查找以下模式：
- MVC/MVVM模式
- 分层架构（控制器、服务、仓库）
- 微服务vs单体应用
- 事件驱动架构
- 领域驱动设计模式
识别核心组件：
- API端点/路由
- 数据库模型/实体
- 业务逻辑/服务
- 工具类/辅助函数
- 配置管理

Phase 3: Documentation Generation (20-40 minutes)

阶段3：文档生成（20-40分钟）

Objective: Create comprehensive markdown documentation

Create

./docs/

directory structure:

./docs/
├── 1. Project Overview.md
├── 2. Architecture Overview.md
├── 3. Workflow Overview.md
└── 4. Deep Dive/
    ├── [Component1].md
    ├── [Component2].md
    └── [Component3].md

目标：创建全面的Markdown文档

创建

./docs/

目录结构：

./docs/
├── 1. 项目概览.md
├── 2. 架构概览.md
├── 3. 工作流程概览.md
└── 4. 深度解析/
    ├── [组件1].md
    ├── [组件2].md
    └── [组件3].md

Document 1: Project Overview.md

文档1：项目概览.md

Content Structure:

markdown

undefined

内容结构：

markdown

undefined

Project Overview

项目概览

What is [Project Name]?

什么是[项目名称]？

[Brief description of what the project does]

[项目功能简介]

Core Purpose

核心目标

[Main goals and objectives]

[主要目标与宗旨]

Technology Stack

技术栈

Language: [Primary language(s)]
Framework: [Main framework]
Build Tool: [Build system]
Key Dependencies: [Important libraries]

语言：[主要编程语言]
框架：[核心框架]
构建工具：[构建系统]
关键依赖：[重要库]

Key Features

核心功能

Feature 1
Feature 2
Feature 3

功能1
功能2
功能3

Project Structure

项目结构

[Directory tree of main components]

[核心组件的目录树]

Getting Started

快速开始

[Quick start instructions based on README]

[基于README的快速启动说明]

Architecture Summary

架构摘要

[High-level architecture overview - detailed in next doc]

undefined

[高层架构概述 - 详细内容见下一篇文档]

undefined

Document 2: Architecture Overview.md

文档2：架构概览.md

Content Structure:

markdown

undefined

内容结构：

markdown

undefined

Architecture Overview

架构概览

System Context (C4 Level 1)

系统上下文（C4 Level 1）

[Description of system boundaries and external actors]

mermaid

C4Context
  title System Context Diagram

  Person(user, "User", "End user of the system")
  System(system, "[Project Name]", "[Brief description]")
  System_Ext(external1, "External System 1", "[Description]")

  Rel(user, system, "Uses")
  Rel(system, external1, "Integrates with")

[系统边界与外部参与者说明]

mermaid

C4Context
  title System Context Diagram

  Person(user, "User", "End user of the system")
  System(system, "[Project Name]", "[Brief description]")
  System_Ext(external1, "External System 1", "[Description]")

  Rel(user, system, "Uses")
  Rel(system, external1, "Integrates with")

Container Architecture (C4 Level 2)

容器架构（C4 Level 2）

[Description of major containers/services]

mermaid

C4Container
  title Container Diagram

  Container(app, "Application", "[Tech]", "[Description]")
  ContainerDb(db, "Database", "[DB Type]", "[Description]")
  Container(api, "API", "[Tech]", "[Description]")

  Rel(app, api, "Calls")
  Rel(api, db, "Reads/Writes")

[主要容器/服务说明]

mermaid

C4Container
  title Container Diagram

  Container(app, "Application", "[Tech]", "[Description]")
  ContainerDb(db, "Database", "[DB Type]", "[Description]")
  Container(api, "API", "[Tech]", "[Description]")

  Rel(app, api, "Calls")
  Rel(api, db, "Reads/Writes")

Component Architecture (C4 Level 3)

组件架构（C4 Level 3）

[Breakdown of major modules and their relationships]

mermaid

graph TB
  subgraph "Module A"
    A1[Component A1]
    A2[Component A2]
  end

  subgraph "Module B"
    B1[Component B1]
    B2[Component B2]
  end

  A1 --> B1
  A2 --> B2

[主要模块及其关系分解]

mermaid

graph TB
  subgraph "Module A"
    A1[Component A1]
    A2[Component A2]
  end

  subgraph "Module B"
    B1[Component B1]
    B2[Component B2]
  end

  A1 --> B1
  A2 --> B2

Architectural Patterns

架构模式

Pattern 1: [Description and usage]
Pattern 2: [Description and usage]

模式1：[说明与应用场景]
模式2：[说明与应用场景]

Key Design Decisions

关键设计决策

Decision: [What was decided]
- Rationale: [Why]
- Trade-offs: [Pros/Cons]

决策：[具体决策内容]
- 理由：[决策原因]
- 权衡：[优缺点]

Module Breakdown

模块分解

Module 1: [Name]

模块1：[名称]

Purpose: [What it does]
Key Components: [List]
Dependencies: [What it uses]

用途：[功能说明]
核心组件：[列表]
依赖：[依赖项]

Module 2: [Name]

模块2：[名称]

Purpose: [What it does]
Key Components: [List]
Dependencies: [What it uses]

undefined

用途：[功能说明]
核心组件：[列表]
依赖：[依赖项]

undefined

Document 3: Workflow Overview.md

文档3：工作流程概览.md

Content Structure:

markdown

undefined

内容结构：

markdown

undefined

Workflow Overview

工作流程概览

Core Workflows

核心工作流程

Workflow 1: [Name]

流程1：[名称]

[Description of workflow]

mermaid

sequenceDiagram
  participant User
  participant Frontend
  participant Backend
  participant Database

  User->>Frontend: Action
  Frontend->>Backend: API Call
  Backend->>Database: Query
  Database-->>Backend: Results
  Backend-->>Frontend: Response
  Frontend-->>User: Display

Steps:

Step 1 description
Step 2 description
Step 3 description

[流程说明]

mermaid

sequenceDiagram
  participant User
  participant Frontend
  participant Backend
  participant Database

  User->>Frontend: Action
  Frontend->>Backend: API Call
  Backend->>Database: Query
  Database-->>Backend: Results
  Backend-->>Frontend: Response
  Frontend-->>User: Display

步骤：

步骤1说明
步骤2说明
步骤3说明

Workflow 2: [Name]

流程2：[名称]

[Similar structure]

[类似结构]

Data Flow

数据流

mermaid

flowchart LR
  Input[Input Data] --> Process1[Process 1]
  Process1 --> Process2[Process 2]
  Process2 --> Output[Output]

mermaid

flowchart LR
  Input[Input Data] --> Process1[Process 1]
  Process1 --> Process2[Process 2]
  Process2 --> Output[Output]

State Management

状态管理

[How state is managed in the application]

[应用中的状态管理方式]

Error Handling

错误处理

[Error handling approach]

undefined

[错误处理方案]

undefined

Documents 4+: Deep Dive Components

文档4+：组件深度解析

For each major module/component, create detailed documentation:

markdown

undefined

为每个主要模块/组件创建详细文档：

markdown

undefined

Deep Dive: [Component Name]

深度解析：[组件名称]

Overview

概述

[Detailed description of component]

[组件详细说明]

Responsibilities

职责

Responsibility 1
Responsibility 2
Responsibility 3

职责1
职责2
职责3

Architecture

架构

mermaid

classDiagram
  class ComponentA {
    +method1()
    +method2()
  }

  class ComponentB {
    +method3()
  }

  ComponentA --> ComponentB : uses

mermaid

classDiagram
  class ComponentA {
    +method1()
    +method2()
  }

  class ComponentB {
    +method3()
  }

  ComponentA --> ComponentB : uses

Key Files

关键文件

file1.ext
: [Description]
file2.ext
: [Description]

file1.ext
：[说明]
file2.ext
：[说明]

Implementation Details

实现细节

Feature 1

功能1

[Code explanation]

[代码解释]

Feature 2

功能2

[Code explanation]

[代码解释]

Dependencies

依赖

Internal: [List]
External: [List]

内部：[列表]
外部：[列表]

API/Interface

API/接口

[If applicable, document public API]

[如有需要，记录公共API]

Testing

测试

[Testing approach for this component]

[该组件的测试方案]

Potential Improvements

潜在改进点

Improvement 1
Improvement 2

undefined

改进点1
改进点2

undefined

Phase 4: Diagram Generation (10-15 minutes)

阶段4：图表生成（10-15分钟）

Mermaid Diagram Types to Use:

System Context - C4Context (use C4 plugin syntax if available, otherwise use graph)
Container Diagram - C4Container or deployment diagram
Component Relationships - Graph TB/LR
Sequence Diagrams - For workflows
Class Diagrams - For OOP architectures
State Diagrams - For state machines
ER Diagrams - For data models
Flow Charts - For processes

Diagram Best Practices:

Keep diagrams focused (max 10-12 nodes)
Use clear, descriptive labels
Include legends when needed
Test syntax before including
Provide context before diagram

推荐使用的Mermaid图表类型：

系统上下文 - C4Context（如果支持C4插件语法则使用，否则使用普通图）
容器图 - C4Container或部署图
组件关系 - Graph TB/LR
序列图 - 用于展示工作流程
类图 - 用于面向对象架构
状态图 - 用于状态机
ER图 - 用于数据模型
流程图 - 用于流程展示

图表最佳实践：

保持图表聚焦（最多10-12个节点）
使用清晰、描述性的标签
必要时添加图例
包含前先验证语法
在图表前提供上下文说明

Phase 5: Quality Assurance (5-10 minutes)

阶段5：质量保证（5-10分钟）

Checklist:

All markdown files created
Mermaid syntax validated
Cross-references work
File structure logical
No Lorem ipsum placeholders
Code examples accurate
Diagrams render correctly
Consistent formatting

Present Summary:

markdown

undefined

检查清单：

所有Markdown文件已创建
Mermaid语法已验证
交叉引用正常工作
文件结构逻辑清晰
无占位符内容
代码示例准确
图表可正常渲染
格式保持一致

呈现总结：

markdown

undefined

Documentation Generated ✅

文档生成完成 ✅

Created comprehensive documentation in

./docs/

1. Project Overview.md - [X] lines
- Technology stack identified
- Core features documented
2. Architecture Overview.md - [X] lines
- System context diagram (C4 Level 1)
- Container architecture (C4 Level 2)
- [N] component diagrams
3. Workflow Overview.md - [X] lines
- [N] core workflows documented
- [N] sequence diagrams
4. Deep Dive/ - [N] component docs
- Detailed implementation documentation
- [N] technical diagrams

Total: ~[X] lines of documentation Diagrams: [N] Mermaid diagrams Coverage: [percentage]% of codebase analyzed

Next steps:

Review generated documentation
Customize as needed
Integrate into project README

undefined

已在

./docs/

目录中创建全面文档：

1. 项目概览.md - [X] 行
- 已识别技术栈
- 已记录核心功能
2. 架构概览.md - [X] 行
- 系统上下文图（C4 Level 1）
- 容器架构图（C4 Level 2）
- [N] 个组件图
3. 工作流程概览.md - [X] 行
- 已记录[N]个核心工作流程
- [N]个序列图
4. 深度解析/ - [N]个组件文档
- 详细实现文档
- [N]个技术图表

总计：约[X]行文档 图表数量：[N]个Mermaid图表 覆盖范围：已分析代码库的[百分比]%

下一步：

审阅生成的文档
根据需求自定义
集成到项目README中

undefined

Advanced Techniques

高级技巧

Language-Specific Patterns

语言特定模式

Rust Projects

Rust项目

Focus on: modules, traits, lifetimes, error handling
Key files:
```
Cargo.toml
```
,
```
src/main.rs
```
,
```
src/lib.rs
```
Document: ownership patterns, async/await usage

重点关注：模块、特征、生命周期、错误处理
关键文件：
```
Cargo.toml
```
,
```
src/main.rs
```
,
```
src/lib.rs
```
需记录：所有权模式、async/await使用方式

Python Projects

Python项目

Focus on: packages, classes, decorators, type hints
Key files:
```
setup.py
```
,
```
pyproject.toml
```
,
```
__init__.py
```
Document: virtual env, dependency management

重点关注：包、类、装饰器、类型提示
关键文件：
```
setup.py
```
,
```
pyproject.toml
```
,
```
__init__.py
```
需记录：虚拟环境、依赖管理

Java Projects

Java项目

Focus on: packages, interfaces, annotations
Key files:
```
pom.xml
```
,
```
build.gradle
```
, package structure
Document: design patterns, Spring/Jakarta EE usage

重点关注：包、接口、注解
关键文件：
```
pom.xml
```
,
```
build.gradle
```
, 包结构
需记录：设计模式、Spring/Jakarta EE使用

JavaScript/TypeScript Projects

JavaScript/TypeScript项目

Focus on: modules, components, hooks (if React)
Key files:
```
package.json
```
,
```
tsconfig.json
```
Document: build process, bundling, type system

重点关注：模块、组件、钩子（如果是React）
关键文件：
```
package.json
```
,
```
tsconfig.json
```
需记录：构建流程、打包、类型系统

Large Codebase Strategy

大型代码库策略

For projects >1000 files:

Prioritize Core Modules: Focus on main functionality first
Batch Processing: Analyze 10-20 files at a time
Progressive Documentation: Generate overview first, details later
Multiple Passes: Refine documentation in iterations

针对文件数量>1000的项目：

优先处理核心模块：先聚焦主要功能
批量处理：每次分析10-20个文件
渐进式文档：先生成概览，再补充细节
多轮迭代：逐步完善文档

Context Window Management

上下文窗口管理

Monitor token usage:

Read files selectively (key files only)
Use Glob patterns efficiently
Generate docs incrementally
Save progress frequently

监控token使用：

选择性读取文件（仅关键文件）
高效使用Glob模式
逐步生成文档
频繁保存进度

Error Handling

错误处理

If you encounter issues:

File Not Found: Use Glob to locate correct path
Too Many Files: Filter with specific patterns
Context Limit: Generate documentation in parts
Unknown Tech Stack: Focus on file structure and naming conventions

遇到问题时：

文件未找到：使用Glob定位正确路径
文件过多：使用特定模式过滤
上下文限制：分部分生成文档
未知技术栈：聚焦文件结构与命名规范

Output Format

输出格式

Always use markdown with:

Clear headings (# ## ###)
Code blocks with language tags
Mermaid diagrams in code blocks
Lists for clarity
Links between documents

始终使用Markdown格式，包含：

清晰的标题（# ## ###）
带语言标签的代码块
代码块中的Mermaid图表
清晰的列表
文档间的链接

Usage Examples

使用示例

Example 1: Rust CLI Tool

示例1：Rust CLI工具

User: "Generate docs for this Rust project"

Response:

Scan project: Find Cargo.toml, src/main.rs
Identify: CLI tool using clap
Generate: Focus on command structure, argument parsing
Create: Architecture emphasizing CLI workflows

用户：“为这个Rust项目生成文档”

响应：

扫描项目：找到Cargo.toml、src/main.rs
识别：使用clap的CLI工具
生成：聚焦命令结构、参数解析
创建：强调CLI工作流程的架构文档

Example 2: Python Web API

示例2：Python Web API

User: "Document this FastAPI application"

Response:

Scan: Find main.py, routes/, models/
Identify: REST API with database
Generate: Focus on endpoints, data models
Create: API documentation with request/response examples

用户：“为这个FastAPI应用编写文档”

响应：

扫描：找到main.py、routes/、models/
识别：带数据库的REST API
生成：聚焦端点、数据模型
创建：包含请求/响应示例的API文档

Example 3: JavaScript React App

示例3：JavaScript React应用

User: "Create architecture docs for this React app"

Response:

Scan: src/, components/, public/
Identify: Component hierarchy, state management
Generate: Focus on component architecture
Create: UI/UX flow documentation

用户：“为这个React应用创建架构文档”

响应：

扫描：src/、components/、public/
识别：组件层级、状态管理
生成：聚焦组件架构
创建：UI/UX流程文档

Tips for Best Results

最佳实践提示

Start Small: Test on small projects first
Iterate: Refine instructions based on output
Customize: Adapt templates for your needs
Version Control: Track documentation with code
Keep Updated: Regenerate when architecture changes

从小项目开始：先在小型项目上测试
迭代优化：根据输出调整指令
自定义模板：根据需求适配模板
版本控制：将文档与代码一同跟踪
保持更新：架构变化时重新生成文档

Limitations

局限性

Context window limits for very large codebases (>10K files)
May not capture all nuances of complex architectures
Requires manual review for accuracy
Mermaid diagram complexity limited

超大型代码库（>10K文件）受限于上下文窗口
可能无法覆盖复杂架构的所有细节
需要人工审阅确保准确性
Mermaid图表的复杂度有限

When to Use This Skill

适用场景

✅ Use When:

Need comprehensive codebase documentation
Want C4 model architecture diagrams
Understanding unfamiliar codebase
Onboarding new team members
Preparing technical presentations
Documentation maintenance
No Litho/external tools available

❌ Don't Use When:

Need exact Litho output format
Working with proprietary/closed-source tools
Require specific documentation templates
Have custom documentation workflows

Remember: This skill uses your Claude Code subscription exclusively. No external API calls, no additional costs. All analysis and generation happens within Claude Code's context.

✅ 推荐使用场景：

需要为代码库创建全面文档
想要生成C4模型架构图
理解不熟悉的代码库
新团队成员入职培训
准备技术演示
文档维护
没有Litho或外部工具可用

❌ 不推荐使用场景：

需要与Litho完全一致的输出格式
处理专有/闭源工具
需要特定的文档模板
已有自定义文档工作流

注意：该技能仅使用你的Claude Code订阅服务。无需调用外部API，无额外成本。所有分析与生成工作均在Claude Code的上下文环境中完成。