better-documents

ドキュメントレビュー

ビジネス文書の作成やレビューでは、適切なメッセージが適切な順序で適切な読者に届くよう、コミュニケーションのベストプラクティスを適用します。

このスキルは、Anil Dash 氏のより良いドキュメントを作成するの原則を適用します。

対象範囲

このスキルの対象はビジネス文書です。プレゼンテーション、スライド資料、提案書、レポート、メモ、概要資料、1 ページ資料、メールが含まれます。UI、Web コンポーネント、フロントエンドアプリケーションは対象外です。これらには frontend-design スキルを使用してください。

ここで扱うデザイン原則は、重要な点でフロントエンドデザインとは異なります。

• 表現よりも抑制を重視します。 UI は大胆な美的判断や際立ったビジュアルの個性を活かせます。一方、ビジネス文書ではコンテンツの邪魔をしないことが大切です。取締役会向け資料や顧客への提案書を読む人の多くは、タイポグラフィを楽しむために読んでいるわけではありません。
• 読者は操作できません。 Web インターフェースでは、読者が自由に探れることが価値になります。一方、文書は一度だけ読まれ、多くの場合は流し読みされ、小さな画面で読まれたり、印刷されたりします。注意を引くデザイン上の選択はすべて、メッセージから注意を奪います。
• 非デザイナーが作成者であり、読者でもあります。 UI はデザインに関する知識が身近にある環境で作成され、利用されます。ビジネス文書は、オペレーション担当者、アナリスト、経営幹部、創業者が作成し、同じ人たちが読みます。デザイナーなら直感的に扱える複雑さも、それ以外の人にとってはノイズになります。

モード

モード	使用する場面	実施する内容
generate	「提案書を書いて」「資料を作成して」「メモの下書きを作って」	文書の作成時に 5 つの原則をすべて適用します。別途レポートを作成する必要はありません
full-review	「この文書をレビューして」「この資料を確認して」	既存の文書に対して 5 つのチェックをすべて行い、構造化されたレポートを作成します
rewrite	「これを直して」「もっと良くして」	すべてのチェックを適用し、修正版を返します
targeted	「依頼内容は明確ですか」「書式を確認して」	関連するチェックのみを行います
quick	「さっと見て」「これで問題ないか確認して」	1 と 2 のチェックのみを行い、重要な問題を 3 件指摘します

新しい文書をゼロから作成する場合は、デフォルトで generate を使用してください。指示がない状態で既存の文書が渡された場合は、デフォルトで full-review を使用してください。

---

5 つのチェック

以下の順に適用します。それぞれ異なる失敗要因を対象としています。

チェック 1 — 読者と目的

文書がうまく機能しない最も一般的な理由は、読者ではなく作成者に向けて書かれていることです。

確認項目：

• 文脈の不足：読者が知らない可能性のある知識を前提にしていませんか？説明のない専門用語、背景情報、頭字語があれば指摘します。
• 依頼事項が埋もれている：必要な依頼、決定、行動はありますか？ある場合は、文書の最後ではなく、最初の 3 分の 1 までに明確に示されていますか？
• 作成者中心の書き出し：共有できる文脈ではなく、作成者の不安、背景、経歴から始まっていませんか？該当する場合は指摘し、共通の前提から始まるよう順序を変える提案をします。
• 期限や重要性の説明不足：決定や返答が必要な場合、期限が示されていますか？その期限を設定する理由は、作成者の視点だけでなく、読者の視点から説明されていますか？

重大度の目安：

• CRITICAL — 主要な依頼や決定がない、または最後にしか示されていない
• MAJOR — 読者が不明確で、読む人によって解釈が異なる可能性がある
• MINOR — 一文を補えば解消できる文脈の不足

パス 2 — 構成と順序

順序は重要度を示します。読み手は、最初に出てくる内容が最も重要だと考えます。 そうでなければ、重要な箇所にたどり着く前に混乱したり、読む気をなくしたりする可能性があります。

以下を確認してください。

• 作成順の構成：文書は、読み手が必要とする順序（結論 → 根拠となる論理 → 次の行動）ではなく、書かれた順序（背景 → 分析 → 結論）で構成されていますか？
• ミステリー仕立ての構成：要点を最初に述べず、最後に明かす構成になっていますか？重要な結論や依頼が後半に出てくる文書には、すべてフラグを立ててください。
• 説明のない順序：文書が時系列、カテゴリー別、または重要度以外の基準で並んでいる場合、そのことが明示されていますか？そうでなければ、読み手は順序に意味を見いだそうとして迷うことになります。
• 重要情報が不適切な場所にある：重要な情報が、話者ノート、付録、脚注にしか記載されていませんか？中心となる要点は本文に記載してください。

