technical-writing

テクニカルライティング

開発者とコーディングエージェント向けに、正確でタスクに焦点を絞ったドキュメントを書きます。各セクションは、明示されていない前提に頼らず、内容をすばやく把握し、必要な情報を見つけ、行動に移せるようにします。

リポジトリの確認

書き始める前に、リポジトリの AGENTS.md を読みます。ドキュメントの階層、公開用の一文、機能名、使用禁止の表現、DESIGN.md の場所を確認します。.cursor/rules/ の glob ルールがこのスキルより優先されます。更新する階層（MDX、README、ルール）の判断には /w-docs を使い、ここにルーティング表を重複させないでください。

文体

• 読者には you と呼びかけ、手順には命令形の動詞を使います。能動態、現在形、具体的な名詞を使います。
• アメリカ英語とオックスフォードコンマを使います。ランタイムを指す場合は eve を小文字で表記します。
• 各ページとセクションの冒頭で、答えや結果を示します。1ページにつき主な目的は1つにします。
• 著者が意図した意味、ニュアンス、不確実性を保ちます。必要最小限の編集にとどめ、優れた文章はそのままにします。
• リポジトリに記録されたチームの意図的な行動を説明する場合に限り、we を使います。

冗長な表現や誇張表現を避けます。easy、simple、quick、just、obviously、utilize、facilitate、leverage、robust、seamless、宣伝的な形容詞、修辞疑問、反応を促す表現を使いません。

AIらしい表現を避けます。要約へのつなぎ言葉（With this setup complete…）、途切れ途切れの断片、仕様書調の動詞（provides、is configurable）、先行する文脈のない書き出し、定型的な締めくくりや格言、人間らしく見せるために作り込んだ具体性は使いません。

文章のリズム。悪い例：「APIは柔軟です。多くのユースケースに対応しています。それが価値です。きっと気に入るでしょう。」良い例：「apps/api にルートを登録し、OpenAPI で公開してから、クライアントジェネレーターを実行します。これにより、Webアプリで型付きの呼び出しを利用できるようになります。」

情報源の優先順位

動作について、学習データに頼らないでください。次の順序で確認します。

1. リポジトリ内の該当するソース、公開型、テスト
2. 最寄りの README に記載された CLI のヘルプとパッケージスクリプト
3. AGENTS.md で指定されたドキュメント階層内の既存の MDX または Markdown
4. ADR とアーキテクチャページ。マージ後の動作と一致するまでは、提案段階の意図として扱います
5. Issue とユーザーレポート。読者の問題を把握するために使い、製品の事実を確定する根拠にはしません

主張を検証できない場合は、省略するか、確認すべき担当者を明記します。完成した文章に [VERIFY] を残してはいけません。提案段階の動作を、提供済みの機能として記載してはいけません。

方法

1. 成果物の目的を1つに定め、読者のタスクを明確にします。
2. そのトピックをすでに扱っているページを探し、新しいページを作る前に既存ページを拡張します。
3. 構成を組み立てます。結果 → 前提条件 → 基本手順 → 代替手段 → 問題への対処 → 関連リンク。
4. 下書きを作成し、ソースと照合しながら主張を検証します。
5. 検索しやすさを考えて見直します。重要な記述では名詞を省略せず、重要な事実をリンク先だけでなく、その場にも記載します。
6. 次の観点でレビューします。目的と構成、正確性、網羅性、文体と検索しやすさ、差分の節度（ついでの書き換えをしない）。

モード

Docu MDX（リポジトリに apps/docu/content/docs/ がある場合）：フロントマターに title と description を記載します。ナビゲーションを変更する場合は、フォルダーの meta.json を更新します。関連ハブから本文へのリンクを設け、孤立したページを作らないようにします。ルートを移動する場合は、ドキュメントアプリの設定に恒久的なリダイレクトを追加します。MDXコンポーネントは、近接するページですでに使われている場合に限って使用します。ドキュメントの変更を出荷する準備ができたら、pnpm --filter @repo/docu checktypes を実行して完了とします。

README（**/README.md）：.cursor/rules/base/readme.mdc に従います。ルートREADMEで製品の全体像を説明し、アプリとパッケージのREADMEは簡潔に保ち、技術ドキュメントへのリンクを記載します。

ルートの製品関連Markdown（例：PRODUCT.md、ARCHITECTURE.md、AGENTS.md の指示対象となる DESIGN.md）：同じ文体を使います。機能名は、そのリポジトリのアーキテクチャに関する情報源と一致させます。ホストされた上流ドキュメントを優先するのは、AGENTS.md がローカルのプロジェクトドキュメントより優先すると定めている場合に限ります。

制約

• フラグ、エンドポイント、デフォルト値、例、指標、ユーザーの反応を決して捏造しないでください。
• ドキュメントとプロダクトのどちらの範囲かを判断せずに、1つのサポートスレッドを新しいページにしないでください。
• セクションや相互リンクで不足を補える場合に、包括的なガイドを重複して作成しないでください。
• 説明上の都合で、利用側のリポジトリに記載された公開向けの一文、使用禁止の文言、機能名と矛盾させないでください。
• サポートの証拠から分かるのはユーザーの混乱です。動作を確定するのは実装とテストです。

このスキルの対象外

• /w-docs — どのレイヤーを修正するか
• /w-api-docs — OpenAPI と生成されたクライアント
• /w-deslop — ブランチ上のコードの冗長さ
• /w-architecture — ADR と境界の計画
• 個人またはマーケティングの文体カタログ（例：gabo）