# Doc Coauthoring

> [ユーザーとの対話必須] 仕様書・提案書・設計ドキュメント・RFC・ADR などをユーザーと共同執筆するワークフロースキル。「仕様書を作って」「提案書を書いて」「設計ドキュメントを作成して」「PRDを書いて」「RFCを書いて」「ADRを書いて」などで発動する。

- Skill: `ynitto/doc-coauthoring` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ynitto/doc-coauthoring`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ynitto/doc-coauthoring/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: ynitto (https://skillmd.com/u/ynitto)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ynitto/doc-coauthoring

---


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

このスキルは、ドキュメントを共同で作成するための構造化されたワークフローを提供する。**コンテキスト収集**・**構造化と推敲**・**読者テスト**の3ステージで、アクティブなガイドとしてユーザーを導く。

> **注意:** このスキルはユーザーとの積極的なインタラクションを前提とする。各ステップでユーザーの確認・選択・フィードバックを求めること。ユーザーの応答を待たずに先へ進まないこと。

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

**トリガー条件:**
- ドキュメント執筆の言及:「ドキュメントを書いて」「提案書を書いて」「仕様書を作って」「まとめて」など
- 特定の文書タイプの言及:「PRD」「設計ドキュメント」「決定ドキュメント」「RFC」「ADR」
- 実質的な執筆タスクを始めようとしている

**最初の提案:**
構造化ワークフローで共同執筆することを提案する。3つのステージを説明する:

1. **コンテキスト収集**: ユーザーが関連情報をすべて提供し、エージェントが確認質問をする
2. **構造化と推敲**: セクションごとにブレインストーミング・精査・反復改善を行う
3. **読者テスト**: コンテキストを持たない新鮮なAIインスタンスで文書を検証し、盲点を見つける

このアプローチにより、他の人が読む際（他者がAIに貼り付けた場合を含む）にも機能するドキュメントが作成できることを伝える。このワークフローを試したいか、自由形式で進めたいかを確認する。

ユーザーが断った場合は自由形式で対応する。承諾した場合はステージ1へ進む。

---

## ステージ1: コンテキスト収集

**目標:** ユーザーが知っていることとClaudeが知っていることのギャップを埋め、後の賢いガイダンスを可能にする。

### 最初の質問

ドキュメントのメタコンテキストを確認する:

1. これはどんな種類のドキュメントか？（例: 技術仕様、意思決定ドキュメント、提案書）
2. 主な読者は誰か？
3. 誰かがこれを読んだ後に望む影響は何か？
4. 従うべきテンプレートや特定のフォーマットはあるか？
5. 他に制約やコンテキストはあるか？

回答は箇条書きや短縮形でよいと伝える。

**テンプレートが提供された場合またはドキュメント種類が言及された場合:**
- 共有できるテンプレートドキュメントがあるか確認する
- 共有ドキュメントへのリンクが提供された場合、適切な統合機能で取得する
- ファイルが提供された場合は読み込む

**既存の共有ドキュメントを編集する場合:**
- 適切な統合機能で現在の状態を読み込む
- alt-text なしの画像を確認する
- alt-text なしの画像がある場合: 他の人がClaudeで文書を理解しようとする際にClaudeが画像を見られないことを説明する。alt-text生成を希望するか確認し、希望する場合は各画像をチャットに貼り付けるよう依頼する。

### 情報ダンプ

最初の質問への回答後、持っているコンテキストをすべてダンプするよう促す。以下のような情報を求める:
- プロジェクト・問題の背景
- 関連するチームのやり取りや共有ドキュメント
- 代替案を採用しない理由
- 組織のコンテキスト（チームのダイナミクス、過去の出来事、政治的背景）
- タイムラインのプレッシャーや制約
- 技術的なアーキテクチャや依存関係
- ステークホルダーの懸念

整理しなくてよいと伝え、とにかくすべて出力するよう促す。コンテキストの提供方法を複数提案する:
- 意識の流れでダンプする
- チャンネルやスレッドを指示する
- 共有ドキュメントへのリンクを貼る

**統合機能が利用可能な場合**（Slack、Teams、Google Drive、SharePoint、その他のMCPサーバーなど）:
これらを使ってコンテキストを直接取り込めることを伝える。

**統合機能が検出されず、コネクター設定が可能なエージェント環境の場合:**
エージェントの設定でコネクターを有効にすると、メッセージングアプリやドキュメントストレージから直接コンテキストを引き込めることを案内する（例: Claude.ai の Settings > Connectors）。

**VSCode + GitHub Copilot Chat環境の場合:**
GitHub Copilot Chatの`#file`や`@workspace`を使ってリポジトリ内のドキュメントやコードをコンテキストとして引き込める。Teams会議のトランスクリプト（`.vtt`や`.txt`）があればファイルとして参照できる。

