coauthoring-docs

ドキュメント共同作成ワークフロー

このスキルは、ユーザーと協力してドキュメントを作成するための、体系的なワークフローを提供します。積極的にガイド役を務め、「コンテキストの収集」「推敲と構成」「読者テスト」の3つの段階を進めます。

概要

基本原則： ユーザーはコンテキストを把握しており、あなたは構成を把握しています。このワークフローでは、ユーザーのコンテキストを効率よく共有してもらい、その後、ドキュメントをセクションごとに作成します。これにより、ユーザーが関わっていない大量の文章を確認する必要がなくなります。

3つの段階がある理由：

段階	解決する課題
1. コンテキストの収集	組織のコンテキストを把握していないため、もっともらしく聞こえるものの誤った内容を書いてしまうこと
2. 推敲と構成	ユーザーが完成した草案を受け取り、何を変更すべきかを後から読み解かなければならないこと
3. 読者テスト	作成者には理解できるドキュメントが、ほかの人には理解しにくいこと

最も省略されがちで、最も多くの問題を発見できるのは段階3です。書いた人にとって完璧に読めるドキュメントは、あらゆるドキュメント作成における典型的な失敗パターンです。

チェックリスト

各項目についてTODOを作成します。段階は順番に進めます。段階2では、各セクションについての作業を繰り返します。

1. ワークフローを提案する — 合意を得るか、自由形式で進める
2. 段階1：メタ質問 — 種類、対象読者、望ましい影響、テンプレート、制約
3. 段階1：情報の洗い出し — ユーザーに頭の中の情報をすべて出してもらう。整理するために話を遮らない
4. 段階1：明確化の質問 — 番号付きの、簡潔に回答できる質問を5～10個する
5. 段階2：構成に合意する — その後、すべてのセクションにプレースホルダーを設けたファイルを作成する
6. 段階2：セクションごとの作業 — 質問 → アイデア出しを5～20個 → ユーザーが選別 → 不足点の確認 → 草案作成 → 推敲
7. 段階2：ドキュメント全体の確認 — 流れ、重複、矛盾、冗長な記述を確認する
8. 段階3：読者テスト — コンテキストを持たない新しいエージェントが、想定される読者の質問に回答する
9. 段階3：不足点を修正する — 問題がなくなるまで繰り返す
10. 最終レビュー — ドキュメントの主導権をユーザーに戻す

完了条件

各段階には、完了を判断するための具体的なテストがあります。完了したように感じても、次の段階へ進まないでください。

段階	完了条件
1	基本事項の説明を求めずに、例外的なケースやトレードオフについて質問できる
2	3回連続の反復で、実質的な変更が発生しない
3	コンテキストを持たない新しいエージェントが、想定される読者の質問に正しく回答し、新たな曖昧さを指摘しない

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

開始条件：

• ユーザーがドキュメントの作成に言及した場合：「ドキュメントを書いて」「提案書を草案にして」「仕様書を作成して」「文書にまとめて」
• ユーザーが特定のドキュメントの種類に言及した場合：「PRD」「設計書」「意思決定書」「RFC」
• ユーザーが本格的な文章作成に取りかかろうとしているように見える場合

最初の提案： ドキュメントを共同作成するための体系的なワークフローをユーザーに提案します。次の3つの段階を説明します。

1. コンテキストの収集：エージェントが明確化の質問をしながら、ユーザーが関連するコンテキストをすべて提供する
2. 推敲と構成：ブレインストーミングと編集を通じて、セクションごとに反復的に作成する
3. 読者テスト：コンテキストを持たない新しいエージェントでドキュメントをテストし、ほかの人が読む前に見落としを発見する

この方法により、ほかの人が読んだときにもドキュメントがきちんと機能すること（ドキュメントをエージェントに貼り付けた場合も含みます）を確認しやすくなると説明します。このワークフローを試すか、自由形式で進めるかを尋ねます。

ユーザーが希望しない場合は、自由形式で進めます。希望する場合は、段階1に進みます。

