簡易英語 は何をしますか？
概要
ジャレットのルール ルール1: チャット出力、生成ドキュメント、コードコメント、コミットメッセージは簡易テクニカル英語を使用します。スタイルは ASD-STE100 の原則に基づきます。読者は事実をより速く見つけられます。英語を第一言語としない読者はより多くを理解できます。
このスキルは独自の要約です。ASD-STE100 標準ではなく、その辞書も含みません。
使用するタイミング
- 仕様書、計画書、ADR、README、語彙エントリ、その他のドキュメントを執筆または編集する場合
- コードコメントまたはコミットメッセージを書く場合
- ルール1に従ってテキストをレビューする場合
コード識別子、引用出力（エラー、ログ、コマンド出力）、スキルファイル、またはユーザーが書いたテキストには適用しないでください。
プロセス
テキストを書きます。次に、各ルールに対してチェックします。
| # | ルール | 良くない例 | 良い例 |
|---|---|---|---|
| 1 | 一文につきトピックは1つ。 | フックはファイルを読み、もしファイルが欠けていれば警告を表示し、ユーザーがそれを見ます。 | フックはファイルを読みます。ファイルが欠けている場合、フックは警告を表示します。ユーザーは警告を見ます。 |
| 2 | 指示: 20語以内。説明: 25語以内。 | ブランチをプッシュする前に、完全なテストスイートを実行し、出力を確認してください。 | ./scripts/test.sh を実行します。次にブランチをプッシュします。 |
| 3 | 能動態を使用します。 | ルールはフックによってロードされます。 | フックがルールをロードします。 |
| 4 | 指示は命令形を使用します。 | テストはコミットの前に実行されるべきです。 | コミットの前にテストを実行します。 |
| 5 | 一つの単語は一つの意味を持ちます。.claude-work/docs/VOCABULARY.md の用語を使用します。 | 警告し、後で同じアクションに「フラグ」「アラート」「通知」を使用する。 | 毎回「警告」を使用します。 |
| 6 | 単純時制を使用します: 現在、過去、未来。 | フックは入力をチェックしていたことになります。 | フックは入力をチェックします。 |
| 7 | 単一の動詞を使用し、句動詞やイディオムは使用しません。 | ビルドをキックオフする。原因をフィギュアアウトする。 | ビルドを開始します。原因を見つけます。 |
| 8 | 「the」と「a」を保持します。 | スクリプトを実行、出力をチェック。 | スクリプトを実行します。出力をチェックします。 |
| 9 | ステップごとに1つの指示。 | 1. ファイルを開き、バージョンを変更します。 | 1. ファイルを開きます。2. バージョンを変更します。 |
| 10 | 段落: 6文以内。 | 10文のブロック。 | 2つの短い段落、またはリスト。 |
追加ルール:
- 警告や注意は、適用されるステップの前に書きます。危険から始めます: 「警告: これはブランチを削除します。」
- 数値には単語ではなく数字を使用します: 「72文字」、 「七十二文字」ではありません。
- 3つ以上の項目を挙げる場合は、リストまたは表を使用します。
- テキストに変化をつけるために同義語を使用しないでください。同じ用語を繰り返します。
- 名詞が不明確な場合は「it」や「this」を使用しないでください。名詞を再度指定します。
- 用語が語彙に含まれておらず、意味が不明確な場合は、ユーザーに質問します。その後、用語を語彙に追加します。
よくある言い訳
| 言い訳 | 現実 |
|---|---|
| 「短い文はロボットっぽい。」 | 短い文は読むのが速く、誤読されにくい。読者の速度がスタイルよりも重要です。 |
| 「同義語を使うとテキストの繰り返しが減る。」 | 同義語は読者に別のものかどうかを疑問にさせます。 |
| 「このコメントはルールを適用するには小さすぎる。」 | コメントとコミットメッセージも対象です。小さなテキストは修正が簡単です。 |
| 「受動態の方がフォーマルだ。」 | 受動態は誰がアクションを行うかを隠します。行為者を明記します。 |
注意すべき点
- 2つのトピックを結合する「and」「which」「so that」を含む文。
- 指示における「should」「could」「might」。
- 同じ文書内で同じものに2つの名前がある。
- 2つのアクションを含むステップ。
- 適用されるステップの後に警告がある。
検証
- 各文が1つのトピックを持つ。
- 指示が20語以内、説明が25語以内。
- すべての指示が命令形と能動態を使用している。
- すべての用語が語彙と一致している。
- 各リストステップに1つの指示がある。
- 段落が6文を超えていない。