最初のダンプが終わったら確認質問をすることを伝える。

**コンテキスト収集中:**

- チャンネルや共有ドキュメントが言及された場合:
  - 統合機能あり: コンテンツを今読み込む旨を伝え、適切な統合機能を使用する
  - 統合機能なし: アクセスできないことを説明し、ClaudeのSettings > Connectorsでコネクターを有効にするか、関連コンテンツを直接貼り付けるよう提案する

- 未知のエンティティ・プロジェクトが言及された場合:
  - 接続されているツールを検索して詳細を調べるか確認する
  - ユーザーの確認を待ってから検索する

- コンテキストが提供される中で、分かったことと不明なことを追跡する

**確認質問:**

ユーザーが初期ダンプを終えたと示した後（または十分なコンテキストが提供された後）、理解のためのギャップに基づいて5〜10個の番号付き質問をする。

回答は短縮形でよい（例:「1: はい、2: #チャンネル参照、3: 後方互換性のため不可」）、追加ドキュメントへのリンク、チャンネルの指示、または情報ダンプの継続も受け付けることを伝える。

**終了条件:**
基本的なことを説明しなくても、エッジケースとトレードオフについて質問できるようになったとき、十分なコンテキストが収集できた状態とする。

**移行:**
この段階でさらにコンテキストを提供したいか、それとも文書の草稿作成に移るかを確認する。

ユーザーが追加したい場合は追加させる。準備ができたらステージ2へ進む。

---

## ステージ2: 構造化と推敲

**目標:** ブレインストーミング・精査・反復改善を通じてセクションごとに文書を構築する。

**ユーザーへの説明:**
セクションごとに文書を構築することを説明する。各セクションで:
1. 含めるべき内容について確認質問をする
2. 5〜20個のオプションをブレインストーミングする
3. ユーザーが残す・削除する・統合するものを指示する
4. セクションを草稿する
5. 外科的な編集で推敲する

最も不明点が多いセクション（通常は核心的な決定や提案）から始め、残りを処理する。

**セクションの順序:**

ドキュメント構造が明確な場合:
どのセクションから始めたいか確認する。

最も不明点が多いセクションから始めることを提案する。意思決定ドキュメントなら核心的な提案、仕様書なら技術的アプローチが通常該当する。サマリーセクションは最後に残すのが良い。

ユーザーが必要なセクションを分からない場合:
ドキュメントの種類とテンプレートに基づいて、適切な3〜5つのセクションを提案する。

この構造で良いか、調整したいか確認する。

**構造が合意されたら:**

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

**アーティファクト（artifacts）が利用可能な場合（Claude.ai等）:**
`create_file`を使ってアーティファクトを作成する。これはClaudeとユーザー双方の足場となる。

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

**ファイルを使う場合（Claude Code・ターミナル環境・VSCode等）:**
作業ディレクトリにMarkdownファイルを作成する。適切な名前をつける（例: `decision-doc.md`、`technical-spec.md`）。

> **Windowsの注意点:**
> - パス区切り文字は `\`（ただしMarkdownリンク内では `/` も可）
> - ファイル作成時のカレントディレクトリを確認し、絶対パスで伝える
> - PowerShellを使う場合: `New-Item -ItemType File -Path "decision-doc.md"` または単に `Write-Output "" > decision-doc.md`

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

**GitHub Copilot Chatの場合:**
VSCode上のCopilot Chatでは、`#file:decision-doc.md`で作成したファイルを参照しながら共同作業ができることを案内する。

### 各セクションの手順

#### ステップ1: 確認質問

[セクション名]セクションの作業を開始することを告げる。含めるべき内容について5〜10個の確認質問をする。

コンテキストとセクションの目的に基づいた具体的な質問を5〜10個生成する。

回答は短縮形でよい、または重要なことを示せばよいと伝える。

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

