writing: 読み手には5分しかない、一文一文がその価値を支える は何をしますか？
この方法で防ぐ失敗：多くの言葉で少ししか語らないテキスト、あらゆるモデルが生成するリズム（宣言的な冒頭、3点の本文、繰り返しの結論）、そしてその過程で数字を変え、「たぶん」を落とし、出典をでっち上げてしまうこと。二番目の失敗は、テキストを滑らかに書き換えて、書き手の個性を削ぎ落としてしまうこと。
0. プロジェクトが決める
プロジェクトのために書き始める前に、CLAUDE.md / AGENTS.md を読み、.claude/skills/ にあるプロジェクト独自のスキルを探して確認する。プロジェクトのルールとスキルは、このスキルより優先される：PRテンプレートとゲート、コミット規約、宣言された言語、音声ガイド、見た目のデザインシステム。このスキルは、プロジェクトにそれらがない場合のデフォルトである。言語、言語使用域、声はプロジェクトから取得する（セクション10）。固定のプロジェクトや人物から取得してはならない。
使用するのは、人間が読むテキストを書くすべてのスクワッドエージェント（ランディングページ、カード、ハンドオフ、PR、レポート、コミット、README）。スキルは書くことだけを行う。送信、公開、投稿は常に所有者の責任である。$WRITING はこのスキルのディレクトリ（~/.claude/skills/writing）。スクリプトはPython標準ライブラリ製で、python3 -I で実行する。
1. 5つのジョブ：開始前に一つ選べ
| ジョブ | トリガー | 出力 |
|---|---|---|
| 執筆（デフォルト） | テキストを生成する：ドキュメント、メッセージ、PR、返信 | テキストそのもの。テキストについての付加情報はなし |
| 編集 | 所有者が修正用のドラフトを渡す | 編集済みドラフトと短い「変更点の説明」 |
| 検出 | 「これAIっぽくない？」、「監査して」、「書き換えずに指摘して」 | 名前付きパターン、それぞれに対する引用行1つ、修正案（数語）。書き換えなし、スコアなし、誰が書いたかの主張なし |
| 校正 | 2つ以上のサンプル：「俺みたいに書いて」、「プロダクトの声」 | references/voice-profile.md 形式の音声プロファイル。編集して保持する |
| 圧縮 | 「CLAUDE.mdを圧縮して」、「メモリをトリミングして」、「このハンドオフのトークンを減らして」 | すべての事実を含む小さくなったファイルと、fidelity_check.py の結果 |
検出における名前付きパターンは、所有者が確認できる証拠である。AI検出器は推測する。音声プロファイルはセッション内の後続のすべてのジョブで保持され、リンターに --profile として渡され、機械的なパターンのみを変更する。事実や禁止された構文は決して変更しない。
2. 儀礼の段階
プロセスはリスクに従う。すべての段階はルールに従う。変わるのはゲートだけである。
| 段階 | テキスト | プロセス |
|---|---|---|
| 0 | チャット返信、ターミナルステータス、コミットメッセージ、コードコメント、1行カード | メモリのルール。スクリプトなし、レポートなし、メタコメントなし |
| 1 | PR本文、AgenFKカード、ハンドオフ、Slack/WhatsApp投稿、メール、変更履歴、短いREADME | ルールと機械的スイープ（セクション9） |
| 2 | 第三者読者がいる約400語以上のテキスト：仕様、ADR、提案、レポート、ポストモーテム、アーキテクチャドキュメント | 完全なプロセス。完了と言う前に両方のスクリプトがパスしていること |
リーンモード。「リーンモード」、「洞窟人間（caveman）」、「簡潔に」、「トークンを減らして」の場合、段階0は「通常モード」になるまでより厳しくなる：まず回答を述べる、儀礼はゼロ、冠詞は省略可能で否定はしない、最大20語の一文に一つのアイデア、ペイロード（コード、コマンド、パス、エラー）はそのまま、ツールステータスは簡潔に、モードを演じない。セキュリティ警告、不可逆的な操作、手順の順序、混乱した依頼者、ユーザーへの質問、およびチャットの外に記録されるすべてのものについては、完全な文章に戻す。コミットメッセージはリポジトリの規約に従う（最初に git log を読む）。規約がない場合は、Conventional Commits（命令形）、本文は理由のみ。完全なルールと送信前のチェック：references/lean.md。
段階0は免除ではない。ルールはセッション内のすべての返信に適用される。なぜなら、数ターン後にはデフォルトのリズムが戻ってくるからである。段階0と1のメモリ自己チェック：eval.md の最後のブロック。
3. 重大度
調査結果の重みは同じではない。順序が何を最初に修正するか、何を絶対に出荷しないかを決める。構造は語彙より重い。単語リストがきれいで、かつ「発表・本文・要約」という形をしたドキュメントは、それでもスロップである。リストに載っている正確な用語も同様である。
| レベル | 内容 | ゲート |
|---|---|---|
| ブロック | でっち上げの事実、名前、数字、日付、引用、出典。修飾語の削除、弱化、強化。決定、数字、要件の変更。コード、表、リンク、フロントマターへの変更。出典との矛盾 | 絶対に出荷しない。allow ディレクティブはこれをカバーしない。fidelity_check.py が非ゼロ、またはカバレッジリストの項目が欠落している |
| 修正 | リンターのERROR：禁止された語彙や構文、汎用的な見出し、絵文字、散文の代わりのリスト、チャットボットの残滓。構造的：空虚な冒頭、要約的な結び、同じ型の段落 | 修正するか、1行の正当化またはインライン allow で保持する。決して、調査結果が存在する事実を削除することによって行わない |
| 修正推奨 | リンターのWARN：柔らかい構文、リズム、密度、遷移、確実性、名詞化、移植性 | 事実を犠牲にしない場合に修正する。そうでなければ放置して次に進む |
| 助言 | eval.md の判断：15%削減、見出し、メディア、対称性 | 判断は任せる。何を残したか述べる |
4. すべてに優先する3つのルール
忠実性は読みやすさに勝る。 文の流れを良くするために、要件、決定、数字、名前、リスク、受入基準、事実を決して変更してはならない。事実が読みにくければ、事実ではなく、その周りの文を変更する。事実、名前、数字、日付、引用、出典を決してでっち上げてはならない。コード、コマンド、図、リンク、表、フロントマター、技術識別子はそのまま保持する。
個性は洗練に勝る。 問題を解決する最小限の編集を行う。まず、ドラフトの語彙、リズム、率直さ、ユーモア、不確実性、脱線に注目し、それらを保持する。すべての段落を等しくきれいに整えてはならない。強い意見、罵り言葉、率直な告白は、それが書き手のものである場合にそのまま残る。テキストをオープンにすることは、愚かにすることではない。個性は投稿や意見記事に適合する。参照、 legal 、インシデントのテキストは中立を保つ。
不確実性は事実である。 「可能性がある」、「推定される」、「推測される」、「まだ測定されていない」は、書き手の知識の範囲を示す。積み重なった hedges を削減すると、一つの hedge が残り、何が不確実かを特定する。決して主張を格上げしてはならない。セキュリティ、法律、金融、医療、インシデントのテキストでは、修飾語が内容そのものであり、文がなくても読みやすくなる場合でもそのまま残る。逆も同様に誤りである：出典が明確に述べている事実に hedge をかけてはならない。
5. 文のテスト
すべての文は、情報、推論、必要な文脈、またはアクションを提供する。強調、儀礼、またはパディングだけを目的とする文は、書き換えずに削除する。
技術文書や運用文書ではハードルが高い。なぜなら、そこでの推論は通常短く、すべての文が事実、数字、コマンド、名前、決定、リスクを運ぶからである。エグゼクティブ向け散文や会話では、原因と枠組みのための余地があり、それを失うことは別の失敗である。
移植性テスト。 文を変更せずに別の人物、会社、国、製品に移動できる場合、それはパディングである。削除するか、主題に固有の事実、メカニズム、結果、判断に置き換える。
示せ、語るな。 事実、アクション、結果が強調を担う。重要な、驚くべき、または微妙な点としてラベルを付けるコメントは、それを示す代わりに削除する。
尺度を入れよ。 数字のない測定可能な形容詞は、証拠のない主張である。技術的分類は異なる：public endpoint、private subnet、external dependency、manual approval、reversible migration、immutable tag は正確な用語であり、そのまま残る。
| 単語 | 置き換え |
|---|---|
| 堅牢 / robusto | 何に耐えるか：リトライ、フェイルオーバー、Nでテスト |
| スケーラブル / escalável | どの程度まで：RPS、ノード、GB、テナント |
| 重要 / significativo | 数字 |
| 高速 / rápido | レイテンシまたは期間 |
| 多数 / vários | カウント |
| 最近 / recentemente | 日付 |
| ベストプラクティス / boa prática | 誰の、どのドキュメント |
6. 構造
- 最初に回答を述べる。決定、修正、数字、またはコマンドを最初の行にする。
- ドキュメントの内容を宣言する冒頭段落、繰り返す結論段落はなし。各結論は一度だけ。読者はそれを読んだばかりである。
- 見出しは内容に名前を付ける（「ロールバック」）。決して質問をせず、その下の最初の文で繰り返されてはならない。禁止形：概要、重要なポイント、最後に、結論、はじめに、今後の展望、包括的な概要、戦略的ハイライト、実装の旅路。
- 段落は推論を運ぶ。リストは本当に集合であるもののため。表は、読者が行と列を比較する場合のみ。
- 文と段落の長さを変える。3つで完全に聞こえるからといって、3つのグループを決して作ってはならない。
- 3行に収まるなら、3行にする。
ファイルに付随するメッセージは、何が変わったかを1行で述べる。「ここにドキュメントがあります」や支援の申し出は不要。ドキュメントタイプごとの形状：references/shapes.md。
7. 最も明確なメディア
デフォルトで散文から始めてはならない。長いセクションの前に、読者が理解する必要のある関係を特定し、意味を保持する最小のメディアを選ぶ。完全なルールは references/visuals.md。
| 読者がする必要があること | 使用するもの |
|---|---|
| 3つ以上のアイテムを2つ以上の属性で比較する、または正確なマッピングを読む | 表 |
| シーケンス、トポロジー、階層、所有権、状態、依存関係に従う | 図 |
| 画面、位置、レイアウト、またはビフォー/アフターを認識する | 注釈付き図 |
| 手順を実行する | 番号付き手順と貼り付け可能なコード |
| 原因、ニュアンス、または決定理由を理解する | 散文 |
ビジュアルは、出典で確認された素材のみから作成し、1行の結論と代替テキストを付け、散文でそれを複製しない。生成された画像は、正確なトポロジー、データ、値、アーキテクチャには決して使用しない。大きくて空の図はスロップである。
アーキテクチャ図やクラウド図は、実際のシステムに関する主張である。cloud-diagram スキルに従う（幾何学の前にインベントリ、現在または提案、編集可能なソース、レンダリングプローブ）。このスキルはその周りの散文のみを管理する。
レンダリングされたドキュメント（HTML、アーティファクト、そのPDF）：見た目はプロジェクトに属する。templates/document.html から開始し、上部の --ds-* ブロックを python3 -I ~/.claude/skills/design-reference/scripts/sweep.py <root> --css の出力で置き換える（プロジェクトにデザインシステムがない場合は、チームの中立パレットが残る）。デフォルトでは単一言語。バイリンガルはバイリンガルな読者またはリクエストがあった場合のみ、templates/document-bilingual.html から <html data-languages="en pt"> を使用する。配信前に：python3 -I "$WRITING/scripts/artifact_check.py" <file>。PR、カード、コミット、docs/ 内のMarkdownはこれらを一切取らない。ルール：references/rendered-document.md。
プレゼンテーション：プレゼンテーションスキルがインストールされている場合、スライドを計画する前にそれを呼び出す。プレゼンテーションスキルが構造、レイアウト、レンダリングを所有し、このスキルは散文と忠実性を所有する。依頼がない限り、README、ADR、ランブック、カード、メールをスライドに変換してはならない。
プルリクエスト：本文は、レビュアーが差分を開くかどうかを30秒で判断するためのもの：何が変わったか、なぜか、何が省かれたか、どのように検証されたか、リスク、ロールバック。エージェントの作業を物語ったり、コミットを繰り返したりしない。構造：pull-request スキル（またはプロジェクトのもの）。references/pull-requests.md の30秒テスト。github だけが、verifier のSHIP後にPRを開く。
8. 削除するパターンと単語
修正方法、ビフォー/アフターのペア、両言語の単語リストを含むカタログは references/patterns.md にある（クイックサマリーがファイルを開く）。セッションごとに一度読むこと。最も頻繁なもの：二項対比（「それは単なるXではなく、Yだ」）、コロンによる啓示、のどの清め（「注目に値するのは」）、偽の洞察、宣言（「さあ始めよう」）、浅い -ing 節（文末）、誇張、曖昧な出典、メタ談話、隠れた行為者、文末の切り詰められた否定（「問題なし」）、チャットボットの残滓、積み重なった hedges 、劇的な断片の連続。
フラグが立てられた単語（レバレッジ、シームレス、デルブ、堅牢；アラバンカル、ロブスト、ジョルナダ、エコシステム）は、同義語と交換するのではなく削除される。文脈によっては正確な単語もある（戦略文書での「戦略的决定」；技術用語としての ゲート、ハーネス、パイプライン、レルム）：それを保持するには、1行の正当化または <!-- writing: allow <term> --> が必要であり、決して黙認してはならない。空の副詞（単に、実際に、単純に； só、literalmente、na verdade）は、何も付け加えない場合は削除され、強調、不確実性、または書き手のリズムを運ぶ場合は保持される。
9. 機械的スイープ
最終テキストでは、段階1以上で：emダッシュやenダッシュは使用しない（書き手のサンプルが使用している場合を除く）、ストレート引用符、文ケースの見出し、コロンの後は小文字、絵文字なし、定義された用語または警告にのみ太字、太字ラベルのリストなし、貼り付けられるすべてのものにコードブロック。完全なリストは references/process.md。
10
…
[翻訳のため省略]