tech-tutorial-lab-template

Appearance

tech-tutorial-lab-template ​

ライブラリ・フレームワーク別のチュートリアルリポジトリを作成するためのテンプレートです。

このリポジトリは GitHub の Template repository として利用することを想定しています。
Use this template から新しいリポジトリを作成し、対象のライブラリ・フレームワークに合わせて内容を調整してください。

このテンプレートの目的 ​

  • 学習内容を機能ごとに整理する
  • 説明、実行できるコード、重要な要点をセットで管理する
  • 学習順序とチュートリアルの対応関係を分かりやすくする
  • Codex などの AI 補助を使って、追加・修正・レビューしやすくする

想定する使い方 ​

このテンプレートから、対象のライブラリやフレームワークごとに新しいリポジトリを作成します。

例:

txt
react-tutorial-lab
nextjs-tutorial-lab
fastapi-tutorial-lab
langchain-tutorial-lab
playwright-tutorial-lab

新しいリポジトリを作成したら、リポジトリ名、説明、チュートリアル構成を対象技術に合わせて変更してください。

推奨ディレクトリ構成 ​

txt
.
├── README.md
├── AGENTS.md
├── docs/
│   ├── overview.md
│   ├── roadmap.md
│   └── glossary.md
├── tutorials/
│   ├── 00-getting-started/
│   │   ├── README.md
│   │   └── code/
│   ├── 01-core-concepts/
│   │   ├── README.md
│   │   └── code/
│   └── 02-feature-example/
│       ├── README.md
│       └── code/
├── examples/
│   ├── minimal-app/
│   └── practical-app/
└── templates/
    └── tutorial-readme-template.md

各ファイルとディレクトリの役割 ​

パス役割
README.mdリポジトリ全体の概要、対象技術、チュートリアル一覧、使い方を書く
AGENTS.mdCodex などの AI エージェントが作業するときのルールを書く
docs/overview.md対象技術の概要を書く
docs/roadmap.md学習順序とチュートリアルの対応関係を書く
docs/glossary.md初学者がつまずきやすい用語、概念、略語を整理する
tutorials/機能ごとのチュートリアルを置く
examples/複数機能を組み合わせた実践的なサンプルを置く
templates/新しいチュートリアルを作るときの雛形を置く

チュートリアルの基本構成 ​

各チュートリアルは、以下の構成を基本とします。

txt
tutorials/XX-feature-name/
├── README.md
└── code/
ファイル内容
README.mdチュートリアル本体。概要、学ぶこと、前提条件、追加で必要な準備、実行方法、コードの解説、まとめを書く
code/実行できるサンプルコードを置く

共通の環境構築はリポジトリ内の一か所にまとめ、各チュートリアルでは実行方法と、その章で追加で必要な準備だけを書いてください。

特に以下の内容を含めると、初学者が進めやすくなります。

  • 共通で必要なランタイムやツール
  • そのチュートリアルで追加で必要な依存関係
  • サンプルコードの実行方法
  • 実行結果の確認方法
  • よくあるエラーと対処方法
  • 最後に見返せる短いまとめ

共通セットアップ ​

このテンプレートでは、共通の環境構築をリポジトリ内の一か所にまとめ、各チュートリアルでは追加で必要な準備だけを書く運用を想定しています。

テンプレート利用後は、このセクションを対象技術向けの内容に置き換えてください。

例:

1. 必要なツールを確認する ​

  • Node.js、Python、Docker など、対象技術で共通して必要なツール
  • エディタや拡張機能など、学習を進めやすくする補助ツール

2. 依存関係をインストールする ​

対象技術に合わせて、最初に一度だけ必要なインストール手順を書きます。

bash
# Node.js 系の例
npm install
bash
# Python 系の例
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

3. 動作確認をする ​

セットアップ後に、最小構成が動くか確認する手順を書きます。

bash
# 例
npm run dev

確認ポイントの例:

  • 開発サーバーが起動する
  • エラーが出ずにサンプル画面やメッセージを確認できる
  • 次のチュートリアルに進む前提環境が整っている

補足:

  • 各チュートリアルでは、この共通セットアップを繰り返さず、その章で追加で必要な作業だけを書きます
  • 対象技術の公式ドキュメントを確認し、セットアップ手順に誤りがないようにしてください

ドキュメントサイトの生成方法 ​

このリポジトリでは、README.md、docs/、tutorials/ の Markdown を正本として扱い、VitePress で GitHub Pages 用の HTML を生成できます。