段階1：コンテキストの収集

目標： ユーザーが知っていることとエージェントが知っていることのギャップを埋め、後の段階で適切にガイドできるようにします。

初回の質問

まず、文書のメタ情報についてユーザーに質問します。

1. これはどのような種類の文書ですか？（例：技術仕様書、意思決定文書、提案書）
2. 主な読者は誰ですか？
3. 読んだ人にどのような影響を与えることを目指していますか？
4. 従うべきテンプレートや特定の形式はありますか？
5. ほかに知っておくべき制約や背景情報はありますか？

簡単な箇条書きでも、伝えやすい方法で情報をまとめて提示してもらって構わないことを伝えます。

ユーザーがテンプレートを提示する、または文書の種類に言及した場合：

• 共有できるテンプレート文書があるか尋ねます
• 共有文書へのリンクが提示された場合は、適切な連携機能を使って取得します
• ファイルが提示された場合は、その内容を読みます

既存の共有文書の編集についてユーザーが言及した場合：

• 適切な連携機能を使って現在の内容を読みます
• 代替テキストのない画像がないか確認します
• 代替テキストのない画像がある場合、ほかの人がエージェントを使って文書を理解しようとしても、エージェントには画像が見えないことを説明します。代替テキストの生成を希望するか尋ねます。希望する場合は、説明用の代替テキストを生成するため、各画像をチャットに貼り付けるよう依頼します

情報の共有

最初の質問に回答があったら、把握している背景情報をすべて共有するよう促します。次のような情報を求めます。

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

情報を整理する必要はなく、思いつくままにすべて共有すればよいと伝えます。背景情報を提供する方法を複数提示します。

• 思いつくままに情報を共有する
• 読んでほしいチームのチャンネルやスレッドを指定する
• 共有文書へのリンクを提示する

連携機能が利用可能な場合（例：Slack、Teams、Google Drive、SharePoint、その他の MCP サーバー）、これらを使って背景情報を直接取得できることを伝えます。

**連携機能が検出されず、ホスト型エージェントの UI を使用している場合：**エージェントの設定でコネクターを有効にすれば、メッセージングアプリやドキュメントストレージから背景情報を直接取得できることを案内します。

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

背景情報の収集時：

• ユーザーがチームのチャンネルや共有文書に言及した場合：

  • 連携機能が利用可能な場合：これから内容を読み取ることを伝え、適切な連携機能を使います
  • 連携機能が利用できない場合：アクセスできないことを説明します。エージェントの設定でコネクターを有効にするか、関連する内容を直接貼り付けるよう提案します

• ユーザーが未知のエンティティやプロジェクトに言及した場合：

  • 接続済みのツールで検索して詳しく調べてよいか尋ねます
  • 検索を始める前に、ユーザーの確認を待ちます

• ユーザーから背景情報を受け取るたびに、把握できたことと、まだ不明なことを整理します

確認の質問：

ユーザーが最初の情報共有を終えたと知らせたとき（または十分な背景情報が集まったとき）に、理解を確認するための質問をします。

背景情報の不足箇所に基づいて、5～10個の番号付き質問を作成します。

簡単な回答でよいことを伝えます（例：「1：はい、2：#channel を参照、3：いいえ。後方互換性のため」）。関連文書へのリンクや、確認してほしいチャンネルを提示してもらうことも、引き続き情報を共有してもらうこともできます。最も効率のよい方法で構いません。

終了条件： 質問に対する回答から十分な理解が得られたら、背景情報の収集は完了です。つまり、基本事項を改めて説明してもらわなくても、エッジケースやトレードオフについて質問できる状態です。

次の段階への移行： この段階でさらに共有したい背景情報があるか、文書の下書きに進んでよいか尋ねます。

追加情報がある場合は共有してもらいます。準備ができたら、ステージ 2 に進みます。

ステージ 2：詳細化と構成

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

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

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

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

セクションの順序：

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

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

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

この構成でよいか、調整したいかを尋ねます。

