system-overview

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

System Overview — first-pass orientation for an unfamiliar codebase

系统概览 — 陌生代码库快速入门指南

Produces a single

SYSTEM_OVERVIEW.md

at the repo root. The audience is a senior engineer who has never seen the code. The output is a draft for human review, not a finished architecture document.

Source. Prompt structure adapted from Aaron Sumner, "My go-to prompt for legacy code exploration," https://leftofthe.dev/2025/11/09/legacy-code-overview-llm (2025-11-09), which in turn borrows from Alex Chesser, "Attention Is the New Big-O," https://alexchesser.medium.com/attention-is-the-new-big-o-9c68e1ae9b27 (2025-08-19).

在代码库根目录生成一份

SYSTEM_OVERVIEW.md

文档，目标受众为从未接触过该代码的资深工程师。输出内容为供人工审核的草稿，而非最终的架构文档。

来源：提示结构改编自Aaron Sumner的《我用于遗留代码探索的首选提示词》（https://leftofthe.dev/2025/11/09/legacy-code-overview-llm，2025-11-09），该文章又借鉴了Alex Chesser的《注意力是新的大O复杂度》（https://alexchesser.medium.com/attention-is-the-new-big-o-9c68e1ae9b27，2025-08-19）。

Before You Start

开始之前

Root
```
README.md
```
— the project's own framing. Match its vocabulary.
Root
```
CLAUDE.md
```
(or
```
AGENTS.md
```
) — repo-specific guardrails the human authors put down.
Top-level entry points —
```
main.py
```
,
```
app/
```
,
```
src/index.ts
```
,
```
cmd/
```
,
```
Dockerfile
```
,
```
docker-compose.yml
```
. Read them before claiming what the system is.

根目录下的
```
README.md
```
— 项目自身的说明文档，需与其词汇保持一致。
根目录下的
```
CLAUDE.md
```
（或
```
AGENTS.md
```
） — 人类作者设定的代码库特定约束规则。
顶层入口文件 —
```
main.py
```
、
```
app/
```
、
```
src/index.ts
```
、
```
cmd/
```
、
```
Dockerfile
```
、
```
docker-compose.yml
```
。在断言系统功能前，请先阅读这些文件。

Step 1: orient with the file tree

步骤1：通过文件目录定位系统

bash

tree -L 2 -I 'node_modules|.git|.venv|__pycache__|dist|build'
find . -maxdepth 2 -name 'README*' -not -path '*/node_modules/*'

