From d7a55542d4429bade37846ebd89276e9d16db9ba Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 12 Aug 2026 13:16:06 +0000 Subject: [PATCH 1/4] =?UTF-8?q?docs:=20=E6=97=A5=E6=9C=AC=E8=AA=9E?= =?UTF-8?q?=E6=8A=80=E8=A1=93=E6=96=87=E6=9B=B8=E3=81=AE=E6=96=87=E7=AB=A0?= =?UTF-8?q?=E8=A6=8F=E7=AF=84=E3=82=92=E3=83=97=E3=83=AD=E3=82=B8=E3=82=A7?= =?UTF-8?q?=E3=82=AF=E3=83=88=E3=82=B9=E3=82=AD=E3=83=AB=E3=81=A8=E3=81=97?= =?UTF-8?q?=E3=81=A6=E5=B0=8E=E5=85=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit k16shikano 氏の Gist (fd287c3) を .claude/skills/japanese-tech-writing として取り込み、日本語のレビュー・ドキュメント作成時の文章規範とする。 AGENTS.md の review 節から本スキルを参照するようにした。 Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_013TCsENo93FrhfB8ohsSoXH --- .claude/skills/japanese-tech-writing/SKILL.md | 148 ++++++++++++++++++ AGENTS.md | 2 + 2 files changed, 150 insertions(+) create mode 100644 .claude/skills/japanese-tech-writing/SKILL.md diff --git a/.claude/skills/japanese-tech-writing/SKILL.md b/.claude/skills/japanese-tech-writing/SKILL.md new file mode 100644 index 0000000..9f6709d --- /dev/null +++ b/.claude/skills/japanese-tech-writing/SKILL.md @@ -0,0 +1,148 @@ +--- +name: japanese-tech-writing +description: 日本語の技術文書・書籍原稿の文章規範。整形（一文一行、引用ブロック、脚注、コラム記法）、段落と論証の構成（パラグラフライティング）、論証の厳密さ（ツッコミどころの除去）、読み手の負荷の管理、視点と語り、演出の抑制、LLM っぽい空句の禁止、冗長の排除を定める。日本語で技術書の章、草稿、記事、解説文を書くとき、または推敲・リライトするときに使用する。 +--- + +# 日本語技術文書の文章規範 + +日本語で技術的な原稿（書籍の章、記事、解説文）を書く・推敲するときは、以下の規範に従う。 + +## 整形 + +- 一文ごとに改行する。段落の区切りは空行で示す。 +- コード、差分、ログ、設定ファイルの断片はコードブロックで示す。 +- 用語の由来や定式化の名称など、本筋から一段外れる補足は、本文に並べず脚注（`[^ラベル]`）に降ろす。 +- 定義や分類の列挙は箇条書きで示してよい。定義される用語は太字にする。 +- 用語を本文中で初めて定義・導入するときも、その語は太字にする。すでに導入した語を話題として指すとき、引用、通称には「」を使い、太字と使い分ける（初出の定義は太字、以後の言及は「」）。 +- ダッシュ（em ダッシュ `—`、horizontal bar `―`、いわゆる2倍ダッシュ「——」）を日本語の地の文・見出しで使わない。同格・補足の挿入（「A——挿入——B」）は括弧（）に、言い換え・敷衍（「A——B」）は句点で二文に分けるか読点でつなぐ。範囲を示す en ダッシュ `–` や英語の複合語（`Curry–Howard` など）、コードブロック・書誌情報は対象外。 +- 中黒（・）を日本語の並列で使わない。ただし単一の固有名詞の内部では使ってよい。 +- 見出し・コラム見出しに、区切り線（罫線 `─` U+2500 やダッシュ類）で「種別──主題」「主題──概念」のように二要素を詰め込まない。見出しは単一の自然な句にする（要素を一つに絞るか、助詞・読点でつなぐ）。コラム見出しも「基礎」「補足」のような種別名だけで済ませず、「同値関係としての分類」「ループ不変条件と帰納法」のように内容を特定する。 +- 用語とその定義を並べる箇条書きは、区切り線ではなく全角コロンで「**用語**：説明」と書く。 + +## 段落と論証の構成 + +パラグラフライティングを基本とする。段落は論証の一歩であり、読者は段落単位で論理を追えなければならない。 + +- 一つの段落には一つのトピックだけを置く。場面の進行（調査、報告、検証、評価）が複数混ざった長い段落は、一歩ずつの段落に分割する。 +- 段落の最初の文を読めば、その段落が何の話かわかるようにする。 +- 段落の先頭では、前の段落との論理関係を接続表現で明示する（「であれば」「実際」「しかし」「この例自体からも」）。 +- 新しい概念・術語を導入するときは、いきなり「XはYである」の辞書型断定で始めない。先に導入文で対象を置き、次にその働き・差分を述べ、必要なら三文目で定義を与える。 +- 論証は一方向に進める。結論を出してから反論を処理し、結論を言い直す構成にしない。反論と疑念の処理を終えてから、結論を一度だけ置く。 +- 例への弁明（作為的に見える、への先回りなど）は、場面の山場の直後に挟んで流れを切らない。次の節の冒頭でまとめて処理する。 +- 読者が立てそうな誤った解釈は、明示的に否定してから本当の理由を述べる（「その理由は『〜だから』ではない。〜だからだ」）。 +- 「AではなくB」と否定するときは、否定の根拠を一文添える。反実仮想（「もしAなら、〜だっただろう」）が使えることが多い。 +- 譲歩（「確かに〜」）では、事実の確認にとどめる。あとで訂正する内容を著者の声で因果として断定すると、自己矛盾になる。表面的な診断を一度認めたいときは、読者や通説の声に帰属させる（「〜と要約できてしまうかもしれない」）。 +- 山場で効かせたい情報（数値、固有の事実）は、その手前の段落で先出ししない。 +- 何かを否定・限定するときは、否定する命題そのものを「」で正確に書き出す（「明文化されていればすべてを任せられる」を意味しない、など）。「何もかもが解決するわけではない」のような漠然とした否定で済ませない。 +- 「後の章で扱う」のような前方参照は、論証が一段落した位置（段落末・節末）に置く。論証の途中に挟んで流れを切らない。 + +## 論証の厳密さ + +文章の論理にツッコミどころを残さない。書き上げたら、読み手の反論を先回りして次の点を点検する。 + +- 推量・可能性・読者の疑念・反実仮想として書かれている文を、機械的に断定へ変えない。 + 「かもしれない」「だろう」「ようだ」「らしい」は、根拠なく主張を弱めている場合だけ削る。 + 事実未確認の可能性、作中人物の認識、ログからの推定、読者が抱きそうな疑念、反実仮想を表す場合は、その不確実性を保つ。 + 断定に直せるのは、本文内の根拠によって命題が確定している場合に限る。 + 悪い例：「提示し続けているかもしれない」を「提示し続けている」に変える。 + 良い例：「提示し続けている可能性がある」のように、不確実性を残して文を整える。 +- 異なるものを「同じ」とまとめない。区別すべき対象（別々の決定、別々の原因、種類の違う問題）を一括りの言葉でくくらない。悪い例：相互依存する三つの未決事項を「同じ決定を別々に下していた」と書く。良い例：「どれも別々の決定であり、しかも互いに依存している」と腑分けする。 +- 複数の要因がある事象を、単一の原因に還元しない。例が複数種類の問題を含むなら、それぞれを切り分け、どの道具がどれを説明するのかを対応づける。悪い例：契約の不在と情報隠蔽の失敗が混ざった事故を、丸ごと「情報隠蔽の問題」と説明する。 +- 章・節をまたいで、同じ概念の扱いを一致させる。ある節で「人間が決める」と分類したものを、別の節で「チームで合意する」と書かない。分類・定義・用語の地位は全体で揃える。 +- 因果を主張するときは、その機構（なぜそうなるのか）を一文で示す。「AだとBになる」とだけ書いて理由を省略しない。悪い例：「手順で分けると変更が全体に波及する」。良い例：「各工程がデータを受け渡すための表現を共有してしまい、その表現を変えると全体に波及する」。 +- 検出・保証・解決を「必ず」できるかのように書かない。条件付きで正確に述べる（「〜しやすい」「〜できることが多い」「〜が成り立つときに限り」）。 +- 主張は、挙げた例が実際にその全体を支えているかを確認する。例が主張の一部しか支えないなら、主張の範囲を例に合わせて狭める。 +- 「次節で扱う」と前方に逃がした論点は、本当にそこで回収されることを確認する。回収しない伏線を張らない。 +- 譲歩や限定（「ただし」「とはいえ」）を置いたら、その後で必ず論を進める。逆接で終えて宙吊りにしない。 +- 節の中心となる語は、その節以前に定義・対象範囲を述べてから使う。定義せず使い始めない。 +- 複数の概念を一つの上位語にまとめるときは、命名の直前に、それらが同じものに帰着すると + 一文で述べる。腑分けの逆の操作にも橋を架ける。 + +## 読み手の負荷の管理 + +読者の記憶と注意は有限の資源として扱う。 + +- 後で参照する必要のない固有名（ファイル名、関数名、識別子）を出さない。「仕様書」「金額計算のユーティリティ」のような一般的な言い方で済ませる。 +- 抽象的な言い回しの指す内容が文脈から一意に決まらないときは、可能なときは丸括弧による同格挿入でその場で特定し、できるだけ読者に前を読み返させない。 +- 新しい例や場面を追加して、読者が保持すべき文脈が増えるときは、前の例と何が違うのか、なぜもう一つ必要なのかを前置きして納得感を与える。 +- 章冒頭や節の導入では、これから例で扱う内容に関係しない過剰な詳細を詰め込まない。 +- 例の節の中でも、**その節の問い・帰結に関係しない**過剰な詳細だけを omit する。議論に必要な具体は残す。省略の典型は、エージェント報告の装飾的精度（時刻、HTTP ステータス、カバレッジ率など）や、後で参照しない固有名 + +## 視点と語り + +- 例示では、結果の羅列や受動態（「特定され、判明した」）ではなく、行為者を主語にした動作の連なり（「リポジトリを調査して特定し、見つけてくれた」）で書く。 +- 「入社2年目のエンジニアが」のような架空の人物設定を無意味に冠しない。 +- 論証の中で読者を「あなた」と呼ばず、役割名（「開発者」「読者」）で書く。二人称の呼びかけは、場面への導入（「〜としよう」）や章・本の結びなど、限られた要所にとどめる。 +- 対象を指す語は具体的に選ぶ。「AI」「ツール」のような広い語でぼかさない。 +- 章や節で定式化・術語（K、契約、不変条件など）を導入したら、以後はその語で通す。「文脈」「ツール」「AI」のような曖昧語に後退しない（定式化する前の導入語として「文脈」などを使うのはよい）。 +- 術語・訳語は、その分野で慣用されている語を選ぶ（プッシュ通知は「配送」ではなく「配信」、など）。意味の近い漢語を一般語の感覚で充てない。 +- 人物そのものに言及するときは原綴りで書く（Lehman、Bainbridge）。ただし、歴史上の人物や、人名を冠した概念を定着名で紹介するときは、日本語で通用しているカタカナの通称を使う。 +- 術語の響きを持つ語を、術語でない場面に流用しない（システムから人間までの連なりを「経路」と呼ぶ、など）。「届くまでの流れ」「あいだに何があるか」のように普通の言い方で書く。 +- イ形容詞の終止に「です」を続けた文（「難しいです」「多いです」）を書かない。これは文体の規則ではなく、文の流れの破綻の兆候である。イ形容詞を裸で言い切る必要が生じるのは、その文が前後から孤立しているからであり、流れている文章なら「〜は難しく、…」と文が続くか、「〜でしょう」「〜である」で受けられる。出現したら文末だけ取り繕わず、前後の流れごと書き直す。ナ形容詞の「〜です」（「重要です」）は対象外。 + +## 演出の抑制 + +演出の規範は全面禁止ではなく、節度の規範である。修辞は、それが効果を生む箇所でのみ使う。 + +- 溜め（「ここには〜が潜んでいる」）や修辞疑問で導出を演出するのは、緊張が議論に効く要所に限る。説明で足りる箇所では、そのまま述べる。 +- 短い決め台詞を独立した段落にして緊張を作る演出を多用しない。段落内の短い体言止め（「ここまでわずか数十秒。」など）は、場面の山場に限り使ってよい。 +- 本文中の太字強調を多用しない。誤読を防ぐ否定や節の帰結など、論理の要所に限り、一節に一、二箇所まで使ってよい（導入部でも可）。それ以外は文の順序と構造で際立たせる。 +- 「〜してはならない」という命令調の断定より、「〜するわけにはいかない」のような、作業者の判断として書く形を選ぶ。 +- 転回点を過剰に劇的にしない。事実を述べる一文で足りる場合が多い。議論の山場にかぎり、感嘆符つきの短い一文程度は許容する。 +- 帰結の列挙によって事故や危険を煽らない。 +- 「重要なのは〜である」のような前置きで主張を予告しない。主張をそのまま書く。ただし、主張の様式を宣言する前置き（「標語として言い換えれば」など）は使ってよい。 +- 「AではなくBだった」という対句の決め台詞を多用しない。軽い補足や評価は括弧書きで添えてよい。 +- 慣用表現をひねった言い回し（「知識を体に入れる」など）や、指す内容が一意に決まらない比喩（「報告の外側に世界が広がっている」など）を使わない。平易な動詞でそのまま言う（「身につく」「気付く機会が減る」）。 + +## LLM っぽい表現の禁止 + +LLM が大量生成する、中身のない型に誘惑されない。書き上げたら、この節で点検する。 +本書の術語（本質的複雑さ、回収、判断の配置など）を議論に使うのはよい。空虚な装飾として使うのが問題である。 + +次のような言い回しは、論点を増やさず「ちゃんと書いている感」だけを付ける LLM 口調である。使わない。 + +- **予告と総括**：「重要なのは〜である」「本章では〜を扱う／探求する」「ここでは〜について見ていく」「まとめると」「要するに」（直前の言い換えだけのとき）、「〜に他ならない」 +- **正面から系**：「正面から扱う」「正面から回収する」「正面から見る／書く／立てる」——中身の代わりに姿勢だけを宣言する +- **空虚な形容**：「不可欠」「核心的」「鍵となる」「根本的な」（主張の中身を説明せず強調だけする）、「多角的」「包括的」「総合的」（何をどう見たかを書かない） +- **空虚な動詞**：「掘り下げる」「深掘りする」「言語化する」（何をどう書いたかを示さず終わる）、「触れる」「言及する」（一段落で済ませるだけ） +- **接続の型**：「〜において」「〜という側面から」「〜の観点から」（新情報なし）、「さらに」「また」「加えて」の連打 +- **弱い緩和と称賛**：「〜と言えるだろう」「〜かもしれない」（根拠なく主張を弱める場合だけ。推量・仮定・読者の疑念・作中人物の認識なら残す）、「非常に」「極めて」「大いに」（中身のない強調） + +悪い例：「本章では、〇〇の理論を正面から扱う」「この前提を、ここで正面から回収する」「多角的に分析すると、重要なのは〜である」。 +良い例：「本章では、〇〇の理論を扱う」「ここで、この前提を回収する」「評価の核心は、正しさを誰が知っているかにある」。 + +## 冗長の排除 + +無駄な文章をなるべく残さない。 + +- 同じ主張を言い換えて繰り返さない。一つの主張は一度だけ書く。 +- 隣接する節が同じことを別の角度で述べているなら、役割が重複している。片方に吸収して一つの節にまとめる。 +- 場面を描写した直後に、その内容を要約し直さない。意味づけの一文（「このような作業は、ほぼ完全に任せられる」など）だけを置く。 +- 同じ論理的役割を持つ並列の事実は、文を分けて重ねず一文にまとめる。その事実群の論理的地位は文頭の語で示す（「当然、経理部の月次処理も顧客の支払いも〜」）。 +- 読者が自力で補える中間段階の説明は書かない。 +- 数文にわたる議論を一文に圧縮できるなら、圧縮した一文だけを残す。要約の合図として「要するに」を使ってよい。 +- 接続や評価のためだけの文（「それ自体はよいことである」など）を置かない。 +- 想像上の読者との問答（問いを立てて一語で答える形など）を修辞として使わない。主張はそのまま述べる。読者の反応を演じて応答する形（「〜と感じたかもしれない。そのとおりである」）も同様に避け、譲歩は地の文で簡潔に行う（「もちろん、処置そのものは開発者が決める問題ではない」）。 +- 読者が抱きそうな発想を、メタな枠取り（「ここまでの話には自然な続きがある」「〜という発想である」）で紹介しない。その発想自体を直接書く。読者の疑問なら疑問文のまま書いてよい（「その保守も任せればよいのではないだろうか」）。 +- 「本書もそれを否定しない」のような、著者の立場の弁明や断りを書かない。事実の記述（「〜に書かせる場合が多い」）だけを置く。 +- 文脈を最短で読み手と共有できる文章にする。導出を一歩ずつ展開しなくても伝わるなら、構造に名前を与えて言い切る。 +- 本文でまだ導入していない概念や文書名を、先回りして持ち出さない。 +- ためらいのある弱い述語（「有効な対策であり」など）で済ませない。本文内の根拠で確定していることは強く具体的に言い切る（「活用において必須であり」など）。ただし、不確実性・可能性・仮定・読者の疑念を表すための弱い述語は保持する。語調を整えるための意図的な緩和（「必須だと言ってもいい」など）は許す。 +- 文章のリズムを作るための接続表現（「しかし一方で」など）は、冗長と見なさない。 + +## 見出しの付け方 + +見出しは内容を特定できる具体的なものにする。その節が答える問い、または扱う対象を指す句にする。 + +- 作業の手順だけを述べる見出し（「例に戻す」「〜を読み直す」など）や、情報量のない見出しにしない。その節が答える問い、または扱う対象を見出しにする。 +- 見出しを、節の結論を言い切る「セリフ」にしない。見出しの時点で読者がオチを知る状態を避ける。 +- 節で扱っている対象を指す名詞句でもよい。 +- 見出しが疑問形か断定形かは問わない。問うのは、扱う対象や読者の持つ問いを指しているかである。 +- 疑問形か、対象を指す名詞句かは、本文のトーンに合うほうを選ぶ。 + +## 読者への誠実さ + +- 例が作為的に見えうる場合、それを隠さない。読者の疑念を先回りして認め、現実に十分あり得ることの根拠を短く添える。 +- その根拠は、著者の断定（「十分あり得る状況だ」）ではなく、読者自身の経験に訴える一般的事実や通説に求める（「この症状は珍しくないだろう」「〜という言い方もよく耳にする」）。 +- 確認していないことを、確認したかのように滑らかに書かない。 + diff --git a/AGENTS.md b/AGENTS.md index b292b96..be79d20 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,6 +4,8 @@ Always review in Japanese. +レビューコメントやドキュメントなど日本語の文章を書くときは、`.claude/skills/japanese-tech-writing` の文章規範に従う。 + ## github - 機能実装時はデフォルトブランチへのPRを作成する From c83e718652367adc390cc72cac1c3054b268c0ed Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 12 Aug 2026 13:20:59 +0000 Subject: [PATCH 2/4] =?UTF-8?q?docs:=20=E8=AA=8D=E7=9F=A5=E3=83=AA?= =?UTF-8?q?=E3=82=BA=E3=83=A0=E3=81=AE=E6=97=A5=E6=9C=AC=E8=AA=9E=E3=83=A9?= =?UTF-8?q?=E3=82=A4=E3=83=86=E3=82=A3=E3=83=B3=E3=82=B0=E8=A6=8F=E7=AF=84?= =?UTF-8?q?=E3=82=92=E3=82=B9=E3=82=AD=E3=83=AB=E3=81=A8=E3=81=97=E3=81=A6?= =?UTF-8?q?=E8=BF=BD=E5=8A=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit k16shikano 氏の Gist (eb2929f) を .claude/skills/cognitive-rhythm-writing として取り込む。japanese-tech-writing を前提に併用する規範であり、 兄弟ディレクトリ配置により `../japanese-tech-writing/SKILL.md` の参照が解決する。 AGENTS.md からも本スキルを参照する。 Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_013TCsENo93FrhfB8ohsSoXH --- .../skills/cognitive-rhythm-writing/SKILL.md | 133 ++++++++++++++++++ AGENTS.md | 1 + 2 files changed, 134 insertions(+) create mode 100644 .claude/skills/cognitive-rhythm-writing/SKILL.md diff --git a/.claude/skills/cognitive-rhythm-writing/SKILL.md b/.claude/skills/cognitive-rhythm-writing/SKILL.md new file mode 100644 index 0000000..6b60201 --- /dev/null +++ b/.claude/skills/cognitive-rhythm-writing/SKILL.md @@ -0,0 +1,133 @@ +--- +name: cognitive-rhythm-writing +description: 説明的な文章に緩急を設計するための規範。緩急を装飾ではなく認知モードの切替（観察→逡巡→断定→再観察）と未回収の緊張の管理として扱い、文の拍、段落の密度波形、節の入り方、緩みと駄文の判別、執筆後の機械的な点検手順を定める。読み物として読ませたい章・記事・解説文を生成するとき、または「密度はあるが平坦でおもしろくない」文章を診断・修正するときに使用する。 +--- + +# 認知リズムを生むための日本語ライティング規範 + +密度の高い文章が退屈になるのは、情報が多いからではなく、全文が同じ認知モードで書かれているからである。 +この規範は、読者の認知モード（観察する、迷う、確信する、確かめ直す）を意図的に切り替え、常に「続きを読む理由」を維持することで、読み進める推進力を作る。 + +## 併用する規範 + +作業前に `../japanese-tech-writing/SKILL.md` を読む。 + +## 基本原理 + +- 緩急は情報量の増減ではなく、認知モードの切替として設計する。観察→逡巡→断定→再観察の往復が一つの単位である。 +- 文章は常に、少なくとも一つの**未回収の緊張**（答えの出ていない問い、裏の取れていない確信、あとで返すと約束した答え）を開いておく。緊張がすべて閉じた瞬間、読者は読むのをやめられる。 +- 完成した結論を解説する声ではなく、考えながら進む当事者の声で書く。書き手が答えに至る過程の再演が、読者の思考の再演になる。 +- **生成側の制約**：この規範を適用して文を新しく書くとき、拍・緊張・緩みの材料は状況側（対象世界の出来事・データ・発言、語り手の判断状態）からしか取らない。状況に材料が見つからない位置には、何も足さず平坦なまま残す。本文自身を話題にした文（「〜の列挙はしない」「問いは〜だけである」）でリズムを作るのは、規範の違反であって適用ではない。新造・整形した文は、書いた時点で「緩みと駄文の見分け方」の判定にかける。 +- **装置は実現するものであって、宣言するものではない**：この規範に書かれた装置の名前・手順・例文（「答えの半分」「緊張」「回収」「問いを半分ずつ返す」等）を、本文にそのまま書かない。「問いを半分ずつ返す」は、答えの前半を内容として書くことで実現される。「先に答えを半分だけ置く」「最後にもう一度だけ線を引く」のように、これからやる操作を宣言した文は、それ自体が駄文である。装置が正しく機能していれば、読者は装置の存在に気づかない。 +- **場面のない説明文での状況**：物語の場面を持たない解説・説明文では、状況側とは対象そのものの性質（データ、計算、トレードオフ、素朴な期待が事実に破られること）と、読者が抱く推論・反問である。緊張は対象の性質から作る（「流暢さと正しさが一致しないのはなぜか」は対象の話であり、可）。場面がないからといって、本文の進行を語ることで緊張の代用にしない。 +- **短文化バイアスの禁止**：拍を作るために文を削るのではない。導入で必要な文脈共有（範囲、観点、比較軸、未確定事項）を削って短くするのは、緩急ではなく欠落である。密度を上げる編集は、共有済み文脈の上でだけ行う。 + +## 文の拍 + +- 短文で足場を打ち、長めの文で流し、短文で止める。「立てる→流す→止める」を段落の基本拍にする。 +- 断定だけで押し切らない。断定と逡巡を交互に置く。 + - 断定：「〜だった」「〜である」「〜というわけだ」 + - 逡巡：「〜に違いない」（あとで裏切られる思い込み）、「〜とは思う。ただ…」「〜だろうか」 +- 逡巡は弱さではなく仕掛けである。「あとで事実に裏切られる確信」は、読者の予測を誘導してから崩す布石になる。 + - 例：「うまくいっているに違いない。」→（次の段落で）「ところが、あとになって記録を見ると、そうではなかった。」 +- 転回点では「譲歩→転回→短い停止」の拍が使える（「〜だろう。これからも〜だろう。しかし、ここで扱うのは〜のほうだ。考えたいのは、そちらである。」）。転回のあとの短い指示文が、読者の視線を固定する。 + +## 段落の密度波形 + +- 密な段落が2〜3個続いたら、疎の段落を1つ置く。疎の段落の機能は、確定事項の一行固定、次の判定対象の提示、視点距離の切替のいずれかに限る。 +- 視点の距離を固定しない。具体（記録、数値、発言、コード）に寄る段落と、意味づけで一段引く段落を交互に置く。 +- 箇条書きは情報の圧縮だけでなく、本文の呼吸を止める「間」としても使える。列挙のあとの一段引いた文（「要するに〜」）は、この間があるから効く。 + +## 冒頭の設計 + +- 冒頭の仕事は、最初の数文で未回収の緊張を一つ作ることである。**型は問わない**。使える型の例： + - 読者の実感の言い直し（「〜と感じることがあるだろう」）から仮説（「〜が違うのかもしれない」）へ + - 読者への直接の問いかけ。ただし置き去りにせず、すぐ自分の答えを返す + - 確信を帯びた一般命題。あとの本文がその確信を試す + - 語り手の思い込みを肯定的に書き切ってから、事実で崩す場面 + - 前章・前節が残した問いの、当事者の言葉での言い直し +- 予告や要約は禁止ではない。態度を帯びた一〜二文（「〜を考えるうえで、これほど適切な切り口もないはずだ」「言い換えると〜という話である」）なら、それ自体が緊張を作る。禁止すべきは、態度のない議題表（「本章ではA、B、Cを扱う」）だけである。 +- 読者が抱くであろう抵抗（古い、作為的、実用性がない、自分には関係ない）は、読者の言葉で先に言い、短く処理してから本題に入る。 + +## 節の入り方 + +- 節の頭で「本節では〜を扱う」と宣言しない。代わりに次のいずれかで入る。 + - 直前の節が残した違和感を、当事者の問いとして言い直す + - 読者が当然抱く反問をそのまま書く（「では、先に〜しておけばよかったのだろうか」）。反問には即答せず、一度「そうしたかった、とは思う」と受けてから崩す + - 書き手の告白から入る（「白状すれば、〜という算段もあった」）。告白は自己批判のためではなく、直後の論証（「この算段は半分だけ正しい」）の足場として使う +- 理論・概念・引用は、読者の中に「まだ名前のない違和感」を作ってから導入する。理論は答えではなく命名として入れる。先に理論を出して例で確認する順は、読者の発見を奪う。 +- 節と節の橋は、前節の末尾ではなく次節の頭に置く。前節の末尾に「次は〜を見る」型の予告を足すのは進行実況であり、駄文である。次節の頭が反問・違和感・告白で開けば、予告がなくても読者は続けて読む。 + +## 列挙の着地 + +- 性質や分類を列挙したら、列挙しっぱなしにしない。各項目を直前の具体的な場面へ一つずつ着地させる（「一つめは、さっき見た〜の正体である」「二つめにも身に覚えがある」）。 +- 着地の文体は均一にしない。正体の指摘、身に覚え、固有の事実への対応づけ、未来の断念、と変化をつける。 + +## 問いの回収と結び + +- 途中で立てた問いは、放置せず明示的に回収する。問いを半分ずつ返す（「答えの半分がこれである」「残り半分は〜にある」）と、後半の推進力になる。 +- 結びは、積んだ抽象を、読者がすでに持っている具体（冒頭の場面、読者自身の経験、序盤の問い）へ着地させてから閉じる。抽象論や一般則のまま終えない。 +- 緊張は選んで閉じる。最後に一つだけ開いたまま残してよい。謙抑や読者への委任（「足りない部分は読者が埋めてほしい」）は、読者の参加余地として機能する。 +- 二人称の呼びかけ、読者への依頼（「どうか〜と割り切って読んでほしい」）、書き手の謙抑や断りは、章の冒頭・結びなどの境界でだけ緩みとして機能する。中盤の論証に混ぜない。 + +## 緩みと駄文の見分け方 + +判定の軸は一つだけである。 +**その文が更新するのは「状況」か、「文書」か。** + +- 状況を更新する文：対象世界の出来事・データ・人物の発言、あるいは語り手の判断の状態（思い込み、保留、後悔、譲歩、告白）を新しく伝える。→ 緩みとして残してよい。 +- 文書を更新する文：この章・この節・この説明・ここまでの話が「どう見えるか」「次に何を書くか」だけを伝える。→ 原則として削除する。 + +駄文の典型（いずれも話題が本文自身であり、状況の情報がゼロ）： + +- 「ここまでだと、概念の説明に見えるだろう。なので、すぐに例へ戻す。」（説明の見え方と執筆の予定） +- 「要するに、この章の主題は〜ではなく〜である。」（章の性格づけの言い直しだけで、対象の新情報がない） +- 「誤解しないでほしいのだが、〜を否定したいわけではない。」（退ける誤読を特定しない弁明。下の例外1の形なら残せる） +- 「テクニックの列挙はしない。」「〜の話ではない。問いは〜だけである。」（本文の性格・範囲の宣言。否定形でも短文でも、話題が本文自身なら駄文） +- 「先に答えを半分だけ置く。」「最後にもう一度だけ線を引く。」（この規範の装置の実況。装置は内容で実現し、操作を宣言しない） +- 「ここまでで〜は見えた。次の問いは〜である。」「次は〜を見る。」（節末の進行予告。節間の推進力は、次節の頭に置く反問・違和感で作る。前節の末尾で予告しない） + +駄文は、長い説明文の形だけでなく、短い断定の形でも現れる。 +文書更新の文を削除する代わりに短く断定調へ整形すると、拍が効いた決め台詞に見えて残りやすい。これが駄文の最大の混入経路である。 +短くてリズムが良いことは、残す理由にならない。拍の良し悪しは、話題テストを通過した文についてだけ評価する。 + +良い緩みの典型（いずれも状況か、語り手の判断状態を更新している）： + +- 「うまくいっているに違いない。」（思い込み。あとで崩される布石） +- 「まあ、今すぐ手を打つほどでもないのだけど、どこかの時点で整理は要るだろう。」（判断の保留という状態の更新） +- 「最初からわかっていたらそうしていたのに、というのが口惜しい。」（判断の誤差を可視化する感情） +- 「そうしたかった、とは思う。」（反問への譲歩。直後の転回の足場） + +文書について述べる文でも、次の四つの形だけは残してよい。 + +1. **反論処理**：読者の誤読・反論を「」で具体的に書き出して退ける（「ここまでの話を『〜せよ』という主張と読まれると、それは違う」）。退ける対象が具体的に引用されていることが条件。漠然と「誤解しないでほしい」だけの文は駄文。 +2. **問いの設置と回収**：境界に置く「この章では〜を考える」（緊張を作ったあとに限る）、「その答えの半分がこれである」。残せるのは問いの文そのものと回収の文だけである。本文が「何でないか」「何をしないか」の宣言（「〜の列挙はしない」「〜の話ではない」）は問いの設置ではない。例外1の形で具体的な誤読を退けるのでない限り、削除する。 +3. **読者への依頼・断り**：境界に置く「どうか〜と割り切って読んでほしい」。 +4. **例の枠の開閉**：架空の例・場面の枠を開く文（「〜としよう」）と閉じる文（「冒頭の例にオチを付けておこう」）。例が架空であることを読者に思い出させ、抽象的な議論から場面へ戻す機能を持つ。境界（節の頭）に置く。話題が本文自身に見えても、例の枠を操作しているなら駄文ではない。 + +削除と書き換えの手順： + +- 文書を更新するだけの文を見つけたら、まず削除して前後を読み、つながるならそれで終わり。 +- 削除で論理が飛ぶ場合は、その文が指そうとしていた内容を、状況の側の文に書き換える（「ここまでだと概念の説明に見える」→「この三つの性質は、どれも冒頭の失敗の中にそろっている」）。 +- 書き換えた結果の文がまだ本文自身を話題にしているなら（短くしただけ、言い回しを変えただけ）、その書き換えは失敗である。例外1〜3のどれかの形に収まらない限り、文ごと削除して前後を橋渡しし直す。 + +## 執筆後の点検手順 + +草稿を書き上げたら、次の順で機械的に点検する。 + +1. **話題テスト**：段落の頭の文と、独立した短文をすべて拾い、「状況を更新しているか、文書を更新しているか」を判定する。文書側は、例外3形に該当しない限り削除または書き換え。推敲で新しく書いた文・短く割り直した文は、駄文の混入経路なので、書いた直後にもこのテストにかける。 +2. **漏出テスト**：この規範の語彙・例文（「答えの半分」「緊張」「回収」「線を引く」「問いを〜返す」等）が本文にそのまま現れていないか検索する。現れていれば、装置を宣言してしまった証拠なので、その文を削除し、装置を内容の側で実現し直す。あわせて、節末に「次は〜」型の進行予告がないかを全節末で確認する。 +3. **緊張台帳**：本文中で立てた問い・思い込み・約束（「答えは半分ずつ返す」等）を列挙し、それぞれの回収位置を行で指す。指せないものは、回収を書き足すか、問いごと削る。 +4. **拍の点検**：長い断定文が3つ以上連続している箇所を探し、短い足場か停止、または逡巡を挿む。 +5. **境界の点検**：二人称の呼びかけ・依頼・謙抑が本文中盤にないか確認する。あれば境界へ移すか削る。 + +## 修正指示への使い方 + +平坦な文章を診断するときは、症状から処方を引く。 + +- **全段落が同じ調子で疲れる**：文の拍がない。点検手順3を適用する。 +- **正しいのに読み進める気がしない**：未回収の緊張がない。冒頭に緊張を作る型のどれかを入れ、緊張台帳で以降も常に一つは開いていることを確認する。 +- **理論の節で急に温度が下がる**：理論が違和感より先に出ている。理論の前に反問か告白を置き、列挙は場面へ一項目ずつ着地させる。 +- **緩い文はあるのに弛んで見える**：緩みが文書更新（進行実況）になっている。話題テストにかけ、状況側の文（感情の微差、判断の保留、思い込み）に書き換える。 +- **章末が説教くさい**：抽象論のまま閉じている。読者がすでに持っている具体へ着地させる一文を先頭に置き、未決の問いを一つ残して終える。 +- **冒頭が事務的**：態度のない議題表になっている。削るのではなく、予告文に態度を与えるか、予告の前に読者の実感・抵抗の処理を置く。 diff --git a/AGENTS.md b/AGENTS.md index be79d20..1ce0671 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,6 +5,7 @@ Always review in Japanese. レビューコメントやドキュメントなど日本語の文章を書くときは、`.claude/skills/japanese-tech-writing` の文章規範に従う。 +読み物として読ませたい解説文を書くときは、あわせて `.claude/skills/cognitive-rhythm-writing` の緩急の規範を用いる。 ## github From 72a4e61eae83bb5985dde1d4fa86ea8506785206 Mon Sep 17 00:00:00 2001 From: qazx7412 Date: Wed, 12 Aug 2026 22:23:45 +0900 Subject: [PATCH 3/4] Add Japanese writing guidelines for comments and docs Add guidelines for writing comments and documentation in Japanese. --- AGENTS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 1ce0671..72f480b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,6 +4,8 @@ Always review in Japanese. +## document / comment + レビューコメントやドキュメントなど日本語の文章を書くときは、`.claude/skills/japanese-tech-writing` の文章規範に従う。 読み物として読ませたい解説文を書くときは、あわせて `.claude/skills/cognitive-rhythm-writing` の緩急の規範を用いる。 From bc31ddc89973edc440115e6ddb5dbd53fabf5078 Mon Sep 17 00:00:00 2001 From: qazx7412 Date: Wed, 12 Aug 2026 22:27:28 +0900 Subject: [PATCH 4/4] Update Japanese writing guidelines in AGENTS.md Revised guidelines for writing comments and documentation in Japanese, specifying the use of certain writing standards. --- AGENTS.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 72f480b..d741286 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,8 +6,9 @@ Always review in Japanese. ## document / comment -レビューコメントやドキュメントなど日本語の文章を書くときは、`.claude/skills/japanese-tech-writing` の文章規範に従う。 -読み物として読ませたい解説文を書くときは、あわせて `.claude/skills/cognitive-rhythm-writing` の緩急の規範を用いる。 +コメントやドキュメンテーションなど日本語の文章を書くときは下記を読む + - .claude/skills/japanese-tech-writing + - .claude/skills/cognitive-rhythm-writing ## github