writing-simplified-technical-english について
ASD-STE100の制御言語ルールを、人やエージェントが行動に移す技術文書に適用するライティングスキルです。明確さと一義性を重視し、引用文は変更しません。
主な機能
- 01単語ごとに意味を一つに限定
- 02能動態と単純な時制
- 03短い文と段落
- 04段階的な書き換え手順
- 05送信前の明確さの確認
活用シーン
- 01エージェント作成のレポートや要約の編集
- 02エージェント向けプロンプトや指示の作成
- 03ツール説明やエラーメッセージの作成
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/writing-simplified-technical-englishを入力して読み込まれたか確認します。
同梱ファイルreferences/before-after.mdreferences/writing-rules.md
詳細
シンプルな技術英語を書く
ASD-STE100 は、制御言語の標準です。 航空宇宙・防衛産業は、整備手順を技術者が読み違えないように、この標準を作成しました。 読み違いの主な原因を2つ取り除きます。複数の意味を持つ単語と、複数の構造に解釈できる文です。
同じ規律を適用すれば、エージェントが書く文章によくある問題も解消できます。 エージェントの出力は、内容は正しくても読みにくいことがよくあります。長い文、重ねた婉曲表現、受動態、そして同じ操作を別の操作のように見せる類義語の使い回しが原因です。 読者は書き手に質問できないため、曖昧さがあると、少なくとも読み直しが必要になり、最悪の場合は誤った操作につながります。
文章を書くときは、以下のルールを適用してください。 まず情報を詰め込んだ文章を書き、その後で整える方法は避けてください。
いつ使うか
人または別のエージェントが行動する必要のあるテキストに使用してください。
- レポート、調査結果、要約。
- PR の説明、コミットメッセージ、コードコメント。
- 別のエージェントに渡す指示やプロンプト。
- ツールの説明、エラーメッセージ、空の状態、ログ行。
文体が重要なものには使用しないでください。マーケティングコピー、ブログ記事、説得を目的とする文章などが該当します。 STE は意図的に平板な文体です。 引用文も変更しないでください。 ユーザー、ログ、文書から引用する場合は、原文のまま引用してください。
ルール
| ルール | すること | しないこと |
|---|---|---|
| 1つの単語に1つの意味 | 操作ごとに動詞を1つ選び、毎回同じ動詞を使う | 同じ操作に「check」「verify」「confirm」を使い分ける |
| 1つの単語に1つの品詞 | 「Apply oil to the valve」 | 「Oil the valve」 |
| 能動態 | 「The worker deletes the file.」 | 「The file is deleted.」 |
| 単純な時制 | 「We received the report.」 | 「We have received the report.」 |
| 1文に1つの考え | 「Open the file. Read line 3.」 | 「Open the file and read line 3, then check it matches.」 |
| 文の長さ | 指示は20語以下、説明は25語以下 | 従属節を連ねる |
| 名詞の連なり | 3語以下（「fuel pump valve」） | 「high pressure fuel pump inlet valve assembly」 |
| 省略語を使わない | 長くなっても主語、動詞、冠詞を入れる | 対象のファイルが分からなくなる「Files not backed up will be lost」 |
| 婉曲表現は最大1つ | 「The client version is probably out of date.」 | 「An error may have occurred which could be caused by...」 |
| 段落 | 1つのトピックに絞り、6文以下にする | 複数のトピックを含める |
| リスト | 手順や条件が3つ以上ある場合はリストを使う | 1つの文に順序を埋め込む |
| 専門用語 | 必要な専門用語を使い、1度だけ定義する | 読者が知らない内部名称を使う |
PostHog のハウススタイルはこれらのルールに加えて適用し、両者が異なる場合はハウススタイルを優先します。 アメリカ英語、センテンスケース、オックスフォードコンマを使用します。 エムダッシュは使用しません。
書き換え方
- 意味を把握するために、文章を一度読みます。何を伝え続ける必要があるのか分かるまでは、書き換えを始めないでください。
- 文ごとに確認します。それぞれの文がどのルールに違反しているかを明示してください。
- 違反を修正するように文を書き換えます。すべての事実、数値、条件、限定表現を残してください。
- もう一度ルールに照らして結果を確認します。書き換えによって、新たに長い文が生まれることはよくあります。
簡潔さよりも正確さを優先してください。 短くすると安全上の条件、適用範囲の限定、または数値が抜け落ちる場合は、長い文のままにし、その理由を説明してください。
文章がすでにルールに従っている場合は、その旨を伝えてください。 ルールに従っている文章は変更しないでください。
セルフチェック
文章を送る前に、一度読み、次の点を確認してください。
- 25語を超える文はありませんか？
- 1つの文に2つの指示が含まれていませんか？
- 同じ操作が異なる2つの動詞で表現されていませんか？
- 受動態の文で、行為者を明示できますか？
- 予備知識のない読者が、ここから読み始めても次に何をすべきか分かりますか？
参考資料
references/writing-rules.md：表の詳細と出典。references/before-after.md：エージェントの出力を含む、書き換えの実例。