[セクション名]セクションで含めることができる候補を、セクションの複雑さに応じて5〜20個ブレインストーミングする。以下を探す:
- 共有されたコンテキストで見落とされているかもしれないもの
- まだ言及されていない視点や考慮事項

セクションの複雑さに基づいて5〜20個の番号付きオプションを生成する。追加のオプションが必要ならブレインストーミングを続けることを提案する。

#### ステップ3: 精査

どのポイントを残す・削除する・統合するかを確認する。次のセクションの優先度を学ぶため、簡潔な理由を求める。

例を示す:
- 「1,4,7,9を残す」
- 「3を削除（1と重複）」
- 「6を削除（読者はすでに知っている）」
- 「11と12を統合」

**ユーザーが自由形式のフィードバックをくれた場合**（「良さそう」「ほとんど良いけど...」など）、希望を抽出して進む。

#### ステップ4: ギャップチェック

選択されたものに基づいて、[セクション名]セクションで重要なものが欠けていないか確認する。

#### ステップ5: 草稿作成

選択されたものに基づいてこのセクションを草稿する。

`str_replace`を使ってこのセクションのプレースホルダーテキストを実際の草稿内容に置き換える。

**アーティファクトを使用している場合:**
草稿後にアーティファクトへのリンクを提供する。

読み通して変更したい点を伝えるよう依頼する。具体的に伝えると次のセクションへの学習に役立つと伝える。

**ファイルを使用している場合:**
草稿完了を確認する。

[ファイル名]に[セクション名]セクションを草稿した旨を伝え、読み通して変更したい点を伝えるよう依頼する。

**ユーザーへの重要な指示（最初のセクション草稿時に含める）:**
ドキュメントを直接編集するのではなく、変更したい点を伝えるよう依頼する。例:「Xの箇条書きを削除 - Yで既にカバーされている」「3段落目をもっと簡潔に」のように。これにより、以降のセクションのスタイル学習に役立てる。

#### ステップ6: 反復改善

ユーザーのフィードバックに従い:
- `str_replace`で編集する（全文を再印刷しない）
- **アーティファクトを使用している場合:** 各編集後にアーティファクトへのリンクを提供する
- **ファイルを使用している場合:** 編集完了を確認するだけにする
- ユーザーが直接ドキュメントを編集してClaudeに読むよう求めた場合: 変更を把握し、以降のセクションに活かす（スタイルの好みが分かる）

ユーザーが満足するまで反復を続ける。

### 品質チェック

実質的な変更のない3回連続の反復後、重要な情報を失わずに削除できるものがないか確認する。

セクションが完了したら[セクション名]完了を確認し、次のセクションに進む準備ができているか確認する。

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

### 完成に近づいたら

完成が近づいたら（セクションの80%以上完了時）、以下を確認するためにドキュメント全体を再読する意図を告げる:
- セクション間のフローと一貫性
- 冗長や矛盾
- 「スロップ」や一般的なフィラーのような感じのもの
- すべての文が意味を持つかどうか

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

**すべてのセクションが草稿・推敲されたら:**
すべてのセクションが草稿完了であることを告げ、もう一度完全な文書をレビューする意図を伝える。

全体的な一貫性・フロー・完全性をレビューする。

最終的な提案を提供する。

読者テストに進む準備ができているか、それとも何か推敲したいかを確認する。

---

## ステージ3: 読者テスト

**目標:** コンテキストのない新鮮なAIインスタンスで文書を検証し、読者にとって機能するか確認する。

**ユーザーへの説明:**
読者にとって文書が実際に機能するかテストすることを説明する。著者には意味が通るが他の人を混乱させる盲点を見つけるためのものだと伝える。

### テストアプローチ

**サブエージェントが利用可能な場合:**

ユーザーの関与なしに直接テストを実行する。

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

読者がこのドキュメントを発見しようとするときに尋ねそうな質問を予測する意図を告げる。

読者が現実的に尋ねる5〜10個の質問を生成する。

#### ステップ2: サブエージェントでテスト

これらの質問を、このコンテキストを持たない新鮮なAIインスタンスでテストする意図を告げる。

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

各質問について読者AIが正しく回答したか・間違えたかを要約する。

#### ステップ3: 追加チェック

追加チェックを実施する意図を告げる。

あいまいさ・誤った仮定・矛盾を確認するサブエージェントを呼び出す。

発見された問題を要約する。

