writing

文章を書く、直すときの規範である。

• 読者である人間の読み方と考え方は humanity-and-humanness に従う
• 日本語の言い回しは philtzjp/skills の japanese に従う
• この skill の規範は、その上に足すものである

この skill が必要な理由と達成したい状態

この skill が必要な理由は、AI が文を、読者に何を判断させるかからではなく、学習した説明文の形から反射的に組み立てることにある。そのため理由が欠ける。コードから導出できる陳腐化する情報が増える。反射的な読点が不自然な拍を作る。全文が同じ認知モードで平坦になる。さらに AI は、書いてあることをそのまま読み取れる自分を読者の模型にする。推測で補いながら読む人間には、項目が数えられず、流れに乗れず、読んでも頭に残らない文章になる。この癖は読者を疲れさせ、大事な判断基準を埋もれさせる。

この skill で達成したい状態は、読者が一度読むだけで書き手の判断とその理由を受け取り、最後まで読み進められる文章になっていることである。

大原則

規範は、文型や禁止事項として機械的に当てはめるものではない。先に決めるのは「どう直すか」ではなく「その修正で文章の何を守るのか」である。形式ではなく、文章が果たしている働きで判断する。

読み手の読み方に合わせた構成

人間は順に読み、読んだ順に理解を組み立てる。一覧して全体を把握してから詳細に入る。構成はその読み方に合わせる。

• 1 つの文書には 1 つの種類だけを入れる
• 規則を並べる前に、その規則がなければ何が起きるかを書く
• 題と冒頭だけで、何の文書で何を守るかが分かるようにする
• 何の文書かは短い文の段落で書き、守ることは箇条書きで並べる
• 並列の項目はリストにする。文章に畳まない
• 別のファイルや節への索引には、一行の要約を付ける
• 一文に置く独立した判断は 1 つにする
• 同じ段の見出しは、同じ問いに答える
• 見出しには話題名ではなく要点を持たせる。手順の見出しは動詞句、概念の見出しは名詞句にする

文書の種類は 4 つある。仕事のための手順、仕事のための事実である参照、理解のための説明、学習のための手順である。読み手は種類ごとに読み方を変えるので、手順の中に背景を、参照の中に説得を書くと、読み手は読み方を切り替えられない。混ぜたくなったら文書を分けてリンクする。

同じ段の見出しの観点が揃っていないと、読み手は一覧しても何を軸に分けてあるのか掴めない。規則の節と手順の節と対象の節を同じ段に並べない。

規則を先に並べて理由を後から添えると、疑問が立たないので流れが生まれない。必要な理由から達成したい状態、大原則、規則へ進む構成は、この流れを文書全体に作ったものである。

一文に判断が複数あると、人間は読み飛ばして推測で埋める。AI は全部を実行する。ここで両者の認識がずれる。

緩急の設計

rhythm も読むこと。

密度の高い文章が退屈になるのは、情報が多いからではない。全文が同じ認知モードで書かれているからである。読者の認知モードを、観察する、迷う、確信する、確かめ直すのあいだで切り替え、常に「続きを読む理由」を残す。

• 緩急は情報量の増減ではなく、認知モードの切替として設計する
• 未回収の緊張を、常に 1 つは開いておく
• 完成した結論を解説する声ではなく、考えながら進む当事者の声で書く
• 拍、緊張、緩みの材料は、状況の側からだけ取る
• 装置は内容で実現し、宣言しない
• 拍を作るために文を削らない

緊張がすべて閉じた瞬間に、読者は読むのをやめられる。未回収の緊張とは、答えの出ていない問い、裏の取れていない確信、あとで返すと約束した答えである。

状況とは、対象世界の出来事、データ、発言、語り手の判断状態である。場面のない説明文では、対象そのものの性質と、読者が抱く推論や反問が状況にあたる。状況に材料がない位置は、何も足さず平坦なまま残す。本文自身を話題にした文でリズムを作るのは、規範の違反である。

「先に答えを半分だけ置く」のように、これからやる操作を述べた文は、それ自体が駄文である。装置が機能していれば、読者は装置の存在に気づかない。

範囲、観点、比較軸、未確定事項といった導入に必要な文脈を削って短くするのは、緩急ではなく欠落である。密度を上げる編集は、共有済みの文脈の上でだけ行う。

規範

説明文を書くときは、次もすべて読むこと。

• purpose-and-reason。目的と理由を書く
• no-perishable-information。コードから導出できる情報を文書に複製しない
• punctuation。句読点は役割の境界と、意味が確定する場所に打つ
• purpose-before-means。手段より目的を先に置く
• headings。見出しと箇条書きは体言止めにする

用途

usecases/ は特定の文章を書く手順である。

• ai-context。SKILL.md、AGENTS.md、CLAUDE.md のように AI が読む文書を書く
• readme-md。人間が使うかを決めて使い始めるための README.md を書く
• novel。小説を書く