doc-coauthoring

ドキュメント共同執筆ワークフロー

このスキルでは、ユーザーが共同でドキュメントを作成するための構造化されたワークフローを提供します。コンテキストの収集、推敲と構成、読者テストの3つの段階を通して、積極的にユーザーを案内してください。

実行時の前提条件

コネクター、アーティファクト、読者テスト用サブエージェントを提案する前に、現在の環境で何が利用できるかを判断するため、references/RUNTIME-MATRIX.md を参照してください。

アーティファクトのような機能を利用できない場合は、ユーザーが指定したパスにある通常の Markdown ファイル、または明示的に指定された作業ファイルをデフォルトとして使用してください。アーティファクトが利用できると決めつけないでください。

このワークフローを提案するタイミング

トリガー条件:

• ユーザーがドキュメントの作成について言及している場合：「ドキュメントを書いて」「提案書をドラフトして」「仕様書を作成して」「まとめて」
• ユーザーが特定のドキュメントの種類について言及している場合：「PRD」「設計ドキュメント」「決定事項ドキュメント」「RFC」
• ユーザーが本格的な執筆作業を始めようとしていると思われる場合

最初の提案: ドキュメントを共同執筆するための構造化されたワークフローをユーザーに提案してください。次の3つの段階について説明します。

1. コンテキストの収集：ユーザーが関連するコンテキストをすべて提供し、Claude が確認の質問をします
2. 推敲と構成：ブレインストーミングと編集を通じて、各セクションを段階的に作成します
3. 読者テスト：他の人に読んでもらう前に、コンテキストのない新しい Claude にドキュメントを読ませ、見落としを見つけます

この方法により、他の人が読むとき（ドキュメントを Claude に貼り付ける場合も含めて）にうまく機能するよう、ドキュメントの品質を確保できると説明してください。このワークフローを試すか、自由な形式で進めるかをユーザーに尋ねてください。

ユーザーが断った場合は、自由な形式で進めてください。ユーザーが承諾した場合は、ステージ1に進んでください。

ステージ1：コンテキストの収集

目標： ユーザーが知っていることと Claude が知っていることの差を埋め、後の段階で適切な案内ができるようにします。

最初の質問

まず、ドキュメントのメタコンテキストについてユーザーに尋ねてください。

1. どのような種類のドキュメントですか？（例：技術仕様書、決定事項ドキュメント、提案書）
2. 主な読者は誰ですか？
3. 読んだ人にどのような影響を与えることを目指していますか？
4. 従うべきテンプレートや特定の形式はありますか？
5. ほかに把握しておくべき制約やコンテキストはありますか？

簡潔に回答しても、答えやすい形で情報をまとめて提供してもよいと伝えてください。

ユーザーがテンプレートを提供した場合、またはドキュメントの種類について言及した場合：

• 共有できるテンプレートドキュメントがあるか尋ねてください
• 共有ドキュメントへのリンクが提供された場合は、適切なインテグレーションを使って取得してください
• ファイルが提供された場合は、その内容を読み取ってください

ユーザーが既存の共有ドキュメントの編集について言及した場合：

• 適切なインテグレーションを使って現在の内容を読み取ってください
• 代替テキストのない画像がないか確認してください
• 代替テキストのない画像がある場合、他の人が Claude を使ってドキュメントを理解しようとしても、その画像は見られないことを説明してください。代替テキストを生成するか尋ねてください。希望する場合は、画像の説明的な代替テキストを生成するため、各画像をチャットに貼り付けてもらってください。

情報の一括共有

最初の質問に回答したら、ユーザーに手元にあるコンテキストをすべて共有してもらうよう促します。次のような情報を求めてください。

• プロジェクトや問題の背景
• 関連するチーム内の議論や共有ドキュメント
• 代替ソリューションを採用していない理由
• 組織的な背景（チームの力学、過去のインシデント、政治的な事情）
• スケジュール上のプレッシャーや制約
• 技術アーキテクチャや依存関係
• ステークホルダーの懸念

情報を整理する必要はないと伝え、とにかくすべて共有してもらいます。コンテキストを提供する方法を複数提示してください。

• 思いつくままに情報を一括共有する
• 確認してほしいチームのチャンネルやスレッドを示す
• 共有ドキュメントへのリンクを提示する

インテグレーションが利用できる場合（Slack、Teams、Google Drive、SharePoint、その他の MCP サーバーなど）、それらを使ってコンテキストを直接取得できることを伝えます。

インテグレーションが検出されず、Claude.ai または Claude アプリを使用している場合： Claude の設定でコネクタを有効にすれば、メッセージングアプリやドキュメントストレージからコンテキストを直接取得できることを提案します。

