mcpField
D
doc-generator

doc-generator

github.com/atholaドキュメント343157 回インストール1 日前に更新
リポジトリ

doc-generator について

doc-generatorは、技術文書の作成や改訂に使う、開発者や文書作成者向けのスキルです。主旨を先に示し、具体的な根拠を用いる方針と、冗長さや文章品質のチェックを備えています。

主な機能

  1. 01読者と主旨に基づく範囲設定
  2. 02スタイルプロファイルに沿った草案作成
  3. 03冗長さとAI文体のチェック
  4. 04文単位・文書単位の品質基準
  5. 05文書とコメントの改訂

活用シーン

  1. 01README・ガイド・API文書の作成
  2. 02読者層に合わせた内容の調整
  3. 03意図を保った既存文章の整理
  4. 04規則に沿ったコードコメントの改訂

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/athola/claude-night-market --skill doc-generator

インストール後、Claude Code で/doc-generatorを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

modules/
generation-guidelines.md
quality-gates.md
remediation-workflow.md

詳細

ドキュメント生成

ドキュメントのコストは、読者が費やす時間の合計です。そのコストに見合う価値を提供するか、削減しましょう。

具体的な主張に基づき、要点を冒頭に置き、すべての文に価値があるドキュメントを作成します。「目まぐるしく変化する現代社会では」のような埋め草や、根拠のない「徹底的」「包括的」といった曖昧な形容は冗長です。ドキュメントの要点を伝えたり、例示したり、範囲を定めたり、繰り返したりしない文も同様です。

このスキルは、文単位の簡潔さ（冗長な語彙、ダッシュの多用、おべっかを使う書き出しを避けること）と、ドキュメント全体の簡潔さ（要点を先に示し、すべての文に意味を持たせ、要点の繰り返しだけを認めること）の両方を徹底します。基準の全文については、Skill(scribe:slop-detector) モジュール document-economy.md を参照してください。

使用しない場合

  • 外部ファイルを Markdown に変換する場合（leyline:document-conversion とその project-import モジュールを使用してください）
  • 既存の文章に AI らしいパターンがないか調べる場合（scribe:slop-detector を使用してください）

執筆の基本原則

能動態を使い、執筆者の視点を示します。中立的な定型文を並べるのではなく、技術的な選択の理由（なぜ別のデータベースではなく、このデータベースなのか）を説明します。短く、並列的にまとめる場合に限って、箇条書きを控えめに使います。複数行にわたる長い箇条書きは文章にまとめ、論理の流れが伝わるようにします。

語彙とスタイル

ビジネス用語や、文構造の反復、ダッシュの多用といった言葉遣いの癖は避けます。ドックストリングには命令形を使います（「入力を検証する」であって、「入力を検証します」ではありません）。生きていないものを人間のように表現しないでください（「コードが望んでいる」「関数が語りかける」など）。

避ける表現使う表現
フォールバックデフォルト、代替
活用する使う
利用する使う
促進する助ける、可能にする
包括的徹底的、完全な
9. 擬人化表現を制限する

「〜の下にある」「〜に語りかける」などの表現が意味をなすのは、生き物に対してだけです。

10. ドックストリングには命令形を使う

「検証する」であって、「検証します」ではありません（PEP 257、pydocstyle、ruff に準拠）。

必須の TodoWrite 項目

  1. doc-generator:scope-defined - 対象ファイルと種類を特定済み
  2. doc-generator:style-loaded - スタイルプロファイルを適用済み（利用可能な場合）
  3. doc-generator:content-drafted - 初稿を作成済み
  4. doc-generator:slop-scanned - AI らしい表現を確認済み
  5. doc-generator:quality-verified - 原則のチェックリストに合格済み
  6. doc-generator:user-approved - 最終承認を受領済み

モード：生成

新しいドキュメントを作成する場合：

ステップ 1：対象範囲を定める
## Generation Request

**Type**: [README/Guide/API docs/Tutorial]
**Audience tier**: [newcomer | practitioner | expert | persona: <one line>]
**Audience**: [developers/users/admins]
**Audience size**: [1 / small team / org / public]
**Read frequency**: [once / weekly / per-invocation]
**Thesis**: [one sentence the reader must walk away with]
**Length target**: [~X words or sections]
**Style profile**: [profile name or "default"]

要点の項目は必須です。要点を一文で述べられない場合、対象範囲はまだ定まっていません。読者数と閲覧頻度は、読者の時間予算に影響します（scribe:slop-detector モジュール document-economy.md を参照）。50 人が毎日読み込むスキルと、1 対 1 の設計メモでは、時間予算が大きく異なります。

読者層も必須です。依頼に記載がない場合は、推測せずに質問してください。読者を推測すると、有能そうに見えても誰の役にも立たないドキュメントになります。読者層の表、読者層を聞き出すためのソクラテス式質問、創作執筆に関する例外については、scribe:slop-detector モジュール audience-targeting.md を参照してください。

読者層によって、初稿に残す内容が決まります。

層残す内容詳細説明に回す内容
newcomer最初から最後まで機能する唯一の手順内部実装、歴史、検討した代替案
practitionerリポジトリ固有で、読者が自力では導き出せない事実一般分野の解説
expert新規性のある主張と、その数値なし。詳細説明はこちらに含めます
ステップ 2：スタイルを読み込む（利用可能な場合）

スタイルプロファイルがある場合：

cat .scribe/style-profile.yaml

