plain-language-writing

plain-language-writing

独立した 2 つのルールセットです。呼び出し側が、どちらを適用するかを指定します。COMMS は、その場で一度だけ読むテキスト向けです。ARTIFACT は、永続的なファイルに保存され、再読やレビューの対象となる文章向けです。両者を混同して適用しないでください。異なる読解条件に合わせて調整されています。

これらのルールは、信頼できる根拠（ISO 24495-1、Kimble の平易な言葉に関する研究、EARS、INCOSE の要件記述ガイド）に基づく基準を実践に適用するものですが、各ルールが個別に実証されているわけではありません。確実な解決策ではなく、現時点で最も根拠のあるアプローチとして扱ってください。十分な裏付けがあるもの（代名詞のルール、COMMS #4／ARTIFACT #3）と、妥当ではあるものの実証されていないものについては、上記の調査文書を参照してください。COMMS #5（構成）には、実証的な裏付けがまったくありません。以前の版の規則（A5）は根拠がないため調査から削除されており、ここでは実証済みのルールではなく、文体上の標準としてのみ残しています。

COMMS — エージェントからユーザーへのリアルタイムのテキスト

インタビューの質問、確認や要約を促すプロンプト、状況報告、手順を案内する質問、障害・一時停止・停止のメッセージ。

1. 文の長さ。 おおむね 20 語以内にします。長い文は分割します。

2. 1 文につき 1 つの節。 異なる 2 つの考えを「and／but／which」でつなげません。

3. 慣用句、比喩、ユーモアは使いません。 「let's dive in」「heads up」「ballpark」ではなく、文字どおりに表現します。

4. 曖昧な代名詞は使いません。 文中で重要度の近いものを 2 つ導入した場合、「it／this／that」で指し戻さず、該当する対象を明記します。すべての代名詞をなくす必要はありません。複数の対象を指す可能性がある場合に限ります。

5. 因果関係や複数段階の説明には、密度の高い段落ではなく、ラベル付きの構成を使います。 根本原因や複数段階のプロセス（何かが失敗した理由、その結果どうなるか）を説明するときは、短い大文字のセクションラベルに続けて、番号付きの手順、または分岐ロジックを示す IF／THEN を使います。短いインタビューの質問や 1 行の状況報告には適用しません。これらは通常の文のままにします。無理に構成を加えると不自然になります。

   次の形式に従います。

   PROBLEM.
   <one or more sentences naming what's wrong>
   
   WHY THIS HAPPENS.
   <mechanism, as numbered steps if there's a sequence>
   1. ...
   2. ...
   
   THE ROOT CAUSE.
   IF <condition> THEN <result>.
   IF <other condition> THEN <other result>.
   
   CONCLUSION.
   <one sentence confirming or correcting the user's read>
   
   NEXT STEP.
   <what happens next, or what's still open>
   

ARTIFACT — 永続的な成果物の文章

proposal.md、specs/*.md、design.md、tasks.md、align.md における自由形式の文章です。成果物で必須とされる既存の構成（### Requirement／#### Scenario ブロック、WHEN／THEN、チェックボックス構文、差分操作のヘッダー、SHALL／MUST の用法）を上書きすることはありません。

1. 曖昧な表現や、但し書きとなる語句は使いません。 「adequate」「reasonable」「as appropriate」「where possible」「etc.」は避けます。測定可能な基準、または明示的なリストを示します。
2. 1 文につき 1 つの義務または判断。 2 つの要件や判断を「and／or」でつなげません。
3. 曖昧な代名詞は使いません。 COMMS #4 と同じ条件です。
4. 規範キーワードは要件ブロック内に置きます。 SHALL／MUST／SHOULD は、実際の ### Requirement の記述内でのみ大文字にします。説明文（proposal.md、design.md の根拠説明）では大文字にしません。
5. 1 つの概念には 1 つの用語を使います。 proposal.md、specs/*.md、design.md、tasks.md を通して同じ名称を再利用し、類義語に置き換えないでください（例：「user」／「actor」／「consumer」）。