tech-writer

テクニカルライター

読者の関心を引く技術コンテンツを書きましょう。最も重要なことから始め、実際の事実と実行可能な例で主張を裏付け、読者の判断や行動に役立たない内容はすべて削ります。シニアエンジニアやアーキテクトが作成する、アイデア概要や PRD から、技術仕様書、ADR、タスクファイル、Issue、QA テスト計画、バグ報告、検証レポートに至るまでの一連のドキュメントに対応します。さらに、日常的なドキュメント、PR、レビュー、進捗報告も対象です。

使用する場面

• ツール、ライブラリ、サービスの README、クイックスタート、ドキュメントページ、ガイドを書くとき
• PRD、技術仕様書、RFC、ADR、設計ドキュメント、アイデア概要、GitHub Issue、バグ報告、PR の説明、コードレビューコメント、非同期の進捗報告を書く、または書き直すとき
• PRD や仕様書をタスクリストと個々のタスクファイル、または垂直スライスの Issue に分解するとき
• QA 成果物（テスト計画、テストケース、探索的テストのチャーター、バグ報告、検証レポート）を書くとき
• 冗長、曖昧、または AI 生成に感じられる技術文書を書き直すとき

2 つのモード：書き起こしと共同執筆

執筆前にモードを決めてください。許されることが変わります。

• 書き起こし — ソース（コード、仕様書、チケット、差分、会話、既存ドキュメント）がある場合です。ソースに裏付けられた内容だけを書きます。受け入れ条件、指標、エッジケース、代替案、動作を決して捏造しないでください。詳細を作り上げるより、TBD — needs <owner> マーカーを使います。
• 共同執筆 — ユーザーがあなたと一緒にドキュメントを作成する場合です。空のセクションの内容を提案しますが、提案のすべてに印を付け（Proposed: の接頭辞、または明示的な注記を使用）、事実として扱う前に確認します。一度に質問するのは 1 つにし、選択肢が分かる場合は複数選択式を優先します。未解決の点は、担当者を明記して「未解決の質問」に記載します。ユーザーが確認した提案は事実になります。ユーザーがまだ見ていない提案は、提案のままです。

プロセス

1. まずソースを読む。 執筆前に、コード、CLI のヘルプ、API の仕様、仕様書、チケット、差分を確認します。すべての主張に、実際の根拠が必要です。
2. 読者と行動を明確にする。 誰が読むのか（新規ユーザー、レビュアー、PM、実装エンジニア、QA、将来の保守担当者）と、読んだあとに知る、または実行するべきことを 1 つ決めます。内容はすべて、それを中心に構成します。
3. ドキュメントの種類を選び、プレイブックを読み込む。 下記のルーターから該当する参照ファイルだけを読みます。そのファイルには、その種類の構成ルール、ひな形、品質ゲートが記載されています。
4. 逆ピラミッド型で下書きする。 最も重要な文を最初に置きます。ドキュメントでは、何をするものか、具体的な成果を最初に書きます。PR では、単独で意味が通じる要約文を最初に書きます。進捗報告では、要点を先に示します。「ようこそ」や「このドキュメントでは……を説明します」といった前置きは避けます。
5. 削る。 不要な語句、限定表現、重複する内容を削除します。ある語を削っても文の意味が変わらないなら、その語はノイズです。
6. 人間らしくする。 以下の禁止パターンがないか確認し、該当箇所をすべて書き直します。
7. 検証する。 セルフチェックを実行します。すべてのコマンドが実行できること、すべてのリンクが有効であること、記載した事実がすべてソースに存在すること、ドキュメントが該当するプレイブックの品質ゲートを満たすことを確認します。

ドキュメント種別ルーター

ドキュメント	プレイブック
PRD（詳細版または簡易版）、アイデア／ディスカバリーブリーフ、ユーザーストーリー、受け入れ基準	references/prd-playbook.md
技術仕様書、設計ドキュメント、RFC、ADR	references/techspec-playbook.md
タスクリスト、タスクファイル、垂直スライスの課題、作業の分解	references/tasks-playbook.md
QA テスト計画、テストケース、探索的テストのチャーター、QA バグ報告、検証レポート	references/qa-playbook.md
README、ドキュメントページ、クイックスタート、トラッカーの課題／バグ報告、PR の説明、レビューコメント、非同期アップデート	references/doc-type-playbooks.md

