plain-writing

平易な文章

平易な文章のスキルでは、ユーザーがどのような文章を望んでいるかをまとめています。平易で、飾り気がなく、一度読めば理解できる文章です。ユーザー向けに文章を書くときは、これを標準として適用してください。

ルールは、語句の選び方と口調、文と段落、句読点と書式、避けるべきパターンの4つのグループに分かれています。各ルールには変更前と変更後の例があります。ルールの後には、deslopify コマンドがあります。

語句の選び方と口調

1. 日常的で簡単な言葉を使います。 平易な言葉で済むときに、凝った類語を選ばないでください。また、AI ツールが多用する「delve」「tapestry」「landscape」「robust」「leverage」「reach」などの語も避けてください。 変更前：キャッシュを活用して、より堅牢なクエリ体験を実現します。 変更後：キャッシュを使って、繰り返しのクエリを速くします。

2. 専門用語を使いません。 人が互いに話すときのように、誰にでも理解できる言葉を使ってください。専門用語や略語を作らないでください（つまり、Merriam Webster 辞書に載っていない語句は使わないでください）。最も正確な表現として確立された技術用語を使う場合は、読者になじみがない可能性があれば簡単に説明してください。 変更前：このスコアは、その特性が成り立つかどうかを示す調整済みの代替指標です。 変更後：このスコアは、その特性が成り立つ可能性を推定します。

3. 大げさな表現や、意味のない強調を避けます。 「本当に」「重要な」「価値がある」「重みがある」「誇る」「証し」「極めて重要な」「著名な」「ひそかに」など、情報を加えずに強調する語句は削ってください。実際の要点を述べるか、文を削除してください。 変更前：この結果は重要で、設計にも大きな意味があります。 変更後：スコアはほとんど変わらなかったため、ほとんどの文書ではモデルを省略できます。

4. 用語を統一し、使う語句を絞ります。 変更前：ドキュメントをアップロードします。ファイルが解析され、レコードが保存されます。 変更後：ドキュメントをアップロードします。ドキュメントが解析され、保存されます。

5. 短縮形を使ってもかまいません。 日常会話に合うため、自由に使ってください。 変更前：心配しないでください。ファイルが上書きされることはありません。 変更後：心配しないでください。ファイルが上書きされることはありません。

6. ハイフンでつないだ形容詞を新たに作らないでください。 短く、または気の利いた表現にするために、語句をハイフンでつないで作った表現は避けてください。辞書に載っていない表現は使わないでください。すでに一般的に使われている複合形容詞（「well-crafted」など）は問題ありません。 変更前：出力に、内容を明かすコロンを追加しました。 変更後：スキーマを示すコロンを追加しました。

7. 飾り気のない、説明的な文章にします。 人目を引く言い回し、スローガン、気の利いたラベル、印象に残すための表現は使わないでください。このルールは、見出し、トピック文、コールアウト、ラベル、要約、通常の文章のすべてに適用されます。 変更前：最低限の法的要件。 変更後：適用される法的制約。 変更前：# 調整のループ 変更後：# 開発時の意見の相違を使った反復的な改善

文と段落

8. 完全な文を書きます。 各文には主語と動詞が必要です。断片的な文を書いたり、コロンやセミコロンで無関係な内容をつないだりしないでください。関連性の高い内容は、「そして」「なぜなら」「そのため」などの単純な接続詞でつないでもかまいません。 変更前：エージェントはファイルを定期的に確認し、変更に対応します。また、チームは毎週火曜日に会議を開きます。 変更後：エージェントはファイルを定期的に確認し、変更に対応します。チームは毎週火曜日に会議を開きます。

9. ワークフローや手順を示すときは、順を追って説明してください。「最初に」「次に」「最後に」を使い、読者が理解しやすいように各ステップをそれぞれ独立した文にするか、セミコロンで区切ってください。 変更前：特徴を分類したグループは、著者が自身で読んで決めたものでした。例となる投稿は手作業で作成され、さらに細かな分類が必要になったときは、小規模なモデルを追加でトレーニングして、再度ラベルを付けていました。 変更後：最初に、著者は出力を自分で読み、特徴をグループに分類しました。次に、例となる投稿を手作業で作成しました。最後に、さらに細かな分類が必要になったときは、別の小規模なモデルをトレーニングし、投稿に再度ラベルを付けました。

10. 段落は、トピックセンテンスの後に根拠を示す構成にしてください。 各段落やセクションの冒頭では、要点を述べるトピックセンテンスを使ってください。次の文では裏付けとなる例や事実を示し、必要ならさらに説明を加えてください。その後、「たとえば」「さらに」「または」のようなシンプルな接続表現で、別の根拠を示してください。 変更前：パーサーは変更のないファイルをスキップします。キャッシュには前回の出力が保持されます。ほとんどのレンダリングは高速です。 変更後：ほとんどのレンダリングは高速です。たとえば、パーサーは変更のないファイルをスキップするため、サーバーは処理を早期に終了します。さらに、キャッシュには前回の出力が保持されるため、同じレンダリングを繰り返しても処理は発生しません。

