japanese-document-writing

name	japanese-document-writing
model	sonnet
description	日本語の技術文書を執筆、翻訳、推敲するときに、Bajutsuの日本語文章規範を適用する。document-writingと併用する。

日本語の技術文書の文章規範

日本語で技術的な原稿（書籍の章、記事、解説文）を書く・推敲するときは、本スキルの規範に従う。

本スキルは、言語に依存しない執筆規範 document-writing の下位に位置する日本語レイヤーである。同じ傘の下には、対になる英語レイヤー english-document-writing がある。日本語の散文を書くときは document-writing と本スキルの両方を適用し、重なる部分（冗語、重複、演出の抑制）は本スキルの記述を 優先する。上位規範は、上から下への推敲、文の強調位置、主語と述語の近接、能動態といった、言語に 依存しない技法を定める。

規範の読み込み

規範の本体は references/ に置いた3つのファイルに分かれている。執筆、翻訳、推敲の いずれであっても、書き始める前に3つとも読む。

• references/formatting.md：整形と見出しの付け方
• references/argument.md：段落の構成、論証の厳密さ、読み手の負荷の管理
• references/expression.md：視点と語り、演出の抑制、LLM 口調の排除、冗長の排除、読者への誠実さ

必要になった段階で1つずつ読む形は採らない。どの手順がどの規範を必要とするかという対応が規範の側に なく、一部だけを適用したまま規範に従ったつもりになれてしまうからである。

文章を書き上げたら、規範による推敲に加えて、textlint による 機械的な検証を必ず通す。手順と、指摘がすべて消えるまで推敲を繰り返す約束は、末尾の 「推敲後の textlint 検証（必須）」に置く。 相反する規範については、textlint のルールを優先する。

文体（敬体・常体）

文書の種別で文体を選ぶ。このリポジトリのドキュメント（docs/ja/）とロードマップ項目（*-ja.md）は、 敬体（ですます調）で書く。常体（だ・である調）は使わない。書籍・記事の原稿は、その媒体の慣例に従う （多くは常体）。どちらの場合も、1つの文書のなかで敬体と常体を混在させない。敬体にするのは文末の述語だけで、 連体修飾節や接続・条件の形（「〜する場合」「〜すると」「〜であり」）は常体のままにする。見出しや純粋な 体言止めのラベルには繋辞を付けない。

一文を短く、読点を絞る

このリポジトリのtextlintは、1文の長さと読点の数にも上限を課す。ja-technical-writing/sentence-lengthは、 1文が100字前後を超えると指摘する。ja-technical-writing/max-tenは、1文の読点が4つ以上だと指摘する。 上から下へ推敲を進めるときは、最初から短い一文で書く。読点も少なく抑える。「〜であり、〜のため、〜する」 のように節をいくつもつなぐ文は、分割の対象である。複数の文に分けるか、箇条書きに置き換える。

同じ助詞を1文の中で2回使うと、ja-technical-writing/no-doubled-joshiが指摘する。「に」「も」「にも」が 典型である。「AとBのどちらにも」のように言い換えれば、並列強調の意味を保ったまま指摘を避けられることが 多い。

推敲後の textlint 検証（必須）

textlint による機械的な検証は、英語・日本語のどちらの文章にも共通の実行環境として document-writing スキルに一本化されている。インストール、実行コマンド、--fix の扱い、ルールの変え方は、すべて そちらに書いてある。

書き上げた日本語は、最後に必ず textlint にかけ、新たな 指摘を持ち込んでいないことを確かめる。基準はゼロではなく、手を付ける前のそのファイルの指摘数 である。ゼロを基準にしないのは、それが到達できない数だからで、届かない目標は誰も狙わない。 マージ済みの項目はいずれも指摘を抱えており、BE-0390 の日本語側は77件、BE-0376 は59件を返す。 しかも BE-0390 の77件のうち69件は no-mix-dearu-desumasu で、これは箇条書きを である調 にせよと 要求する。CLAUDE.md が *-ja.md に義務づける敬体と、そもそも両立しない。

箇条書きを含め、文書全体を敬体で統一する。 地の文だけを敬体にして箇条書きを体言止めや常体で 書くと、この規範と textlint の双方に反する。統一した結果として残る no-mix-dearu-desumasu の 指摘は、直さずに残す。文体の規範は CLAUDE.md が定めるものであって、textlint のルールはその下に 立つ。

手を付ける前から在った指摘は、自分の担当範囲の外にある。消そうとすると差分が広がるので残す。 新規に起こしたファイルには「手を付ける前の指摘数」が存在しないので、この基準は当てはまらない。 ゼロと読み替えると、ここで退けたはずの到達不能な基準が戻ってくる。代わりに既存の項目と比べる。 分量の近いマージ済み項目を2、3件 textlint にかけ、同じ桁に収まっていれば良い。BE-0376 の日本語側は 59件を返すので、新規の項目がその近辺なら妥当であり、数倍に達しているなら直すべき問題が実際にある。 textlint はあくまで機械的な下限であって、これを通しただけで上の規範を満たしたことにはならない。 文体以外で規範と textlint が相反するときは textlint を優先し、指摘は設定を緩めてではなく散文を 直して消す。設定ファイル tools/textlint/.textlintrc.json は、 日本語の技術文書向けの定番プリセット textlint-rule-preset-ja-technical-writing を含む、日本語 向けのルールを有効にしている。