最初の情報共有が終わったら、明確化のための質問をすることを伝えます。

コンテキストを収集している間：

• ユーザーがチームのチャンネルや共有ドキュメントに言及した場合：

  • インテグレーションが利用できる場合：これから内容を確認すると伝え、適切なインテグレーションを使用します
  • インテグレーションが利用できない場合：アクセスできないことを説明します。Claude の設定でコネクタを有効にするか、関連する内容を直接貼り付けるよう提案します。

• ユーザーが不明な組織やプロジェクトに言及した場合：

  • 接続済みのツールを検索して詳細を確認するか尋ねます
  • 検索する前にユーザーの確認を待ちます

• ユーザーがコンテキストを提供するたびに、把握できたことと、まだ不明なことを記録します

明確化のための質問：

ユーザーが最初の情報共有を終えたと示したとき（または十分なコンテキストが提供された後）に、理解を確かなものにするための明確化の質問をします。

コンテキストの不足箇所に基づいて、番号付きの質問を5〜10個作成します。

回答には省略形を使ってもよいこと（例：「1：はい、2：#channel を参照、3：後方互換性のため不可」）、ドキュメントへのリンクを共有したり、確認してほしいチャンネルを示したり、情報共有を続けたりしてもよいことを伝えます。最も効率的な方法を選んでもらいます。

終了条件： 質問を通じて理解が示され、基礎的な事項の説明を求めなくても、エッジケースやトレードオフについて質問できる段階に達したら、十分なコンテキストが集まったと判断します。

次の段階への移行： この段階で追加のコンテキストがあるか、またはドキュメントの作成に進む準備ができているかを尋ねます。

ユーザーが追加を希望する場合は、その内容を受け取ります。準備ができたら、ステージ2に進みます。

ステージ 2：洗練と構成

目標： ブレインストーミング、取捨選択、反復的な改善を通じて、セクションごとにドキュメントを作成します。

ユーザーへの指示： ドキュメントをセクションごとに作成していくことを説明します。各セクションでは、次の手順を進めます。

1. 含める内容について確認の質問をします
2. 5～20 個の案をブレインストーミングします
3. 残す項目、削除する項目、統合する項目をユーザーに選んでもらいます
4. セクションの草案を作成します
5. 細部を慎重に編集しながら改善します

不明点が最も多いセクション（通常は中心となる決定事項や提案）から始め、その後、残りのセクションに取り組みます。

セクションの順序：

ドキュメントの構成が明確な場合： どのセクションから始めたいかを尋ねます。

不明点が最も多いセクションから始めることを提案します。意思決定ドキュメントの場合は、通常、中心となる提案です。仕様書の場合は、一般に技術的なアプローチです。要約セクションは最後に作成するのが最適です。

必要なセクションがわからない場合： ドキュメントの種類とテンプレートに基づき、その種類に適したセクションを 3～5 個提案します。

この構成で問題ないか、調整したい点があるかを尋ねます。

構成が合意されたら：

すべてのセクションにプレースホルダーテキストを入れた、ドキュメントの初期構成を作成します。

アーティファクトを利用できる場合： create_file を使用してアーティファクトを作成します。これにより、Claude とユーザーの両方が作業に使える土台ができます。

すべてのセクションにプレースホルダーを入れた初期構成を作成することを伝えます。

すべてのセクション見出しと、「[作成予定]」や「[ここに内容を記載]」のような簡潔なプレースホルダーテキストを含むアーティファクトを作成します。

土台へのリンクを提示し、各セクションの内容を埋めていく段階であることを伝えます。

アーティファクトを利用できない場合： 作業ディレクトリに Markdown ファイルを作成します。適切な名前を付けます（例：decision-doc.md、technical-spec.md）。

すべてのセクションにプレースホルダーを入れた初期構成を作成することを伝えます。

すべてのセクション見出しとプレースホルダーテキストを含むファイルを作成します。

ファイル名を伝え、各セクションの内容を埋めていく段階であることを伝えます。

各セクションについて：

ステップ 1：確認の質問

[SECTION NAME] セクションに取り組み始めることを伝えます。何を含めるべきかについて、確認の質問を 5～10 個します。

セクションの目的と文脈に基づいて、具体的な質問を 5～10 個作成します。

簡潔な回答でも、重要な点を示すだけでもよいことを伝えます。

ステップ 2：ブレインストーミング

[SECTION NAME] セクションについて、複雑さに応じて含める内容の候補を 5～20 個ブレインストーミングします。次の点を探します。

• 共有されていたものの、忘れられている可能性のある背景情報
• まだ触れられていない観点や考慮事項

セクションの複雑さに応じて、候補を 5～20 個、番号付きで提示します。最後に、追加の候補が必要なら、さらにブレインストーミングできることを伝えます。