重大度の目安：

• CRITICAL — 文書の結論または主要な依頼が後半にある
• MAJOR — 順序が分かりにくく、説明もない
• MINOR — 流れをよくするために、補足的な要点を並べ替えられる

---

パス 3 — 書式の節度

書式の過剰な使用は、考えが明確でないことが最も目に見える形で表れたものです。すべてが強調されていると、何も強調されていないのと同じです。

以下を確認してください。

• 強調の過剰使用：同じテキストに太字、斜体、下線、色が組み合わされていますか？1つの要素に2種類以上の強調が使われている箇所には、フラグを立ててください。
• リンクではない箇所の下線：ハイパーリンクではない下線すべてにフラグを立ててください。下線はクリックできることを示すためのものです。装飾として使うと、読み手を混乱させます。
• 色の氾濫：使用されている色（画像を除く）の種類を数えてください。2色を超えると、ほとんどの場合問題です。3色を超えると、必ず問題です。
• 境界線の多用：太い境界線を使った表やセクションにフラグを立ててください。コンテンツは線よりも余白で区切るほうが明確です。
• 内容を補わないビジュアル：内容のメッセージに特化していない画像、アイコン、クリップアートにフラグを立ててください。ストック写真を使うより、空白のほうが適切です。
• 書式の不統一：明確な理由もなく、文書内で見出し、タイトル、ラベルのサイズ、太さ、色にばらつきがありますか？意図的でなくても、読み手には意味があるように受け取られる不統一にフラグを立ててください。

重大度の目安：

• CRITICAL — 意味のあるシグナルとして受け取られる書式の不統一（例：文書の途中で理由なくフォントが変わる）
• MAJOR — 強調の多用により、何が本当に重要なのか判別できない
• MINOR — 意味を加えず、ノイズになる小さな装飾

---

パス 4 — 道筋と情報密度

読み手は、話のどこにいるのか、あとどれくらい読めばよいのかを知る必要があります。

以下を確認してください。

• 全体像が分からない：1ページまたは5枚を超えるスライドで構成される文書に、簡単な概要、セクション見出し、進捗マーカーなど、構成を示すものがありますか？なければフラグを立ててください。
• 要約のないデータ：タイトルやキャプションに、何を示しているかの説明がないまま、グラフ、表、データ表示が掲載されていますか？読み手が何の説明もなくデータを解釈しなければならない状態は避けてください。「このデータは何を示しているか」に答えていないタイトルのグラフや表すべてにフラグを立ててください。
• 回答できない質問：選択肢で答えられない自由回答形式の質問が、見出しやプロンプトとして文書に含まれていますか？意思決定ではなく、哲学的な議論につながりかねない質問にフラグを立ててください。良い例：「オプションAとオプションBのどちらを選びますか？」悪い例：「どうすれば改善できますか？」
• 密度が高く、切れ目のない文章：意味を損なわずに箇条書きにすると読みやすくなる、約6行を超える段落がありますか？

重大度の目安：

• CRITICAL — 解釈の手がかりがないままデータを提示している
• MAJOR — 長い文書に構成を示す手がかりがない
• MINOR — より答えやすい形にできる質問がある

---

パス 5 — 命名とバージョン管理

タイトルは情報です。多くのドキュメント名は、その情報を捨てています。

次の点を確認してください。

• 一般的すぎるタイトル、または自動生成されたタイトル：ドキュメントのタイトルが「無題」「下書き」「会議メモ」、あるいは宛先の相手の名前になっていませんか？問題として指摘し、トピック、日付、背景または所有者を含むタイトルを提案してください。
• 宛先を先にした命名：別の組織にいる相手向けのドキュメントの場合、作成者やトピックではなく、相手の名前を付けていませんか？相手は自分の名前ではなく、あなたの名前で検索します。
• バージョンの曖昧さ：ファイル名やタイトルに _v2、_final、_final_final、あるいは日付のない連番を使っていませんか？問題として指摘し、日付ベースのバージョン管理を提案してください。
• 参加者名を使った会議招待：ドキュメントが会議に関連する場合、「[Name] との会議」というタイトルの招待を問題として指摘してください。会話の目的が相手に伝わりません。