構成に合意したら：

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

アーティファクトのレンダリングが利用可能な場合： write ツールを使ってアーティファクトを作成します。これにより、エージェントとユーザーの両方が作業の土台として利用できます。

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

すべてのセクション見出しと、「[To be written]」や「[Content here]」のような簡潔なプレースホルダーテキストを含むアーティファクトを作成します。

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

アーティファクトのレンダリングが利用できない場合： 作業ディレクトリに 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] セクションに重要な不足項目がないか尋ねます。

Step 5: 下書きの作成

edit ツールを使って、このセクションのプレースホルダーテキストを実際の下書き内容に置き換えます。

選択された内容に基づいて、[SECTION NAME] セクションの下書きをこれから作成することを伝えます。

アーティファクトのレンダリングを使用する場合： 下書きの作成後、ファイルパスを知らせます。

内容を確認し、変更したい箇所を伝えるよう依頼します。具体的に伝えることで、次のセクションに向けた学習に役立つことも伝えます。

ファイルを使用する場合（アーティファクトのレンダリングなし）： 下書きの作成後、ファイルが書き込まれたことを確認します。

[filename] に [SECTION NAME] セクションの下書きを作成したことを伝え、内容を確認して変更したい箇所を知らせるよう依頼します。具体的に伝えることで、次のセクションに向けた学習に役立つことも伝えます。

ユーザーへの重要な指示（最初のセクションの下書きを作成する際に含める）： ドキュメントを直接編集するのではなく、変更したい箇所を伝えるよう依頼する旨を記載します。これは、今後のセクションに向けてユーザーのスタイルを学習するのに役立ちます。例：「X の箇条書きを削除してください。Y ですでに説明されています」や「3 段落目をもっと簡潔にしてください」。

Step 6: 反復的な調整

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

• edit ツールを使って編集します（ドキュメント全体を再出力しないでください）。
• アーティファクトのレンダリングを使用する場合： 編集のたびにファイルパスを確認します。
• ファイルベースのレンダリングを使用する場合： 編集が完了したことだけを確認します。
• ユーザーがドキュメントを直接編集し、それを読むよう依頼した場合：変更内容を把握し、今後のセクションでもユーザーの好みとして反映します（これはユーザーの好みを理解するうえで役立ちます）。

ユーザーがそのセクションに満足するまで、調整を続けます。

品質チェック

実質的な変更がない状態で3回連続して反復した後、重要な情報を失わずに削除できるものがあるか尋ねます。

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

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

完成間近

完成が近づいたら（セクションの80％以上が完了したら）、ドキュメント全体を読み直し、次の点を確認する意向を伝えます。

• セクション間の流れと一貫性
• 重複や矛盾
• 「質の低い内容」や一般論の埋め草のように感じられる箇所
• すべての文に意味があるか

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

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

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

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

リーダーテストに進んでよいか、またはほかに調整したい箇所があるか尋ねます。

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

目標： 新しいエージェント（会話の前提知識を引き継がないもの）でドキュメントをテストし、読者にとって役立つ内容になっているか確認します。

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

テスト方法

サブエージェントを利用できる場合（例：task ツールを使う opencode）：

ユーザーを介さずにテストを直接実施します。

Step 1: 読者の質問を予測する

読者がこのドキュメントを見つけて読もうとするとき、どのような質問をするか予測する意向を伝えます。

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

Step 2: サブエージェントでテストする

これらの質問を、新しいエージェントのインスタンス（この会話のコンテキストを持たないもの）でテストすることを伝えます。

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

各質問について、Reader Agent が正しく理解した点と誤って理解した点を要約します。

Step 3: 追加チェックを実施する

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

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

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

Step 4: 報告して修正する

問題が見つかった場合： Reader Agent が具体的にどの点でつまずいたかを報告します。

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

こうした不足点を修正する意向を示します。

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

---

サブエージェントを利用できない場合：

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

Step 1: 読者の質問を予測する

