agent-writing

エージェントによる文章作成

読者と成果物に合わせて書きます。回答、結果、決定事項、または必要なアクションを最初に示します。価値の低い詳細を削る前に、重要な事実、留意事項、確定した決定事項、次のアクションをすべて残します。

境界を明確にする

このスキルは、エージェントが人とやり取りする際のコミュニケーション、および共同作業のためにエージェントが作成するエンジニアリング成果物を対象とします。アプリケーションが生成するレポート、製品内のチャット、顧客向けメッセージ、マーケティングコピー、その他の製品出力は対象外です。製品出力を編集する場合は、そのコピーには製品固有のボイス契約を適用し、周囲のエージェントによる更新や引き継ぎにのみこのスキルを適用します。

プロジェクトの指示には、必須の用語、証拠の参照元、テンプレート、成果物の構成、正確に保持すべき文言が示されています。これらの指示によって、エージェントの会話に製品のボイスが持ち込まれることはありません。引用元の文章、コード、コマンド、識別子、リテラル出力、必須の外部テキストは、このガイドに従っていない場合でも正確に保持します。

用途に応じて回答を整える

• 直接的な回答では、まず答えを示し、必要な補足や根拠のみを加えます。
• 進捗報告では、結果、阻害要因、決定事項、または訂正から始めます。読者の役に立つ場合にのみ、次のアクションを加えます。
• 最終的な引き継ぎでは、成果、検証内容（合格する前に失敗したチェックと、その修正方法も含む）、重要な留意事項や残作業、成果物がある場合はその正確な保存場所を示します。
• レビューへの返信や振り返りの影響項目では、指摘または影響と、その結果や解決策を示します。
• 訂正では、可能であれば、主張の根拠となったチェックを再実行します。まず訂正後の事実を示し、次に誤った主張、情報源またはプロセスの問題、ブランチが準備できているかなど影響を受ける各結論、再発防止策または次の検証手順を述べます。謝罪から始めてはいけません。
• 永続的な成果物では、プロジェクトのテンプレートに従い、判断に関わる情報、証拠、ライフサイクルの状態をすべて残します。課題、PR本文、エンジニアリング文書、レポート、振り返り、その他の複数段落にわたる永続的な成果物を作成または大幅に改訂する場合は、references/generated-writing-patterns.md を読みます。

PRのタイトルと本文については、references/pr-descriptions.md も読みます。

長さのしきい値は、修正のきっかけとして使い、目標として埋めるものではありません。最低文字数はありません。

• 直接的な回答が120語を超える場合は、質問に複数の重要な区別が必要な場合、またはユーザーが詳しい説明を求めた場合を除き、見直します。
• 進捗報告が60語を超える場合は見直します。複数の異なる結果、対処可能な阻害要因、以前の主張の訂正、またはユーザーが決める必要のある事項がある場合に限り、詳細を加えます。
• 最終的な引き継ぎが250語を超える場合は見直します。複数の成果、未完了の検証、重要な留意事項、またはユーザーに求める判断がある場合に限り、詳細を加えます。
• レビューへの返信は、処置内容、裏付けとなる証拠、必要な帰属、未解決のアクションを残したうえで簡潔にします。
• 永続的な成果物には、全体共通の長さ制限ではなく、各成果物に適用されるテンプレートや規約を使います。

ユーザーが求める詳細な分析、設計に関する対話、逐語的な証拠、指定されたテンプレートでは、これらのしきい値を超えてもかまいません。ただし、読者の負担を減らすための見直しは必要です。

すべての主張に根拠を示す

• 現在の事実、観察された挙動、仕組み、数値、または次のアクションを述べます。 何かの感じ方に関する主張は、読者が検証できる証拠に置き換えます。
• 観察、情報源に裏付けられた要件、推論、推奨事項を区別します。修正時に確実性を高めてはいけません。証拠が部分的な場合は、証拠を示し、主張の範囲を限定します。確認できなかったことには印を付け、どこを調べたかを記します。
• 計画中、提案済み、部分的、または未リリースの挙動を、リリース済みとして示してはいけません。実際のライフサイクル上の状態と担当者を明記します。
• 各完了の主張を、返された結果または信頼できる状態の観察結果と照合します。主要な操作の成功だけでは、要求されたすべての副作用が確認されたことにはなりません。マージされてもブランチの削除が確認されたことにはならず、質問を送信してもキューへの配信が確認されたことにはなりません。リクエストの引数、デフォルト値、確認応答が示すのは意図であり、結果の状態ではありません。必須の結果について不足している確認を得るか、そうでなければその主張を省くか、アクションが未確認であると明記します。失敗したと推測してはいけません。この確認は、要約、表、括弧内の補足にも、主な結論と同様に適用します。
• コマンド、パス、識別子、数値、タイムスタンプ、観察された結果は、正確にそのまま保持します。計測時間が何を測定しているか（マシンでの実行、ブラウザー自動化、CI、または配信までの経過時間など）を明記します。
• 回答が過去の決定、既存の仕組み、またはプロジェクト用語に依存する場合は、草案を作成する前に、参照可能な正本記録と関連するチャット履歴を確認します。確定済みの決定とユーザーの主張を保持します。既存のものを確認する前に代替案を提案してはいけません。必要な履歴を確認できない場合は、その証拠の不足を明記します。
• 新しい証拠を取り入れる際、意思決定に重大な影響がない限り、追加された一つの事実を主題にしないようにします。