#### ステップ4: 報告と修正

問題が見つかった場合:
読者AIが特定の問題で詰まったことを報告する。

具体的な問題をリストアップする。

これらのギャップを修正する意図を告げる。

問題のあるセクションの推敲に戻る。

---

**サブエージェントが利用できない場合:**

ユーザー自身でテストを行う必要がある。

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

ドキュメントを発見しようとする際に人々が尋ねそうな質問を確認する。

読者が現実的に尋ねる5〜10個の質問を生成する。

#### ステップ2: テスト設定

別のAIチャットセッション（現在の会話とは別）を用意してもらう。ドキュメントの内容を貼り付けるか参照させ、生成した質問を尋ねるよう指示する。

各質問について、読者AIに以下を求めるよう指示する:
- 回答
- あいまいまたは不明確だったことがあるか
- このドキュメントが読者にすでに知っていると仮定している知識やコンテキストは何か

読者AIが正しく回答するか、それとも何か誤解するかを確認する。

#### ステップ3: 追加チェック

読者AIに以下も尋ねる:
- 「このドキュメントで読者にとってあいまいや不明確な点はどこか？」
- 「このドキュメントは読者がすでに持っていると仮定している知識やコンテキストは何か？」
- 「内部的な矛盾や不一致はあるか？」

#### ステップ4: 結果に基づいて反復

読者AIが間違えたり詰まったりした点を確認する。それらのギャップを修正する意図を告げる。

問題のあるセクションの推敲に戻る。

---

### 終了条件（両アプローチ共通）

読者AIが質問に一貫して正しく答え、新たなギャップやあいまいさを指摘しなくなったとき、文書は完成している。

---

## 最終レビュー

読者テストが通過したら:
文書が読者AIテストを通過したことを告げる。完了前に:

1. 自分自身で最終的に読み通すことを推奨する - 文書はユーザーのものであり、その品質に責任を持つ
2. 事実・リンク・技術的詳細を再確認することを提案する
3. 意図した影響を達成しているか確認する

もう一度レビューしたいか、作業が完了したかを確認する。

**ユーザーが最終レビューを希望する場合は提供する。そうでない場合:**
文書完成を告げる。最後のヒントを提供する:
- 読者が開発過程を理解できるよう、この会話（またはチャット履歴）を付録としてリンクすることを検討する
- メインドキュメントを肥大化させずに詳細を提供するために付録を使用する
- 実際の読者からのフィードバックが届いたらドキュメントを更新する

---

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

**トーン:**
- 直接的で手続き的に
- ユーザーの行動に影響する場合は理由を簡潔に説明する
- アプローチを「売り込もう」とせず、ただ実行する

**逸脱への対応:**
- ユーザーがステージをスキップしたい場合: これをスキップして自由形式で書くか確認する
- ユーザーがいら立っているように見える場合: 予想より時間がかかっていることを認め、スピードアップする方法を提案する
- 常にユーザーにプロセスを調整する主体性を与える

**コンテキスト管理:**
- 途中で言及されたことについてコンテキストが不足している場合、積極的に確認する
- ギャップを積み重ねないよう、気づいた時に対処する

**アーティファクト管理:**
- 全セクションの草稿には `create_file` を使用する（エージェントがアーティファクトをサポートしている場合）
- すべての編集には `str_replace` を使用する
- 変更のたびにアーティファクトへのリンクを提供する
- ブレインストーミングリストにはアーティファクトを使わない - それは会話の中で行う

**Windowsでのファイル管理:**
- ファイルパスはWindows形式（`\`）と汎用形式（`/`）を両方案内する
- PowerShellコマンドが必要な場合は明示する（`New-Item`、`Get-Content`等）
- ファイルを作成した後は絶対パスを伝え、エクスプローラーで確認できるようにする

**IDEエージェント連携（Copilot、Kiro等）:**
- IDEのエージェントではFile参照やWorkspace参照を活用できることを案内する（例: GitHub Copilot Chatの`#file`・`@workspace`）
- エージェントのインストラクション設定（copilot-instructionsや.kiro/steering等）に共同執筆のルールを記録することで次回以降のセッションでも一貫したスタイルを維持できる

**品質よりスピード優先にしない:**
- ステージを急がない
- 各反復で意味のある改善を行う
- 目標は読者にとって実際に機能する文書を作ること