orient

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create Orientation

创建入门引导文档

Purpose

用途

Generate a repo-specific

orientation.md

file inside the

learning-opportunities

skill's

resources/

directory. This file is used by that skill when invoked as

/learning-opportunities orientation

to run a structured learning exercise for someone new to the codebase.

在learning-opportunities skill的

resources/

目录下生成特定代码仓库的

orientation.md

文件。当用户调用

/learning-opportunities orientation

命令时，该skill会使用这个文件为刚接触代码库的人员运行结构化的学习练习。

Step 1: Find where to write orientation.md

步骤1：确定orientation.md的写入位置

Always write to the project level, regardless of where the

learning-opportunities

skill is installed:

.claude/skills/learning-opportunities/resources/orientation.md

(relative to the current working directory)

If the directory

.claude/skills/learning-opportunities/resources/

does not exist, create it. If it already exists, leave it and any files inside it untouched — only write

orientation.md

This keeps orientation files co-located with the repo they describe — they can be committed to version control, shared with teammates, and never collide across projects.

无论learning-opportunities skill安装在什么位置，始终写入到项目根层级：

.claude/skills/learning-opportunities/resources/orientation.md

（相对于当前工作目录的路径）

如果

.claude/skills/learning-opportunities/resources/

目录不存在，请创建它。如果目录已存在，保留目录及其中的所有原有文件不变，仅写入

orientation.md

即可。

这种方式可以让入门引导文件和它所描述的代码仓库存放在同一位置，支持提交到版本控制、与团队成员共享，且不会在不同项目之间产生冲突。

Argument check

参数检查

You were invoked with arguments:

$ARGUMENTS

If the argument is

showboat

, skip to the Showboat Path section below.

Otherwise, continue with Steps 2–5 (the default path).

本次调用传入的参数为：

$ARGUMENTS

如果参数为

showboat

，直接跳转到下方的Showboat路径部分。

否则，继续执行步骤2-5（默认路径）。

Step 2: Detect the repo's primary language(s)

步骤2：检测仓库的主要开发语言

Check for these manifest/config files at the project root and note all that exist. A repo may use multiple languages.

Language	Signal files
Python	`pyproject.toml` , `setup.py` , `setup.cfg` , `Pipfile` , `requirements.txt`
JavaScript	`package.json` (no `tsconfig.json` )
TypeScript	`package.json` + `tsconfig.json`
R	`DESCRIPTION` , `NAMESPACE` , any `*.Rproj`
Ruby	`Gemfile` , any `*.gemspec`
Go	`go.mod`
Rust	`Cargo.toml`
C/C++	`CMakeLists.txt` , `configure.ac` , root-level `Makefile`
Java/Kotlin	`pom.xml` , `build.gradle` , `build.gradle.kts`
C#	any `.csproj` or `.sln`

Record all detected languages. For each detected language, read its primary manifest file in full — it contains declared purpose, dependencies, entry points, and scripts/commands that are essential for orientation.

检查项目根目录下是否存在以下清单/配置文件，记录所有存在的文件，一个仓库可能使用多种语言。

语言	标识文件
Python	`pyproject.toml` 、 `setup.py` 、 `setup.cfg` 、 `Pipfile` 、 `requirements.txt`
JavaScript	存在 `package.json` 且不存在 `tsconfig.json`
TypeScript	同时存在 `package.json` 和 `tsconfig.json`
R	`DESCRIPTION` 、 `NAMESPACE` 、任意 `*.Rproj` 文件
Ruby	`Gemfile` 、任意 `*.gemspec` 文件
Go	`go.mod`
Rust	`Cargo.toml`
C/C++	`CMakeLists.txt` 、 `configure.ac` 、根目录下的 `Makefile`
Java/Kotlin	`pom.xml` 、 `build.gradle` 、 `build.gradle.kts`
C#	任意 `.csproj` 或 `.sln` 文件

记录所有检测到的语言。针对每一种检测到的语言，完整读取它的主清单文件，文件中包含了声明的项目用途、依赖、入口点，以及入门引导必备的脚本/命令信息。

Step 3: Explore the repo

步骤3：探索代码仓库

Use the following sequence, drawn from research on expert program comprehension strategies. Experts read strategically and selectively, not exhaustively. The goal is a mental model of structure, not line-by-line understanding.