ステップ 3：取捨選択

どの項目を残すか、削除するか、統合するかを尋ねます。次のセクションでも優先事項を把握できるよう、簡単な理由も添えてもらいます。

次のような例を示します。

• 「1、4、7、9 を残す」
• 「3 を削除（1 と重複）」
• 「6 を削除（対象読者はすでに知っている）」
• 「11 と 12 を統合」

ユーザーが番号で選ぶ代わりに自由形式でフィードバックをした場合（例：「よさそうです」や「ほとんど気に入りましたが……」）、その希望をくみ取って進めます。残したい点、削除したい点、変更したい点を整理して反映します。

ステップ 4：不足点の確認

選択された内容に基づいて、[SECTION NAME] セクションに含めるべき重要な内容で、まだ不足しているものがないか尋ねます。

ステップ 5：草案の作成

str_replace を使用して、このセクションのプレースホルダーテキストを実際に作成した内容に置き換えます。

選択内容に基づいて、[SECTION NAME] セクションの草案を作成することを伝えます。

アーティファクトを使用する場合： 草案を作成した後、アーティファクトへのリンクを提示します。

内容に目を通し、変更したい点を伝えるよう依頼します。具体的に伝えると、次のセクションでの学習に役立つことを説明します。

ファイルを使用する場合（アーティファクトなし）： 作成が完了したことを伝えます。

[filename] に [SECTION NAME] セクションの草案を作成したことを伝え、内容に目を通して変更したい点を知らせるよう依頼します。具体的に伝えると、次のセクションでの学習に役立つことを説明します。

ユーザーへの重要な指示（最初のセクションの草案作成時に含める）： ドキュメントを直接編集するのではなく、変更したい点を伝えるよう依頼する注意書きを加えます。そうすることで、今後のセクションに向けてユーザーの文体を学習できます。たとえば、「X の箇条書きを削除してください。Y ですでに説明されています」や「3 段落目をもっと簡潔にしてください」のように伝えてもらいます。

ステップ 6：反復的な修正

ユーザーからフィードバックがあった場合：

• str_replace を使用して編集します（ドキュメント全体を再出力しないでください）。
• アーティファクトを使用している場合： 編集のたびにアーティファクトへのリンクを提示します。
• ファイルを使用している場合： 編集が完了したことだけを伝えます。
• ユーザーがドキュメントを直接編集して内容を確認するよう依頼した場合は、編集内容を把握し、今後のセクションに反映します（ユーザーの好みを示すことにつながります）。

ユーザーがセクションに満足するまで、修正を続けます。

品質チェック

実質的な変更がない状態で 3 回連続してやり取りした後、重要な情報を損なわずに削除できる内容があるか尋ねます。

セクションが完成したら、[SECTION NAME] が完了したことを伝え、次のセクションに進んでよいか尋ねます。

すべてのセクションで繰り返します。

完了間近

セクションの 80% 以上が完成した段階で、ドキュメント全体を読み直し、次の点を確認することを伝えます。

• セクション間の流れと一貫性
• 重複や矛盾
• 「粗雑な文章」や一般的すぎる埋め草に感じる箇所
• すべての文に意味があるか

ドキュメント全体を読み、フィードバックを提示します。

すべてのセクションの草案作成と修正が完了したら： すべてのセクションの草案が完成したことを伝えます。ドキュメント全体をもう一度確認する意向を示します。

全体の一貫性、流れ、網羅性を確認します。

最終的な提案があれば提示します。

リーダーテストに進む準備ができているか、またはほかに修正したい点があるか尋ねます。

ステージ 3：リーダーテスト

目標： 新しい Claude（会話の文脈を引き継がない状態）でドキュメントをテストし、読者にとって実用的か確認します。

ユーザーへの指示： ドキュメントが読者にとって実際に役立つか確認するため、テストを行うことを説明します。これにより、作成者には明らかでも、ほかの人にはわかりにくい点など、見落としを見つけられます。

テスト方法

サブエージェントを利用できる場合（例：Claude Code）：

ユーザーの関与なしに、テストを直接実施します。

ステップ 1：読者の質問を予測する

読者がこのドキュメントを探す際にどのような質問をするか予測することを伝えます。

読者が実際に尋ねそうな質問を 5〜10 個作成します。

ステップ 2：サブエージェントでテストする

これらの質問を、新しい Claude インスタンス（この会話の文脈なし）でテストすることを伝えます。

各質問について、ドキュメントの内容と質問だけを渡してサブエージェントを呼び出します。

Reader Claude が各質問に正しく答えた点と、誤った点を要約します。

ステップ 3：追加チェックを実施する

追加チェックを実施することを伝えます。