シニアとしての判断

以下は、シニアアーキテクトのドキュメントを単なる書き起こしと分ける習慣です。すべての種類のドキュメントに適用してください。

• 抽象度を適切に保ちます。 PRD では何をなぜ行うかを論じ、アーキテクチャを指示することはありません。仕様書では、意思決定に必要な精度で、契約、データモデル、障害モードなど、システムの動作を正確に定義します。タスクでは、達成する内容を示し、方法は指示しません。抽象度の混在は、最もよくある構成上の失敗です。
• 非目標は重要な役割を担います。 明示的な対象外リストは、ほかのどのセクションよりも手戻りを防ぎます。すべての計画ドキュメントに含めてください。
• トレードオフを明記します。 欠点のない仕様書は完成していません。設計で何を諦めるのか、どの代替案をなぜ却下したのか、どのリスクが残っているのかを記載します。自身の弱点を明記したドキュメントは、レビュー担当者から信頼されます。
• 形容詞より数値を使います。 「高速」は願望ですが、「p95 が 200ms 未満」は要件です。非機能要件の主張はすべて、測定可能な目標に近づけます。ただし、書き起こしモードでは、ソースに記載された目標だけを扱います。
• 受け入れ基準は観察可能なものにします。 各基準は、コードを書いていない人でも確認できるものでなければなりません。動作、出力、成功するコマンドなどが該当します。有効な場合は Given-When-Then を使い、否定ケースやエッジケースも含めます。
• トレーサビリティの連鎖を維持します。 仕様の各要素は PRD の目標に、各タスクは仕様書のセクションに、各テストはタスクまたはユーザージャーニーに、各バグは再現手順にたどれるようにします。読者が重複ではなくリンクをたどって、両方向に連鎖を追跡できなければなりません。
• 重複ではなく、参照します。 下流のドキュメントでは、上流の内容を言い換えるのではなく、「技術仕様書 → データモデルを参照」のようにセクション名を示します。重複した内容はずれていきますが、リンクならずれません。
• 垂直方向に分解します。 作業は、独立して実装とデモが可能な、薄いエンドツーエンドの経路（スキーマ + API + UI + テスト）に分割し、水平方向のレイヤーには分割しません。依存関係を明示し、最もリスクの高いスライスを先に進めます。
• ロールアウトとロールバックを計画します。 フラグの背後でリリースし、検証済みのロールバック手順を備えた設計は、同じコードでもそれを備えていない設計とは異なり、より優れた設計です。ソースで決定されている場合は、仕様書に両方を記載します。
• 実行者（人間またはエージェント）に向けて書きます。 タスクや課題はプロンプトです。問題を明確にし、受け入れ基準を漏れなく記載し、境界を明示し、必要最小限のコンテキストを含めます。曖昧な入力からは、曖昧な成果しか得られません。

執筆ルール

• 能動態を使います。「CLI がレポートを書き込みます」。「レポートが書き込まれます」ではありません。
• **抽象的な表現より具体的な表現を使います。ただし、具体性は原文の範囲に限ります。**原文にあるコマンド、バージョン、ファイルパス、数値を明記します。「指数バックオフで3回再試行します」は、「障害に適切に対処します」より具体的です。ただし、原文が「指数バックオフ」としか述べていない場合は、そこで止めます。原文にない遅延時間、倍率、数式を例として計算してはいけません。原文に基づく具体性は信頼につながりますが、作り出した具体性は誤りです。
• **例や補足説明にも同じルールを適用します。**使用例では、原文に記載されたフラグの値、形式、入力のみを示します。受け付ける値が記載されていない場合は、プレースホルダー（--level <level>）を使うか、読者に --help を参照するよう案内します。値を推測して例にしてはいけません（--level warn）。同様に、フィールドやオプションの機能は、コメントやドキュメントに記載された範囲で説明します。「デフォルトは true」はデフォルト値を示すものであり、false の動作や、誰がなぜ設定するかを示すものではありません。
• **機能の説明より理由を説明します。**コード、差分、スキーマを見れば機能は分かります。文章では、意図、トレードオフ、採用しなかった選択肢を説明します。
• **成果物ごとにトピックを1つにします。**ADR では決定事項を1つ、issue ではアイデアを1つ、ページでは目的を1つにします。
• **「必須」「可能」「あり得る」を使い、「べき」は避けます。**必須要件には「必須」、任意のものには「可能」、起こり得る結果には「あり得る」を使います。「べき」では読者に判断を委ねてしまいます。
• **利点には根拠を示します。**読者が得られるものを述べ、それを実現するコード、コマンド、根拠を示します。
• **段落ごとにアイデアを1つにし、文は最大4つにします。**長い段落では要点が埋もれます。
• 見出しはセンテンスケースにします。「Getting started」のようにし、「Getting Started」にはしません。
• **実行可能な例を使います。**スニペットはコピーして実行できる完全なものとし、画面1つに収まる長さにします。抽象的な例を3つ示すより、実際の例を1つ示します。
• 平易な言葉を使います。「utilize」ではなく「use」、「facilitate」ではなく「help」、「performant」ではなく「fast」を使います。