ドキュメントサイトの生成には Node.js が必要です。
GitHub Actions では Node.js 22 を使います。ローカルでも Node.js 18 以上を使ってください。

初回は依存関係をインストールします。

bash
npm install

ローカルで表示を確認する場合は、開発サーバーを起動します。

bash
npm run docs:dev

公開用の HTML を生成する場合は、次のコマンドを実行します。

bash
npm run docs:build

生成結果は site/ に出力されます。
site/ は生成物なので、通常は Git にコミットしません。

生成済みのサイトをローカルで確認する場合は、次のコマンドを使います。

bash
npm run docs:preview

GitHub Pages 公開設定 ​

GitHub Pages は GitHub Actions から公開する想定です。
リポジトリの Settings > Pages で、Build and deployment の Source を GitHub Actions に設定してください。

main ブランチへ push すると、.github/workflows/pages.yml が実行されます。
ワークフローでは npm ci、npm run docs:build を実行し、site/ を Pages の artifact としてアップロードします。

GitHub Pages では、リポジトリ名に合わせた base path が必要です。
このリポジトリでは、ワークフロー内で BASE_PATH=/リポジトリ名/ の形になるように値を渡して自動調整します。

docs/roadmap.md とチュートリアルの紐づけ ​

docs/roadmap.md は、学習順序と tutorials/[番号]-[機能名] を紐づけるためのファイルです。

チュートリアルを追加、削除、並び替えた場合は、docs/roadmap.md も更新してください。

ロードマップは、現在あるフォルダ数に合わせて 3 Step などへ機械的に要約するのではなく、対象技術で学ぶ主要機能を洗い出して、機能ごとまたは機能群ごとに段階化する形をおすすめします。
そのため、1 つの段階に複数の tutorials/[番号]-[機能名] を紐づけても問題ありません。

ドキュメントサイトのサイドバーは、docs/roadmap.md の Step と Tutorials 列をもとに学習ブロック別に表示されます。
チュートリアル数が多い場合は、24 章をそのまま直列に並べるのではなく、「導入」「基本操作」「検証」「実践」などの関連する学習ブロックに整理してください。

例:

md
# Roadmap

| Step | Topic | Tutorials | Goal |
| ---- | ----- | --------- | ---- |
| 1. 基本セットアップ | 開発を始める準備を整える | `tutorials/00-getting-started/` | 環境構築、実行方法、最小構成の確認を行う |
| 2. 基本機能を理解する | 仕組みの土台になる考え方を押さえる | `tutorials/01-core-concepts/` | 用語、基本概念、最初に必要な使い方を理解する |
| 3. データを扱う | 外部データや内部データの流れを理解する | `tutorials/02-data-fetch/`、`tutorials/03-data-display/` | データ取得、表示、更新の流れを追えるようにする |
| 4. 画面や状態を管理する | 複数の機能をつなげて扱う | `tutorials/04-state-management/`、`tutorials/05-routing/` | 状態管理や画面遷移の役割を理解する |

Codex 用の任意設定 ​

このテンプレートの通常構成には含めませんが、Codex を使う場合は必要に応じて以下を追加できます。

パス用途
AGENTS.mdリポジトリ内で Codex に守ってほしい作業ルールを書く
.agents/skills/このリポジトリ固有の Codex skills を置く
.codex/Codex の project-scoped 設定や hooks を置く

skills や hooks は学習コンテンツ本体ではなく、Codex の作業を補助するための任意設定として扱います。

テンプレート利用後に最初に変更するもの ​

Use this template から新しいリポジトリを作成したら、まず以下を対象技術に合わせて変更してください。

  • README.md のタイトル
  • 対象ライブラリ・フレームワーク名
  • チュートリアル一覧
  • 共通の実行環境・セットアップ手順
  • docs/overview.md の概要
  • docs/roadmap.md の学習ロードマップ
    • 現在あるフォルダ数に合わせて 3 Step に要約せず、主要機能を洗い出して段階化する
    • 必要なら 4 Step 以上に分ける
    • 各段階に対応する tutorials/[番号]-[機能名] を紐づける
    • チュートリアル数が多い場合は、サイドバーで見やすいように関連する学習ブロックへまとめる
  • docs/glossary.md の用語
  • AGENTS.md の作業ルール

Codex などの AI 補助を使う場合は、以下のように依頼すると作業しやすくなります。

txt
このリポジトリは、[対象ライブラリ・フレームワーク名] のチュートリアルリポジトリです。

README.md、docs/overview.md、docs/roadmap.md、docs/glossary.md、AGENTS.md を確認し、
テンプレート用の記述を対象技術向けの内容に置き換えてください。

