orient

创建 Orientation

目的

在 learning-opportunities 技能的 resources/ 目录中生成一份针对特定代码库的 orientation.md 文件。当使用 orient 参数调用该技能时，此文件将用于为代码库新手开展结构化学习练习。

---

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

无论 learning-opportunities 技能安装在哪里，都始终写入项目级目录。

在 Codex 中运行时，写入：

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

在 Claude Code 中运行时，写入：

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

这两个路径都相对于当前工作目录。

如果目标目录不存在，请创建它。如果目录已存在，则保持目录及其中的文件不变——只写入 orientation.md。

这样，orientation 文件就会与其描述的代码库放在一起——它们可以提交到版本控制、与队友共享，并且不会在不同项目之间发生冲突。

---

参数检查

调用时使用的参数为：$ARGUMENTS

如果参数为 showboat，则跳转到下方的Showboat 路径部分。

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

---

步骤 2：检测代码库的主要语言

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

语言	标识文件
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

记录所有检测到的语言。对于每种检测到的语言，都要完整阅读其主要清单文件——其中包含用途、依赖项、入口点和脚本/命令等重要信息，可用于了解代码库。

---

步骤 3：探索代码库

按照以下顺序进行探索。该顺序借鉴了关于专家代码理解策略的研究。专家会有策略地选择性阅读，而不是通读所有内容。目标是建立对结构的整体认识，而不是逐行理解。

3a. README 和顶层文档

阅读项目根目录中的 README.md、README.rst 或 README。同时检查是否存在 docs/ 目录——如果有，请阅读其索引或目录。这有助于了解项目声明的用途和目标受众。

来源：Spinellis，《Code Reading: The Open Source Perspective》（2003）——在阅读任何应用代码之前，先从构建系统和 README 入手。

3b. 目录树

运行 find . -maxdepth 3 -not -path '*/.git/*' -not -path '*/node_modules/*' -not -path '*/__pycache__/*' -not -path '*/.venv/*' 以获取顶层结构。将目录树视为架构目录——命名惯例（src/、lib/、tests/、cmd/、pkg/）无需阅读代码，便能揭示项目意图。

来源：Spinellis（2003）——“将目录树视为目录”。

3c. 入口点

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

• 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，《程序员的大脑》（2021，Manning）——沿着入口点和调用图，一次深入一层。

3d. 测试文件

阅读 2–3 个测试文件，优先选择集成测试或端到端测试，而非单元测试。测试是可执行的规格说明——阅读测试名称和断言，是了解模块预期用途的最快方法之一。

来源：Storey 等人，《软件开发者如何使用工具、认知策略和表征来浏览代码》（IEEE TSE，2006）——将测试套件作为规格说明。

3e. 核心模块

根据目前了解到的信息，找出 5–8 个最重要的源文件。阅读其顶层结构（类名、函数名、导入项、文档字符串），不一定要完整阅读每个实现。

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

运行 git log --oneline -20 查看近期活动。运行 git log --format="%f" | sort | uniq -c | sort -rn | head -10 找出修改最频繁的文件。频繁变动的文件通常是系统的核心。

来源：Spolsky 的从业者文章——“找出最大、修改最频繁的文件；阅读 git 历史，了解代码为何如此设计。”

---

第 4 步：综合并编写 orientation.md

将文件写入第 1 步中确定的路径。使用以下确切结构：

# Repo Orientation: [repo name]

> Generated by orient. Re-run to update.

## 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]

## 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.]

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

## 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.]

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

每个部分都应简洁。这是教学脚手架，而非文档。优先考虑清晰，而非面面俱到。

---

第 5 步：向用户确认

技能维护者须知：第 3a–3f 步中探索方法所依据的学术和从业者资料记录在 resources/orient-bibliography.md 中。仅在需要更新或引用资料时加载该文件；正常执行技能时无需加载。

告知用户：

• 文件写入的位置
• 找到了多少个关键文件和概念
• 如何使用：使用 orient 参数调用 learning-opportunities
• 代码库不断演进时，他们可以随时重新运行 orient 来重新生成文件

---

Showboat 路径

当参数为 showboat 时，此路径会取代第 2–5 步。它会在第 1 步确定的同一位置生成 orientation.md，但会使用 Showboat CLI 工具（通过 uvx）构建一份详细、按顺序展开的代码导览。

Showboat 第 1 步：检查 uv

运行 command -v uv，确认是否已安装 uv。

如果未找到 uv，请告知用户：

Showboat 模式需要 uv，但在你的 PATH 中未找到它。 请从此处安装：https://docs.astral.sh/uv/getting-started/installation/

然后停止，不要继续操作。

Showboat 第 2 步：阅读代码库并规划文档

阅读代码库，了解其结构、用途和关键代码路径。然后规划一份按顺序展开的导览文档，其中包括：

• 标题和目录
• 以叙述方式按阅读顺序讲解代码库的说明章节
• 代码清单附录，包含说明中引用的实际代码片段
• 建议的练习顺序（与第 4 步的练习要求相同——恰好 2 个方向练习）

在开始编写前，预先规划所有章节标题、代码片段和连续的清单编号。每个清单都应有连续编号（清单 1、清单 2 等）和简短说明。

Showboat 第 3 步：了解 Showboat 工具

运行 uvx showboat --help，了解可用命令及其语法。

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

使用 showboat CLI 构建该文件。输出路径与第 1 步中的 orientation.md 相同。按以下顺序执行命令：

4a. 初始化文档

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

然后使用 uvx showboat note 添加目录。

4b. 编写所有说明章节

使用 uvx showboat note 添加每个说明章节。说明内容遵循以下规则：

• 说明中不要使用围栏代码块——改用行内反引号代码（`like_this`）
• 使用行内链接引用代码清单：*([清单 N：说明](#listing-N))*
• 以叙述方式编写——解释代码为何采用这种结构，而不只是说明代码做了什么

4c. 编写代码清单附录

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

1. 添加锚点说明：使用 uvx showboat note 添加一个标题，如 ### Listing N: description，并添加 HTML 锚点 <a id="listing-N"></a>
2. 使用 uvx showboat exec 添加代码，以捕获文件的实际内容（例如，使用 cat 或 sed 提取相关行）

4d. 附加建议的练习序列

使用 uvx showboat note 添加最后一个章节，其中恰好包含 2 个方向练习。这些练习遵循默认路径第 4 步的相同标准：

• 首先指引学习者阅读一份具体、简短的资料
• 然后要求他们综合或解释刚读过的内容
• 绝不要要求他们预测阅读后仍无法知道的事情
• 明确指定要打开的确切文件、要阅读的内容，以及要回答的综合问题

4e. 验证文档

运行：

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

在继续之前修复报告的所有问题。

Showboat 第 5 步：向用户确认

告知用户：

• 文件写入的位置
• 文件是使用 showboat 模式生成的（线性代码演练）
• 如何使用：/learning-opportunities orient
• 随时可以重新运行 /orient showboat 来重新生成该文件