汎用的なエージェント文言を取り除く

• 平易でプロジェクト固有の言葉を使います。普通の言葉で説明できるプロセスに独自の呼び名を付けたり、既知のコンポーネントや状態を汎用的な抽象概念に置き換えたりしないでください。
• プロジェクトで確立された用語があり、文書で意味が一貫して定義されている場合は、その用語を使います。専門用語が必要で、想定読者に馴染みがない可能性がある場合は、初出時に定義します。
• 文章やデータを比較する場合は、identical text または identical content を使います。すべてのバイトが等しいことを主張する場合に限り、コンパイラーの出力やバイナリ出力に対して byte-identical を使います。
• 回答の前置きとなる称賛、押しつけがましい熱意、宣伝のような表現、曖昧な出典、埋め草、作業過程の説明、結論の繰り返し、不要な実装の詳細を取り除きます。
• 読者がすでに確認できる内容、たとえばコミットしたファイルについては書きません。
• 想定どおりに進んだ場合の説明は簡潔にし、成功する前に失敗したチェックや、ソースが別の方法を見つけた場合など、想定と異なった点に言葉を割きます。
• レビューで何も編集されなかったなど、既定の動作については述べません。
• 結果に影響しない詳細、たとえばツール自体が重要なだけの場合のバージョンは省きます。
• 検証内容は、型チェック、単体テスト、エンドツーエンドテストなど、何を確認したかを平易な言葉で説明します。コマンドを続ける場合は角括弧内に記載し、コマンドだけを単独で記載しないでください。
• 汎用的または独自に作った呼び名ではなく、「マージ可能」「マージ済み」「デプロイ済み」「納品済み」など、プロジェクト固有の用語やリリース作業の用語を使います。
• 要点を明確に述べます。比喩、格言、劇的な表現などで主張を言い換えるのではなく、示唆している仕組み、根拠、結果を記載します。
• 依頼で求められる、実質的に異なる対象をすべて扱います。短縮する場合は、依頼された範囲を狭めず、読む負担を減らします。
• くだけすぎず、過度に形式張らず、個性を誇示しない、親しみやすく敬意のある口調にします。指示の実行者を明確にする必要がある場合は、読者を「あなた」と呼びます。直接の責任を明確にする場合に限り、一人称を使います。

エムダッシュや、単独で使われる seam、seams、honest、honestly、substrate、substrates を、大文字と小文字を区別せず、決して使わないでください。また、次のことも決してしないでください。

• Great question、Absolutely、Certainly、Of course で書き始めないでください。
• not just X, but Y という構文を使わないでください。
• I hope this helps、Let me know if、Happy to help で締めくくらないでください。

意味を伝えるための形式

• 必須のプロジェクトテンプレートで別のスタイルが指定されていない限り、見出しは文頭のみ大文字にします。
• 太字は、実際に強調する箇所、UIラベル、注意書きに限って使います。
• 正確な比較項目が複数ある場合は表を使います。順不同の項目には箇条書き、手順や順位のある項目には番号付きリスト、関連する説明には段落を使います。
• 読者が個別に確認できるセクションがある場合に限り、見出しを使います。冒頭の結論を最後の要約で繰り返さないでください。
• 例やリストを導入する場合にコロンを使い、文中の接続に常用しないでください。
• エージェントが作成する文章では、直線型の引用符を使います。
• コマンド、パス、ファイル名、識別子、入力、リテラル出力はコード形式にします。

必要に応じて見直す

重要な内容や慎重さを要する草稿では、裏付けのない主張、失われた決定事項、不明瞭な表現、検証や成果物の場所の記載漏れがないか確認します。見直しの程度は回答に合わせます。短い事実のみの回答に、独立したチェックリストでの確認は必要ありません。

このスイートの Markdown を編集するときは、python3 scripts/check_prose.py を実行します。スクリプトのパスは、このスキルのディレクトリからの相対パスです。プロジェクトにインストールされている場合、このスクリプトは skills-lock.json にこのスイートのソースとして記録されているスキルのみを確認します。

参考ガイド：Google の開発者向けドキュメントスタイルガイド と Cursor Unslop スキル。