Onboarding readability

Purpose

「読んでも何をすべきかわからない」ドキュメントを防ぐ。 作成者視点ではなく「初見の読み手」視点でドキュメントを評価し、オンボーディングコストを下げる。

Use When

• 新しいドキュメント・README を公開・共有する前
• 既存ドキュメントへの更新後に可読性を確認する場合
• 別のAIに引き継ぐコンテキストドキュメント（CLAUDE.md / CONTEXT.md）を作成する場合
• チームメンバーや外部協力者が初めてプロジェクトに触れる前

Inputs

以下を準備すること。不足している場合は推測せず、不足を明示する。

• 対象ドキュメント: 評価するドキュメントの内容またはパス
• 想定読み手: 誰が読むか（新メンバー / 外部協力者 / 別セッションのAI / 顧客）
• 読み手の前提知識: 読み手が持っているべき / 持っていない知識
• ドキュメントの目的: このドキュメントを読んだ後に読み手がどう行動すべきか

Output Contract

以下の順で出力すること。順序を変えない。

1. 論点: このドキュメントの可読性を左右する核心的な問題
2. 根拠: その論点をそう判断した理由
3. 可読性評価: 評価項目ごとのチェック結果
4. 含意: 可読性の低さが引き起こすオンボーディングの失敗・誤解のリスク
5. 改善案: 可読性を高める最小限の修正案（構造・用語・導線）
6. 代替案: ドキュメントの目的・読み手が変わる場合の別構成案
7. 判断材料: 「このまま公開 / 修正してから公開 / 構造から見直す」を選ぶための情報

可読性評価 フォーマット

チェック項目	状態	問題箇所・備考
目的・用途が冒頭で明確	OK / 注意 / NG
前提知識・対象読者が明示されている	OK / 注意 / NG
専門用語が定義または説明されている	OK / 注意 / NG
読んだ後のアクションが明確	OK / 注意 / NG
セクション構造・見出しが論理的	OK / 注意 / NG
参照リンク・関連ドキュメントが整備されている	OK / 注意 / NG
情報の鮮度・更新日が把握できる	OK / 注意 / NG
他LLMが読んでも誤解なく実行できる	OK / 注意 / NG

Review Lens

• 目的妥当性: 評価基準が想定読み手に対して適切か
• 範囲の過不足: ドキュメント全体が評価されているか / 一部に偏っていないか
• 中長期リスク: 更新されずに陳腐化するリスクはないか
• LAB全体との整合性: CLAUDE.md / CONTEXT.md との整合性が取れているか
• 非エンジニア理解可能性: 非技術者の読み手を想定した評価になっているか
• 他LLM移植耐性: 評価基準が Claude 固有の読み方に依存していないか

Instructions

1. ドキュメントを「初見の読み手」として読む（作成者の意図を前提にしない）
2. 各評価項目を OK / 注意 / NG で評価する
3. NG・注意の項目に対して具体的な問題箇所（セクション名・行番号等）を記録する
4. 修正コストが低い改善案（1行追加・用語追加等）から順に提示する
5. ドキュメントの構造自体に問題がある場合は構造の見直し案を提示する
6. 「読んだ後に何をすべきか」が不明な場合は必ず指摘する
7. 最終判断は人間に委ねる

Guardrails

• 「読めば分かる」で問題を見逃さない（初見の読み手は背景を知らない）
• 作成者の意図を補完して評価しない（書かれていないことは「ない」として評価する）
• 読みやすさのために技術的正確性を犠牲にする修正案を提示しない
• 更新日・バージョン情報がない場合は必ず指摘する
• AI読み手向け評価（他LLM移植耐性）を省略しない

LAB Cross-Check

観点	状態	備考
自動化フロー	—	自動化フローの操作手順が初見で実行可能か
データ / 認証 / ログ	—	DB・認証の設定手順が初見で分かるか
実装 / 運用フロー	—	実装手順・デプロイ手順が初見で追えるか
非エンジニア理解可能性	—	非技術者が読んで役割を理解できるか
会員共有 / 再利用耐性	—	評価基準が他ドキュメントにも転用できるか
他LLM移植耐性	—	他LLMが読んでも誤解なく実行できるか

状態は OK / 注意 / NG / 対象外 で記入すること。

Handoff Notes

• 要件: 可読性評価結果（チェック項目の状態と問題箇所）
• 成功条件: 想定読み手が追加質問なく次のアクションを実行できる
• 失敗条件: NG 項目が残ったまま公開・共有される
• 実行範囲: ドキュメントの評価・改善案提示のみ（ドキュメントの直接編集は行わない）
• 影響範囲: ドキュメントを読む全員のオンボーディング体験
• ロールバック方針: 誤った修正案を適用した場合は元の版に戻す（git revert）
• コスト比較: 可読性評価コスト vs 誤解・誤操作によるオンボーディング失敗コスト

Further Reading

• reusable-doc-structure skill — ドキュメントの再利用可能な構造設計
• llm-portability-review skill — 他LLMへの移植耐性チェック
• summary-structuring skill — 長文ドキュメントの構造化要約
• docs/CONTEXT.md — プロジェクト文脈ドキュメントの参照例