jp-writing
Skill1 starsChanged 5 days agoMITView on GitHub
日本語の文章規範。README・技術記事・Zenn・リポ内解説など、日本語で Markdown や文書を新規に書くとき、または既存文書をリライト・推敲するときは必ず適用する。冗長の排除、LLM口調・翻訳調の禁止、型の反復禁止、視点と語りの一貫性、文の組み立てと読点、リライト時の意味の保持と一律適用の禁止を定める。
In this repository14 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- consolidate-rulesSkill
- guarantee-auditSkill
- local-issueSkill
- md-writingSkill
- memory-writeSkill
- mermaid-diagramSkill
- module-devSkill
- mvp-docsSkill
- nix-tool-installSkill
- pr-workflowSkill
- repo-shipSkill
- skill-devSkill
- sops-secretsSkill
The file
Files
jp-writing
日本語の Markdown・文書を書く/直すときに常に適用する文章規範。README・技術記事・Zenn・リポ内の解説 Markdown を主対象とする。ソースコード内(.astro, .tsx 等)の日本語にも同じ規範を適用する。
使い方
- 執筆時: 後述の規範に従って書く。プロジェクトの CLAUDE.md や
context/に書き方の規約があれば先に読む。書き終えたら「執筆後の点検」を行う。 - リライト時: 規範に照らして修正する。「リライトの作法」に従う。
- Zenn リポ(
articles/が存在する): 修正を終えた記事のフロントマターにwriting-reviewed: trueを付ける。すでに付いている記事は対象外。
リライトの作法
デフォルトは keep(直さずに残す)で、直すのは、その箇所を直すことで読者の得が具体的に言える場合だけにする。ただし、この既定は他人が書いた文と、今回の作業より前からある文に当てる。自分がいま書いた文は、規範をすべて当てて直す。
個々の修正が正しくても、同じ変換を全箇所へ一律に当てると、その処理の均質さ自体が新しい機械臭になる。元の文書が持つ自然な不揃い(節ごとの濃淡、口語の引用、表記の癖)は欠陥ではなく資産であり、実際に読解を妨げている箇所だけを整える。
やらないこと
- 著者の主張・論旨を変えない。変えるのは表現だけ。次の3点も、直す前と後で同じに保つ
- 比重: 否定していたものを並列(Aに加えてB)や順位づけ(AよりB)に変えない。差や比較を述べる文で、何と何を比べているかを示す語句を削らない
- 言い切りの強さ: 断定・推量・可能性に加え、許可(〜してよい)・能力(〜できる)・義務(〜しなければならない)・保証(必ず〜する)の言い方を変えない。仕様の文書では、この違いがそのまま仕様の違いになる。「含めてよい」を「含める」にしない、「〜場合がある」を消して言い切らない、「必ず」を足さない
- 文の種類: 伝聞を断定に、意見を事実に、依頼を説明に、仮定を予定に、例えを言い切りに変えない
- 原文と文脈にない動作主・原因・条件・数値・例を足さない。とくに、原文にない人や担当(担当者・通知先・書き手の一人称)を、主語や知らせる・頼む相手として足さない。ぼかした語を、より狭い具体的な事実へ勝手に置き換えない
- 著者の意図・方針を新設しない。元文書が未解決のまま置いている論点に見解を書き足さない。本文の「未定」を断定に格上げしない
- 判断に迷う箇所(意図的な表現か規範違反か区別できない)は修正せず、報告に回す
- コミット・push はしない。変更はワーキングツリーに残し、ユーザーの指示があったときのみ行う
報告
修正後に以下を報告する:
- 修正した箇所と理由(規範のどのルールか)
- 迷って手を付けなかった箇所(あれば)
- Zenn 記事の場合:
writing-reviewed: trueを追加した旨
規範
文体
- 新規執筆時の文体は文書の種類で決める。
- README・
docs/などリポ内の文書: 地の文も箇条書きも「である」調で揃え、1つのリポの中でですます調と混ぜない。読み手が複数いて、文書が長く残るためである。既存の公開リポの README もこの形で揃っている - 技術記事(Zenn など): 地の文を「ます」調、体験談や所感を「る」調にする程度の自然な混合にする
- README・
- リライト時は、元の文書の文体に従う。ただしリポ内の文書でですます調が混ざっていれば、「である」調へ揃える。
文末と文の働き
主語を省いた日本語では、文末が「誰が動くか」と「決まりか、勧めか、説明か」を伝える。文末は、文書の行き先と読み手から立場を決めて選ぶ。分野の名前(技術記事・仕様)だけでは立場を決めない。
- 決まり(運用ルール・手順書・仕様): 「〜しましょう」「〜ことが重要である」が決まりそのものを書いているなら「〜する」にそろえる。理由を述べる文と「〜してください」は残す。
- 勧め(心得・助言): 読み手への助言を、書き手の予定に見える「〜します」「〜しておきます」で書かない。
- 説明(技術の説明・報告): 書き手の予定や、実施済みの変更はそのまま書く。
立場が決まっても、すべての文末を同じ種類にはしない。助言の文書の中でも、道具の動作を説明する文は説明のまま書く。「〜しましょう」と「〜してください」のような、同じ立場の中の強さの差も変えない。語尾の単調さを散らすために、文の働きや時制を変えない。
変更を報告する文(PR の本文・CHANGELOG・作業の報告)では、次を守る。
- どの設定・実装・方針をどう改めたかを、述語まで書く。「方針を改定した」と宣言して、新しい方針を並べるだけで済ませない。
- 完了した変更を、予定に見える「〜する」で書かない。逆に、現在の動作や仕様の説明まで過去形にそろえない。
- 変えたと分かることだけを変更として書く。改定前の内容が分からなければ、前後の比較や改善の幅を作らない。現在の動作しか分からない記述を、今回導入した・維持したと書き換えない。
- 現在の方針を述べるときは、書き手の作業予定と読み違えない形(「〜する方針である」「〜するよう設定している」)にする。システムの動作(「〜を返す」)、機能(「〜できる」)、依頼(「〜してください」)、予定(「〜する予定である」)は、それぞれの形で書く。
整形
- 段落の区切りは空行で示す。
- 段落内では、意味の区切りで改行してよい。一文ずつ機械的に改行しない。ベタ書きもしない。改行位置は書き手の判断に委ねる。
- コード、設定ファイル、ログの断片はコードブロックで示す。
- 定義や分類の列挙は箇条書きで示してよい。定義される用語は太字にする。
- ダッシュ(
—、――)を日本語の地の文で使わない。補足は括弧()に、言い換えは読点か句点で処理する。 - 補助動詞と形式名詞の「事」「為」はひらがなで書く(実行してください・指定できます・試してみる・することが・するために)。「事の経緯」のような中身のある名詞は漢字のまま書く。それ以外の表記の揺れ(長音・送り仮名)は、リライトでそろえない。
冗長の排除
- 同じ主張を言い換えて繰り返さない。
- 場面や例を示した直後に、その内容を要約し直さない。意味づけの一文だけを置く。
- 接続や評価のためだけの文(「それ自体はよいことである」など)を置かない。
- 読者が自力で補える中間段階の説明は書かない。
- 想像上の読者との問答を修辞として使わない。主張はそのまま述べる。
- 「重要なのは〜である」のような前置きで主張を予告しない。主張をそのまま書く。前置きが評価そのものを担っているときは、評価を消さずに述語へ移す(「〜が重要である」)。
- 「この状況を解決するために」のような、次に書く内容を予告するだけの文は省く。
- 読み手が思いそうなことを先回りして認めるだけの「もちろん、〜。」の短い文を書かない。「もちろん、」のあとに同じ文で具体的な内容が続く文と、問いへの答えの「もちろんです」は残す。
- 書き手が AI に出した指示が本文に残った文(「今回は一般論ではなく、自分の体験に絞って紹介します」「ここでは専門用語を使わずに振り返ります」)は、指示の部分を削る。読者のために扱う範囲や前提を示す文(「この手順書では、退職の手続きは扱わない」)は残す。
LLM口調の禁止
次のような言い回しは、中身のない型である。使わない。自分がいま書いた文では、挙げた語が1回でも出たら書き直す。他人の文と既存の文では、単体では日常語のものもあるため、頻度と文脈で判断する。
書き直すときは、語を近い語へ差し替えて済ませない。差し替えた先も中身のない言い方(「良いほうに働く」「役に立つ」「ポイントになる」)になりやすい。何がどう変わるのか、誰が何をするのかを書く。原文と文脈から中身が分からなければ、推測で足さずに報告に回す。
- 予告と総括: 「本記事では〜を扱う」「それでは見ていきましょう」「ここまで見てきたように」「まとめると」「要するに」「結局のところ」「総じて」(直前の言い換えだけのとき)、「〜に他ならない」。本文の繰り返しだけの「まとめ」の節も同じ
- 前置きの言い回し: 「結論から言うと」「正直に言うと」「大切なのは」「ポイントは」「面白いのはここである」「驚くべきことに」(主張の前に置く合図だけの句。主張をそのまま書く)
- 文末の付け足し: 「〜というわけである」「〜と言っても過言ではない」「〜と言えるだろう」(論旨を足さずに文を締めるだけの型)
- 定型の結びとチャットの名残: 「いかがでしたか」「ぜひ試してみてください」「参考になれば幸いです」「必要なら次に〜する」「ご希望があれば〜できる」(文書の中に、読み手への挨拶や会話の受け答えを残さない)
- 空虚な形容: 「不可欠」「核心的」「鍵となる」「根本的な」「多角的」「包括的」「本質的」(「本質を捉えた」「本質的な判断」も同じ。何が主かを書くか、「主な」「大きな」で足りる)
- 空虚な動詞: 「掘り下げる」「深掘りする」「踏み込む」「言語化する」「落とし込む」「紐解く」(何をどう調べた・書いた・決めたかを示さず終わる)
- 具体を装う語: 「解像度を上げる」「手触り」「肌感」「温度感」「熱量」「体温」「血の通った」「腹落ち」「余白」「自分なりの軸」(何をどこまで調べた・決めた・書いたかを書かずに済ませる型。その中身を書く)
- 評価を装う比喩: 「土台」「主役」「両輪」「〜のカギ」「〜への近道」「〜の第一歩」「勝ち筋」「定石」「刺さる」「地に足のついた」「これは強い」(何がどう役立つのかを書かずに評価だけを置く型。何に使えて何が変わるのかを書く。土台・基礎工事のような文字どおりの用法は残す)
- 「効く」: 「〜に効く」「ここが効く」「地味に効く」「効いてくる」「効き目」「効かせる」。何がどう良くなるのかを書かずに済ませる型である。規則やフラグの適用範囲を言う「常に効く」も、「常に適用される」「〜にだけ当たる」と書く。薬や味など文字どおりの効き目は残す
- 現象をぼかす比喩動詞: 「壊れる」「崩れる」「潰す」「痩せる」「共倒れする」「〜側に倒す」「時間を溶かす」「例外を逃がす」「〜に収斂する」を比喩で使い、実際に何が起きるかを書かない型。起きることの語で書く(拒否される・記録されない・一覧から落ちる・成績が一斉に落ちる・除外する)。本文で現象を説明しているなら、比喩をその語に置き換えられないか見る。比喩のほうが事実より強くなっていることがある(「同時に書くと壊れる」と書いたが、実際は片方の書き込みが拒否されるだけ、など)。文字どおりの破損(「JSON が壊れる」)と、文書内で定義済みの言い方は残す。言い換えても、元の語の含み(「うっかり」の不注意、「ようやく」の待ちくたびれた感じ、「〜てしまった」の後悔)は残し、原文より強い確度の語(確実に・必ず)を足さない。「骨が折れる」「手を焼く」のような定着した慣用句は残す
- 中身を伏せる「出る」「読む」: 結果や判定が決まることを「出る」(「出るもの」「段階が出る」「次に何をするかが出なくなる」「実力より下に出る」)、判定する・材料にする・分かることを「読む」(「能力で読む」「同じ記録を読む」「定義から読める」「この表から読めること」)と書く型。何が決まるのか、誰が何で判定するのかを書かずに済ませる。「決まる」「付く」「分かる」「判定する」「材料にする」など、起きることの語で書く。文書やファイルを文字どおり読む文、画面やエラーに表示される意味の「出る」、定着した「読み替える」は残す
- 大げさな名詞: 決まりや方針を「契約」、確認の手順を「ゲート」と呼び、何を区別するのかを書かずに「境界」と呼ぶ型。「ルール」「方針」「確認」「チェック」など実際の役割の語か、何と何を分けるかで書く。取引の契約・数学や区域の境界・製品名の品質ゲートと、文書内で定義した術語(「正本」「保証台帳」など)は残す
- 抽象物を指す比喩の名詞: 評価の基準を「物差し」、判断の材料や情報の出どころを「源」、例に挙げる人物や目指す状態を「像」(「〜のための像」「揃った像」「到達像」)と呼ぶ型。何を測る基準か、何を読むのか、誰や何を指すのかを書かずに済ませる。「評価基準」「成果物」「記録」「架空の人物」「到達点」など実物の名前で書く。「データ源」「電源」「全体像」のような定着した複合語と、文字どおりの物差しや像は残す
- 「穴」: 書き込む欄や未記入の箇所を「穴」(「穴を埋める」「穴埋め」「穴のまま残す」)、足りないものを「〜が埋める穴」と呼ぶ型。何をどこに書くのか、何が足りないのかを書かずに済ませる。欄なら「
<...>の欄」「書き込む箇所」「未記入の欄」、不足なら「足りないもの」「欠けている記録」のように実物の名前で書く。文字どおりの穴と、試験の「穴埋め問題」は残す - 「札」: 画面の小さな表示やタグを「札」と呼ぶ型(「スキルの札」「名前を示す小さな札」)。何の部品かが伝わらない。「ラベル」「タグ」「バッジ」のような通用している呼び名で書く。「切り札」「捨て札」のような定着した慣用句と、紙幣や改札の札は残す
- 姿勢だけの宣言: 「正面から扱う」「正面から論じる」(何をどう論じるかが一切増えていない。扱う内容そのものを書く)
- 弱い緩和: 「〜と言えるだろう」「〜かもしれない」「〜のではないでしょうか」(根拠なく主張を弱めている場合のみ削る。推量・仮定・読者の疑念を表す場合は残す)
- 予防線の積み上げ: 「一概には言えないが」「あくまで一例だが」(頻出すると何も言っていない文章になる。言い切れないなら条件を具体的に書く)
- 空虚な強調と誇張: 「非常に」「極めて」「大いに」「圧倒的」「爆速」「革命的」「徹底解説」。数値や比較があるならそれを書く
- 決まり文句と名詞化: 「シームレス」「シナジー」「価値を最大化」「〜を担保する」「〜を図る」「〜に資する」「〜を実施する」「〜を行う」「〜が可能である」。「確かめる」「〜できる」のような動詞で書く。何が保証されるのかが原文から分からなければ、効果を推測で足さずに報告に回す
- 機械的なつなぎ: 前後に因果がはっきりしないのに置く「これにより」。前の文の動作から後ろの結果が生じると読めるなら残す
- 無理な三点整理: 「大きく分けて3つの」と先に数を決めてから列挙する型。論点の数だけ書く。
翻訳調の禁止
日本語として成立していても、英語の構文を透かして見える言い回しは避ける。
- 「〜することができる」(can の直訳): 可能形か「〜できる」に。「〜することが可能です」も同様。
- 「〜することによって」(by ~ing の直訳): 「〜すると」「〜すれば」に。
- 無生物主語 + 他動詞: 「この事実は〜を示している」→「この事実から〜と分かる」。主語を人や状況に戻すか、述語を状態描写に変える。直すのは、概念や道具に意志や感情があるように書いた文(「コードが語る」)と、人の判断を抽象名詞の作用のように書いた文(「見積もりの甘さが判断を遅らせた」)である。後者を人の行動に戻すのは、誰の行動か原文から分かるときに限る。道具や仕組みの動作を述べる文(「このツールはログを集める」)は残す。
- 「〜という観点から」「〜という点で」: 「〜で見ると」「〜については」で足りる場面に機械的に挿入しない。
- 「〜を持つ」(抽象名詞が目的語のとき): 「この決定は大きな意味を持つ」→「この決定には大きな意味がある」。
- 「静かに〜」「黙って〜」(silently の直訳): 「静かに間違える」「黙って消える」→「気づかないうちに間違える」「知らないうちに消える」。「エラーを出さずに」「警告なしに」と仕組みの話で書くのは、エラーや警告が出ないと前後から分かるときに限る。
- 「〜した瞬間」(the moment の直訳): 時点を言うだけなら「〜した時点で」「〜するとすぐ」に。物理的な一瞬(「扉を開けた瞬間」)や、タイミングの細かさ自体が要点の場合は残す。
- 「唯一の真実」(single source of truth の直訳): 「正本」と呼ぶ。
- 「指紋」(fingerprint の直訳): 「画面の指紋」「設定の指紋」。変化を見分けるための値なら「ハッシュ」と呼び、何から取った値かを書く(「画面を決めるファイルの差分から取ったハッシュ」)。何かを特定する手がかりという意味なら、何が特定されるかを書く(「デバイス構成を特定する手がかりになる」)。生体の指紋は残す。
- 英語の短い術語に当てた漢字1字: 「今回の版」(version)、「一覧の頭」(head)、「lint の印」(mark)。段(stage・tier)、窓(window)、帯(range・band)、床(floor)、口(port・endpoint)、門(gate)、旗(flag)、系(series・system)、組(set・pair)、枠(frame)、箱(box)も同じ型になりやすい。その分野で定着した呼び名(バージョン・先頭・冒頭・指摘・マーカー・ステージ・ウィンドウ・範囲・下限・フラグ など)で書き、何を指すか決まらなければ本文を残して報告に回す。出版物の版(第2版)、記号の印(×印・目印)、体の部位や慣用句に使う頭(頭が痛い・頭に入れる)、「3段の棚」「窓を開ける」のような文字どおりの使い方は残す。
- 実物の代わりに置いた場所のたとえ: 「入口」「受け口」「〜先」で実物の名前(エンドポイント・URL・関数)を書かずに済ませる型。名前を書く。「駅の入口」「パッケージの依存先」のような定着した言い方は残す。
- 直すかどうかは、その分野の人が仕様や手順書に自分で書くときにその言い方を選ぶか、英語に戻すと一語ずつ英語に対応するかで問う。語を1つ差し替えるだけで済ませず、誰が何をどうするかが読める文に書き直す。
視点と語り
- 対象を指す語は具体的に選ぶ。「AI」「ツール」のような広い語でぼかさない。記事内で名前がある対象は名前で呼ぶ。
- 術語・固有名を導入したら、以後はその語で通す。曖昧語に後退しない。
- 内輪の呼び名や比喩を術語にしない。その語だけを見て、初めて読む人が中身を言えないなら、中身をそのまま書く。術語として入れるなら、初めて出るところで何を指すかを書く。
- 技術用語は和語の比喩に置き換えず、通用している呼び名で書く。git の branch は「ブランチ」と書き、「枝」と呼ばない。
- 例示では、結果の羅列や受動態ではなく、行為者を主語にした動作で書く。
- 「入社2年目のエンジニアが」のような架空の人物設定を無意味に冠しない。
文の組み立てと読点
- 主語の「が」、短い目的語の「を」、主題の「は」「も」「には」「では」「とは」の直後に、間を作るだけの読点を打たない(「応答は、〜」「古いキャッシュが、重複して読み込まれる」)。リライトでも外す。
- 次の読点は残す: 主題のあとに別の動作主が続く所(「会議では、担当者が説明した」)、長い主語や節のあと、挟み込みの句の前、並んだ語句の区切り、外すと掛かり先が変わる所(「店長は、慌てて逃げた客を追いかけた」)。
- 次の位置で間を作るだけの読点も外す: 列挙の先頭の「1つ目は、」、「AではなくB」の「なく、」、見出しの中、スライドで1行に収まる箇条の中。見出しは「AではなくB」の形にせず、Bだけを書く。
- 長いことだけを理由に文を分けない。原文で1文に書いた目的や理由を後ろへ切り出して、「〜ためである。」「〜からである。」の短い文を新しく作らない。
- 他動詞の連用形を1語だけ名詞にした語を「の」で受けない(「結果の確かめ」「二つの案の比べ」)。「結果を確かめる」と文に戻すか、「結果の確認」のように定着した漢語にする。漢語を和語にひらくときに出やすい。定着した語(資金集め・見直し・組み合わせ)は残す。
- 主題「〜は」「〜では」は文末まで掛かって読まれる。後半の節が主題とは別のものの動作なら、後半の冒頭にその主体を書く(「上長が差し戻した場合、システムが通知する」)。どの主題の話か原文から決まらなければ、主体を足さずに報告に回す。
型の反復禁止
- 同じ鋳型を3回続けない。定義文の型(「Xは〜ではない。〜である。」)、文の書き出し(数字→数字→数字)、文末の形(体言止めの連続、「〜だ。〜だ。」)のいずれも、3回目は入り口か構造を変える。
- 「〜ではなく、〜」の否定→肯定対比は、読み手が実際に誤解していそうな場面に限る。単なる言い換えの強調に使わない。見分け方は、対比の後半だけで文が成立するかどうか。否定を残す場合も、2文に分けた形(「必要だったのは新しい道具ではない。使い方をそろえることだった。」)は、「〜ではなく、〜」の1文にまとめる。
- 段落あたりの文数・厚みを揃えない。重要な節は厚く、軽い節は正直に軽く書く。全節が同じ厚みに見える構成は、それ自体が機械臭になる。
演出の節度
全面禁止ではなく、節度の規範。
- 太字強調を多用しない。誤読を防ぐ否定や帰結など、論理の要所に限る。
- 太字の両端に句読点や括弧を置かない。
**の外側に和文が続くと GitHub では太字にならず、**がそのまま出る。句読点や括弧は**の外に出す(**〜する**。、「**〜**」)。 - 短い決め台詞を独立段落にする演出は、記事の山場に限る。
- 「〜してはならない」より「〜するわけにはいかない」のような判断の形を選ぶ。
- 慣用表現をひねった比喩や、指す内容が一意に決まらない比喩を使わない。平易な動詞でそのまま言う。
執筆後の点検
- スケルトン通読: 見出しと各段落の先頭文だけを抜き出して読み、論旨が通るか確かめる。細部を読み直すより構成の乱れを見つけやすい。
- 素材不足の判別: 段落から固有名詞・数値・実例をすべて抜いても文意が変わらないなら、それは一般論止まりのサインである。原因は書き方でなく素材の不足にあり、言い回しの修正では解決しない。素材を集め直すか、ないなら空欄・要確認として残す。
- 見出し・太字と本文の照合: 見出しや太字の一文を、それを説明する本文と突き合わせる。短く言い切る位置ほど比喩が強くなり、本文の事実からずれやすい。
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