重大度の目安：

• CRITICAL — 外部共有を想定したドキュメントのタイトルが無題、または一般的すぎる
• MAJOR — 複数の下書きがあるドキュメントで、バージョンが曖昧
• MINOR — 後で見つけにくくなる可能性のある、最適ではない命名

---

出力形式

生成モード

5つすべての原則を後付けのチェックリストではなく、最初から制約として適用してドキュメントを作成してください。具体的には、次のとおりです。

• 結論または依頼は締めくくりではなく、冒頭に記載する
• 内容は、作成した順ではなく、読者にとって重要な順に並べる
• 必要最小限の書式設定にする：強調の種類は一度に1つだけにし、装飾的な下線は使わず、色は2色までとし、枠線より余白を優先する
• ドキュメントが1ページまたは5枚のスライドを超える場合は、構成を示す目印を含める
• トピック、日付、関連する背景を含むタイトルを付ける

デフォルトのビジュアルスタイルを適用しないでください。 Claude のデフォルトのドキュメントデザイン（温かみのあるクリーム色の背景、セリフ体のディスプレイ書体（Georgia、Fraunces、Playfair）、テラコッタやアンバーのアクセント、本文ブロックの上に小さなすべて大文字のラベルを置くスライドレイアウト）は、AI 生成だと分かりやすく、多くの業務用途には不適切です。これらを適用しないでください。

代わりに、ビジュアルスタイルを設定してドキュメントを作成する前に、次の手順を踏んでください。

1. まずブランドやビジュアル上の制約について尋ねます。 ユーザーにブランドカラー、テンプレート、使用するフォントはありますか？ある場合は、その指定に正確に従ってください。
2. ブランドに関する指定がない場合、ニュートラルなスタイルをデフォルトにします。白地に黒のテキスト、全体で1種類のサンセリフ書体、装飾的な色は使いません。配色ではなく、コンテンツで伝えます。
3. ユーザーがビジュアルスタイルを明示的に希望する場合、互いに異なる方向性を2～3案、各1文で提示します（例：「ニュートラル／ミニマル」「大胆／高コントラスト」「温かみのある／エディトリアル」）。先にユーザーに選んでもらってから進めてください。ユーザーに代わって選ばないでください。

生成モードではレビュー報告は不要です。原則は最初から適用されています。

---

全体レビュー・モードと対象指定モード

## Document Review: [Title or description]

### Summary
[2–3 sentences: what the document is trying to do, how well it's set up to succeed,
the one or two changes that would most improve it]

### Pass 1 — Audience and Purpose [N issues]
[Each issue: location → what the problem is → suggested fix → severity]

### Pass 2 — Structure and Sequencing [N issues]
[Same format]

### Pass 3 — Formatting Restraint [N issues]
[Same format]

### Pass 4 — Wayfinding and Density [N issues]
[Same format]

### Pass 5 — Naming and Versioning [N issues]
[Same format]

### Top 3 Changes
[The three revisions that would most improve this document's effectiveness,
ranked by impact]

書き直しモード

修正したドキュメントを返し、その後に各パスで何を変更したか、またその理由を簡潔に記してください。細かな修正を一つずつ説明する必要はありません。意味や順序を変えた構成上の判断のみを説明してください。

クイックモード

パス1と2で見つかった問題のうち、重要度の高い上位3件のみを返し、それぞれに修正案を1行で添えてください。全体のレポートは不要です。

---

制約

• 著者の語り口を変えないでください。 レビューおよび書き直しモードでは、スタイルではなく、構成と明瞭さを改善してください。明快で効果的な文はそのままにしてください。
• 内容を創作しないでください。 情報（期限、選択肢、対象読者に関する背景など）が不足している場合は、その不足を指摘し、補わないでください。
• 対象読者が不明な場合は、生成する前に質問してください。 生成モードでは、誰が文書を読むのか、また文書によってどのような判断を促す必要があるのかが指定されていない場合は、執筆する前に質問してください。どれほど構成が優れていても、対象読者を誤った文書は役に立ちません。
• 具体的にしてください。 指摘にはすべて、実際の文章または箇所を示してください。どこをどう明確にするのかを示さずに、「明確にすることを検討してください」とだけ述べないでください。
• 意図的な選択を尊重してください。 文書が明示的に物語形式やミステリー形式の企画書である場合、構成上の慣例を違反としてではなく、リスクとして指摘してください。

---

Anil Dash による より良い文書を作成する に基づいています。