対応してほしいこと:
- README.md のタイトルを対象技術名に合わせて変更する
- 対象ライブラリ・フレームワークの概要を追記する
- チュートリアル一覧を対象技術の学習順に更新する
- 共通の実行環境・セットアップ手順を追加する
- docs/overview.md に対象技術の概要を整理する
- docs/roadmap.md に学習ロードマップを追加する
- docs/roadmap.md では、今あるフォルダ数に合わせて 3 Step に要約しない
- 対象技術で学ぶ主要機能を洗い出し、機能ごとまたは機能群ごとに段階的なロードマップを作る
- 必要なら 4 Step 以上に分ける
- docs/roadmap.md では各段階と tutorials/[番号]-[機能名] を紐づける
- docs/roadmap.md の Step は、サイドバーの学習ブロック見出しとしても分かりやすい名前にする
- docs/glossary.md に主要な用語を追加する
- AGENTS.md の作業ルールを対象技術向けに調整する
- テンプレート由来のプレースホルダーや不要な記述を削除する

チュートリアル追加の流れ ​

  1. tutorials/ 配下に XX-feature-name 形式のフォルダを作成する tutorials/ は章数をそろえるためではなく、学ぶ機能ごとに分けて追加する想定です。
  2. templates/tutorial-readme-template.md を参考にする
  3. チュートリアルの README.md に概要、学ぶこと、追加で必要な準備、実行方法、コードの解説、まとめを書く
  4. code/ に実行できるサンプルコードを追加する
  5. ルートの README.md にチュートリアル一覧を追記する
  6. docs/roadmap.md に対応するチュートリアルフォルダを紐づけて追記する 関連する機能は、1 つの学習段階や機能群としてまとめて整理しても構いません。
  7. 必要に応じて docs/glossary.md に用語を追加する

Codex などの AI 補助を使う場合は、以下のように依頼すると構成をそろえやすくなります。

txt
AGENTS.md のルールに従って、tutorials/[番号]-[機能名] を追加してください。

要件:
- templates/tutorial-readme-template.md を参考にする
- README.md に概要、学ぶこと、追加で必要な準備、実行方法、コードの解説、まとめを書く
- code/ を作成する場合は、共通セットアップとは別に必要な追加手順だけを README.md に含める
- コードや本文で初めて登場する主要な API、メソッド、設定値は、何を確認・操作・設定しているのかを説明する
- README.md 末尾のまとめには、読み返したい重要な内容だけを短く整理する
- code/ に実行可能なサンプルコードを追加する
- ルート README.md のチュートリアル一覧を更新する
- docs/roadmap.md では、既存フォルダ数に合わせて無理に 3 Step にまとめない
- docs/roadmap.md は、対象技術の主要機能をもとに、機能ごとまたは機能群ごとに段階化する
- docs/roadmap.md に tutorials/[番号]-[機能名] と紐づく段階を追加する
- チュートリアル数が多い場合は、サイドバーが長い直列一覧にならないように、関連する学習ブロックへまとめる
- docs/glossary.md に新しい用語があれば追加する
- 既存のディレクトリ構成や文体に合わせる
- 対象技術の公式ドキュメントを確認し、内容に誤りがないようにする

レビュー依頼の例 ​

txt
tutorials/[番号]-[機能名] の内容をレビューしてください。

確認してほしいこと:
- README.md の説明が分かりやすいか
- コードを含む場合、共通セットアップへの導線と実行手順が分かるか
- コードや本文に登場する主要な API、メソッド、設定値の説明が初出時にあるか
- README.md 末尾のまとめが短く読み返しやすいか
- code/ のサンプルが実行可能か
- 初学者が手順通りに進められるか
- docs/roadmap.md とチュートリアルフォルダが紐づいているか
- サイドバーで見たときに、チュートリアルが長い直列一覧ではなく関連する学習ブロックに整理されているか
- ファクトチェックをして、誤りがないか
- 既存のディレクトリ構成や文体に合わせているか

コードの挙動は必要がない限り変更せず、説明や構成の改善を優先してください。

チュートリアル一覧 ​

このセクションは、テンプレート利用後に対象技術に合わせて更新してください。

現在の 3 件はあくまでサンプルです。
実際には、対象技術で学ぶ機能に合わせてチュートリアルを追加、削除、並び替えてください。

No.チュートリアル内容
00Getting Started環境構築と最小構成
01Core Concepts基本概念
02Feature Example主要機能のサンプル

ライセンス ​

必要に応じて LICENSE を追加してください。