orient

オリエンテーションの作成

目的

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 のみを書き込みます。

これにより、オリエンテーションファイルは説明対象のリポジトリと同じ場所に置かれ、バージョン管理に含めたり、チームメイトと共有したりでき、プロジェクト間で衝突することもありません。

---

引数の確認

次の引数で呼び出されました：$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, “The Programmer's Brain”（2021年、Manning）— エントリーポイントと呼び出しグラフを、一度に1レベルずつたどってください。

3d. テストファイル

テストファイルを2～3個読み、ユニットテストよりも統合テストやエンドツーエンドテストを優先します。テストは実行可能な仕様です。テスト名とアサーションを読むことは、モジュールの目的を理解する最も手早い方法の一つです。

出典：Storey et al., “How Software Developers Use Tools, Cognitive Strategies, and Representations to Navigate Code”（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 を作成しますが、uvx 経由で showboat CLI ツールを使い、詳細な線形コード解説を作成します。

Showboat ステップ 1：uv を確認する

command -v uv を実行して、uv がインストールされていることを確認します。

uv が見つからない場合は、ユーザーに次の内容を伝えます。

showboat モードには uv が必要ですが、PATH 上に見つかりませんでした。 インストール先：https://docs.astral.sh/uv/getting-started/installation/

その後、停止します。それ以上進めないでください。

Showboat ステップ 2：リポジトリを読み、ドキュメントを計画する

リポジトリを読み、その構造、目的、主要なコードパスを理解します。次に、以下を含む線形の解説ドキュメントを計画します。

• タイトルと目次
• 読む順にコードベースを物語形式で説明する解説セクション
• 解説で参照する実際のコードスニペットを収録したコード一覧の付録
• 提案する演習の順序（ステップ4の演習要件と同じ基準。オリエンテーション演習はちょうど2つ）

何かを書く前に、すべてのセクション見出し、コードスニペット、連番付きの一覧番号をあらかじめ計画します。各一覧には連番（Listing 1、Listing 2 など）と短い説明を付けます。

Showboat ステップ 3：showboat ツールを確認する

uvx showboat --help を実行し、利用可能なコマンドとその構文を確認します。

Showboat Step 4: showboat コマンドを使って orientation.md を作成する

showboat CLI を使ってファイルを作成します。出力先は Step 1 と同じ orientation.md です。次の順序でコマンドを実行します。

4a. ドキュメントを初期化する

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

次に、uvx showboat note を使って目次を追加します。

4b. 解説セクションをすべて記述する

各解説セクションを uvx showboat note を使って追加します。ノートの内容には次のルールに従ってください。

• ノート内ではフェンス付きコードブロックを使わず、インラインのバッククォートコード（`like_this`）を使います
• コードの一覧はインラインリンクで参照します：*([Listing N: description](#listing-N))*
• コードの内容だけでなく、なぜそのような構成になっているのかを説明するように、物語調で記述します

4c. コード一覧の付録を作成する

Showboat Step 2 で予定した各一覧について、次を行います。

1. ### Listing N: description のような見出しと HTML アンカー <a id="listing-N"></a> を含むアンカーノートを、uvx showboat note で追加します
2. uvx showboat exec を使って、実際のファイル内容をキャプチャするコマンド（例：関連する行を抽出するための cat や sed）を実行します

4d. 推奨する演習の順序を追加する

uvx showboat note を使って、オリエンテーション演習をちょうど 2 つ含む最終セクションを追加します。これらは、デフォルトパスの Step 4 と同じ基準に従います。

• 最初に、特定の短い成果物を読むよう学習者に指示します
• 次に、読んだ内容をまとめるか、説明するよう求めます
• 読まずに知ることのできない内容を予測するよう求めてはいけません
• 開く正確なファイル、読む内容、回答する総括の質問を指定します

4e. ドキュメントを検証する

次を実行します。

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

続行する前に、報告された問題をすべて修正します。

Showboat Step 5: ユーザーに完了を伝える

ユーザーに次の内容を伝えます。

• ファイルの書き込み先
• showboat モード（コードを順にたどる形式）で生成されたこと
• 使用方法：/learning-opportunities orient
• いつでも /orient showboat を再実行して再生成できること