曖昧さ、誤った前提、矛盾がないか、サブエージェントに確認させます。

見つかった問題を要約します。

ステップ 4：報告して修正する

問題が見つかった場合： Reader Claude が特定の問題でつまずいたことを報告します。

具体的な問題を列挙します。

これらの不足を修正することを伝えます。

問題のあるセクションの修正に戻ります。

---

サブエージェントを利用できない場合（例：claude.ai のウェブインターフェース）：

ユーザーが手動でテストする必要があります。

ステップ 1：読者の質問を予測する

このドキュメントを見つけようとしている人が、どのような質問をするか考えてください。Claude.ai には何と入力するでしょうか？

読者が実際に尋ねそうな質問を 5～10 個生成してください。

ステップ 2：テストの準備

テスト手順を提示してください。

1. 新しい Claude の会話を開きます：https://claude.ai
2. ドキュメントの内容を貼り付けるか共有します（コネクターが有効な共有ドキュメントプラットフォームを使用している場合は、リンクを提示します）。
3. Reader Claude に、生成した質問を尋ねます。

質問ごとに、Reader Claude に次の内容を回答するよう指示してください。

• 回答
• 曖昧または不明瞭な点があったかどうか
• このドキュメントが、すでに知っていることを前提としている知識やコンテキスト

Reader Claude が正しく回答しているか、誤解している点がないか確認してください。

ステップ 3：追加の確認事項

Reader Claude に、次の質問もしてください。

• 「このドキュメントで、読者にとって曖昧または不明瞭な可能性がある箇所はどこですか？」
• 「このドキュメントは、読者がすでにどのような知識やコンテキストを持っていると想定していますか？」
• 「内部に矛盾や不一致はありますか？」

ステップ 4：結果に基づいて反復する

Reader Claude が何を誤解したか、または何に苦労したかを確認してください。そうした不足を修正する意図を伝えてください。

問題のあるセクションについて、改善を繰り返してください。

---

完了条件（両方のアプローチ）

Reader Claude が一貫して質問に正しく回答し、新たな不足や曖昧さを指摘しなくなったら、ドキュメントの準備は完了です。

最終レビュー

読者テストに合格したら： ドキュメントが Reader Claude のテストに合格したことを伝えてください。完了する前に：

1. 最終確認として、本人がドキュメントを読み返すことを勧めてください。ドキュメントの責任者は本人であり、品質にも責任があるためです。
2. 事実、リンク、技術的な詳細を再確認するよう提案してください。
3. ドキュメントが意図した効果を実現しているか確認するよう依頼してください。

もう一度レビューするか、作業を完了するか尋ねてください。

ユーザーが最終レビューを希望する場合は実施してください。そうでない場合は： ドキュメントが完成したことを伝えてください。最後に、次のヒントをいくつか提示してください。

• 読者がドキュメントの作成過程を確認できるよう、この会話を付録にリンクすることを検討してください。
• 本文を膨らませずに詳しい情報を提供するには、付録を活用してください。
• 実際の読者からフィードバックが寄せられたら、ドキュメントを更新してください。

効果的なガイダンスのヒント

トーン：

• 直接的で、手順に沿って説明してください。
• ユーザーの行動に影響する場合は、その理由を簡潔に説明してください。
• このアプローチを「売り込もう」とせず、ただ実行してください。

逸脱への対応：

• ユーザーがステージを省略したい場合は、このステージを省略して自由形式で書くか尋ねてください。
• ユーザーがいら立っているようなら、想定より時間がかかっていることを認めてください。より早く進める方法を提案してください。
• 常に、プロセスを調整する選択権をユーザーに与えてください。

コンテキストの管理：

• 会話の中で言及された内容のコンテキストが不足している場合は、その都度、先回りして確認してください。
• 不足を積み重ねず、発生した時点で対処してください。

成果物の管理：

• セクション全体の草案作成には create_file を使用してください。
• 編集にはすべて str_replace を使用してください。
• 変更のたびに成果物へのリンクを提示してください。
• ブレインストーミングのリストには成果物を使用しないでください。会話内で扱ってください。

速さより品質を優先：

• ステージを急いで進めないでください。
• 各反復で、意味のある改善を行ってください。
• 目標は、読者にとって実際に役立つドキュメントにすることです。

参考ファイル

必要なものだけを読み込んでください。

• references/RUNTIME-MATRIX.md - Claude Code、Claude.ai、コネクターが豊富な環境、コネクターが限られた環境に合わせてワークフローを調整する方法
• references/DOC-TYPES.md - 一般的なドキュメントタイプのデフォルトのセクション構成
• references/READER-TEST.md - 読者テストのプロンプト、引き継ぎパッケージ、合否の基準