museum-documentation について
Groveの読者向けに技術文書を書くスキルです。実装の詳細に入る前に背景や設計理由を案内する構成を用います。ヘルプセンターやアーキテクチャ入門に適し、APIリファレンスや技術仕様には使用しません。
主な機能
- 01背景と読者の利点を先に説明
- 02事実だけでなく設計理由を解説
- 03ツアー形式で文書を構成
- 04コード、図、表を活用
- 05適用範囲と対象外を明示
活用シーン
- 01システムの仕組みを説明
- 02読者向けのコードベース文書を作成
- 03ヘルプセンターや設計入門を作成
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/museum-documentationを入力して読み込まれたか確認します。
詳細
博物館ドキュメント
おもてなしとしてのドキュメント。キュレーションされたコレクションとしてのコード。
技術システムを、親しみやすいガイド付きツアーへと変える技術です。博物館スタイルのドキュメントでは、実装の詳細に踏み込む前に「なぜ」という問いを通じて読者に寄り添って案内するガイドとして、書き手を位置づけます。
これは Grove の洗練されたドキュメントスタイルです。経験レベルを問わず、Grove を形作るテクノロジー、パターン、意思決定について理解したい Wanderers に向けたものです。
いつ使うか
- 開発者ではなく、Wanderers に読んでもらうことを目的としたドキュメントを作成するとき
- システムの仕組みを説明するナレッジベース記事を書くとき
- 興味を持った訪問者向けに、コードベース、機能、システムをドキュメント化するとき
- ヘルプセンター向けに「仕組み」コンテンツを作成するとき
- 威圧感ではなく親しみやすさを感じさせる技術コンテンツを書くとき
- 将来のナレッジベースのセクション向けに展示を作成するとき
- アーキテクチャを順に説明するオンボーディング用ドキュメントを作成するとき
対象外：
- API リファレンス（grove-documentation を使用してください）
- 技術仕様書（grove-spec-writing を使用してください）
- クイックリファレンスガイド
基本理念
ドキュメントはおもてなしとして機能するべきです。
読者がコードベースやシステムに入るとき、読者はアーキテクチャや設計上の決定について何も知らない訪問者です。博物館スタイルのドキュメントでは、書き手をリファレンス集の編集者ではなくガイドとして位置づけ、実装に踏み込む前に「なぜ」という問いを通じて読者に寄り添って案内します。
博物館の比喩
🌲 Welcome 🌲
╭─────────────────────╮
│ │
│ ╭─────────────╮ │
│ │ EXHIBIT A │ │
│ │ │ │
│ │ How Login │ │
│ │ Works │ │
│ │ │ │
│ ╰─────────────╯ │
│ │ │
│ ═════╪═════ │
│ │ │
│ ╭─────────────╮ │
│ │ EXHIBIT B │ │
│ ╰─────────────╯ │
│ │
╰─────────────────────╯
Walk through. Take your time.
Every exhibit tells a story.
博物館はカタログを渡して、あとは幸運を祈るようなことはしません。複雑さよりも背景を、仕様よりも物語を先に伝え、厳選された体験へと導きます。
主な原則
説明する前に、全体像を示す
展示は背景を示すところから始めます。コードやアーキテクチャを見せる前に、読者に次のことを伝えます。
- 読者が何を見ているのか
- なぜそれが存在するのか
- 誰にとって役立つのか
次のように書くのではなく：
TokenRefreshMap は、ユーザー ID をキーにして、アクティブなトークン更新処理を保存します。
次のように書きます：
誰かのログイン期限が切れたとき、ログアウトさせずに認証情報を更新する必要があります。このマップはその処理を調整し、複数のタブが開いていても更新処理が重複して開始されるのを防ぎます。
事実よりも理由を説明する
コードが示すのは「何をするか」です。ドキュメントが説明するのは「なぜそうするか」です。
Map がトークン更新処理を保存すると述べるだけでなく、それによって解決する調整上の問題を説明します。その抽象化が生み出す体験につなげます。
わかりやすい比喩を使う
技術的な概念を、身近な体験と結びつけます。
| 技術的な概念 | 博物館の比喩 |
|---|---|
| データベース | 整理された引き出しのあるファイリングキャビネット |
| キャッシュ | ドアのそばにある、すぐに調べられる棚 |
| ミドルウェア | 通り抜けるセキュリティチェックポイント |
| キュー | リクエストが順番を待つ行 |
| ワーカー | バックグラウンドでタスクを処理する、頼れるアシスタント |
| Webhook | 何かが起きたときに鳴るドアベル |
実際のコードを示し、その後に分析する
実際のコードスニペットを提示し、その意義をわかりやすく説明します。
const pending = this.refreshInProgress.get(userId);
if (pending) return pending;
この人の更新処理がすでに進行中なら、新しい処理を始めずに、その処理を待ちます。キッチンは一つ、料理人も一人です。
構成の枠組み
博物館の展示には、一貫した構成があります。
1. タグライン付きのタイトル
# The Authentication Exhibit
> Where login happens. Where trust begins.
2. 「いま見ているもの」セクション
すぐに読者の状況を把握できるようにします。
## What You're Looking At
This is where login happens. When someone proves they own an email
address, this code decides what they can access and how long that
access lasts.
You'll see OAuth flows, session management, and token refresh logic.
Nothing scary—just careful choreography.
3. 整理されたツアー構成
ギャラリー、パート、セクションを使って、読者の道筋を整理します。
## The Tour
### Gallery 1: The Front Door
How visitors arrive and prove who they are.
### Gallery 2: The Memory Room
How we remember who's logged in.
### Gallery 3: The Renewal Office
How sessions stay fresh without interrupting work.
4. 「応用できるパターン」
他でも活用できる教訓を取り上げます。
## Patterns Worth Stealing
**The "already in progress" check.** Before starting an expensive
operation, check if it's already running. Simple, but easy to forget.
**Centralized error handling.** All auth failures flow through one
function. One place to fix, one place to log.
5. 「得られた教訓」
率直な振り返りを伝えます。
## Lessons Learned
We tried stateless JWTs first. Simpler, they said. Scalable, they
promised. But logout was impossible—tokens couldn't be revoked.
Session-based auth is older, but it works. Sometimes boring is right.
6. 「ツアーを続ける」
関連する展示へのリンクを示します。
## Continue Your Tour
- **[The Database Exhibit](./database.md)** — Where sessions are stored
- **[The API Exhibit](./api.md)** — How protected routes check access
- **[The Security Exhibit](./security.md)** — Rate limiting and protection
7. 印象に残る締めくくりの署名
---
_— Autumn, January 2026_
または、詩的な一文：
---
_Trust is built one verified request at a time._
視覚要素
ASCII フロー図
プロセスと関係を示します。
Visitor Grove Google
│ │ │
│ "Log me in" │ │
│ ───────────────────────>│ │
│ │ "Who is this?" │
│ │ ────────────────────────>│
│ │ │
│ │ "It's autumn@..." │
│ │ <────────────────────────│
│ │ │
│ "Welcome back" │ │
│ <───────────────────────│ │
│ │ │
クイックリファレンス用の表
| File | What It Does | Why It Matters |
| --------------- | -------------------- | -------------- |
| `auth.ts` | Handles OAuth flow | The front door |
| `session.ts` | Manages login state | The memory |
| `middleware.ts` | Checks every request | The bouncer |
文脈を添えたコードブロック
コードだけを単独で示してはいけません。必ず前後に説明を加えます。
// Every request passes through this checkpoint
export async function authGuard(request: Request): Promise<Response | null> {
const session = await getSession(request);
if (!session) {
return redirect("/login");
}
return null; // Continue to the page
}
ログインしていない場合はログイン画面に進みます。ログイン済みの場合はそのまま続行します。シンプルなチェックポイントの仕組みです。
文体とトーン
推奨すること
- 「あなた」や「私たち」を自然に使い、会話調で書きます
- 不完全だった点にも触れます（「最初に X を試しましたが、うまくいきませんでした。」）
- 個人的な一言を添えます（「うまく仕上げるまでに 3 回試しました。」）
- 段落は短くします（2～4 文）
- 文のリズムに変化をつけます
避けること
詳しくは owl-archive/references/anti-patterns.md を参照してください。博物館風の文章で特に避けたいものは次のとおりです。
- ダッシュ（句点、読点、括弧を使います）
- 企業的な専門用語（「堅牢な」「シームレスな」「活用する」「利用する」「効率化する」）
- 大げさな接続表現（「さらに」「そのうえ」「加えて」「注目すべき点は」）
- 「X ではなく Y」というパターンとその変形（「X ではない。Y でもない。Z だけだ。」）
- 能動態のほうが明快な場合の受動態
- ぼかした表現（「これは潜在的に役立つ可能性があります……」）
- 使い古された比喩（同じ比喩を段落ごとに繰り返さないこと）
- 自己相似的な要約（各セクションを予告し、説明し、そのあと再要約しないこと）
- 「ここがポイントです」「さらに驚くべきことに」といった、期待を煽るだけの表現
- 動名詞の断片を並べたリスト（「バグ修正。機能開発。コードのリリース。」）
- 歴史的な類似例を次々に並べること（「Apple……Facebook……Uber……」のように立て続けに挙げること）
- 物語調のリストで、各項目を太字から始めるパターン
違い
一般的な文体（避ける）：
このモジュールは、業界標準の OAuth プロトコルを活用して、認証フローをシームレスに処理するための堅牢な機能を提供します。
博物館風の文体（推奨）：
ここでログイン処理が行われます。メールアドレスの所有者であることが証明されると、このコードがアクセスできる対象を決めます。
構成パターン
コードベース全体：MUSEUM.md
コードベース全体を記録する場合は、入り口となる MUSEUM.md を作成します。
# Welcome to the Grove Museum
> A guided tour of how this forest grows.
## The Wings
- **[The Architecture Wing](./docs/exhibits/architecture.md)** — The big picture
- **[The Authentication Exhibit](./docs/exhibits/auth.md)** — Trust and identity
- **[The Database Galleries](./docs/exhibits/database.md)** — Where data lives
単一ディレクトリ：EXHIBIT.md
複雑な機能やディレクトリを 1 つだけ記録する場合：
# The Editor Exhibit
> Where words become posts.
This directory contains everything that powers the writing experience...
複雑な機能：ギャラリー構成
複数の部分から成るシステムには、ギャラリー構成を使います。
## Gallery 1: Data Layer
How posts are stored and retrieved.
## Gallery 2: API Endpoints
The doors visitors knock on.
## Gallery 3: The Editor Component
Where the magic happens in the browser.
## Gallery 4: Security Considerations
Keeping things safe.
検証チェックリスト
博物館風のドキュメントを完成させる前に、次の項目を確認します。
構成
- タイトルにタグラインが含まれている
- 「いま見ているもの」で読者に概要を伝えている
- 論理的なギャラリーやセクションに整理されている
- 「参考にしたいパターン」で応用可能な教訓を紹介している
- 「ツアーを続ける」で関連コンテンツにリンクしている
- 意味のある締めくくりがある（署名または詩的な一文）
視覚的な変化
- ASCII 図またはフロー図が少なくとも 1 つある
- 比較に役立つ箇所では表を使っている
- コードブロックに説明文を添えている
- 4～5 段落を超える長い文章の塊がない
文体（grove-documentation を参照）
- ダッシュを使っていない
- 企業的な専門用語を使っていない
- 動機を説明する直接的なトーンになっている
- 正直に伝えるべき不完全な点にも触れている
- システムの各部分がどうつながるかを明確にしている
読者の体験
- 初めて読む人がツアーについていける
- 「どのように」より先に「なぜ」に答えている
- 技術的な詳細に文脈を添えている
- 筋道が通っていて、たどりやすい
他のスキルとの連携
執筆前
- walking-through-the-grove — 展示に名前を付ける必要がある場合
- grove-documentation — 文体のガイドライン、特に「避けること」のリストを確認します
執筆中
- grove-spec-writing — 図の ASCII アート技法を取り入れます
- grove-documentation — 用語（Wanderer、Rooted など）を確認します
- GroveTerm components — 展示の UI で Grove の用語を使う場合、用語を直接埋め込むのではなく、
@autumnsgrove/lattice/uiのGroveTerm、GroveSwap、またはGroveTextを使います。新しい訪問者には標準用語が表示され、Grove Mode のユーザーには自然をテーマにした用語が表示されます。Markdown の内容では[[term]]構文を使うと、rehype-groveterm プラグインによって自動変換されます。
執筆後
- 初めて読む人の視点で読む — 初めて目にするドキュメントとして、最初から最後までたどります
- 流れは論理的ですか？ さらに読み進めたいと思いますか？
例：展示の完成形
# The Session Exhibit
> How Grove remembers who you are.
## What You're Looking At
When you log in, Grove needs to remember you. Not forever—just long
enough for your visit. This exhibit shows how that memory works.
You'll see cookies, database tables, and the careful dance of
"who are you?" that happens with every page load.
---
## Gallery 1: The Cookie Jar
A session starts with a cookie. Not the chocolate chip kind—a small
piece of text your browser holds onto.
```typescript
const SESSION_COOKIE = "grove_session";
const SESSION_DURATION = 7 * 24 * 60 * 60 * 1000; // 7 days
```
7日間。使いやすい長さでありながら、安全性も保てます。
ログインすると、ランダムな ID を生成し、この Cookie に保存します。 ID 自体には何の意味もありません。ユーザーを検索するためのキーにすぎません。
ギャラリー 2：記憶の書
実際のセッションデータはデータベースに保存されます。
| 列 | 保存される内容 |
|---|---|
id | Cookie にあるランダムなキー |
user_id | このセッションのユーザー |
created_at | ログインした日時 |
expires_at | このセッションが終了する日時 |
ページを読み込むたびに、このテーブルで Cookie の ID を検索します。 見つかり（かつ有効期限が切れていなければ）、引き続きログイン状態になります。
ギャラリー 3：更新のダンス
セッションには有効期限があります。しかし、毎週ログインするのは面倒です。
そこで、ひそかに更新します。セッションの有効期間が半分を過ぎると、 有効期限を延長します。ユーザーが気づくことはありません。アクティブな間は、 ログイン状態が続きます。
if (session.expiresAt < Date.now() + SESSION_DURATION / 2) {
await extendSession(session.id);
}
アクティブな訪問者はとどまり、使われなくなったセッションは期限切れになります。
参考にしたいパターン
「半分の時点で更新する」パターン。 有効期限が切れるまで待たずに、 訪問者がアクティブな間にセッションを延長します。
連番ではなくランダムな ID を使う。 セッション ID は予測できないものにします。 セキュリティトークンに自動採番の番号を使ってはいけません。
学んだこと
以前は、セッションデータを Cookie 自体に保存していました（JWT）。そのほうがシンプルだと 考えていました。しかし、その場合はセッションを無効化できません。誰かのトークンが 漏えいしても、無効にする方法がなかったのです。
データベースセッションは古い技術です。古いほうが賢明なこともあります。
ツアーを続ける
— Autumn、2026年1月
---
## The Underlying Purpose
Museum documentation respects readers' time and intelligence while acknowledging that code is knowledge deserving careful stewardship.
Wanderers who read these exhibits should leave understanding not just *what* Grove does, but *why* it does it that way. They should feel like they've been welcomed into the workshop, not handed a manual.
*Every codebase has stories. Museum documentation tells them.*