# Brushup Doc > 指定された章のドキュメント（index.md）の文章品質を向上させ、内容を充実化する。わかりやすさ・読みやすさの改善と、説明の補足・Tips追加を行う。 Use when this capability is needed. - Skill: `tomevault-io/brushup-doc` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/brushup-doc` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/brushup-doc/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/brushup-doc --- # ドキュメントブラッシュアップスキル 指定された章のドキュメント（`index.md`）の文章品質を向上させ、内容をより充実したものにする。 ## 手順 ### Step 1: 対象ファイルの特定 1. `$ARGUMENTS` から章番号またはドキュメントパスを判定する - `chapter3` や `3` → `packages/@ai-suburi/docs/docs/chapter3/index.md` - フルパスが渡された場合はそのまま使用 2. 対応するソースコードディレクトリを特定する（例: `packages/@ai-suburi/core/chapter3/`） ### Step 1.5: ブラッシュアップ対象範囲の判定 対象ドキュメントに未コミットの変更差分があるかを確認し、ブラッシュアップの対象範囲をユーザーに確認する。 1. `git diff <対象ファイルパス>` および `git diff --cached <対象ファイルパス>` を実行し、未コミットの変更差分を確認する 2. 変更差分が**ある**場合 → `AskUserQuestion` でユーザーに対象範囲を確認する - 選択肢: - **変更差分のみ**: 差分に含まれるセクションだけをブラッシュアップする - **ドキュメント全体**: ドキュメント全体を対象にブラッシュアップする 3. 変更差分が**ない**場合 → ドキュメント全体を対象として続行する **「変更差分のみ」が選択された場合の動作:** - `git diff` の出力から、変更が含まれるセクション（`##` 見出し単位）を特定する - Step 3 以降のチェック・改善は、特定されたセクションのみを対象とする - まとめ・参考文献セクションは、変更セクションに関連する部分のみ確認する ### Step 2: ドキュメントとソースコードの読み込み 1. ドキュメントファイル（`index.md`）を読み込む - Step 1.5 で「変更差分のみ」が選択された場合は、対象セクションとその前後のセクションを読み込む 2. 対応するソースコードディレクトリ内の全 `.ts` ファイルを `Glob` で列挙し、各ファイルを読み込む - 「変更差分のみ」の場合は、対象セクションで参照されているソースコードのみ読み込む 3. ドキュメント全体のセクション構成を把握する ### Step 3: 概念・トピックの網羅性チェック ドキュメント内で**名前だけ言及されているが詳しく解説されていない概念**がないか確認する。 #### 3-1. サマリーテーブルとの整合性 概要テーブルや一覧表に名前が挙がっている概念・手法それぞれに対して、独立した解説セクション（見出し + 説明 + コード例）が存在するか確認する。 - テーブルにのみ記載があり詳細セクションがない場合 → 解説セクションの追加を検討する - 例: 「CoT / ToT / ReAct」がテーブルに並んでいるのに、ReAct だけ詳しく書いてある → CoT と ToT にも解説セクションを追加する #### 3-2.「なぜ必要か（Why）」の確認 各主要セクションに「なぜこの機能・手法が必要なのか？」「どういう問題を解決するのか？」の説明があるか確認する。 - 「何ができるか（What / How）」だけ書かれていて「なぜ必要か（Why）」が欠けている場合 → 冒頭に動機づけの説明を追加する - いきなり実装コードに飛んでいる場合 → コードの前に概念説明や背景を追加する #### 3-3. 概念間のつながり 関連する概念同士のつながりが明示されているか確認する。 - 前のセクションで説明した概念が後のセクションの基盤になっている場合 → 「前述の○○の仕組みを活用しています」のようなリンクを追加する - 例: 「ReAct の Thought 部分は CoT による推論そのもの」「messages 配列の蓄積は短期メモリの仕組み」 - 類似概念が複数ある場合 → 「○○との違い」や比較テーブルで関係性を整理する ### Step 4: 図解・ビジュアルの改善 #### 4-1. ASCII 図から mermaid への変換 ドキュメント内の ` ```plaintext ` による ASCII アート図（フローチャート、サイクル図、ツリー構造など）を見つけた場合、mermaid 記法に変換することを検討する。 - フローチャート → `flowchart TD` または `flowchart LR` - サイクル図（ループ） → `graph LR` で循環を表現 - シーケンス図 → `sequenceDiagram` - 木構造 → `graph TD` **変換時の注意点:** - 元の図に含まれていたラベル・注釈・補足テキストが**すべて mermaid 側に反映されているか**必ず確認する。フォーマット変換時に情報が欠落しやすいため特に注意すること - ノードのテキストには `
` で改行を入れ、簡潔な補足説明を添えると理解しやすくなる - 矢印にラベルを付けることで、遷移の意味を明確にする（例: `-- "結果を踏まえて次へ" -->`） **mermaid 図作成時のハマりどころ:** - **改行は `
` を使う**: `flowchart` / `graph` のノードテキストでは `\n` が改行として解釈されず、そのまま表示される。必ず `
` を使うこと - **`block-beta` は避ける**: ブロックのラベルが内部要素と重なりやすく、レイアウトが崩れやすい。代わりに `flowchart` + `subgraph` を使う - **`linkStyle N` は使わない**: リンクインデックスのズレで `Cannot set properties of undefined (setting 'style')` エラーが発生しやすい。矢印を非表示にしたい場合は `~~~`（非表示リンク）を使う - **サブグラフの並び方を制御する**: 独立したサブグラフ同士は `~~~` で接続しないと意図した方向に並ばないことがある。`flowchart TB` で上下、`flowchart LR` で左右に並ぶが、サブグラフ間に `subgraphA ~~~ subgraphB` を明示すると確実 - **サブグラフ内のレイアウト方向**: サブグラフ内に `direction LR`（横並び）や `direction TB`（縦並び）を指定することで、内部ノードの並び方を制御できる - **括弧 `()` をノードテキストに含めない**: mermaid が構文として解釈してしまうため、`openai()` のようなテキストはエラーになる。`openai / anthropic / google` のように括弧を省略するか、HTML エンティティを使う #### 4-2. 図の新規追加 以下のケースでは mermaid 図の新規追加を検討する: - **プロセスやサイクルの説明** がテキストのみで記述されている場合 → フローチャートを追加 - **複数ステップの流れ** が箇条書きで説明されている場合 → フロー図で視覚化 - **概念間の関係性** が文章だけで説明されている場合 → グラフ図で関係を可視化 ### Step 5: 文章品質の改善 各セクションの説明文について、以下の観点で改善する: #### 5-1. わかりやすさの向上 - **専門用語の初出時に補足を追加**: 技術用語が初めて登場する箇所に、簡潔な説明やカッコ書きの補足を追加する - **抽象的な説明を具体化**: 「〜できます」のような曖昧な記述を、具体的なユースケースや例を添えた説明にする - **具体的なシナリオ例の追加**: 抽象的な説明だけでなく、読者がイメージしやすい身近な例（「来週の東京出張に傘は必要？」のような日常的なシナリオ）を追加する - **長文の分割**: 一文が80文字を超える場合、2つ以上の文に分割することを検討する - **主語と述語の明確化**: 主語が省略されて意味が曖昧になっている文を修正する #### 5-2. 読みやすさの向上 - **段落構成**: 1つの段落が5行を超える場合、適切な箇所で段落を分割する - **接続詞の改善**: 「また」「そして」の多用を避け、適切な接続表現（「具体的には」「一方で」「これにより」など）に置き換える - **箇条書きの活用**: 3つ以上の要素を列挙している文は、箇条書き形式に変換することを検討する - **冗長表現の除去**: 「〜することができます」→「〜できます」、「〜という」の不要な使用を削除するなど、冗長な表現を簡潔にする #### 5-3. 文体の統一 - ドキュメント全体で「です・ます調」を統一する - 技術ドキュメントとしてのフォーマルさを維持しつつ、教科書的な読みやすさを確保する - コードの説明に使う表現パターンを統一する（例: 「〜を定義します」「〜を指定します」） ### Step 6: 内容の充実化 各セクションについて、以下の観点で内容を追加・拡充する: #### 6-1. 概要説明の強化 - セクションの冒頭に「なぜこの機能が必要か」「どういう場面で使うか」の説明がなければ追加する - 既存の概要が1文のみの場合、2〜3文に拡充し、背景や目的を明確にする #### 6-2. コード解説の補足 - ソースコード内の重要なポイント（API呼び出し、エラーハンドリング、設定値など）について、コードブロックの前後に解説がなければ追加する - 「このサンプルでは以下を行います」の箇条書きが、実際のコードの主要な処理ステップを網羅しているか確認し、不足があれば追加する - コード内の重要なパラメータや設定値について、選択理由や推奨値の説明を追加する - 1つの概念に複数のバリエーション（例: Zero-shot / Few-shot）がある場合、それぞれの実装例を用意することを検討する #### 6-3. 比較・対照の追加 - 類似する概念や手法がある場合、**比較テーブル**で違いや使い分けを整理する - 例: CoT vs ToT vs ReAct の比較（得意なこと / 限界 / API コール数 / 適したタスク） - 例: 自己評価 vs Reflexion vs 外部フィードバック の比較（コスト / 適した場面） - 前のセクションとの関連性を示すつなぎの文章を追加する - 類似概念を列挙するだけでなく「どういう場面でどれを選ぶか」の判断基準を明示する #### 6-4. Tips・注意事項の追加 - 実装時にハマりやすいポイントがあれば `:::caution` アドモニションで追加する - 便利なテクニックや代替手法があれば `:::tip` アドモニションで追加する - 追加の背景情報や参考になる情報があれば `:::info` アドモニションで追加する - ただし、アドモニションの追加は1セクションあたり最大2つまでとし、過剰にならないようにする #### 6-5. 実行結果の例示 - サンプルコードの実行結果例がない場合、想定される出力をコードブロックで追加する ``` **実行結果の例:** \``` Response: こんにちは！今日の天気は... Total Tokens: 42 \``` ``` ### Step 7: 参考文献の拡充 - 各セクションで紹介しているAPI・ライブラリの公式ドキュメントへのリンクが参考文献セクションにあるか確認する - 不足している場合は `WebSearch` で正しいURLを確認してから追加する - リンクはセクション番号順に整理する ### Step 8: 修正の適用 発見した改善点をすべて `Edit` ツールで適用する。 ## 修正時のルール - 既存のセクション構成パターン（見出し→概要→詳細→コード→実行方法）を崩さない - コードブロックの `title` 属性は `chapter/<ファイル名>.ts` の形式を維持する - コードブロック内のソースコードは変更しない（コードの修正は `review-doc` スキルの担当） - 事実に基づかない内容は追加しない。不確実な場合はユーザーに確認を取る - 追加する内容はソースコードの実装内容と矛盾しないようにする - 1セクションの大幅な書き換えが必要な場合は、修正前にユーザーに方針を確認する - 参考文献セクションの順序は、セクション番号順に並べる - 図のフォーマットを変換する際は、元の情報（ラベル・注釈・補足）がすべて保持されていることを必ず確認する ## 出力 ブラッシュアップ完了後、以下の形式でサマリーを出力する: ``` ## ブラッシュアップ結果サマリー ### 概念・トピックの網羅性 - [ 追加したセクションや、不足を補った箇所 ] - ... ### 図解・ビジュアルの改善 - [ mermaid に変換した図や、新規追加した図 ] - ... ### 文章品質の改善 - [ 改善内容1 ] - [ 改善内容2 ] - ... ### 内容の充実化 - [ 追加内容1 ] - [ 追加内容2 ] - ... ### 参考文献の追加 - [ 追加したリンク ] - ... ### 変更していない項目 - [ 理由とともに記載 ] ### ユーザーへの提案（ある場合） - [ 提案内容（セクション分割、追加の実装例など、自動では判断しにくい改善案）] ``` --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/imamachi-n) — claim your Tome and manage your conversions.