Identify: language(s), top-level directories, framework markers (

pyproject.toml

package.json

go.mod

Cargo.toml

pom.xml

bash

tree -L 2 -I 'node_modules|.git|.venv|__pycache__|dist|build'
find . -maxdepth 2 -name 'README*' -not -path '*/node_modules/*'

识别：使用的编程语言、顶层目录、框架标识文件（

pyproject.toml

、

package.json

、

go.mod

、

Cargo.toml

、

pom.xml

）。

Step 2: locate the entry points and external boundaries

步骤2：定位入口点与外部边界

bash

undefined

bash

undefined

HTTP / RPC entry points

HTTP / RPC 入口点

grep -rln "FastAPI|express()|http.HandleFunc|@RestController|@SpringBootApplication"
--include='.py' --include='.ts' --include='.js' --include='.go' --include='*.java' .

External integrations (DB, cache, queues, third-party APIs)

外部集成（数据库、缓存、消息队列、第三方API）


Every external integration is a node in your container diagram.


每一个外部集成都是容器图中的一个节点。

Step 3: write

SYSTEM_OVERVIEW.md

with the canonical structure

步骤3：按标准结构编写

SYSTEM_OVERVIEW.md

Use exactly the headings below. They come from the source prompt; preserve them so the output is recognisable across teams that adopt this skill.

markdown

undefined

请严格使用以下标题。这些标题来自源提示词，保留它们可让采用本技能的团队识别统一的输出格式。

markdown

undefined

System Overview

Audience: a senior engineer new to this system. Drafted by an LLM, requires human review.

受众：刚接触本系统的资深工程师。由LLM生成，需人工审核。

CORE ANALYSIS (Required)

CORE ANALYSIS（必填）

Tools, frameworks, and design patterns used across the repository
Data models and API design
Mermaid architecture diagram of the system and its dependencies at a high level

代码库中使用的工具、框架与设计模式
数据模型与API设计
系统及其依赖的高层次Mermaid架构图

SYSTEM DESIGN (Required)

SYSTEM DESIGN（必填）

File-by-file explanation of the central modules and how they link
Mermaid sequence diagram for the primary data flow
Mermaid flowcharts for any complex branching flows

核心模块的逐文件说明及其关联方式
主数据流的Mermaid序列图
复杂分支流程的Mermaid流程图

LEGACY ASSESSMENT (If applicable)

LEGACY ASSESSMENT（如适用）

Inconsistencies in architectural patterns
Deviations from language or framework conventions
Distinctions between old and new architectural approaches

undefined

架构模式中的不一致性
与语言或框架规范的偏差
新旧架构方法的差异

undefined

Optional extensions (lecture-specific, not in the source prompt)

可选扩展（针对课程/讲座变体，源提示词中未包含）

If your project uses these conventions (the lecture/coursework variant adds them), append:

Cross-cutting concerns — auth, logging, config, error handling — one paragraph each, with file references.
Technical-concern hotspots — files or modules with high churn, high cyclomatic complexity, or long-standing TODOs.
Open questions for human architects — the things you could not determine from the code alone. List them; do not guess.
Citations rule. Every claim cites at least one
```
path/to/file.ext:line
```
reference.
UNVERIFIED tag. Any inference not directly supported by a file you read is prefixed
```
UNVERIFIED:
```
so reviewers can triage.

如果你的项目遵循这些规范（课程/作业变体新增内容），可追加以下部分：

横切关注点 — 认证、日志、配置、错误处理 — 每个部分用一段文字说明，并附上文件引用。
技术风险热点 — 变更频繁、圈复杂度高或存在长期TODO的文件或模块。
需向人类架构师确认的问题 — 仅通过代码无法确定的内容。列出问题即可，请勿猜测。
引用规则：每一项结论至少引用一个
```
path/to/file.ext:line
```
格式的文件位置。
UNVERIFIED标签：任何未通过已读文件直接验证的推论，需前缀
```
UNVERIFIED:
```
以便审核人员分类处理。

Step 4: anchor every claim to a file

步骤4：为所有结论关联文件依据

Bad: "The system uses an event bus." Good: "Events are published via

EventBus.publish

app/events/bus.py:42

and consumed by handlers registered in

app/events/registry.py:18-31

If you cannot cite a file, either find one or mark the sentence

UNVERIFIED:

错误示例："系统使用了事件总线。" 正确示例："事件通过

app/events/bus.py:42

中的

EventBus.publish

发布，并由

app/events/registry.py:18-31

中注册的处理器消费。"

如果无法找到文件依据，要么找到相关文件，要么在句子前添加

UNVERIFIED:

前缀。

Step 5: render and sanity-check the Mermaid

步骤5：渲染并验证Mermaid图

bash

undefined

bash

undefined

If mmdc is available

如果mmdc可用

npx -y @mermaid-js/mermaid-cli -i SYSTEM_OVERVIEW.md -o /tmp/overview.svg


Or paste the diagram into https://mermaid.live to confirm it parses. A broken diagram is worse than no diagram.

npx -y @mermaid-js/mermaid-cli -i SYSTEM_OVERVIEW.md -o /tmp/overview.svg


或者将图粘贴到https://mermaid.live确认其可正常解析。一个无法解析的图不如没有图。

Verify

验证清单

```
SYSTEM_OVERVIEW.md
```
exists at the repo root.
All three required sections (
```
CORE ANALYSIS
```
,
```
SYSTEM DESIGN
```
,
```
LEGACY ASSESSMENT
```
) are present.
At least one Mermaid block parses.
Every assertion has a file reference, or is prefixed
```
UNVERIFIED:
```
.
The first paragraph names the language, framework, and primary external dependencies.

```
SYSTEM_OVERVIEW.md
```
已存在于代码库根目录。
三个必填章节（
```
CORE ANALYSIS
```
、
```
SYSTEM DESIGN
```
、
```
LEGACY ASSESSMENT
```
）均已包含。
至少有一个Mermaid块可正常解析。
每一项断言都有文件引用，或前缀
```
UNVERIFIED:
```
。
第一段明确说明使用的语言、框架以及主要外部依赖。

Common Mistakes

常见错误

Claiming patterns from file names. A file called
```
repository.py
```
may not implement the Repository pattern. Open it. If you cannot verify, write
```
UNVERIFIED:
```
.
A flat module list pretending to be an architecture. Sequence and dependency between modules is the value; the list is not. Add at least one Mermaid diagram showing edges.
Skipping the
LEGACY ASSESSMENT
because the code "looks fine." If you found zero inconsistencies in 30 minutes of reading, you read too quickly. Cite the conventions you checked against, even if the verdict is "consistent."
Embellishing past the source prompt without flagging it. If you add the optional extensions (hotspots, open questions, UNVERIFIED rule), say so in the document header so reviewers know which sections are the canonical Sumner/Chesser shape and which are local additions.

仅通过文件名断言模式：名为
```
repository.py
```
的文件未必实现了仓储模式，请打开文件查看。如果无法验证，请标注
```
UNVERIFIED:
```
。
用扁平模块列表冒充架构：模块间的顺序和依赖关系才是核心价值，单纯的列表毫无意义。至少添加一个带连接关系的Mermaid图。
因代码"看起来没问题"而跳过
LEGACY ASSESSMENT
：如果在30分钟的阅读中未发现任何不一致，说明你读得太快了。请注明你对照检查的规范，即使结论是"符合规范"。
未标注就扩展源提示词内容：如果添加了可选扩展内容（风险热点、待确认问题、UNVERIFIED规则等），请在文档头部说明，以便审核人员区分哪些部分是标准的Sumner/Chesser结构，哪些是本地新增内容。

system-overview

Original

Translation

System Overview — first-pass orientation for an unfamiliar codebase

系统概览 — 陌生代码库快速入门指南

Before You Start

开始之前

Step 1: orient with the file tree

步骤1：通过文件目录定位系统

Step 2: locate the entry points and external boundaries

步骤2：定位入口点与外部边界

HTTP / RPC entry points

HTTP / RPC 入口点

External integrations (DB, cache, queues, third-party APIs)

外部集成（数据库、缓存、消息队列、第三方API）

Step 3: write
`SYSTEM_OVERVIEW.md`
with the canonical structure

步骤3：按标准结构编写
`SYSTEM_OVERVIEW.md`

System Overview

System Overview

CORE ANALYSIS (Required)

CORE ANALYSIS（必填）

SYSTEM DESIGN (Required)

SYSTEM DESIGN（必填）

LEGACY ASSESSMENT (If applicable)

LEGACY ASSESSMENT（如适用）

Optional extensions (lecture-specific, not in the source prompt)

可选扩展（针对课程/讲座变体，源提示词中未包含）

Step 4: anchor every claim to a file

步骤4：为所有结论关联文件依据

Step 5: render and sanity-check the Mermaid

步骤5：渲染并验证Mermaid图

If mmdc is available

如果mmdc可用

Verify

验证清单

Common Mistakes

常见错误

system-overview

Original

Translation

System Overview — first-pass orientation for an unfamiliar codebase

系统概览 — 陌生代码库快速入门指南

Before You Start

开始之前

Step 1: orient with the file tree

步骤1：通过文件目录定位系统

Step 2: locate the entry points and external boundaries

步骤2：定位入口点与外部边界

HTTP / RPC entry points

HTTP / RPC 入口点

External integrations (DB, cache, queues, third-party APIs)

外部集成（数据库、缓存、消息队列、第三方API）

Step 3: write SYSTEM_OVERVIEW.md with the canonical structure

步骤3：按标准结构编写SYSTEM_OVERVIEW.md

System Overview

System Overview

CORE ANALYSIS (Required)

CORE ANALYSIS（必填）

SYSTEM DESIGN (Required)

SYSTEM DESIGN（必填）

LEGACY ASSESSMENT (If applicable)

LEGACY ASSESSMENT（如适用）

Optional extensions (lecture-specific, not in the source prompt)

可选扩展（针对课程/讲座变体，源提示词中未包含）

Step 4: anchor every claim to a file

步骤4：为所有结论关联文件依据

Step 5: render and sanity-check the Mermaid

步骤5：渲染并验证Mermaid图

If mmdc is available

如果mmdc可用

Verify

验证清单

Common Mistakes

常见错误

Step 3: write
`SYSTEM_OVERVIEW.md`
with the canonical structure

步骤3：按标准结构编写
`SYSTEM_OVERVIEW.md`