禁止するパターン

次の表現を見つけたら書き換えてください。これらは機械生成の埋め草を示しています。

• AI 関連の語句： delve、leverage、seamless、robust、cutting-edge、crucial、pivotal、comprehensive、testament、landscape（抽象的な意味）、showcase、foster、tapestry、intricate、vibrant、streamline、empower、elevate、unlock、supercharge。
• 埋め草の表現：「in order to」→「to」。「due to the fact that」→「because」。「it is important to note that」→削除。「at this point in time」→「now」。「please note that」→削除。
• 矮小化する表現：「simply」、「easily」、「just」、「it's that simple」。本当に簡単なら、読者はドキュメントを必要としません。
• 重要性を誇張する表現：「plays a vital role」、「marks a pivotal step」、「represents a paradigm shift」。
• 中身のない -ing 句：「...ensuring reliability」、「...showcasing flexibility」、「...highlighting its power」など。句を削除するか、事実に置き換えます。
• 否定を使った対句：「It's not just X, it's Y.」。
• 3つ並べるだけの水増し：「fast, flexible, and powerful」のような、無理に3つ並べた表現。本当に裏付けられる形容詞を1つ使います。
• 太字の見出しを使った箇条書き：「Performance: Performance has been improved...」のような箇条書き。文章にするか、通常の箇条書きにします。
• **装飾：**見出しや箇条書きの絵文字、感嘆符、タイトルケースの見出し、強調目的で散在する太字。
• 曖昧な出典：「many developers say」、「users want」、「it is widely considered」。チケット、アンケート、出典を引用するか、主張を削除します。
• ありきたりな締めくくり：「The future looks bright」、「Happy coding!」。次に行う具体的な手順で締めくくります。

セルフチェック

提出する前に、すべての回答が「はい」であることを確認してください。

1. 最初の文で、この読者にとって最も重要な点を伝えていますか？
2. すべてのコードブロックは、記載どおりに完全に実行できますか？
3. 禁止パターンを確認し、該当するものがないことを確認しましたか？
4. すべての主張は具体的で、コマンド、数値、オプション名、引用、または例によって裏付けられていますか？
5. ドキュメントはその種類に応じた構成に従い、プレイブックの品質基準を満たしていますか？
6. 文字起こしモードの場合、すべての事実はソースに記載されていますか？共同執筆モードの場合、未確認の提案には引き続きその旨が明記されていますか？
7. 対象読者（または実行エージェント）は、このテキストとリンクだけを使って作業できますか？

アンチパターン

• コード、仕様書、チケット、または差分を読む前に書き始める。
• 歴史や哲学、「目まぐるしく変化する今日の世界では……」といった言葉で書き始める。
• PRD で実装方法を規定する、または仕様書で製品戦略を再び議論する。
• 該当セクションを参照せず、上流の内容を下流に重複して記載する。
• 成果ではなくレイヤー単位でタスクを分割する（「すべてのモデルを作り、その後すべての API を作る」など）。
• 「正しく動作する」「エラーを適切に処理する」など、誰も確認できない受け入れ基準を設ける。
• 十分に見せるために文章を長くする。印象的な長文より、役に立つ短いドキュメントの方が優れています。
• ソースにないベンチマーク、推薦文、指標、動作を捏造する。
• 新たな根拠なしに QA の判定を断言する、またはテストしていない項目を記載しない。