読者がこのドキュメントを見つけようとするとき、どのような質問をするか考えてください。検索ボックスや AI アシスタントには、どのような内容を入力するでしょうか？

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

Step 2: テストを設定する

テスト方法を説明してください。

1. 事前のコンテキストがない、新しいエージェントセッションを開きます
2. ドキュメントの内容を貼り付けるか共有します（コネクターが有効な共有ドキュメントプラットフォームを使う場合は、リンクを共有します）
3. Reader Agent に作成した質問を尋ねます

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

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

Reader Agent が正しく回答しているか、または何かを誤解していないか確認してください。

Step 3: 追加の確認

Reader Agent に次のことも尋ねてください。

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

Step 4: 結果に基づいて反復する

Reader Agent が何を誤解したか、またはどこで苦労したかを尋ねてください。そうした不足を修正する意向を伝えてください。

問題のあるセクションについて、改善に戻ってください。

---

完了条件（どちらのアプローチでも）

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

最終確認

Reader Testing に合格したら： ドキュメントが Reader Agent のテストに合格したことを伝えてください。完了する前に、次のことを行います。

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

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

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

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

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

トーン：

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

手順からの逸脱への対応：

• ユーザーがステージを省略したい場合：このステージを省略して自由形式で書くかどうか尋ねてください
• ユーザーが不満を感じているようであれば：予想以上に時間がかかっていることを認めてください。より速く進める方法を提案してください
• プロセスを調整する選択肢は、常にユーザーに与えてください

コンテキストの管理：

• 会話全体を通して、言及された内容のコンテキストが不足している場合は、積極的に尋ねてください
• 不足を放置せず、発生した時点で解消してください

成果物の管理：

• 全文の下書きには write ツールを使用してください
• すべての編集には edit ツールを使用してください
• 変更のたびにファイルパスを提示してください
• アイデア出しのリストには成果物を使用しないでください。その場合は会話でやり取りしてください

スピードより品質を優先する：

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

よくある間違い

ステージ 1 が完了する前に書き始める。 流暢で自信に満ちた、誤った内容を作ってしまいます。兆候は、チームが「何を」しているかは説明できても、明白な代替案が「なぜ」却下されたのか説明できないことです。これは執筆の問題ではなく、ステージ 1 の不足です。

選択肢を十分に出さずにブレインストーミングする。 無難な選択肢が 5 つでは、ユーザーは弱い候補群から選ぶことになります。複雑なセクションなら、選択肢が 20 個でも多すぎません。ほとんどは削られますし、削るのは簡単です。

編集のたびにドキュメント全体を再掲する。 変更したセクションには edit ツールを使ってください。再掲すると変更箇所が埋もれ、ユーザーの注意を無駄にします。

頼まれていないのにドキュメントを編集する。 ユーザーが「3 段落目をもっと簡潔にして」と言うとき、それは後続のすべてのセクションで使う文体も教えています。黙って変更するのではなく、何を変更するか尋ねてください。その指示こそが貴重です。

ステージ 3 を省略する。 ドキュメントは、それを作成した 2 人には完璧に読めます。しかし、それだけでは、予備知識なしに読む 20 人にとってどうかは分かりません。

コンテキストが混入したエージェントで読者テストをする。 この会話のコンテキストを引き継いだサブエージェントは、ドキュメントに書かれていないことをすでにすべて知っています。渡すのはドキュメントと質問だけにしてください。

「よさそう」を承認とみなす。 自由形式の肯定的なフィードバックは、たいていユーザーが細かく読むのをやめたことを意味します。確認するには、特定のセクションについて具体的な質問をしてください。

関連スキル

• brainstorming — 書くドキュメントがまだない段階でアイデアを探る場合
• writing-internal-comms — 実質的なドキュメントではなく、近況報告や告知を書く場合
• dispatching-parallel-agents — ステージ 3 の読者テストは互いに独立しており、並行して実行できます
• verifying-before-completion — ドキュメントの完成を宣言する前に、すべての事実、リンク、数値を確認する場合