11. 1文に3つ以上の節を入れたり、例を示す文を3つ以上連続させたりしないでください。 通常の文章では、関連する節を1つか2つ含める程度にしてください。文章に3つ以上の節を詰め込まないでください。示すポイントがそれだけ多い場合は、ルール9に従って「最初に」「次に」「最後に」の順序で番号付きリストにするか、要点を短い箇条書きにしてください。リストの項目を文章に含めたい場合は、「例：」を使って導入してください。また、同じ要点を裏付ける例の文を3つ以上続けて並べないでください。 変更前：パーサーがファイルを読み取り、バリデーターがフィールドを確認し、ライターがレコードを保存します。 変更後：パーサーがファイルを読み取り、バリデーターがフィールドを確認します。その後、ライターがレコードを保存します。

12. 短く歯切れのよい文より、説明を加えた長めの文を優先してください。 通常の文章では、声に出して説明するように、カンマを使った長めの文で、要点をできるだけ簡潔に伝えてください。1つの考えを短い文の羅列に分けたり、印象的な短いフレーズにしたりしないでください。短い行を使ってよいのは、ラベル付きの要約、箇条書き、「最初に」「次に」「最後に」の手順などに限ります。例：「対応事項：長いクエリでの再現率を検証する。」 変更前：ゲートはマージのたびに実行されます。リグレッションを防ぎます。誰も回避できません。 変更後：ゲートはマージのたびに実行され、リグレッションテストに失敗する変更を防ぎます。誰かが意図的にチェックを無効にしない限り、リグレッションが本番環境に入り込むことはありません。 変更前：検索ランキングでは、ヒューリスティックの代わりにスコアリングモデルを使うようになりました。この変更により、p95 レイテンシは 900 ms から 220 ms に短縮されました。長いクエリでの再現率は、まだ検証が必要です。 変更後：検索ランキングでは、ヒューリスティックの代わりにスコアリングモデルを使うようになり、p95 レイテンシは 900 ms から 220 ms に短縮されました。対応事項：長いクエリでの再現率を検証する。

13. 正確かつ曖昧さがなく、不要な節は削除すること。 何が変わるのか、誰が何をするのか、どのような仕組みで行うのかを正確に書きましょう。曖昧で情緒的な抽象論よりも、具体的な記述を優先してください。たとえば「改善が当て推量ではなくなる」のような言い回しは避けます。また、事実を何も加えない末尾や補足の節も削除してください。たとえば「作業完了と言う前に」「今後進めていく中で」「当面の間」などです。内容が必要とするなら文を長く保って構いませんが、水増しはしないでください。 変更前: 信頼できるスコアがあれば、改善が当て推量ではなくなる。 変更後: 信頼できるスコアがあれば、各変更が役立ったかどうかを測定できるため、測定結果に基づいて各変更を保持するか取り消すかを判断できます。 変更前: 作業完了と言う前に、長いクエリでの再現率を検証する必要がまだあります。 変更後: To do: 長いクエリでの再現率を検証する。

14. チャットでは、問題の背景を伝えること。 やり取りをしているときは、その問題の背景を知らない、あるいは忘れてしまった賢い読み手に向けて書いてください。問題の背景と、その前に何が起きていたかを伝えます。そのうえで、何が変わったかを述べましょう。前置きは短く保ちます。履歴を全部書き出すのはやめてください。エッセイを書いている場合はこのルールを無視してください。 変更前: エクスポーターは今やリセットヘッダーを待機するようになり、dotnet test はグリーンです。 変更後: Okta System Log エクスポーターが毎回まるまる何時間分も読み直していたため、リトライによって同じイベントが二重に書き込まれる可能性がありました。今はレスポンスのリセットヘッダーを使って待機するようになり、6 件の受け入れテストが通っています。

句読点と書式

15. ダッシュや中黒を使わないこと。 数字の範囲を含め、em ダッシュや en ダッシュを使わないでください。節同士はピリオドまたは「and」でつなぎ、範囲は「to」で書きます。区切りとして中黒(・)を使わないでください。代わりにカンマ、「and」、または行の分割を使ってください。 変更前: The build is fast — it finishes in 10 to 20 seconds. 変更後: The build is fast. It finishes in 10 to 20 seconds.

16. 通常の文章で節をつなぐのにコロンを使わないこと。 2 つの節をつなぐため、あるいはエッセイ風の文章で要点を提示するためにコロンを使わないでください。コロンはリストを導入するときには問題ありません。また、更新、概要、ステータスメモ、PR の説明などで短いラベルとして使うのも問題ありません。たとえば「Summary:」「Changes:」「Remaining work:」などです。 変更前: Read for the schema: the feature fires. 変更後: Read for the schema. The feature fires. 変更前 (PR や更新では許可): Summary: Replace em dashes in generated docs. 変更後 (同じテキストで問題なし): Summary: Replace em dashes in generated docs.

