elixir-docs-review について
Elixir のドキュメント、仕様、doctest を確認するレビュー用スキルです。公開 API を中心に、チェックリストや状況別ルール、根拠の確認手順を示します。
主な機能
- 01モジュールと関数のドキュメント確認
- 02公開 API の仕様カバレッジ確認
- 03doctest の適切性と実行確認
- 04相互参照とメタデータの確認
- 05根拠に基づくレビューゲート
活用シーン
- 01公開 Elixir モジュールのドキュメントレビュー
- 02エクスポート関数の @doc と @spec の確認
- 03純粋関数の doctest カバレッジ評価
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/elixir-docs-reviewを入力して読み込まれたか確認します。
同梱ファイルreferences/doc-quality.mdreferences/spec-coverage.md
詳細
Elixir ドキュメントレビュー
クイックリファレンス
| 問題の種類 | 参考資料 |
|---|---|
| @moduledoc、@doc の品質、アンチパターン | references/doc-quality.md |
| @spec、@type、@typedoc の網羅性 | references/spec-coverage.md |
レビューチェックリスト
モジュールドキュメント
- すべての公開モジュールに @moduledoc がある
- 先頭行の要約が簡潔である（1 行で、ツールが要約として使用する）
- 適切な場合、@moduledoc に ## Examples が含まれている
- @moduledoc false は内部モジュールまたは実装モジュールにのみ指定されている
関数ドキュメント
- すべての公開関数に @doc がある
- すべての公開関数に @spec がある
- @doc で戻り値が明確に説明されている
- 複数節の関数は最初の節より前にドキュメント化されている
- 引数名の補足説明が必要な場合、関数ヘッダーが宣言されている
doctest
- 純粋で決定論的な関数に doctest がある
- 副作用のある操作（DB、HTTP など）には doctest がない
- doctest が実際に実行される（テストファイルにモジュールが含まれている）
相互参照
- モジュール参照にバッククォートの自動リンクを使用している（
MyModule） - 関数参照に適切なアリティ形式を使用している（
function/2） - 型参照に t: プレフィックスを使用している（
t:typename/0） - 自動リンクが可能な箇所で、プレーンテキストの参照を使用していない
メタデータ
- 新しい公開 API の追加に @since 注釈がある
- 適切な場合、移行方法を示す @deprecated がある
有効なパターン（指摘しないこと）
- コールバック実装での @doc false - ビヘイビアーレベルでドキュメント化されています
- プロトコル実装での @doc false - プロトコルのドキュメントで意図が説明されています
- プライベート関数に @spec がない - 内部関数では @spec は任意です
- ## Examples のない、簡潔な @moduledoc を持つ単純なユーティリティモジュール - すべてのモジュールに例が必要なわけではありません
- 個別の @doc なしで @impl true を使用する - ビヘイビアーのドキュメントを継承します
文脈に応じたルール
| 問題 | 次の場合にのみ指摘 |
|---|---|
| @moduledoc がない | モジュールが公開されており、かつプロトコル実装ではない |
| @spec がない | 関数が公開されており、かつエクスポートされている |
| doctest がない | 関数が純粋で、かつ決定論的である |
| 一般的すぎる @doc | ドキュメントが価値を加えず、関数名を言い換えている |
ゲート（順番に実施し、飛ばさないこと）
順番どおりに進めてください。直前のステップに合格するまで、指摘事項の作成や提出を行わないでください。
- 対象範囲の固定 — 合格条件： レビュー対象の正確な
.ex／.exsファイルパス（またはModule名）を列挙しており、「プロジェクト」など曖昧な対象範囲を指定していないこと。 - 全コンテキストの確認 — 合格条件： 各候補の問題について、差分の一部や検索結果の抜粋だけでなく、その定義全体（複数節の関数ではすべての節、モジュールレベルの指摘では
@moduledocブロック全体）を読んでいること。 - 根拠の提示 — 合格条件： 指摘案のすべてに
[FILE:LINE] ISSUE_TITLE形式のヘッダー（行範囲も可）があり、問題となる@doc／@spec／doctest のテキストをそのまま引用するか、場所を示していること。Module.function/arityは補足情報として記載できますが、[FILE:LINE]のアンカーの代わりにはなりません。「doctest が失敗する」という指摘の場合、合格条件： 該当ファイルまたは行に関するmix testの出力、または正確なエラー文字列を引用すること。 - 報告前のプロトコル確認 — 合格条件： 問題一覧を確定する前に review-verification-protocol（Pre-Report チェックリスト）を読み、手順に従っていること。確定した後ではありません。
参考資料を読み込むタイミング
- @moduledoc または @doc の品質をレビューするとき、アンチパターンを見つけたとき -> doc-quality.md
- @spec、@type、または @typedoc の網羅性をレビューするとき -> spec-coverage.md
コメント
Markdown 対応