使用以下流程，该流程源自专家代码理解策略相关研究。专家会有策略、有选择性地阅读代码，而非逐行通读。目标是建立代码结构的心智模型，而非逐行理解所有实现细节。

3a. README and top-level docs

3a. README和顶层文档

Read

README.md

README.rst

, or

README

at the project root. Also check for a

docs/

directory — read its index or table of contents if present. This gives the stated purpose and intended audience.

Source: Spinellis, "Code Reading: The Open Source Perspective" (2003) — start with the build system and README before reading any application code.

读取项目根目录下的

README.md

、

README.rst

或

README

文件。同时检查是否存在

docs/

目录，如果存在则读取其索引或目录内容。这一步可以了解项目公开说明的用途和目标受众。

来源：Spinellis《Code Reading: The Open Source Perspective》（2003）——阅读应用代码前先从构建系统和README开始。

3b. Directory tree

3b. 目录树

Run

find . -maxdepth 3 -not -path '*/.git/*' -not -path '*/node_modules/*' -not -path '*/__pycache__/*' -not -path '*/.venv/*'

to get the top-level structure. Read the directory tree as an architectural table of contents — naming conventions (

src/

lib/

tests/

cmd/

pkg/

) reveal intent before any code is read.

Source: Spinellis (2003) — "directory tree as table of contents."

运行命令

find . -maxdepth 3 -not -path '*/.git/*' -not -path '*/node_modules/*' -not -path '*/__pycache__/*' -not -path '*/.venv/*'

获取顶层目录结构。将目录树看作架构目录，命名规范（如

src/

、

lib/

、

tests/

、

cmd/

、

pkg/

）在阅读代码前就能体现设计意图。

来源：Spinellis（2003）——“目录树即内容目录”。

3c. Entry points

3c. 入口点

Identify and read the main entry points based on detected language:

Python:

__main__.py

cli.py

main.py

, or the

[tool.poetry.scripts]

[project.scripts]

section of

pyproject.toml

JavaScript/TypeScript:
```
main
```
field in
```
package.json
```
,
```
index.js
```
,
```
src/index.ts
```
Go: files in
```
cmd/*/main.go
```
or root
```
main.go
```
Rust:
```
src/main.rs
```
or
```
src/lib.rs
```
R:
```
R/
```
directory, the
```
DESCRIPTION
```
file's
```
Imports
```
Ruby: files in
```
bin/
```
,
```
lib/<gem-name>.rb
```
C/C++:
```
main.c
```
,
```
main.cpp
```
, or the primary target in
```
CMakeLists.txt
```

Source: Hermans, "The Programmer's Brain" (2021, Manning) — follow the entry point and call graph one level at a time.

根据检测到的语言识别并读取主入口点：

Python：

__main__.py

、

cli.py

、

main.py

，或者

pyproject.toml

中的

[tool.poetry.scripts]

[project.scripts]

部分

JavaScript/TypeScript：
```
package.json
```
中的
```
main
```
字段、
```
index.js
```
、
```
src/index.ts
```
Go：
```
cmd/*/main.go
```
下的文件或根目录下的
```
main.go
```
Rust：
```
src/main.rs
```
或
```
src/lib.rs
```
R：
```
R/
```
目录、
```
DESCRIPTION
```
文件的
```
Imports
```
部分
Ruby：
```
bin/
```
下的文件、
```
lib/<gem-name>.rb
```
C/C++：
```
main.c
```
、
```
main.cpp
```
，或者
```
CMakeLists.txt
```
中的主目标

来源：Hermans《The Programmer's Brain》（2021, Manning）——逐层跟进入口点和调用图。

3d. Test files

3d. 测试文件

Read 2–3 test files, prioritizing integration or end-to-end tests over unit tests. Tests are executable specifications — reading test names and assertions is one of the fastest ways to understand what a module is meant to do.

Source: Storey et al., "How Software Developers Use Tools, Cognitive Strategies, and Representations to Navigate Code" (IEEE TSE, 2006) — use the test suite as a specification.

读取2-3个测试文件，优先选择集成测试或端到端测试，而非单元测试。测试是可执行的需求规范，阅读测试名称和断言是理解模块设计用途的最快方式之一。