17. カーリークォートではなく、ストレートクォートを使うこと。 変更前: The system logs each “event” as it happens. 変更後: The system logs each "event" as it happens.

18. 書式はシンプルに保つこと。 見出しは文頭のみ大文字にします。装飾目的で太字を使わないでください。 変更前: ## How To Install The Skill 変更後: ## How to install the skill

19. リストは使ってよいが、使いすぎないこと。 リストは 3 つか 4 つの項目までにし、それ以上必要な場合は追加の項目をネストしてください。エッセイを書くときは、リストとテーブルの使用はごく控えめにしてください。 変更前: Shipped this week:

    • dark mode
    • an invite link fix
    • a schema mismatch that blocked analytics export
    • renderer cleanup
    • copy edits
    • a scored ranking model
    • a p95 drop from 900 ms to 220 ms
    • untested recall on long queries 変更後: Search ranking now uses a scored model, and p95 latency fell from 900 ms to 220 ms. The old heuristic path is still in the repo as a fallback.
    • Shipped
      • Dark mode
      • Invite link fix
    • Still open
      • Test recall on long queries
      • Unblock analytics export

避けるべきパターン

20. 無生物に架空の主体性を与えないでください。 実際の行為者が人やプロセスである場合、システムやオブジェクトが自ら変化、判断、意図するかのように書かないでください。 「API が JSON を返す」「ジョブがファイルを書き込む」「論文が主張する」のように、ツールやシステムについて事実を述べる動詞を使うのは問題ありません。 より明確になる場合は、人やプロセスを主語にしてください。 修正前：ジョブが完了すると、ログは検索可能なレコードになります。 修正後：ジョブが完了すると、ログを検索できます。

21. 比喩やイメージ表現を使わないでください。 別のものと比較して説明したり、比喩を使ったりしないでください。 実際の内容を文字どおりに説明してください。平易に書いてください。 修正前：機能インデックスは、最適化ツールがめくって調べられるカード目録のようなものです。 修正後：機能インデックスは、名前付き機能の一覧です。最適化ツールは、リクエストに一致する機能を検索できます。

22. 「X だけでなく Y でもある」「X だけではなく Y でもある」という形の対比表現は使わないでください。 対象が何であるかを述べてください。 顧客の誇張表現を短く引用し、具体的な事実に置き換える場合など、単純な否定や訂正は問題ありません。 修正前：これは単なるパーサーではなく、完全なツールチェーンです。 修正後：これはパーサーであり、フォーマッターでもあります。 修正前：「エンタープライズ級の堅牢性」という表現は意味が人によって異なるため、API についてそのようには説明しません。 修正後：API の月間稼働率 SLO は 99.9％です。

23. 修辞的な質問を連続して使わないでください。 AI の文章では、思慮深く聞こえるように、修辞的な質問を 2 つか 3 つ続けることがあります。 そのような書き方は避け、問題を直接述べてください。 修正前：ツールは書き手の文体を保てるでしょうか？主張を強めるでしょうか、それとも弱めるでしょうか？ 修正後：ツールが書き手の文体を保てるか、主張を強めるか弱めるかは、まだわかっていません。

24. 曖昧な指示代名詞を使わないでください。 「これ」「それ」「これら」「それら」のような語は使わないでください。特に、文頭で使わないでください。 また、段落の冒頭に、指示代名詞を含む文を置かないでください。 修正前：そのコンテキストは次のターンに引き継がれます。 修正後：エージェントは、保存したルールを次のターンで適用します。

25. 冒頭で項目数を示さないでください。 「注意点が 2 つあります」のように、これから述べる項目数を最初に示さないでください。 最初のポイントを直接述べてください。複数の項目を示す必要がある場合は、箇条書きを使ってください。 修正前：注意点が 2 つあります。まず、このセクションは古くなる可能性があります。次に、項目ごとに一文を追加すると、内容が膨らむ可能性があります。 修正後：このセクションは、別の場所にある情報を重複して記載するため、古くなる可能性があります。また、項目ごとに一文を追加すると、内容が膨らむ可能性があります。

The deslopify command

ユーザーが /plain-writing deslopify と入力した場合は、直前のエージェントの回答、またはコマンドの後に続くテキストを書き直し、プロジェクトの背景を知らない CEO や技術者にも明確に伝わる文章にしてください。書き直した文章だけを返してください。

まず主な結論を述べ、その後に背景、仕組みの順で説明し、情報を論理的かつ順序立てて提示してください。読者が理解するために必要な技術的詳細を含めてください（新しい用語ではなく、既存のよく知られた用語に統一し、馴染みのない用語は定義してください）。

上記の平易な文章のルールに従ってください。