文体、語彙、構成のガイドラインを適用します。

ステップ 3：コンテンツの下書き

主張を先に示します。 最初の段落で、伝えたい要点をひとつだけ述べます。読者が冒頭を読んだところで読むのをやめても、メッセージが伝わるようにします。本文で主張を一度、締めくくりで一度繰り返します。それ以外の繰り返しはすべて削ります。

上記の10の基本原則に従います。各セクションでは、次のようにします。

  1. 最も重要な情報から始めます（主張、またはその明確な具体例を述べます）
  2. 価値がある場合に限り、背景情報を加えます（主張を支えるか、具体化するか、範囲を定めるかを確認します）
  3. 具体例を使います（1つは証拠、2つは強調、3つは水増しです）
  4. 箇条書きより文章を優先します
  5. 情報がそろったら終えます（要約で水増しせず、「結論として」のように言い換えて繰り返しません）

各セクションにカットテストを適用し、宣言したティアと照らし合わせます。 読者が行動する前に必要な情報は残し、後から必要になる情報はリンクし、より上位のティアだけが求める情報は別途切り出し、どのティアにも不要な情報は削除します。別途切り出すという判断が見過ごされがちです。newcomerが使えないコンテンツは、たいてい質が低いのではなく、まだ尋ねていない質問に答えているのです。スキルの場合はmodules/<topic>.mdへ、リポジトリのドキュメントの場合はdocs/deep-dive/<topic>.mdへ移し、親ページの冒頭からリンクします。ティアに合わせるために削除してはいけません。

ステップ 4：Slop Detector を実行
uv run --with pyyaml python scripts/slop_score.py --audit <files>

Skill(scribe:slop-detector)

このスクリプトは、ファイル名と行番号を添えてすべての検出箇所を特定します。マージゲートで評価されない、信頼度の低いカテゴリやオプトインカテゴリも含まれます。各箇所の書き換え方法はスキルに記載されています。次に進む前に検出箇所を修正し、(low)と(medium)の検出箇所は人が判断できるよう残します。

ステップ 5：品質ゲート

チェックリストに照らして確認します。

文レベル：

  • ティア1のスロップ語がない
  • 1000語あたりのダッシュ（—）の数が3未満
  • 箇条書きの割合が40％未満
  • すべての主張に具体的な根拠がある
  • 型どおりの書き出しや締めくくりがない
  • 執筆者の視点が示されている
  • 絵文字がない（明示的に求められた場合を除く）

ドキュメントレベル（document-economy モジュール）：

  • 冒頭で主張をひとつ、明確に述べている（2/2）
  • 文の80％超が、主張を支える、具体化する、範囲を定める、または繰り返している（2/2）
  • 主張を少なくとも3回繰り返し、主張以外の繰り返しを削っている（2/2）
  • 執筆時間がおおむね（対象読者の規模 × 読む頻度 × 1回あたりの読書時間）に比例している

対象読者（audience-targeting モジュール）：

  • ティアを宣言しており、依頼で指定されていない場合は推測せずに確認している（2/2）
  • すべてのセクションが宣言したティアに役立つ
  • ティアに合わないコンテンツを削除せず、別途切り出してリンクしている
  • 新たに作成した各詳細解説で、そのティアを宣言している

モード：修正

既存のコンテンツを整える場合：

読み込み：@modules/remediation-workflow.md

ステップ 1：現状を分析
# Get slop score
Skill(scribe:slop-detector) --target file.md
ステップ 2：セクション単位で進める

ファイルが大きい場合（200行超）は、段階的に編集します。

## Section: [Name] (Lines X-Y)

**Current slop score**: X.X
**Issues found**: [list]

**Proposed changes**:
1. [Change 1]
2. [Change 2]

**Before**:
> [current text]

**After**:
> [proposed text]

Proceed? [Y/n/edit]
ステップ 3：意図を維持

変更してよいのは「どのように」伝えるかだけで、「何を」伝えるかは変えません。意味が不明瞭な場合は、質問してください。

ステップ 4：再確認

編集後、改善を確認するために slop-detector を再実行します。

Docstring 固有のルール

コードコメントを編集する場合：

  1. 変更するのは docstring／コメントのテキストのみ
  2. 周囲のコードは変更しない
  3. 命令形を使う（「入力を検証する」。 「入力を検証します」ではありません）
  4. 簡潔にする。水増し表現を削除します
  5. Args／Returns の構造がある場合は維持する

モジュールの参照先

  • コンテンツ作成のパターンについては、modules/generation-guidelines.mdを参照してください
  • 検証基準については、modules/quality-gates.mdを参照してください

他のスキルとの連携

スキル使用するタイミング
slop-detector下書きの作成後、承認前
style-learner生成前にプロファイルを読み込むとき
sanctum:doc-updatesより広範なドキュメントのメンテナンス

終了条件

  • コンテンツが作成または修正されている
  • スロップスコアが 1.5 未満（クリーン評価）
  • リクエストで対象読者のレベルが宣言され、ドラフトに反映されている
  • 文書の簡潔さのスコアが 7/8 以上で、対象読者への適合度が 2/2
  • すべての抽出内容が modules/ または docs/deep-dive/ に配置され、 親ドキュメントの冒頭からリンクされている
  • 品質ゲートのチェックリストに合格している
  • ユーザーの承認を受けている
  • 絵文字が含まれていない（指定がある場合を除く）

コメント

Markdown 対応