来源：Storey等人《How Software Developers Use Tools, Cognitive Strategies, and Representations to Navigate Code》（IEEE TSE, 2006）——将测试套件作为需求规范使用。

3e. Core modules

3e. 核心模块

Identify the 5–8 most important source files based on what you have learned. Read their top-level structure (class/function names, imports, docstrings) without necessarily reading every implementation in full.

基于之前获取的信息，识别5-8个最重要的源码文件。读取它们的顶层结构（类/函数名、导入、文档字符串），无需通读所有实现细节。

3f. Recent git history (if git is available)

3f. 近期git历史（如果可用git）

Run

git log --oneline -20

to see recent activity. Run

git log --format="%f" | sort | uniq -c | sort -rn | head -10

to identify the most-edited files. High-churn files are usually the core of the system.

Source: Spolsky practitioner writing — "find the biggest, most-edited file; read git history to understand why code is the way it is."

运行

git log --oneline -20

查看近期活动。运行

git log --format="%f" | sort | uniq -c | sort -rn | head -10

识别修改最频繁的文件。高改动频率的文件通常是系统的核心部分。

来源：Spolsky实践文章——“找到最大、修改最多的文件；阅读git历史理解代码设计的原因”。

Step 4: Synthesize and write orientation.md

步骤4：整合内容并写入orientation.md

Write the file to the path identified in Step 1. Use this exact structure:

markdown

undefined

将文件写入步骤1中确定的路径，使用以下固定结构：

markdown

undefined

Repo Orientation: [repo name]

仓库入门引导：[仓库名称]

Generated by /orient:orient. Re-run to update.

由/orient:orient生成，可重新运行命令更新。

One-line purpose

一句话用途

[Single sentence: what this repo does and why it exists. Written for someone with no prior context.]

[单句说明：这个仓库的功能以及存在的意义，面向无任何前置背景的人员编写。]

Primary language(s)

主要开发语言

[List languages detected, with the dominant one first.]

[列出检测到的所有语言，占比最高的放在最前面。]

Pipeline / workflow stages

流水线/工作流阶段

[Ordered list of the main stages data or requests flow through. One line each. If the repo has no pipeline, describe the main modules and their relationships instead.]

[数据或请求流转的主要阶段有序列表，每个阶段占一行。如果仓库没有流水线，则描述主要模块及其关联关系。]

Key files

关键文件

[6–10 entries in this format:]

```
path/to/file.py
```
— [what it does] | [why a new developer should read it]

[6-10个条目，格式如下：]

```
path/to/file.py
```
— [功能说明] | [新开发者需要阅读它的原因]

Core concepts

核心概念

[3–5 domain or architectural concepts essential to working in this codebase. For each:] [Concept name]: [Plain-English definition. Where in the code it lives.]

[在该代码库中工作必备的3-5个业务或架构概念，每个概念格式如下：] [概念名称]：[通俗的定义说明，以及它在代码中的位置。]

Common gotchas

常见陷阱

[2–3 things that commonly trip up new developers. Be specific — reference actual file paths or function names.]

[新开发者常遇到的2-3个问题，要具体，可引用实际文件路径或函数名。]

Suggested exercise sequence

建议练习序列

[EXACTLY 2 exercises. These are orientation exercises — their job is to build a high-level mental model of the repo, not to drill implementation details.

Orientation exercises follow this pattern: direct the learner to read one specific, short artifact first, then ask them to synthesize or explain what they just read. Never ask them to predict something they couldn't know without reading — the goal is comprehension and synthesis, not prior knowledge.

Good orientation exercises:

"Open README.md and read the Features section. Then close it and explain to a non-developer what this tool produces and why someone would use it."
"Open
```
models.py
```
. Find the dataclass that represents everything the pipeline produces for one audio file. What fields does it have, and what does that tell you about the pipeline's stages?"
"Open
```
config/default.yaml
```
and skim it. What are the two or three settings you'd most likely need to change for a new project, and why?"

Bad orientation exercises (save these for later sessions):

"Without opening any files, predict the pipeline stages" — learner has no basis for this
Predicting specific function outputs, column names, or algorithmic behavior
Tracing through individual method implementations
Debugging specific logic (e.g. merge suffix behavior, metadata propagation)

For each exercise, specify: the exact file to open, what to read, and what synthesis question to answer after reading.]

