AGENTS.md

このファイルは AI エージェントがこのリポジトリで作業する際のガイドラインです。

プロジェクト概要

研究室の勉強会・輪講・ゼミ向けに、PDF（教科書・論文）から 解説記事・Mermaid 図を自動生成 する MkDocs サイト。

• サイトジェネレーター: MkDocs + Material テーマ
• パッケージマネージャー: uv
• ホスティング: GitHub Pages（main プッシュで自動デプロイ）

スキル

このプロジェクトには 3 つの AI エージェント向けスキルが含まれます。実行時は .agents/skills/<skill-name>/SKILL.md を参照してください。

/add-textbook-session

教科書の輪講セッションを追加するメインスキル。2つのモードがあります。

Mode 1 — 新規セッション作成（セッションが未存在）:

/add-textbook-session [slug] <pdf-path> [display-title] [YYYY-MM-DD]

Mode 2 — サブサブセクション深掘り記事追加（セッションが既存）:

/add-textbook-session <session-id> <pdf-path> --sub <subsection-slug> [subsection-title] [presenter]

slug は省略可能（省略時はPDFファイル名から自動生成）。date 省略時は seminar_config.yml の next_seminar_date を使用。

Mode 1 生成物:

• docs/sessions/<DATE>-<slug>/index.md — サブサブセクション一覧付き概要ページ
• docs/sessions/<DATE>-<slug>/diagrams/architecture.mmd — Mermaid 概要図

Mode 1 自動更新:

• mkdocs.yml の nav: → セッション: にネストグループとして追加
• docs/index.md のセッション一覧テーブルに1行追加

Mode 2 生成物:

• docs/sessions/<SESSION_ID>/<subsection-slug>.md — 数式導出・具体例・議論点を含む深掘り記事

Mode 2 自動更新:

• mkdocs.yml の該当セッショングループにサブページを追加
• docs/sessions/<SESSION_ID>/index.md のサブセクション一覧テーブルを更新

/add-paper-session

論文紹介セッションを追加するスキル（将来使用予定）。

/add-paper-session [slug] <pdf-path> [display-title] [YYYY-MM-DD]

教科書と異なり、Abstract/Method/Experiments/Limitationsの論文固有の構成で記事を生成します。

/setup-seminar-project

MkDocs プロジェクトを新規初期化するスキル。このリポジトリ自体はすでに初期化済みなので、通常は使わない。

ディレクトリ構成と役割

docs/sessions/<DATE>-<slug>/   各セッションのコンテンツ
  index.md                     概要ページ（サブサブセクション一覧・全体の流れ）
  <subsection-slug>.md         サブサブセクション深掘り記事（Mode 2 で追加）
  diagrams/*.mmd               Mermaid 図

.agents/skills/
  add-textbook-session/
    SKILL.md                   スキル定義（実行手順・2モード対応）
    assets/
      overview_template.md     Mode 1 概要ページ用テンプレート
      index_template.md        Mode 2 深掘り記事用テンプレート
    references/
      session_format.md        navフォーマット仕様（ネスト構造含む）
  add-paper-session/
    SKILL.md
    assets/
  setup-seminar-project/
    SKILL.md
    assets/

pdfs/                          PDF置き場（.gitignore で除外、コミット不可）
seminar_config.yml             開催日・発表者のデフォルト設定（任意）

コーディング規約

mkdocs.yml の nav エントリ

新規セッションはネスト構造のグループとして追加する（スペース4つ/6つ）：

nav:
  - セッション:
    - <date> <display-title>:                          # スペース4つ
      - 概要: sessions/<DATE>-<slug>/index.md          # スペース6つ
      - サブセクション名: sessions/<DATE>-<slug>/slug.md  # スペース6つ

docs/index.md のセッションテーブル

| YYYY-MM-DD | [タイトル](sessions/DATE-slug/index.md) |

index.md（概要ページ）の品質基準

• サブサブセクション一覧テーブルに全サブサブセクションを列挙する
• Mermaid 図で全体の流れを図示する
• まとめテーブルに各サブサブセクションの1行要点を記載する

サブサブセクション深掘り記事の品質基準

• 数式はステップバイステップで導出し、各ステップに直感的な説明を添える
• 主要概念は「ざっくり理解」「身近な例」「正確な説明」の順に説明する
• 数式の前に、その式が何を表すのかを日本語で説明する
• 専門用語は初出時に短い言い換えを添え、つまずきポイントを !!! warning で明示する
• Mermaid 図を最低1つ含める
• 前後のサブサブセクションとの接続を !!! abstract admonition で明示する
• 担当者の議論・疑問点を末尾に記載する

よく使うコマンド

# ローカルプレビュー
uv run mkdocs serve

# 依存関係インストール
uv sync

注意事項

• pdfs/ は .gitignore で除外済み。PDF は絶対にコミットしない。
• site/ と .venv/ もコミット不可（gitignore 済み）。
• mkdocs.yml を編集するときはインデントに注意（YAML はスペース厳格）。
• スキルのテンプレート（.agents/skills/*/assets/）を直接編集した場合、既存セッションには反映されない（新規セッションのみ適用）。
• .agents/skills/ と .claude/skills/ は lab-seminar-skills リポジトリの git submodule。スキルのテンプレートを修正する場合は lab-seminar-skills リポジトリを直接編集すること。.agents/skills/ や .claude/skills/ を直接編集してはならない。 修正後は lab-seminar-skills でコミット・プッシュし、lab-seminars で git submodule update --remote を実行する。