[恰好2个练习，属于入门级练习，目标是建立仓库的高层级心智模型，而非演练实现细节。

入门练习遵循以下模式：先引导学习者阅读某个具体的短内容，然后要求他们整合或解释刚阅读的内容。绝对不要要求他们预测不阅读就无法知道的内容，目标是理解和整合，而非考察前置知识。

好的入门练习示例：

"打开README.md并阅读功能部分，然后合上书向非开发人员解释这个工具的输出以及用户使用它的原因。"
"打开
```
models.py
```
，找到表示流水线为单个音频文件生成的所有内容的数据类，它有哪些字段？这些字段能反映出流水线的哪些阶段？"
"打开
```
config/default.yaml
```
并浏览，新项目中你最可能需要修改的2-3个配置是什么？为什么？"

不好的入门练习（留到后续阶段使用）：

"不打开任何文件，预测流水线的阶段"——学习者没有判断依据
预测具体函数的输出、列名或算法行为
追踪单个方法的实现
调试特定逻辑（例如合并后缀行为、元数据传播）

每个练习需要明确说明：要打开的具体文件、要阅读的内容、阅读后需要回答的整合问题。]

Sources consulted

参考来源

[List the files and paths you actually read while generating this file.]


Keep each section concise. This is a teaching scaffold, not documentation. Prioritize clarity over completeness.

---

[生成该文件时实际读取的文件和路径列表。]


每个部分保持简洁，这是教学脚手架而非完整文档，优先保证清晰而非全面。

---

Step 5: Confirm to the user

步骤5：向用户确认结果

Note for skill maintainers: Academic and practitioner sources for the exploration methodology in Steps 3a–3f are documented in resources/orient-bibliography.md. Load that file only if you need to update or cite sources — it is not needed during normal skill execution.

Tell the user:

Where the file was written
How many key files and concepts were identified
How to use it:
```
/learning-opportunities orient
```
That they can re-run
```
/orient:orient
```
at any time to regenerate it as the codebase evolves

skill维护者注意：步骤3a-3f中探索方法的学术和实践来源记录在resources/orient-bibliography.md中，仅在需要更新或引用来源时加载该文件，正常执行skill时不需要。

告知用户以下信息：

文件写入的位置
识别出的关键文件和概念数量
使用方式：
```
/learning-opportunities orient
```
可随时重新运行
```
/orient:orient
```
命令，在代码库演进时重新生成文档

Showboat Path

Showboat路径

This path replaces Steps 2–5 when the argument is

showboat

. It produces

orientation.md

at the same location identified in Step 1, but uses the

showboat

CLI tool (via

uvx

) to build a detailed, linear code walkthrough.

当参数为

showboat

时，该路径替代步骤2-5。它会在步骤1确定的相同位置生成

orientation.md

，但会使用

showboat

CLI工具（通过

uvx

调用）构建详细的线性代码走读文档。

Showboat Step 1: Check for uv

Showboat步骤1：检查uv是否安装

Run

command -v uv

to verify that

uv

is installed.

uv

is not found, tell the user:

uv
is required for showboat mode but was not found on your PATH. Install it from: https://docs.astral.sh/uv/getting-started/installation/

Then stop — do not proceed further.

运行

command -v uv

验证

uv

是否已安装。

如果未找到

uv

，告知用户：

Showboat模式需要安装
uv
，但在PATH中未找到。可在该地址安装：https://docs.astral.sh/uv/getting-started/installation/

然后终止流程，不要继续执行。

Showboat Step 2: Read the repo and plan the document

Showboat步骤2：读取仓库并规划文档结构

Read the repo to understand its structure, purpose, and key code paths. Then plan a linear walkthrough document with:

A title and table of contents
Commentary sections that explain the codebase narratively, in reading order
A Code Listings appendix containing the actual code snippets referenced by commentary
A suggested exercise sequence (same criteria as Step 4's exercise requirements — exactly 2 orientation exercises)

Plan all section headings, code snippets, and sequential listing numbers upfront before writing anything. Each listing gets a sequential number (Listing 1, Listing 2, etc.) and a short description.

读取仓库了解其结构、用途和关键代码路径，然后规划线性走读文档，包含：

标题和目录
按阅读顺序叙事性解释代码库的注释部分
代码清单附录，包含注释部分引用的实际代码片段
建议练习序列（和步骤4的练习要求一致，恰好2个入门练习）

在写入任何内容前提前规划好所有章节标题、代码片段和连续的清单编号，每个清单有一个连续编号（清单1、清单2等）和简短描述。

Showboat Step 3: Learn the showboat tool

Showboat步骤3：了解showboat工具用法

Run

uvx showboat --help

to learn the available commands and their syntax.

运行

uvx showboat --help

了解可用命令及其语法。

Showboat Step 4: Build orientation.md using showboat commands

Showboat步骤4：使用showboat命令构建orientation.md

Use the showboat CLI to build the file. The output path is the same

orientation.md

from Step 1. Execute commands in this order:

使用showboat CLI构建文件，输出路径和步骤1的

orientation.md

路径一致，按以下顺序执行命令：

4a. Initialize the document

4a. 初始化文档

uvx showboat init <path-to-orientation.md> "<Title>"

Then add a table of contents via

uvx showboat note

uvx showboat init <path-to-orientation.md> "<Title>"

然后通过

uvx showboat note

添加目录。

4b. Write all commentary sections

4b. 编写所有注释部分

Add each commentary section using

uvx showboat note

. Follow these rules for note content:

No fenced code blocks inside notes — use inline backtick code (
```
`like_this`
```
) instead
Reference code listings with inline links:
```
*([Listing N: description](#listing-N))*
```
Write narratively — explain why the code is structured this way, not just what it does

使用

uvx showboat note

添加每个注释部分，注释内容遵循以下规则：

注释中不要使用 fenced 代码块，改用行内反引号代码（
```
`like_this`
```
）
使用行内链接引用代码清单：
```
*([清单N: 描述](#listing-N))*
```
叙事性编写，解释代码为什么要这么设计，而不只是说明代码做了什么

4c. Write the Code Listings appendix

4c. 编写代码清单附录

For each listing planned in Showboat Step 2:

Add an anchor note:

uvx showboat note

with a heading like

### Listing N: description

and an HTML anchor

<a id="listing-N"></a>

Add the code via
```
uvx showboat exec
```
to capture the actual file content (e.g., using
```
cat
```
or
```
sed
```
to extract the relevant lines)

针对Showboat步骤2中规划的每个清单：

添加锚点注释：

uvx showboat note

，标题为

### 清单N: 描述

，并添加HTML锚点

<a id="listing-N"></a>

通过
```
uvx showboat exec
```
添加代码，捕获实际文件内容（例如使用
```
cat
```
或
```
sed
```
提取相关行）

4d. Append suggested exercise sequence

4d. 追加建议练习序列

Add a final section via

uvx showboat note

with exactly 2 orientation exercises. These follow the same criteria as the default path's Step 4:

Direct the learner to read one specific, short artifact first
Then ask them to synthesize or explain what they just read
Never ask them to predict something they couldn't know without reading
Specify: the exact file to open, what to read, and what synthesis question to answer

通过

uvx showboat note

添加最后一个部分，包含恰好2个入门练习，遵循默认路径步骤4的相同要求：

先引导学习者阅读某个具体的短内容
然后要求他们整合或解释刚阅读的内容
绝对不要要求他们预测不阅读就无法知道的内容
明确说明：要打开的具体文件、要阅读的内容、阅读后需要回答的整合问题

4e. Verify the document

4e. 验证文档

Run:

uvx showboat verify <path-to-orientation.md>

Fix any issues reported before proceeding.

运行：

uvx showboat verify <path-to-orientation.md>

修复所有报告的问题后再继续。

Showboat Step 5: Confirm to the user

Showboat步骤5：向用户确认结果

Tell the user:

Where the file was written
That it was generated using showboat mode (a linear code walkthrough)
How to use it:
```
/learning-opportunities orient
```
That they can re-run
```
/orient showboat
```
at any time to regenerate it

告知用户：

文件写入的位置
该文件是通过Showboat模式生成的（线性代码走读文档）
使用方式：
```
/learning-opportunities orient
```
可随时重新运行
```
/orient showboat
```
命令重新生成文档