natural-japanese
仕事の日本語文書を、自然で読みやすく、わかりやすい日本語で書く・直すためのスキル。議事録、調査レポート、顧客向けのレポート、社内ガイド、技術記事、PR の説明文、リサーチメモ、企画書、メール、スライド構成などの作成や推敲と、note やブログ、エッセイの執筆に使う。文字起こしから議事録を作るときにも使う。自然な日本語にしたい、読みやすくしたい、簡潔にしたい、結論から書きたいといった依頼のほか、読みづらい、わかりにくい、何を言っているかわからない、AI っぽい、AI 臭い、英語の直訳っぽい、日本語として不自然、違和感があるといった指摘にも使う。書き換えずに AI らしさを判定・採点してほしいという依頼や、自分の文体を学ばせたいという依頼にも対応する。
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
natural-japanese
AI に書かせた仕事の日本語を、読みやすく直す Agent Skill です。議事録、レポート、技術記事、PR の説明文などを、新しく書くときにも使えます。
English summary: An Agent Skill that makes AI-written Japanese work documents read naturally. It never adds facts, opinions, or certainty that the original did not have.
直すとこうなる
何のことか分からない言い回しを、ふだんの言葉に
| 元の文 | 直した文 |
|---|---|
| ジョブが見たいのは「まだ決着していない行」だけ | ジョブが見たいのは、チェックインも取り消しもされていない行だけ |
| リマインドの失敗は握りつぶしていません。 | リマインドの Slack 送信が1件でも失敗すると、同じ回の取り消しが実行されません。 |
AI が書いた技術記事と PR の説明文を「読みやすくして」と直させた実際の出力から、うまく直った例を選んでいます。2行目の元の文は、失敗をきちんと扱っているように読めます。その文書の本文に書いてあったのは、1件の失敗で取り消しまで止まるという不具合でした。
元にないことは足さない。確信の度合いも変えない
調査レポートを、同じメモから Claude Opus 5.5 に書かせた例です。メモには、解約が増えた理由について未検証の見立てが2つ書いてありました。
| 書いた文 | |
|---|---|
| スキルなし | 3月に始めたライトの初月無料キャンペーンとの関係が強く疑われますが、まだ確かめられていません。 |
| スキルあり | チームからは、次の二つの見立てが出ている。どちらも未検証である。 |
スキルなしは、2つの見立てに触れながらも、結論ではキャンペーンとの関係を「強く疑われます」と書いています。スキルありは、メモのとおり2つを並べ、どちらも未検証と書いています。
太字を重ねない
5種類の文書について、種類ごとに同じ素材を5つのモデルに渡して書かせました。太字は、スキルなしの25本で551か所、スキルありの25本で13か所でした。
使い方
Claude Code・Cursor・Codex など、skills が対応するエージェントでは、次のコマンドでインストールできます。
npx skills add coji/natural-japanese
画面の案内に従って、インストールするスキルと利用するエージェントを選んでください。詳しくは skills CLI の説明 を参照してください。
あとは、エージェントに「読みやすくして」「議事録にして」「AI っぽいところを直して」のように頼むだけです。書き換えずに自然さの点数(0〜100)と理由だけを知りたいときは、/natural-japanese score <ファイル> を使います。
バージョンごとの変更点は Releases にあります。
Cursor プラグインとして入れる場合:
Cursor Marketplace での公開は審査待ちです。公開後は Marketplace で natural-japanese を探してインストールできます。公開前にローカルで試す場合は、リポジトリのルートで次を実行します。
rm -rf ~/.cursor/plugins/local/natural-japanese
mkdir -p ~/.cursor/plugins/local/natural-japanese
cp plugin.json ~/.cursor/plugins/local/natural-japanese/
cp -R skills ~/.cursor/plugins/local/natural-japanese/
そのあと Cursor を再起動するか、Developer: Reload Window を実行してください。Customize を開くと、natural-japanese が Skills に表示されます。
AGENTS.md を経由してスキルを読み込ませる場合は、OpenSkills も使えます。
npx openskills install coji/natural-japanese
npx openskills sync
Claude Code プラグイン:
/plugin marketplace add coji/natural-japanese
/plugin install natural-japanese@natural-japanese
手動で入れる場合は、Releases から natural-japanese.skill(critical-thinking も使うなら critical-thinking.skill も)をダウンロードし、エージェントのスキルディレクトリに展開してください。
直すときに守ること
元の文書にない事実・数値・意見・方針は足しません。確信の度合いも変えません。「次回また相談する」を「合意した」にすると、書き手が言っていないことを書き手の言葉として伝えてしまうからです。直したあとは元の文書と並べて、足した内容がないかを確かめます。
苦手なこと
- 英語の言い方を1語ずつ訳した熟語や、動作を名詞にまとめた言い回しは、半分ほど見逃します。書いたモデルにも直すモデルにも、自然に見えるためです
- effort(モデルが推論にかける量の設定)を下げると、手順の一部を省いて見逃しが増えます。選べる環境では high を使ってください
決裁者の目で見て直す(critical-thinking)
同じリポジトリに、文書の「考え」を決裁者の目で検査して直すスキル critical-thinking が入っています。natural-japanese が日本語を直すのに対し、こちらは中身を見ます。対象は稟議書、提案資料、企画書、報告書のような、読んだ人に何かを決めてもらう文書です。評価は、欠陥を仕込んだ架空の稟議書・障害報告書・コンサルの提案資料・社内の制度企画で行っています。
/critical-thinking 稟議書.md # 全工程。検査して3つまで聞き、直した文書と、端的にした版・組み直した版を作る。full と同じ
入口はこの1つです。文書の中で答えが出ること(矛盾、計算、言い切りの強さ、並びのねじれ)は聞かずに直し、書き手にしか答えられないこと(文書にない事実、決めてもらうことの読み、頼む範囲)だけを3つまで聞いて、答えを本文に入れます。「分からない」と答えた問いは本文を仮定の形にし、残りの問いと合わせて文書とは別のファイル 稟議書.確認事項.md に出します。直した文書には印も確認事項の節も入らないので、そのまま出せます。書き手の代わりに決めず、本編を元より長くしません。
/critical-thinking logic 稟議書.md # 文書の中で筋が通っているか。矛盾・根拠のない主張・事実と推論の混在・並列のねじれ
/critical-thinking somosomo 稟議書.md # そもそも前提は合っているか。他の選択肢・覆る条件・誰のための何か
/critical-thinking fix 稟議書.md # 検査の指摘を反映して直す
/critical-thinking short 稟議書.md # もっと端的に。detail なら、もっと丁寧に
/critical-thinking rebuild 稟議書.md # 構成から組み直す。構成案を出して選んでもらう
logic と somosomo は文書には一文字も書き込まず、行番号つきの問いと <ファイル>.logic.yaml を返します。直すかどうかは書き手が決めます。検査は LLM の読みに頼るため、同じ文書を2回かけると指摘は揺れます。
「もっと端的に」「もっと丁寧に」と頼むと、検査で書き出した論理構造(主結論、論点、論拠、根拠の重み)をどの深さまで本文にするかを決めて書き直します。端的は、主張と決裁に要る根拠だけを本編に残し、裏づけは付録に移します。事実と数値は落とさず、矛盾も直さず、主結論と決裁事項は変えません。AI の書いた 3,000〜4,700 字の文書で、本編は 35〜46% になりました。検査のあとで「指摘を反映して直して」と頼むと、答えられる問いは本文で直し、答えられない問いは別ファイルの確認事項に回します。「構成から組み直して」と頼むと、事実と頼む中身は保ったまま論の背骨だけを替え、構成案を2〜3つ出して書き手に選んでもらってから書きます。案のうち1つは必ず「頼む中身を小さくする案」で、検査の問いが決裁事項の前提を疑っているとき、どの問いの答えで元の頼みが倒れるかを示したうえで、縮める・分ける・先に確かめる・取り下げるのどれかを置きます。この案は書き手にしか選べないので、スキルは勝手に選びません。AI に下書きを任せた人は構成を自分の頭に持っていないことが多いので、別の組み立てを見せるのはこの工程の仕事です。
仕組み
疑わしい箇所は lint.py が形態素解析(sudachipy)で検出し、直すかどうかはエージェントが文脈を見て決めます。AI は自分の書き癖に気づきにくいので、検出を機械に任せています。規則と手順はすべて SKILL.md にあります。
uv があれば、スキルを通さずに実行できます。
uv run skills/natural-japanese/scripts/lint.py draft.md # 疑わしい表現と直し方
uv run skills/natural-japanese/scripts/lint.py draft.md --genre tech # 技術文書向けの基準で
uv run skills/natural-japanese/scripts/lint.py draft.md --reading-load # 長すぎる文、続きすぎる漢字など
uv run skills/natural-japanese/scripts/outline.py draft.md # 見出しと各段落の先頭文
uv run skills/natural-japanese/scripts/terms.py draft.md # 専門用語の初出と説明の有無
uv run skills/natural-japanese/scripts/paragraphs.py draft.md # 段落ごとの確認用の一覧
uv run skills/natural-japanese/scripts/calques.py draft.md # 仕組みを場所にたとえた名詞と、機械の処理に当てた動詞の候補
uv run skills/natural-japanese/scripts/newfacts.py original.md revised.md # 直した文書にだけある数値・固有名詞
スクリプトを変えたときは、./dev/check-fixtures.sh で回帰テストを実行してください(git config core.hooksPath .githooks を設定すると、コミット時にも実行されます)。
参考にした資料
- AI臭さを消した日本語執筆エージェントの設計(なつ「いとおり」):機械による検出と文脈による判断を分ける考え方
- 日本語技術文書の文章規範(k16shikano):LLM に特有の空虚な言い回しの分類
- meiseki(bamboo-nova):機械検出と LLM による推敲の組み合わせ方
ライセンス
MIT ライセンスです。詳しくは LICENSE を見てください。
// HOW IT'S BUILT
// FILES
19 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
skills/natural-japanese/SKILL.md51 KB7c16ce6f53aetruncatedupstream ↗
Showing the inlined prefix. The rest is in the upstream file.
--- name: natural-japanese description: 仕事の日本語文書を、自然で読みやすく、わかりやすい日本語で書く・直すためのスキル。議事録、調査レポート、顧客向けのレポート、社内ガイド、技術記事、PR の説明文、リサーチメモ、企画書、メール、スライド構成などの作成や推敲と、note やブログ、エッセイの執筆に使う。文字起こしから議事録を作るときにも使う。自然な日本語にしたい、読みやすくしたい、簡潔にしたい、結論から書きたいといった依頼のほか、読みづらい、わかりにくい、何を言っているかわからない、AI っぽい、AI 臭い、英語の直訳っぽい、日本語として不自然、違和感があるといった指摘にも使う。書き換えずに AI らしさを判定・採点してほしいという依頼や、自分の文体を学ばせたいという依頼にも対応する。 license: MIT argument-hint: "[write|score] [quick|full|exp(score のみ)] [対象ファイルや依頼内容]" --- # natural-japanese 仕事の日本語文書を、読みやすくわかりやすく書く・直すためのスキル。議事録・調査レポート・社内ガイド・リサーチメモ・スライドといった仕事の文書から、技術記事・PR の説明文・note・ブログ・エッセイまでを扱う。AI らしい書き癖を取り除くことも含む。 疑わしい箇所の検出は `scripts/lint.py` が機械的に行い、直すかどうかはあなたが文脈を見て決める。AI は自分の書き癖に気づきにくいので、検出を機械に任せている。 ## いちばん大事な規則:元にない内容を足さない 既存の文書を直すときは、元の文書に書かれていない事実・数値・人名・日付・条件・評価・意見・方針を足さない。直した文書を読んだ人は、そこに書かれていることを書き手が言ったこととして受け取る。足した内容は、たとえ正しくても、書き手が言っていないことを書き手の言葉として広めてしまう。 次の変更も「足す」に当たる。 - 確信の度合いを変える。「次回また相談する」を「合意した」にする、「かもしれない」を「決めた」にする、逆に断定を推定に弱める - 書き手の経験や見解を書き足す。「これには何度も助けられた」「筆者としては〜をすすめる」など - 元にない数の枠組みを足す。「理由は3つある」「主に3種類に分けられる」など - 元の数値や表の値を書き換える。誤りに見えても書き換えず、ユーザーに伝える - 元にない一般論の注意や解説の段落を足す 足してよいのは、元の文書から直接言える補足だけである。略語の正式名称、用語の短い説明、元の文書から読み取れる文と文の関係を示す接続の言葉がこれに当たる。関係が元の文書から読み取れないときは、接続の言葉を足さない(§3)。 例として、議事録の一文を直す場合を挙げる。 - 元の文:「佐藤さんが在庫回転率を使う案を出し、鈴木さんも賛成した。最終的にどう決まったかは次回また相談することになった。」 - 誤った直し方:「在庫回転率に変更する方針で合意した。具体案は田中が7/18までに作る。」(決定・担当・期日が元にない) - よい直し方:「在庫回転率を使う案が佐藤さんから出て、鈴木さんも賛成した。決定は次回に持ち越した。」 内容を変えずに直す例を、ほかに2つ挙げる。どちらも、言い回しだけを変え、事実と確信の度合いは元のままにしている。 - 元の文:「このツールを使用することで、作業効率を大幅に向上させることができると言えるでしょう。」 - 直した文:「このツールを使うと、作業の効率は大きく上がるだろう。」 - 「と言えるでしょう」の控えめな推量は「だろう」で残し、「はずだ」のような強い見込みにはしていない - 元の文:「この事実は、従来の前提が誤っていたことを示している。」 - 直した文:「この事実から、従来の前提が誤っていたと分かる。」 新しく書くときも同じで、ユーザーから受け取った素材と、自分で調べて出典を示せる事実だけを使う。素材が足りないときは推測で埋めず、何が足りないかをユーザーに伝える。 ## 実行モード 同じ工程を、かける手間の違う2つのモードで進める。 クイック(既定)は日常の文書向けで、サブエージェントを使わずにこの場で終える。参照ファイルは、文書タイプが決まったときに `references/doctypes/` の1ファイルを読むだけでよい。lint は文書が短くても必ず1回実行する。短い文書では統計を使う検出器は何も出さないが、禁止語と翻訳調は一文でも検出され、実行は数秒で終わるからだ。既存の文書を直すときは、lint の出力の最後にある段落ごとの確認(§3)も必ず最後まで書き出す。構造の点検(§5)は、見出しと各段落の先頭文を通して読んで確かめる程度でよい。仕上げの `calques.py` と、直したときの `newfacts.py`(§6)も、数秒で終わるので実行する。所要時間の目安は、会議メモ程度で30秒前後、1万字級でも3分程度。 フルは、ユーザーが「しっかり」「時間をかけていい」と言ったとき、対外・経営向けなど誤りの影響が大きい文書、1万字を超える文書に使う。lint に加えて `outline.py` と `terms.py` も実行し、§5 の構造と読みやすさの点検をすべて行う。 サブエージェントは、長い文書を分担して読むと速くなる場合にだけ使い、見つかった問題を直すかどうかは自分で決める。執筆そのものは分担しない。濃淡や章どうしのつながりは、文書全体を見ないと保てないためだ。 フルの所要時間の目安は、短い文書で7分前後、1万字級で15〜20分なので、始める前にユーザーに伝える。effort を選べる環境なら high を使う。effort を低くすると、フルの工程を理由をつけて省きやすくなることを実測で確かめている。 どちらにするか迷ったら、クイックで仕上げ、「フルで見直すこともできる」とユーザーに添える。 ## 呼び出し方 スキルが引数つきのコマンドとして呼ばれたら、次のように解釈する。 - `/natural-japanese [quick|full] <対象>`:書く・直す(既定)。新しく書くのか、既存の文書を直すのかは対象から判断する - `/natural-japanese write [quick|full] <お題や素材>`:新しく書く。§1 から順に進める - `/natural-japanese score [quick|full|exp] <ファイル>`:診断だけを行い、文書は書き換えない。最初に `references/diagnose.md` を読む。スコアの算出式と出力の形式はそこにだけ書いてある。診断のあとでリライトを提案してよいが、頼まれるまで直さない 論旨(主張と根拠の対応、矛盾、前提)を見てほしいという依頼は、このスキルの範囲ではない。同じリポジトリの `critical-thinking` スキル(`/critical-thinking logic <ファイル>`、`/critical-thinking somosomo <ファイル>`)に渡す。 モードの指定がなければ、上の基準で選ぶ。自然な言葉での依頼も同じように扱う。「〇〇について書いて」は write、「この文章 AI っぽい?」は score にする。 ## 1. 書く前に決める ### 読み手と目的 誰が読み、読んだあとに何が起きてほしい文書かを決める。分からなければユーザーに聞く。文書タイプが次のどれかなら、対応するファイルを読む。そこに、その文書タイプの必須要素と、AI がやりがちな失敗がある。 - 議事録:`references/doctypes/minutes.md` - 調査レポート・分析レポート:`references/doctypes/report.md` - 社内ガイド・マニュアル:`references/doctypes/guide.md` - リサーチメモ・ディスカッションペーパー・企画書:`references/doctypes/memo.md` - スライド構成:`references/doctypes/slide.md` ### 主メッセージと見出し 本文の前に、主メッセージを一文で書く。書けないなら、素材が足りていない(→素材)。 見出しには、「背景」「まとめ」のようなラベルでなく、その節の結論を書く。見出しだけを順に読んで論旨が通るかを確かめてから本文に進む。結論が条件つきで、見出しに収まらない節では、条件を落とした結論を書かず、話題を示す見出しにする(§3)。ただし、全部の見出しを「名詞: 結論文」の同じ形にそろえない。同じ形が並ぶと、それ自体が機械的に見えるためだ。短い節はラベルのままでよい。見出しで、本文より確信の度合いを上げない。本文が「予定」と書いていることを、見出しで断定しない。読み手は見出しだけを読んで判断することが多いので、見出しの断定は本文の留保より強く伝わる。 ### 濃淡 重要な節は厚く、軽い節は短く書く。どの節も同じ厚み・同じ文型で書くと、内容に軽重があっても読み手には区別がつかない。書く前に論点を並べ、それぞれにどれだけ書く価値があるかを決めておく。 濃淡は分量の差であって、順位づけではない。もともと並列な項目に「最優先・次点・後回し」のような順位や段階を付けない。内容がもともと順序を持っているときだけ、順序を書く。 ### 素材(新しく書くとき) 固有名詞・数値・実例が手元にないまま書くと、一般論だけの段落になる。主張を、固有名詞・数値・具体的な出来事を使わずに説明できてしまうなら、素材が足りていない。 Web 検索が使えるなら、まず仮の主張と根拠を立て、検索で裏づけるか崩してから、主張を組み直す。これを1〜2回行う。使えないなら、ユーザーに具体例・数値・一次情報があるかを聞く。ユーザーに素材がなければ、内容が一般的になることを伝えて進めてよい。 ### 文体プロファイル(任意) プロジェクトのルートか、ユーザーが指定した場所に `style-profile.md` があれば読み、視点・語彙・リズムの癖を踏まえて書く。なければ汎用の書き方で進める。ユーザーが「自分の文体を学ばせたい」と求めたときだけ、`assets/style-profile-template.md` に沿って過去の文章3〜5本から特徴を抜き出し、プロファイルを書き出す。特徴は断定せず「傾向として」と書く。ユーザーが特定の語や組み合わせを「自分は使わない」「不自然」と言ったときは、一般の規則に広げず、出典と適用範囲を添えてプロファイルの「避ける表現」に記録する。単語全体を禁じず、指摘された組み合わせだけを記録する。 ## 2. 書くときの原則 新しく書くときは、次の原則に沿う。既存の文書を直すときは、§3 で直すと決めた箇所に、元の文書にある内容の範囲で当てる。原則を満たすために内容を足してはいけない。たとえば、元の文書に「次にすべきこと」が書かれていないなら、原則12のために書き足さない。とくに、確信の度合い(原則10)と、事実と意見の区別(原則11)は元の文書のとおりに保ち、表し方だけを変える。「〜と思われます」を「〜と推定する」にするのはよいが、断定に変えてはいけない。原則どうしがぶつかったら、読み手の理解を実際に助けるほうを選ぶ。 1. 結論を先に書く。「本稿では〜について解説する」のような前置きは、読み手に何も伝えない。結論はタイトルか最初の一文に置き、長い文書ではその直後に結論と主な数値を数文でまとめる。 2. 見出しには節の結論を書く(§1)。 3. 因果や経緯は地の文で書く。箇条書きにすると、項目どうしの「だから」「しかし」が消え、その関係を読み手が補うことになる。箇条書きは、担当と期日の並んだ宿題の一覧のように、項目が本当に独立して並ぶときに使う。たとえば「・在庫が減った ・通知が出た ・担当が見落とした ・欠品した」の背後に「通知は出たが見落とした」という関係があるなら、「在庫が減って通知は出たが、担当が見落として欠品した」と書く。関係が元の文書や素材にないなら、関係を足さない。 4. 専門用語は、何をするものかを先に説明してから名前を出す。読み手は、知っている現象に結びつけてから名前を受け取るほうが覚えやすい。初出に、読点のない短い言い換えを括弧で添えるだけでもよい。説明に読点が要るほど長くなるなら、括弧に入れずに一文で書く。物の呼び名は、読み手がその分野で自分で書くときの呼び名にそろえる。長くなってよいので、仕組みや物を、書き手が思いついた短い1語のたとえや言い換えで済ませない。公開エンドポイントを「入口」、リクエストを「要求」、夜間バッチを「夜間の処理」とは書かない。動詞も、「効く」「拾う」「響く」で済ませず、何が起きるかを書く。図の箱や表の列名のように短く書く場所ほど、この置き換えが起きやすい。実験の条件名やブランチ名、集計で付けた区分の名前のように、素材に出てくる作業用の名前も、読み手は知らない。そのまま出さず、何を指すのかを言葉で書く。文書の中で新しく呼び名を作って読み手に覚えさせること(「以下『高』と呼ぶ」)も避ける。言葉で書けば済むなら言葉で書き、呼び名を作るなら、名前だけで中身が分かるものにする(住所と支払いを1画面にまとめた案を「1画面案」と呼ぶ)。 5. 抽象的な主張は、固有名詞・数値・実例で支える。素材がないときは推測で埋めず、何を確かめれば書けるかを書いて空けておく。 6. 太字は、文書全体で本当に目立たせたい箇所だけに使う。段落ごとに太字を置くと、どこも強調に見えなくなる。絵文字や記号でも飾らない。仕事の文書では、飾りは情報を増やさず、読み手の目を散らすだけだからだ。 7. 濃淡をつける(§1)。 8. 同じ型を3回続けない。定義文の型、節の中の組み立て、文の書き出しが3回続いたら、少なくとも1つは変える。最初に選んだ構造を繰り返すほうが書きやすいので、この癖は最後まで残りやすい。変えるときは、文の順序や主語を入れ替える、2文を1文にまとめる、のように内容に合わせて変える。疑問形や体言止めを、型を崩すための手段として入れない。 9. 打ち消し(「〜ではなく〜」「〜ではない。〜だ。」「〜わけではない」)は、読み手が実際に誤解していそうな場面と、事実や注意として要る場面だけで使う。言い換えや強調のために打ち消すと、内容より構文が目立つ。とくに GPT 系のモデルは、誰も言っていない思い込みを先回りして打ち消す文を多く書く(§3)。 10. 確信の度合いは語尾でぼかさず、書き分ける。断定できることは断定し、推定は「〜と推定する」、未確認は【要確認】と書く。「〜と思われます」を全体に散らすと、どこが確かでどこが不確かかが読み手に分からなくなる。 11. 事実と意見を分ける。事実には出典やデータを添え、意見には「筆者は〜と考える」のように話し手を示す。どちらも「〜だ。」で書けてしまうので、文末だけでは区別がつかない。出典を示せない事実は、事実として書かない。 12. 結びでは本文の要約を繰り返さず、要点を1〜2文にまとめる。調査レポートでは、結果から次に何をすべきかを書く。次にすべきことは、素材やユーザーの考えから書く。素材から自分で導いた提案を書くときは、提案であることが分かるように書く(「〜を提案する」)。根拠が支える範囲を超えた提案はしない。ガイドや議事録のように次への導線が別にある文書では、結びの段落自体が要らないこともある。 文の整え方は次のとおり。です・ます体とである体は、文書の中でそろえる。一文に主張は一つにする。一文の長さは50〜60字を目安にするが、主体や語の関係を明示したために長くなった文を、長さだけを理由に削らない。lint の `--reading-load` が長すぎる文として指摘するのは、既定では90字からである。修飾語は長いものを先に、短いものを後に置く。主語と述語はできるだけ近づける。括弧に入れるのは、略語の正式名称、短い言い換え、PR やコミットの番号のように、読点も句点もない短いものだけにする。補足が文や列挙になるなら、本文に書くか、別の文にする。括弧の中は読み飛ばされやすく、大事な事実を入れると読み手が見落とすためだ。 文書のジャンルによって、原則の当てはめ方を変える。技術文書は一文一義と用語の統一をもっとも厳しく守る。ビジネス文書は結論を冒頭に置く構成を優先する。エッセイは、言い切らずに余韻を残す、結論を後に置く、といった逸脱を書き手の意図として認める。公用文や、専門知識のない一般の読み手に向けた文書は、一文を短くし、外来語と二重否定を避け、主語を明示する。 ## 3. 既存の文書を直すとき 直し方は、文書を人が書いたか AI が書いたかで変えない。文章から見分けるのは難しく、新しいモデルが書いた文書は lint の指摘も少ないためだ。直すものを、いつでも直すもの、理由があるときだけ直すもの、どの文書でもしないもの、の三つに分ける。 ### いつでも直すもの - 演出や誇張の言葉。削るだけで外す(次の項) - lint が指摘した言い回し。直し方は各指摘に書いてある - 不要な打ち消し(次の項) - 読み手の手間を増やしている箇所。次の6つは、内容を足さずに直せるので直す - 冗長な言い回し。情報を増やさずに字数だけを増やしている言い回しを縮める(「〜という形で進めていく予定です」を「〜で進める予定です」にする) - 主張が二つ以上入った文。主張ごとに分ける - 何の一覧か、何の話かが後になってから分かる列挙や段落。元の文書の言葉で、先に枠を示す。たとえば、列挙のあとに「〜といった点に注意した。」とあるなら、列挙の前に「注意したのは次の点だ。」と置く - 中身を詰め込んだ括弧。括弧の中に文が入っているもの、話の中身になる列挙が入っているもの、呼び名の取り決め(「これを〜と呼ぶ」)が入っているもの。括弧の中の言葉は、まず括弧の前の文の中に入れる。列挙や説明は、括弧が付いていた語を修飾する形にし、誰がしたかは文の主語にする。「確認したいのは2点(配送料の負担、返品の受付期間)です」は「確認したいのは、配送料の負担と返品の受付期間の2点です」に、「会議室を予約した(総務の木村さんが手配。利用料は無料)」は「総務の木村さんが会議室を予約した。利用料は無料だ」にする。文の中に入らないときだけ、別の一文にする。別の文は、前の文と同じ主語で、前の文の続きとして読めるように書き、文末の形も前の文にそろえる。「移行の手順書は書きました(#512。まだレビューを受けていません)」は「移行の手順書は #512 に書きました。まだレビューを受けていません」にする。「対象は〜です」「例は〜もの」「Xは〜のこと」のように前の語を受け直す文にするとskills/natural-japanese/scripts/calibrate.py33 KB06918ead9141upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
skills/natural-japanese/scripts/calques.py5.4 KB03d36557699cupstream ↗
# /// script # requires-python = ">=3.10" # dependencies = [ # "sudachipy>=0.6.8", # "sudachidict-core>=20240409", # ] # /// """calques.py — 仕組みを場所にたとえた名詞と、機械の処理に当てた動詞の候補を並べる(EXPERIMENTAL)。 書いたモデルは自分の意図で読み返すので、「入口」「効く」のような言葉に自分では気づけない。 指摘されれば直せるので、このスクリプトは気づく段階だけを受け持つ。判断はしない。 誤検出は多めに出る前提で、直すかどうかはエージェントが次の2つの問いで決める。 - この語は、読み手の分野で決まった呼び名か(別の決まった呼び名があるなら直す) - この動詞だけで、何が起きるかが分かるか(分からないなら、起きることを書く) 候補にする型は2つ。 verb 人や物の動きを、機械の処理に当てはめた動詞(拾う・引く・通る・効く・響く・足す など)。 直前が助詞「が・を・に・も・は」のものだけ place 仕組みを場所にたとえて指した名詞(入口・受け口・口・依存先 など)。「口」「先」で終わる名詞 分野の決まった呼び名からずれた漢語(事実・要求・承認 など)は、語の形では見分けられないので対象外。 見出し・箇条書き・表・図(mermaid)の文字も対象にする(短く書く場所ほど言葉がずれやすいため)。 それ以外のコードブロックとインラインコードは対象にしない。 使い方: uv run scripts/calques.py <file.md> [--json] 入力エラーは exit code 1、それ以外は 0。 """ from __future__ import annotations import argparse import json import re import sys from pathlib import Path from textcore import get_tokenizer, read_source_file # 人や物の動きを表す和語の動詞(原形)。文書から逆算した除外リストではなく、型の定義から挙げる。 MOTION_VERBS = { "拾う", "引く", "通る", "通す", "効く", "利く", "響く", "足す", "抜ける", "抜く", "落ちる", "落とす", "走る", "走らせる", "乗る", "乗せる", "回す", "回る", "投げる", "吐く", "叩く", "刺さる", "刺す", "生える", "流れる", "流す", "握る", "噛む", "食う", "食べる", "飛ぶ", "飛ばす", "弾く", "掴む", "潰す", "潰れる", "殺す", "死ぬ", "生きる", "育つ", "眠る", "溜まる", "溜める", "詰まる", "絡む", "漏れる", "溢れる", "折れる", "割れる", "崩れる", "背負う", "抱える", "担ぐ", "跨ぐ", "踏む", "触る", "当たる", "当てる", "被る", "かぶる", "寄せる", "寄る", "逃がす", "逃げる", "剥がす", "捌く", "さばく", "裁く", "捕まえる", "掬う", "すくう", "汲む", "撫でる", "揉む", "絞る", "締める", } _PARTICLES = {"が", "を", "に", "も", "は"} # 「先」は単独の形態素(依存|先、つないでいる|先)だけ。「優先」「宛先」のような1語は候補にしない _PLACE_RE = re.compile(r"先|[一-鿿々ぁ-ん]*口") _FENCE_RE = re.compile(r"^\s*(`{3,}|~{3,})") _INLINE_CODE_RE = re.compile(r"`[^`]*`") _JA_RE = re.compile(r"[-ヿ一-鿿]") def iter_text_lines(text: str): fence = None diagram = False for no, line in enumerate(text.split("\n"), start=1): m = _FENCE_RE.match(line) if m: mark = m.group(1)[0] if fence is None: fence = mark diagram = line.strip().lstrip("`~").strip().lower() == "mermaid" elif fence == mark: fence = None continue # 図(mermaid)の箱や矢印の文字は、短く書くので言葉がずれやすい。読む対象に入れる if (fence is None or diagram) and _JA_RE.search(line): yield no, _INLINE_CODE_RE.sub(" ", line) def find_candidates(text: str) -> list[dict]: tok = get_tokenizer() out = [] for no, line in iter_text_lines(text): ms = list(tok.tokenize(line)) for i, m in enumerate(ms): pos = m.part_of_speech() base = m.dictionary_form() if pos[0] == "動詞" and base in MOTION_VERBS and i and ms[i - 1].surface() in _PARTICLES: out.append({"line": no, "kind": "verb", "word": base, "text": line.strip()}) elif pos[0] == "名詞" and _PLACE_RE.fullmatch(m.surface()): out.append({"line": no, "kind": "place", "word": m.surface(), "text": line.strip()}) return out def main() -> int: ap = argparse.ArgumentParser(description=__doc__.split("\n")[0]) ap.add_argument("file") ap.add_argument("--json", action="store_true") args = ap.parse_args() text, err = read_source_file(Path(args.file)) if err: print(err, file=sys.stderr) return 1 cands = find_candidates(text) if args.json: print(json.dumps(cands, ensure_ascii=False, indent=2)) return 0 if not cands: print("候補なし") return 0 print("| 行 | 型 | 語 | 文 | 読み手の分野の呼び名か / 何が起きるか分かるか | 直す・残す |") print("|---|---|---|---|---|---|") for c in cands: print(f"| {c['line']} | {c['kind']} | {c['word']} | {c['text'][:60]} | | |") return 0 if __name__ == "__main__": sys.exit(main())skills/natural-japanese/scripts/lint.py134 KB84b362b23924upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
skills/natural-japanese/scripts/newfacts.py6.2 KB11e6a46a01f4upstream ↗
# /// script # requires-python = ">=3.10" # dependencies = [ # "sudachipy>=0.6.8", # "sudachidict-core>=20240409", # ] # /// """newfacts.py — 直した文書にだけあって、元の文書にない数値・固有名詞・英字の語を一覧にする。 既存の文書を直すときに、元にない事実を足していないかを確かめる補助(SKILL.md §6)。 「検出は機械、判断はAI」に従い、一覧に出た語が本当に元にない事実かどうかの判断はしない。 検出できるのは、新しく出てきた数値・固有名詞・英字の語だけである。普通の名詞で足した細部、 確信の度合いの変化(「次回相談」→「合意した」)、発言者の入れ替えは検出できない。 何も出なくても、元にない内容がないとは言い切れない。 測定(2026-10、sonnet の推敲47本と、意味の変化の判定器の結果との比較): 判定器が「元にない事実なし」とした14本では1語も出さず、「あり」とした24本のうち11本で語を出した。 使い方: uv run scripts/newfacts.py <元の文書> <直した文書> [--json] uv run scripts/newfacts.py --git <直した文書> [--json] # git の直前のコミットの内容を元の文書として比べる 入力エラーは exit code 1、それ以外は exit code 0(判断は AI に委ねる。ほかの検査と同じ方針)。 """ from __future__ import annotations import argparse import json import re import subprocess import sys import unicodedata from pathlib import Path from textcore import get_tokenizer, read_source_file FENCE = re.compile(r"^(```|~~~).*?^\1", re.M | re.S) NUM = re.compile(r"\d+(?:[.,]\d+)?\s*(?:%|件|分|時間|日|年|月|倍|人|名|割|円|回|個|本|字|週|営業日|チーム|万|点)?") ASCII = re.compile(r"[A-Za-z][A-Za-z0-9.+\-_]*[A-Za-z0-9]") def norm(s: str) -> str: """全角と半角、大文字と小文字の違いをそろえる。""" return unicodedata.normalize("NFKC", s).lower() def items(text: str) -> set[str]: out = {m.group(0).replace(" ", "") for m in NUM.finditer(text)} out |= {m.group(0) for m in ASCII.finditer(text)} tok = get_tokenizer() for line in text.split("\n"): if not line.strip(): continue for m in tok.tokenize(line): pos = m.part_of_speech() if pos[0] == "名詞" and pos[1] == "固有名詞": out.add(m.surface()) return out def bare_number(s: str) -> str: return re.sub(r"[^\d.]", "", s) def new_items(original: str, revised: str) -> list[str]: orig = norm(original) # 元の文書はコードも含めた全文で数え、直した文書はコードブロックを除いて数える a = items(orig) b = items(norm(FENCE.sub("", revised))) # 数字は単位や書き方(「2018/3」と「2018年3月」)が変わるだけのことが多いので、数字そのものが元にあれば除く bare = {bare_number(x) for x in a if re.match(r"\d", x)} cand = {x for x in b - a if not (re.match(r"\d", x) and bare_number(x) in bare)} # 語の切り分け方の違い(「WebGL/WebGPU」、普通名詞と固有名詞の判定の揺れ)で新しく見えるものを除く return sorted(x for x in cand if x not in orig) def locate(revised: str, word: str) -> list[tuple[int, str]]: out = [] for no, line in enumerate(revised.split("\n"), 1): if word in norm(line): out.append((no, line.strip())) return out def main() -> int: ap = argparse.ArgumentParser(description="直した文書にだけある数値・固有名詞・英字の語を一覧にする") ap.add_argument("files", type=Path, nargs="+", help="元の文書と直した文書。--git のときは直した文書だけ") ap.add_argument("--git", action="store_true", help="git の直前のコミット(HEAD)の内容を元の文書として比べる") ap.add_argument("--json", action="store_true", help="JSON で出力する") a = ap.parse_args() if a.git: if len(a.files) != 1: print("エラー: --git のときは、直した文書を1つだけ指定してください", file=sys.stderr) return 1 revised, err = read_source_file(a.files[0]) if err: print(err, file=sys.stderr) return 1 path = a.files[0].resolve() r = subprocess.run(["git", "show", f"HEAD:./{path.name}"], cwd=path.parent, capture_output=True, text=True) if r.returncode != 0: print(f"エラー: git の直前のコミットに {a.files[0]} が見つかりません(git で管理していないか、まだコミットしていない)", file=sys.stderr) return 1 original = r.stdout else: if len(a.files) != 2: print("エラー: 元の文書と直した文書の2つを指定してください(git で管理しているなら --git を使える)", file=sys.stderr) return 1 texts = [] for p in a.files: text, err = read_source_file(p) if err: print(err, file=sys.stderr) return 1 texts.append(text) original, revised = texts found = [{"word": w, "lines": [{"line": n, "text": t} for n, t in locate(revised, w)]} for w in new_items(original, revised)] if a.json: print(json.dumps({"new_items": found}, ensure_ascii=False, indent=2)) return 0 print(f"=== 元の文書にない数値・固有名詞・英字の語: {len(found)}件 ===") for f in found: print(f"- {f['word']}") for ln in f["lines"][:3]: print(f" L{ln['line']}: {ln['text'][:100]}") print() print("※ 検出できるのは新しく出てきた数値・固有名詞・英字の語だけ。普通の名詞で足した細部、確信の度合いの変化、") print(" 発言者の入れ替えは検出できない。0件でも、元にない内容がないとは限らない。") print("※ 一覧に出た語が元にない事実なら、削るか元の内容に戻す。元の文書から直接言える補足(略語の正式名称など)なら残してよい。") return 0 if __name__ == "__main__": sys.exit(main())skills/natural-japanese/scripts/outline.py18 KB17881d49ad47upstream ↗
# /// script # requires-python = ">=3.10" # dependencies = [ # "sudachipy>=0.6.8", # "sudachidict-core>=20240409", # ] # /// """outline.py — 文書のスケルトン(見出し・各段落の先頭文・箇条書き)を抽出する。 設計原則「検出は機械、判断はAI」に基づき、良し悪しの判断はせず、決定的な抽出のみを 行う。SKILL.md §4 の構造レビュー(スケルトン通読)への入力として使う。 スケルトンに加えて「見出し統計」も出力する(本数・レベル分布、見出し長の平均・ 変動係数、体言止め率、見出し間のPOSパターン一致率、テンプレ見出し語彙ヒット、 連番/記号などの構造パターン率)。これらは severity 付きの検出結果(Finding) ではなく、AI臭いかどうかを読む側のAIが判断するための材料の提示に留める ——見出し統計そのものが「AI臭い/自然」を断定することはしない。 使い方: uv run scripts/outline.py <file.md> [--json] 入力エラー(ファイル不在・ディレクトリ指定・読み取り不可等)は exit code 1、 それ以外は exit code 0(判断は人間/AIに委ねる。ほかの検査スクリプトと同じ方針)。 見出し統計の体言止め判定・POSシグネチャ化には sudachipy を使うため、 textcore.py と同じ PEP 723 メタデータを宣言しておく。 """ from __future__ import annotations import argparse import json import re import sys from pathlib import Path from textcore import ( NOUN_ENDING_POS, TEMPLATE_HEADING_WORDS, _BLOCKQUOTE_RE, _CODE_FENCE_RE, _FRONT_MATTER_DELIM_RE, _HEADING_RE, _LIST_ITEM_RE, _TABLE_DELIMITER_RE, _TABLE_ROW_RE, _heading_level_and_text, get_tokenizer, mask_html_comments, read_source_file, strip_trailing_symbols, ) # --------------------------------------------------------------------------- # --outline(スケルトン抽出) # # 設計原則「検出は機械、判断はAI」に基づき、文書の構造(見出し・各段落の先頭文・ # 箇条書きブロック)を決定的に抽出するだけで、良し悪しの判断はしない。 # SKILL.md §4 の構造レビュー(スケルトン通読)への入力として使う。 # # 見出し・コードブロック・引用・表のマスクには mask_markdown_structure() は使わない # (見出し行そのものが空文字になってしまい、スケルトンの主役である見出しテキストが # 消えてしまうため)。かわりに、見出し検出は生テキストに対して直接行い、 # 段落は「空行区切りの行グループ」として独自に走査する。HTMLコメントのみ # mask_html_comments() で先に空白化し、コメント内の見出し風・箇条書き風の行を # 誤ってスケルトンに含めないようにする。 # --------------------------------------------------------------------------- def build_outline(raw_text: str) -> list[dict]: """文書のスケルトン(見出し・各段落の先頭文・箇条書きプレースホルダ)を 行番号付きで抽出する。判断はせず、決定的な抽出のみを行う。 - 見出し行(#〜######): kind="heading", level=1-6 - 空行区切りの段落のうち、箇条書き・コードブロック・引用・表以外: kind="lead" (段落先頭行の最初の文、句点等が無ければ先頭行全体) - 箇条書きだけの段落: kind="bullets"(「(箇条書き N 項目)」プレースホルダ) - コードブロック・引用・表の段落は出力しない(スキップ) ブロックの区切りは空行だけではない。箇条書き行の直後に空行なしで通常段落行が 続く(またはその逆順の)場合も、そこでブロック種別が切り替わるため flush する (空行がないからといって同じブロックにまとめてしまうと、後続ブロックの内容が 丸ごと出力から消えてしまう)。 """ text = mask_html_comments(raw_text) lines = text.split("\n") outline: list[dict] = [] buffer: list[tuple[int, str]] = [] in_fence = False fence_char = "" fence_len = 0 in_front_matter = False def line_kind(line_text: str) -> str: """flush_buffer() のブロック種別判定(buffer[0] 基準)と対応する、 単一行の分類。ブロック種別が切り替わったかどうかの判定に使う。""" if _LIST_ITEM_RE.match(line_text): return "bullets" if _BLOCKQUOTE_RE.match(line_text): return "blockquote" if (_TABLE_ROW_RE.match(line_text) and line_text.count("|") >= 2) or _TABLE_DELIMITER_RE.match( line_text ): return "table" return "lead" def flush_buffer() -> None: if not buffer: return first_no, first_line = buffer[0] if _LIST_ITEM_RE.match(first_line): count = sum(1 for _, line_text in buffer if _LIST_ITEM_RE.match(line_text)) outline.append( {"line": first_no, "kind": "bullets", "level": None, "text": f"(箇条書き {count} 項目)"} ) elif _BLOCKQUOTE_RE.match(first_line): pass # 引用ブロックは段落として扱わずスキップ elif (_TABLE_ROW_RE.match(first_line) and first_line.count("|") >= 2) or _TABLE_DELIMITER_RE.match( first_line ): pass # 表はスキップ else: m = re.search(r"[。!?]", first_line) lead = first_line[: m.end()] if m else first_line lead = lead.strip() if lead: outline.append({"line": first_no, "kind": "lead", "level": None, "text": lead}) buffer.clear() for i, line in enumerate(lines, start=1): if i == 1 and _FRONT_MATTER_DELIM_RE.match(line): in_front_matter = True continue if in_front_matter: if _FRONT_MATTER_DELIM_RE.match(line): in_front_matter = False continue fence_match = _CODE_FENCE_RE.match(line) if fence_match: flush_buffer() fence_run = fence_match.group(1) fc, fl = fence_run[0], len(fence_run) is_close_eligible = line[fence_match.end() :].strip() == "" if not in_fence: in_fence = True fence_char, fence_len = fc, fl elif fc == fence_char and fl >= fence_len and is_close_eligible: in_fence = False continue if in_fence: continue if not line.strip(): flush_buffer() continue if _HEADING_RE.match(line): flush_buffer() level, heading_text = _heading_level_and_text(line) outline.append({"line": i, "kind": "heading", "level": level, "text": heading_text}) continue # 空行を挟まずにブロック種別(箇条書き/引用/表/通常段落)が切り替わった # 場合も、そこで現在のバッファを確定させてから新しいブロックを始める。 # ただし箇条書きブロックの途中に現れるインデントされた継続行(折り返された # 項目の2行目以降。行頭に空白がありマーカーを持たない)は、種別変化とみなさず # 同じ箇条書きブロックに含める(マーカー行だけを項目数として数えるので、 # 継続行が項目数を水増しすることはない)。 if buffer: cur_kind = line_kind(buffer[0][1]) is_indented_continuation = ( cur_kind == "bullets" and line_kind(line) == "lead" and re.match(r"^\s+\S", line) is not None ) if cur_kind != line_kind(line) and not is_indented_continuation: flush_buffer() buffer.append((i, line)) flush_buffer() return outline # --------------------------------------------------------------------------- # 見出し統計(--outline に付随する判断材料の提示) # # ここより下は「検出は機械、判断はAI」の"機械"側の追加ブロックである。ただし # lint.py の検出器群とは性質が異なり、severity 付きの Finding は一切生成しない。 # 見出しの本数・長さ・構造パターンを集計するだけで、「これはAI臭い」という # 判定はしない(例えば体言止め率が高い見出しでも、技術文書では自然に高くなり # うる。閾値判断・良し悪しの判断は読む側のAIに委ねる)。 # # 対象は build_outline() が抽出した kind="heading" のエントリのみ。h1(文書 # タイトル)を含めるかどうかは呼び出し側次第だが、本文の構成パターンを見たい # という目的上、レベル別統計は「レベルごとの兄弟見出し群」を単位に集計する。 # --------------------------------------------------------------------------- # POS シグネチャ化で使う粗い品詞カテゴリ。sudachipy の part_of_speech()[0] は # 「名詞」「動詞」「助詞」等の詳細分類だが、見出し全体の構造パターン(対称性)を # 見たいだけなので、意味のある大分類のみ抽出し、それ以外(助詞・助動詞・記号・ # 空白等の機能語/記号)はシグネチャから除外する。除外しないと「◯◯の設計」 # 「◯◯の実装」のような対称見出しでも助詞「の」の有無等で微妙にシグネチャが # ずれ、パターン一致率が実態より低く出てしまう。 _SIGNATURE_POS = {"名詞", "動詞", "形容詞", "副詞", "接頭辞"} # テンプレ見出し語彙のマッチングは、単純な前方一致だと見出し先頭の記号・番号 # (例:「1. はじめに」「## はじめに」)に引きずられて不一致になる。見出しテキスト # 側の先頭にある番号・記号を軽く剥がしてから判定する。 _LEADING_NUMBERING_RE = re.compile(r"^[\s0-90-9..、,()()【】\[\]#・-]+") # 構造的パターン検出用の正規表現。 # 1) 連番: 「1. ◯◯」「1) ◯◯」「①◯◯」など見出しテキスト先頭の番号 _NUMBERED_HEADING_RE = re.compile(r"^\s*([0-90-9]+[.).、]|[①-⑳])\s*\S") # 2) 括弧見出し: 「【◯◯】」「[◯◯]」など全体または先頭を囲む記号 _BRACKETED_HEADING_RE = re.compile(r"^\s*[【\[[((].+[】\]]))]\s*$") # 3) 「◯◯とは」型: 定義提示の定型 _TOWA_HEADING_RE = re.compile(r".+とは[??]?\s*$") def _heading_pos_signature(text: str) -> tuple[str, ...]: """見出しテキストの粗い品詞列(機能語・記号を除く)をタプル化したもの。 同一シグネチャの兄弟見出しが多いほど、構造的に対称な(=AIが書きがちな テンプレ的な)見出し群である可能性が高い、という判断材料になる。 """ tokenizer = get_tokenizer() sig = [] for m in tokenizer.tokenize(text): pos = m.part_of_speech()[0] if pos in _SIGNATURE_POS: sig.append(pos) return tuple(sig) def _is_nominal_ending(text: str) -> bool: """見出し末尾の実質的な最終形態素が名詞かどうか(体言止め判定)。 lint.py の文末体言止め判定(detect_nominal_ending_and_paragraph_conjunctions) と同じロジックを見出しテキストに適用する。空見出しは False 扱い。 """ tokenizer = get_tokenizer() morphemes = list(tokenizer.tokenize(text)) effective = strip_trailing_symbols(morphemes) if not effective: return False return effective[-1].part_of_speech()[0] in NOUN_ENDING_POS def _match_template_word(text: str) -> str | None: """見出し先頭の番号・記号を除いたうえで、テンプレ見出し語彙カタログ (TEMPLATE_HEADING_WORDS)の前方一致を判定する。ヒットした最初の語を返す。 """ stripped = _LEADING_NUMBERING_RE.sub("", text).strip().lower() for word in TEMPLATE_HEADING_WORDS: if stripped.startswith(word.lower()): return word return None def _match_structural_pattern(text: str) -> str | None: """連番・括弧・「◯◯とは」型など、構造的な定型パターンに一致するか判定する。 複数該当しうるが、提示上は最初に一致したもの1つを採用する。 """ if _NUMBERED_HEADING_RE.match(text): return "numbered" if _BRACKETED_HEADING_RE.match(text): return "bracketed" if _TOWA_HEADING_RE.match(text): return "towa" return None def _summarize_heading_group(headings: list[dict]) -> dict: """見出し群(同一レベルの兄弟、または文書全体)1つ分の統計をまとめる。 headings は build_outline() の kind="heading" エントリのリスト。 """ count = len(headings) if count == 0: return { "count": 0, "length_mean": 0.0, "length_cv": 0.0, "nominal_ending_ratio": 0.0, "dominant_pos_signature_ratio": 0.0, "template_hits": [], "structural_pattern_ratio": 0.0, } lengths = [len(h["text"]) for h in headings] mean_len = sum(lengths) / count if mean_len > 0 and count > 1: variance = sum((length - mean_len) ** 2 for length in lengths) / count stdev = variance**0.5 cv = stdev / mean_len else: cv = 0.0 nominal_count = sum(1 for h in headings if _is_nominal_ending(h["text"])) signatures = [_heading_pos_signature(h["text"]) for h in headings] non_empty_signatures = [s for s in signatures if s] if non_empty_signatures: most_common = max(set(non_empty_signatures), key=non_empty_signatures.count) dominant_ratio = non_empty_signatures.count(most_common) / count else: dominant_ratio = 0.0 template_hits = [] for h in headings: word = _match_template_word(h["text"]) if word is not None: template_hits.append({"line": h["line"], "text": h["text"], "matched": word}) structural_count = sum(1 for h in headings if _match_structural_pattern(h["text"]) is not None) return { "count": count, "length_mean": round(mean_len, 2), "length_cv": round(cv, 3), "nominal_ending_ratio": round(nominal_count / count, 3), "dominant_pos_signature_ratio": round(dominant_ratio, 3), "template_hits": template_hits, "structural_pattern_ratio": round(structural_count / count, 3), } def build_heading_stats(outline: list[dict]) -> dict: """スケルトンから見出しだけを取り出し、レベル別(h1〜h6)+文書全体の 統計をまとめる。severity や良し悪しの判断は含めない(判断材料の提示のみ)。 """ headings = [e for e in outline if e["kind"] == "heading"] by_level: dict[int, list[dict]] = {} for h in headings: by_level.setdefault(h["level"], []).append(h) level_distribution = {str(level): len(hs) for level, hs in sorted(by_level.items())} return { "total_headings": len(headings), "level_distribution": level_distribution, "by_level": { str(level): _summarize_heading_group(hs) for level, hs in sorted(by_level.items()) }, "overall": _summarize_heading_group(headings), } def print_heading_stats_human(stats: dict) -> None: print() print("=== 見出し統計(判断材料。判定はAIが行う) ===") print() print(f"見出し総数: {stats['total_headings']}") if stats["level_distribution"]: dist = ", ".join(f"h{level}={n}" for level, n in stats["level_distribution"].items()) print(f"レベル分布: {dist}") def print_group(label: str, g: dict) -> None: if g["count"] == 0: return print(f"[{label}] 本数={g['count']} 平均長={g['length_mean']}字 " f"長さの変動係数={g['length_cv']} 体言止め率={g['nominal_ending_ratio']:.0%} " f"品詞パターン一致率={g['dominant_pos_signature_ratio']:.0%} " f"構造パターン率={g['structural_pattern_ratio']:.0%}") if g["template_hits"]: hits = ", ".join(f"L{h['line']}:{h['text']}({h['matched']})" for h in g["template_hits"]) print(f" テンプレ見出しヒット: {hits}") for level, g in stats["by_level"].items(): print_group(f"h{level}", g) print_group("全体", stats["overall"]) def print_outline_human(path: Path, outline: list[dict]) -> None: print(f"=== outline: {path} ===") print() if not outline: print("(スケルトンなし)") return for entry in outline: line_tag = f"L{entry['line']}" if entry["kind"] == "heading": indent = " " * max(0, entry["level"] - 1) prefix = "#" * entry["level"] print(f"{line_tag:>6} {indent}{prefix} {entry['text']}") else: print(f"{line_tag:>6} {entry['text']}") def main() -> int: parser = argparse.ArgumentParser( description="文書のスケルトン(見出し・各段落の先頭文・箇条書き)を抽出する(CI ゲートではない)。" ) parser.add_argument("file", type=Path, help="対象の Markdown/テキストファイル") parser.add_argument("--json", action="store_true", help="機械可読な JSON で出力する") args = parser.parse_args() # 「文章の中身に関する判断」と「そもそも実行できない入力エラー」は区別する。 # 前者(抽出結果)は exit 0、後者(ファイル不在/ディレクトリ指定/読み取り不可等)は exit 1。 text, err = read_source_file(args.file) if err is not None: print(err, file=sys.stderr) return 1 outline = build_outline(text) heading_stats = build_heading_stats(outline) if args.json: print(json.dumps({"outline": outline, "heading_stats": heading_stats}, ensure_ascii=False, indent=2)) else: print_outline_human(args.file, outline) print_heading_stats_human(heading_stats) return 0 if __name__ == "__main__": sys.exit(main())skills/natural-japanese/scripts/paragraphs.py5.0 KBfd53e6ceb177upstream ↗
# /// script # requires-python = ">=3.10" # dependencies = [] # /// """paragraphs.py — 文書を段落に分け、番号と行番号を付けた確認用の表を出す。 SKILL.md §3「読み手が何のことか分からない言い回しは、ふだんの言葉に戻す」の手順で使う。 文書全体を通して読むだけだと、モデルは「もう読みやすい」と判断して確認を飛ばす。 段落ごとに表を埋めさせることで、すべての段落を一度ずつ見たことを残す。 判断はしない。分けて並べるだけ。段落の単位は次のとおり。 - 見出しの行 - 箇条書きの1項目(続きの行を含む) - 表の1行(区切り行は除く) - 空行で区切られた地の文 コードブロック、YAML フロントマター、HTML コメントの中は対象にしない。 使い方: uv run scripts/paragraphs.py <file.md> > phrases.md uv run scripts/paragraphs.py <file.md> --json 入力エラー(ファイル不在など)は exit code 1、それ以外は 0。 """ from __future__ import annotations import argparse import json import re import sys from pathlib import Path _FENCE_RE = re.compile(r"^\s*(`{3,}|~{3,})") _HEADING_RE = re.compile(r"^\s{0,3}#{1,6}\s") _LIST_RE = re.compile(r"^\s*(?:[-*+]|\d+[.)])\s+") _TABLE_RE = re.compile(r"^\s*\|.*\|\s*$") _TABLE_DELIM_RE = re.compile(r"^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$") _JA_RE = re.compile(r"[-ヿ一-鿿]") def split_units(text: str) -> list[dict]: lines = text.split("\n") units: list[dict] = [] cur: dict | None = None fence: str | None = None in_front = False in_comment = False def flush(): nonlocal cur if cur and _JA_RE.search(" ".join(cur["lines"])): units.append({"line": cur["line"], "kind": cur["kind"], "text": "\n".join(cur["lines"]).strip()}) cur = None for no, line in enumerate(lines, start=1): if no == 1 and line.strip() == "---": in_front = True continue if in_front: if line.strip() == "---": in_front = False continue m = _FENCE_RE.match(line) if m: flush() mark = m.group(1)[0] if fence is None: fence = mark elif fence == mark and line.strip().strip(mark) == "": fence = None continue if fence is not None: continue if in_comment: if "-->" in line: in_comment = False continue if line.strip().startswith("<!--"): flush() in_comment = "-->" not in line continue if not line.strip(): flush() continue if _HEADING_RE.match(line): flush() cur = {"line": no, "kind": "見出し", "lines": [line]} flush() continue if _TABLE_DELIM_RE.match(line): continue if _TABLE_RE.match(line): flush() cur = {"line": no, "kind": "表", "lines": [line]} flush() continue if _LIST_RE.match(line): flush() cur = {"line": no, "kind": "箇条書き", "lines": [line]} continue if cur is None: cur = {"line": no, "kind": "段落", "lines": [line]} else: cur["lines"].append(line) flush() for i, u in enumerate(units, start=1): u["no"] = i return units def render(units: list[dict], name: str) -> str: out = [ f"# {name} の段落ごとの確認", "", "各段落の動詞と名詞をすべて見て、SKILL.md §3「読み手が何のことか分からない言い回し」の型に当たるものを表に書く。" "指しているものは、元の文書やコードにある事実・名前で書く。当たるものがない段落は、表の代わりに「なし」と書く。", "", ] for u in units: out += [ f"## {u['no']}({u['line']}行目、{u['kind']})", "", u["text"], "", "| 言い回し | 型 | 指しているもの | 直す/残す |", "|---|---|---|---|", "", ] return "\n".join(out) def main() -> int: ap = argparse.ArgumentParser(description=__doc__.splitlines()[0]) ap.add_argument("file") ap.add_argument("--json", action="store_true") a = ap.parse_args() p = Path(a.file) if not p.is_file(): print(f"ファイルが見つからない: {p}", file=sys.stderr) return 1 try: text = p.read_text(encoding="utf-8") except (OSError, UnicodeDecodeError) as e: print(f"読み取れない: {p}: {e}", file=sys.stderr) return 1 units = split_units(text) if a.json: print(json.dumps(units, ensure_ascii=False, indent=1)) else: print(render(units, p.name)) return 0 if __name__ == "__main__": sys.exit(main())skills/natural-japanese/scripts/semantic.py17 KBd3093a4e4ff5upstream ↗
# /// script # requires-python = ">=3.10" # dependencies = [ # "sentence-transformers>=3.0.0", # "numpy", # "sudachipy>=0.6.8", # "sudachidict-core>=20240409", # ] # /// """semantic.py — 文埋め込みによる「話題の平板さ」検出(EXPERIMENTAL・opt-in)。 【重要】これは lint.py の中核パイプラインとは独立した重量級のオプトイン検出器である。 torch + sentence-transformers(cl-nagoya/ruri-v3-310m、初回~1GB級のHFダウンロード)に 依存するため、scripts/lint.py・.github/workflows/release.yml・scripts/check-fixtures.sh の どこにも組み込まない。実行したい人だけが明示的に `uv run scripts/semantic.py` を実行する。 背景・設計思想(corpus/reports/nn-detector-sweep.md §B 参照): perplexity・教師あり分類器・GiNZA係り受けの3系統は、コーパス実測の結果 「ジャンルの文体」や「読みやすさそのもの」を AI らしさとして検出していることが判明し不採用となった。 唯一生き残ったのが本検出器(文埋め込みによる話題平板性)で、表層の文体をどれだけ 磨いても消えにくい「一つの話題を同じ意味距離で刻み続ける」癖を捉えている。 ただし model 依存が重く、閾値もFP基準集合(human quality:high 81文書)の標本がまだ少ないため、 lint.py 本体(sudachipy のみ・数秒で完結)とは別の EXPERIMENTAL な独立エントリとする。 指標定義(corpus/experiments/embedding/sweep.py と同一ロジック。すべて cos類似度、 埋め込みは normalize_embeddings=True 済みなので内積=cos類似度): - coherence_flatness_range: 隣接文類似度(|i-j|==1)の max-min。狭い=話題の起伏が乏しい (最有力指標。primary detector として採用)。 - semantic_repetition_max: 非隣接文ペア(|i-j|>=2)類似度の最大値。高い=言い換え反復 (secondary/reference。severity=info)。 - topic_jump_min: 隣接文類似度の最小値。高い=脈絡のない飛躍がない (secondary/reference。severity=info)。 文分割は corpus/experiments/embedding/embed_corpus.py と同じ経路 (textcore.mask_markdown_structure + split_sentences_with_lines)を使い、 実験で校正した閾値とそのまま対応するようにする。 使い方: uv run scripts/semantic.py <file.md> [--json] [--genre essay|tech|business] 初回実行時は cl-nagoya/ruri-v3-310m(~1GB)を HuggingFace から自動ダウンロードする (2回目以降はHFキャッシュを再利用し、オフラインでも動作する)。 終了コード: lint.py と同じ規律。文章の中身に関する判定は exit 0(検出件数に関わらず)。 入力エラー(ファイル不在・ディレクトリ指定・読み取り不可等)のみ exit 1。 """ from __future__ import annotations import argparse import json import sys from pathlib import Path sys.path.insert(0, str(Path(__file__).resolve().parent)) from textcore import ( Finding, iter_lines_with_no, mask_markdown_structure, read_source_file, split_sentences_with_lines, ) DEFAULT_MODEL = "cl-nagoya/ruri-v3-310m" # 短文書ガード。統計的な起伏・反復の測定は文数が少ないと意味をなさない # (lint.py の低分散検出器などが短文書を除外するのと同じ哲学)。 # コーパス実験(sweep.py)は「n>=3で計算可、n>=2でvar/range計算」という緩い下限だったが、 # 実運用の目安としては最低10文程度なければ「起伏がない」という判定自体が # 統計的に不安定(1〜2箇所の類似度でrange/varがほぼ決まってしまう)と判断し、 # 10文未満はここで打ち切る。 MIN_SENTENCES_FOR_STATS = 10 # --------------------------------------------------------------------------- # 閾値校正(2026-07、corpus/experiments/embedding/sweep-raw.json 542文書分の # 生データを本スクリプト作成時に再集計して算出。算出手順は # corpus/experiments/embedding/sweep.py の sweep_threshold() と同じ規律 # (FP基準集合=human_fp_base で誤検知率<5%を保ちつつAI検出率最大の閾値を # value<=th / value>=th の両方向から全探索)。 # # coherence_flatness_range(primary、severity=warn。隣接文類似度のレンジが # 狭い=話題の起伏が乏しい): # - 全ジャンル共通(デフォルト): threshold=0.1612 (value<=th) → # n(fp_base)=81, FP率=3.7%, n(ai)=405, AI検出率=85.2% # (corpus/reports/nn-detector-sweep.md §B の実験結果そのまま) # - ジャンル別再校正(本スクリプト作成時に実施。essayのFP率問題への対応): # essayは共通閾値0.1612適用時にFP率6.7%(n=30中2件)とレポートで指摘された # 問題ジャンル。essay単体のFP基準集合(n=30)とAI(n=84)で再スイープした結果、 # threshold=0.1581 (value<=th) でFP率=3.3%(1/30)、AI検出率=95.2%(80/84)と # 大幅改善(かつ検出率はむしろ上昇)。 # tech: n(fp_base)=18, threshold=0.1426 (value<=th) → FP率=0%(0/18), # n(ai)=84, AI検出率=52.4%(44/84)。tech人間コーパスは見出し・箇条書き構成に # 寄るぶん元々flatness_rangeが高め(mean=0.2063)で、閾値を厳しく(低く) # しないとFP<5%を保てない。 # business: n(fp_base)=29, threshold=0.1556 (value<=th) → FP率=0%(0/29), # n(ai)=84, AI検出率=73.8%(62/84)。 # 注意: essay(0.1581) > business(0.1556) > tech(0.1426) の順で、essayが # 3ジャンル中もっとも「緩い」(=値が高くても発火しにくい方向に振っている # わけではなく、essay固有のFP基準集合の分布の谷間を使って全体閾値0.1612より # 厳しくした結果、3ジャンル中では最も高い値になった)。数値上essayの # 閾値がtech/businessより高いのは、essay固有の人間分布が0.134と0.161の # 間に空白域を持つため、この空白の直下(0.1581)まで閾値を上げても # FP<5%を保てるという、経験的な校正結果である。 # --------------------------------------------------------------------------- DEFAULT_FLATNESS_THRESHOLD = 0.16122889518737793 GENRE_PROFILES: dict[str, dict] = { "essay": { "flatness_threshold": 0.15813499689102173, "flatness_calibration": "n(fp_base)=30, FP率=3.3%, n(ai)=84, AI検出率=95.2%", }, "tech": { "flatness_threshold": 0.14261949062347412, "flatness_calibration": "n(fp_base)=18, FP率=0%, n(ai)=84, AI検出率=52.4%", }, "business": { "flatness_threshold": 0.15565699338912964, "flatness_calibration": "n(fp_base)=29, FP率=0%, n(ai)=84, AI検出率=73.8%", }, } # secondary/reference 指標(severity=info)。全ジャンル共通閾値のみ # (corpus/experiments/embedding/sweep-result.md の全体スイープ結果をそのまま流用。 # ジャンル別再校正はprimary指標のみに絞り、これらは参考情報にとどめる)。 SEMANTIC_REPETITION_MAX_THRESHOLD = 0.9322158694267273 # value<=th → FP率4.9%(n=81), AI検出率46.4%(n=405) TOPIC_JUMP_MIN_THRESHOLD = 0.765757143497467 # value>=th → FP率4.9%(n=81), AI検出率62.2%(n=405) def doc_sentences_with_lines(raw_text: str) -> list[tuple[int, str]]: """(行番号, 原文の文) のリストを返す。embed_corpus.py の doc_sentences と 同じ経路(マスク済みテキストで文分割→原文から同オフセットで切り出し)だが、 ここでは行番号も保持して Finding.line に使えるようにする。""" masked = mask_markdown_structure(raw_text) lines = iter_lines_with_no(masked) raw_lines_by_no = dict(iter_lines_with_no(raw_text)) sentences = split_sentences_with_lines(lines, raw_lines_by_no) out = [] for no, masked_s, raw_s in sentences: s = raw_s.strip() if raw_s.strip() else masked_s.strip() if s: out.append((no, s)) return out _model_cache = {} def load_model(model_name: str): """初回ロード時だけ ~1GB ダウンロードの可能性を stderr に警告する。""" if model_name in _model_cache: return _model_cache[model_name] print( f"[semantic.py] モデル読み込み中: {model_name} " "(初回実行時はHuggingFaceから自動ダウンロード、~1GB級の可能性があります。" "2回目以降はHFキャッシュを再利用しオフラインでも動作します)", file=sys.stderr, ) import torch from sentence_transformers import SentenceTransformer device = "mps" if torch.backends.mps.is_available() else ("cuda" if torch.cuda.is_available() else "cpu") model = SentenceTransformer(model_name, device=device, trust_remote_code=True) _model_cache[model_name] = model return model def compute_metrics(embeddings) -> dict: """corpus/experiments/embedding/sweep.py の cosine_matrix_stats と同一ロジック。""" import numpy as np n = embeddings.shape[0] out = { "semantic_repetition_max": None, "coherence_flatness_range": None, "topic_jump_min": None, } if n < 3: return out sim = embeddings @ embeddings.T adj = np.array([sim[i, i + 1] for i in range(n - 1)]) if len(adj) >= 2: out["coherence_flatness_range"] = float(adj.max() - adj.min()) out["topic_jump_min"] = float(adj.min()) elif len(adj) == 1: out["topic_jump_min"] = float(adj[0]) iu = np.triu_indices(n, k=2) non_adj = sim[iu] if non_adj.size: out["semantic_repetition_max"] = float(non_adj.max()) return out def run_semantic( raw_text: str, genre: str | None = None, model_name: str = DEFAULT_MODEL ) -> tuple[list[Finding], dict]: profile = GENRE_PROFILES.get(genre, {}) flatness_threshold = profile.get("flatness_threshold", DEFAULT_FLATNESS_THRESHOLD) flatness_calibration = profile.get( "flatness_calibration", "n(fp_base)=81, FP率=3.7%, n(ai)=405, AI検出率=85.2%(全ジャンル共通閾値)", ) sentence_items = doc_sentences_with_lines(raw_text) n_sentences = len(sentence_items) stats: dict = { "genre": genre, "n_sentences": n_sentences, "model": model_name, "flatness_threshold": flatness_threshold, "metrics": None, "skipped": False, "skip_reason": None, } if n_sentences < MIN_SENTENCES_FOR_STATS: stats["skipped"] = True stats["skip_reason"] = ( f"文数が{n_sentences}文と少なく(目安{MIN_SENTENCES_FOR_STATS}文未満)、" "統計的な起伏・反復の測定が安定しないため意味的検出をスキップしました。" ) return [], stats lines_no = [no for no, _ in sentence_items] sentences = [s for _, s in sentence_items] model = load_model(model_name) embeddings = model.encode( sentences, convert_to_numpy=True, show_progress_bar=False, normalize_embeddings=True ) metrics = compute_metrics(embeddings) stats["metrics"] = metrics findings: list[Finding] = [] cfr = metrics.get("coherence_flatness_range") if cfr is not None and cfr <= flatness_threshold: # レポート対象行はとりあえず文書冒頭(文単位ではなく文書全体集計の検出器なので、 # lint.py の antithesis_repetition 等の「文書全体集計型」の扱いに倣う)。 line = lines_no[0] if lines_no else 1 findings.append( Finding( line=line, category="semantic_topic_flatness", excerpt=f"隣接文類似度レンジ={cfr:.4f}(閾値{flatness_threshold:.4f}以下)", severity="warn", # 実験的検出器のため critical にはしない detail=( "隣接文の意味類似度の起伏が乏しい=一つの話題を同じ歩幅で刻み続ける" "AI的な平板さの疑い。EXPERIMENTAL: コーパス校正では" f"{flatness_calibration}(corpus/experiments/embedding/sweep-raw.json " "542文書からの実測。genre指定なしはcorpus/reports/nn-detector-sweep.md " "の全体閾値をそのまま使用)。具体例への降下・視点の転換・短い脱線で" "意味的な緩急をつけることを検討してください。" ), ) ) srm = metrics.get("semantic_repetition_max") if srm is not None and srm <= SEMANTIC_REPETITION_MAX_THRESHOLD: line = lines_no[0] if lines_no else 1 findings.append( Finding( line=line, category="semantic_repetition_max", excerpt=f"非隣接文ペア類似度max={srm:.4f}(参考閾値{SEMANTIC_REPETITION_MAX_THRESHOLD:.4f}以下)", severity="info", detail=( "参考指標(experimental・reference)。非隣接文ペアの意味的類似度の" "最大値が低め=同じ内容の言い換え反復が少ないことを示す(低いほどAI寄り、" "という逆説的な弁別だが、コーパス実測ではhuman_fp_base mean=0.9878 vs " "ai mean=0.9470とAI側が低い)。n(fp_base)=81, FP率=4.9%, n(ai)=405, " "AI検出率=46.4%(corpus/experiments/embedding/sweep-result.md)。" ), ) ) tjm = metrics.get("topic_jump_min") if tjm is not None and tjm >= TOPIC_JUMP_MIN_THRESHOLD: line = lines_no[0] if lines_no else 1 findings.append( Finding( line=line, category="topic_jump_min", excerpt=f"隣接文類似度最小値={tjm:.4f}(参考閾値{TOPIC_JUMP_MIN_THRESHOLD:.4f}以上)", severity="info", detail=( "参考指標(experimental・reference)。隣接文間で意味的に大きく飛躍する" "箇所が無い=脈絡のない話題転換が少ないことを示す。" "n(fp_base)=81, FP率=4.9%, n(ai)=405, AI検出率=62.2%" "(corpus/experiments/embedding/sweep-result.md)。" ), ) ) return findings, stats SEVERITY_LABEL = {"info": "情報", "warn": "警告", "critical": "重大"} def print_human_report(path: Path, findings: list[Finding], stats: dict) -> None: print(f"=== semantic.py (EXPERIMENTAL): {path} ===") print(f"文数: {stats['n_sentences']} モデル: {stats['model']} genre: {stats['genre'] or '(未指定)'}") if stats["skipped"]: print(f"スキップ: {stats['skip_reason']}") return print(f"検出件数: {len(findings)}") print() if not findings: print("検出なし。") return for f in findings: label = SEVERITY_LABEL.get(f.severity, f.severity) print(f"[{label}] L{f.line} ({f.category})") print(f" 該当箇所: {f.excerpt}") if f.detail: print(f" 詳細 : {f.detail}") print() def main() -> int: parser = argparse.ArgumentParser( description=( "EXPERIMENTAL: 文埋め込みによる話題平板性の検出(opt-in・重量級・" "torch+sentence-transformers依存、初回~1GBダウンロード)。" "lint.py とは独立したエントリポイント。" ) ) parser.add_argument("file", type=Path, help="検査対象の Markdown/テキストファイル") parser.add_argument("--json", action="store_true", help="機械可読な JSON で出力する") parser.add_argument( "--genre", choices=sorted(GENRE_PROFILES), default=None, help="ジャンル別に校正した閾値プロファイルを適用する(essay/tech/business)。未指定時は共通閾値", ) parser.add_argument("--model", default=DEFAULT_MODEL, help=f"埋め込みモデル名(既定: {DEFAULT_MODEL})") args = parser.parse_args() text, err = read_source_file(args.file) if err is not None: print(err, file=sys.stderr) return 1 try: findings, stats = run_semantic(text, genre=args.genre, model_name=args.model) except Exception as exc: print( f"エラー: 意味モデルの読み込みまたは推論に失敗しました: {exc}", file=sys.stderr, ) return 1 if args.json: output = { "file": str(args.file), "stats": stats, "findings": [f.to_dict() for f in findings], } print(json.dumps(output, ensure_ascii=False, indent=2)) else: print_human_report(args.file, findings, stats) # lint.py と同じ規律: 文章の中身に関する判定は exit 0(件数に関わらず)。 return 0 if __name__ == "__main__": sys.exit(main())skills/natural-japanese/scripts/terms.py12 KB9be7942a735cupstream ↗
# /// script # requires-python = ">=3.10" # dependencies = [ # "sudachipy>=0.6.8", # "sudachidict-core>=20240409", # ] # /// """terms.py — 専門用語候補(カタカナ複合語・ASCII英略語・固有名詞)を初出順に抽出する。 設計原則「検出は機械、判断はAI」に基づき、有用な専門用語かどうか、初出で説明済みかどうか の判断は行わない(has_gloss_hint はあくまでヒント)。SKILL.md §2 の原則4(初出で説明すべき用語) の確認材料として使う。 使い方: uv run scripts/terms.py <file.md> [--json] 入力エラー(ファイル不在・ディレクトリ指定・読み取り不可等)は exit code 1、 それ以外は exit code 0(判断は人間/AIに委ねる。ほかの検査スクリプトと同じ方針)。 """ from __future__ import annotations import argparse import json import re import sys from pathlib import Path from textcore import ( _HEADING_RE, _heading_level_and_text, get_tokenizer, iter_lines_with_no, mask_html_comments, mask_markdown_structure, read_source_file, ) # --------------------------------------------------------------------------- # --terms(用語インベントリ) # # sudachipy の解析結果から、専門用語候補(カタカナ複合語・ASCII英略語・ # 固有名詞らしき語)を機械的に列挙する。有用な専門用語かどうか、初出で # 説明済みかどうかの判断は行わない(has_gloss_hint はあくまでヒント)。 # SKILL.md §2 の原則4(初出で説明すべき用語)の確認材料として AI に渡す素材。 # --------------------------------------------------------------------------- _KATAKANA_CHAR_RE = re.compile(r"^[ァ-ヶー]+$") # Python の \b は Unicode 単語境界を使うため、日本語の文字(漢字・かな)は # 単語文字として扱われ、「APIとは」のように直後に日本語が続くと \b が成立せず # マッチしない。ASCII の英数字が前後に隣接していない(=英略語として孤立している) # ことだけを見ればよいので、\b の代わりに明示的な否定先読み/後読みで判定する # (直前直後が日本語であることは許容し、直前直後が別の ASCII 英数字であることのみ排除)。 _ASCII_ACRONYM_RE = re.compile(r"(?<![A-Za-z0-9])[A-Z]{2,}[0-9]*(?![A-Za-z0-9])") TERMS_KATAKANA_MIN_LEN = 3 TERMS_GLOSS_CONTEXT_CHARS = 80 TERMS_GLOSS_MARKER_WORDS = ["とは", "と呼ぶ", "という", "、つまり"] def _is_katakana_token(surface: str) -> bool: return bool(_KATAKANA_CHAR_RE.match(surface)) # 英字が先頭大文字で残りが英数字("Cloudflare" "TypeScript" 等)の語。 # sudachipy の辞書は未登録の製品名/固有名詞をしばしば「名詞,普通名詞」と解析する # (固有名詞の品詞が付かない)ため、POS だけに頼ると製品名を取りこぼす。 # 表層の形(先頭大文字+英数字)という単純なヒューリスティクスで補う # (除外辞書は作らない方針のため、あくまで形のみで判定する)。 _CAPITALIZED_LATIN_WORD_RE = re.compile(r"^[A-Z][a-zA-Z0-9]*$") def _is_proper_noun_or_capitalized_latin_morpheme(morpheme) -> bool: pos = morpheme.part_of_speech() if pos[0] == "名詞" and pos[1] == "固有名詞": return True surface = morpheme.surface() return len(surface) >= 2 and bool(_CAPITALIZED_LATIN_WORD_RE.match(surface)) def _term_context_and_gloss_hint( term: str, first_line_no: int, search_text: str, line_offsets: dict[int, int] ) -> tuple[str, bool]: """search_text(HTMLコメントのみ空白化済みの原文相当。文字数・行数は原文と同一) 全体における term の初出近傍(前後 TERMS_GLOSS_CONTEXT_CHARS 字)と、 説明の手掛かり(has_gloss_hint)の有無を返す。 raw_text そのものではなく HTML コメントを空白化したテキストを使うのは、 近傍表示にコメント内のメモ書き(校正メモ等)が紛れ込むのを防ぐため (オフセット・行番号は raw_text と完全に一致するので、term の検索・切り出しは この search_text に対して行っても line_offsets が raw_text 側と食い違わない)。 """ lines = search_text.split("\n") line_text = lines[first_line_no - 1] if 0 < first_line_no <= len(lines) else "" local_idx = line_text.find(term) if local_idx == -1: # 行内に見つからない場合(マスク処理の副作用等)は行全体を近傍として返す return line_text.strip(), any(marker in line_text for marker in TERMS_GLOSS_MARKER_WORDS) abs_pos = line_offsets.get(first_line_no, 0) + local_idx ctx_start = max(0, abs_pos - TERMS_GLOSS_CONTEXT_CHARS) ctx_end = abs_pos + len(term) + TERMS_GLOSS_CONTEXT_CHARS context = search_text[ctx_start:ctx_end] term_start_local = abs_pos - ctx_start term_end_local = term_start_local + len(term) after = context[term_end_local : term_end_local + 2] has_gloss_hint = after.startswith("(") or after.startswith("(") if not has_gloss_hint: has_gloss_hint = any(marker in context for marker in TERMS_GLOSS_MARKER_WORDS) return context.strip(), has_gloss_hint def build_term_inventory(raw_text: str) -> list[dict]: """専門用語候補の一覧を初出順に抽出する。判断(有用な用語かどうか、 既に説明済みかどうか)はしない。has_gloss_hint はあくまで機械的なヒント。 """ tokenizer = get_tokenizer() from sudachipy import SplitMode masked_comments = mask_html_comments(raw_text) masked_structure = mask_markdown_structure(masked_comments) body_lines = iter_lines_with_no(masked_structure) # 見出し行は mask_markdown_structure() で空文字化されるため、見出しテキストも # 用語抽出の対象に含めたい場合は別途生テキストから拾って合流させる # (製品名・専門用語が見出しで最初に登場するケースを取りこぼさないため)。 heading_lines: list[tuple[int, str]] = [] for no, line in iter_lines_with_no(masked_comments): if _HEADING_RE.match(line): _, heading_text = _heading_level_and_text(line) heading_lines.append((no, heading_text)) combined_lines = sorted(body_lines + heading_lines, key=lambda t: t[0]) # masked_comments は raw_text と文字数・行数が完全に一致する(HTMLコメントの # 中身のみ空白化)ため、ここで作るオフセットは raw_text 側にもそのまま使える。 line_offsets: dict[int, int] = {} pos = 0 for no, line_text in enumerate(masked_comments.split("\n"), start=1): line_offsets[no] = pos pos += len(line_text) + 1 # term -> {"first_line": int, "first_offset": int} # first_offset は初出行内での文字オフセット。カタカナ複合語・ASCII英略語・ # 固有名詞をそれぞれ別のパスで走査しているため、同一行内での実際の出現順は # first_line だけでは判定できない(先に全行を走査するパスの語が、行内では # 後ろにあっても先に登録されてしまう)。first_offset を合わせて記録し、 # 最後に (first_line, first_offset) の複合キーでソートすることで、 # 文書内の実際の出現位置の昇順にする。 seen: dict[str, dict] = {} def register(term: str, no: int, offset: int) -> None: term = term.strip() if not term: return if term not in seen: seen[term] = {"first_line": no, "first_offset": offset} for no, line in combined_lines: if not line.strip(): continue # (b) ASCII英略語(大文字2文字以上)は表層の正規表現で拾う for m in _ASCII_ACRONYM_RE.finditer(line): register(m.group(0), no, m.start()) # (a) カタカナ複合語 / (c) 固有名詞・製品名らしき語(sudachiのPOSが固有名詞、 # または先頭大文字の英単語=製品名によくある表層形)は形態素解析で連続する # 同種の形態素をまとめて1つの候補語にする(元のスパンをそのまま使い、 # 語間の空白等も保持する)。 morphemes = list(tokenizer.tokenize(line, SplitMode.C)) i = 0 n = len(morphemes) while i < n: m0 = morphemes[i] if _is_katakana_token(m0.surface()): j = i + 1 while j < n and _is_katakana_token(morphemes[j].surface()): j += 1 span_start = m0.begin() span_end = morphemes[j - 1].end() term = line[span_start:span_end] if len(term) >= TERMS_KATAKANA_MIN_LEN: register(term, no, span_start) i = j continue if _is_proper_noun_or_capitalized_latin_morpheme(m0): j = i + 1 while j < n and _is_proper_noun_or_capitalized_latin_morpheme(morphemes[j]): j += 1 span_start = m0.begin() span_end = morphemes[j - 1].end() term = line[span_start:span_end] register(term, no, span_start) i = j continue i += 1 results = [] for term, info in seen.items(): # 出現回数もコメントを除いた本文(masked_comments)基準で数える # (校正メモ等のコメント内言及を実際の用語出現としてカウントしないため)。 count = len(re.findall(re.escape(term), masked_comments)) context, has_gloss_hint = _term_context_and_gloss_hint( term, info["first_line"], masked_comments, line_offsets ) results.append( { "term": term, "first_line": info["first_line"], "count": count, "has_gloss_hint": has_gloss_hint, "context": context, } ) # 初出順(文書内の実際の出現位置=(first_line, first_offset) の昇順)。 # first_offset は出力スキーマに含めない内部情報なので、seen から引いてソートキーに使う。 results.sort(key=lambda r: (r["first_line"], seen[r["term"]]["first_offset"])) return results def print_terms_human(path: Path, terms: list[dict]) -> None: print(f"=== terms: {path} ===") print( "has_gloss_hint は「説明済みと判定した」印ではなく、初出近傍に説明マーカーが" "見つかったという機械的なヒントに過ぎない。要確認は人間/AIの判断に委ねる。" ) print() if not terms: print("(用語候補なし)") return for t in terms: hint = "あり" if t["has_gloss_hint"] else "なし" print(f"L{t['first_line']} {t['term']} (出現{t['count']}回, 説明手掛かり: {hint})") print(f" 近傍: {t['context']}") print() def main() -> int: parser = argparse.ArgumentParser( description="専門用語候補(カタカナ複合語/ASCII英略語/固有名詞)を初出順に抽出する(CI ゲートではない)。" ) parser.add_argument("file", type=Path, help="対象の Markdown/テキストファイル") parser.add_argument("--json", action="store_true", help="機械可読な JSON で出力する") args = parser.parse_args() # 「文章の中身に関する判断」と「そもそも実行できない入力エラー」は区別する。 # 前者(抽出結果)は exit 0、後者(ファイル不在/ディレクトリ指定/読み取り不可等)は exit 1。 text, err = read_source_file(args.file) if err is not None: print(err, file=sys.stderr) return 1 terms = build_term_inventory(text) if args.json: print(json.dumps({"terms": terms}, ensure_ascii=False, indent=2)) else: print_terms_human(args.file, terms) return 0 if __name__ == "__main__": sys.exit(main())skills/natural-japanese/scripts/textcore.py23 KB60458757c783upstream ↗
"""textcore.py — 検査スクリプト3本(lint.py / outline.py / terms.py)の共有基盤。 エントリポイントではない(単体実行を想定しない)ため PEP 723 インラインメタデータは 持たない。依存(sudachipy / sudachidict-core)は各エントリスクリプト側で宣言する。 `uv run scripts/lint.py` 等の実行時は sys.path[0] が scripts/ ディレクトリになるため、 同ディレクトリの `import textcore` がそのまま解決できる。 提供するもの: - sudachipy Tokenizer の遅延初期化(get_tokenizer) - 文分割(split_sentences_with_lines 等) - Markdown構造のマスク処理(mask_markdown_structure / mask_html_comments) - 行番号付き反復・段落分割ユーティリティ - 入力ファイルの読み込みと入力エラー処理(read_source_file) - 共有データ構造(Finding) """ from __future__ import annotations import dataclasses import re from pathlib import Path # --------------------------------------------------------------------------- # 共有データ構造 # --------------------------------------------------------------------------- @dataclasses.dataclass class Finding: line: int category: str excerpt: str severity: str # "info" | "warn" | "critical" detail: str = "" # 文書全体集計型の検出器(antithesis_repetition, repeated_sentence_lead, # repeated_syntax_template, paragraph_lead_conjunction, nominal_ending 等)で、 # 同じ集計に基づく他の該当行番号を列挙するための任意フィールド。 # 単発検出(forbidden_phrase 等)では None のまま。 related_lines: list[int] | None = None # --baseline 比較を行ったときだけ "new" | "persisting" にセットされる # (比較しない通常実行では None のまま。to_dict() で省く)。 status: str | None = None # どう直すかの短い手引き。lint.py がカテゴリごとに付ける(SKILL.md §4 が参照する)。 hint: str = "" def __post_init__(self) -> None: # JSON 出力でも detail 表記と同じく重複除去・昇順に正規化する if self.related_lines is not None: self.related_lines = sorted(set(self.related_lines)) def to_dict(self) -> dict: d = dataclasses.asdict(self) # --baseline を使わない通常実行では status は常に None なので、 # JSON 出力のフィールド構成を従来どおりに保つためキー自体を省く # (--baseline なしの挙動は完全に不変、という要件のため)。 if d.get("status") is None: d.pop("status", None) if not d.get("hint"): d.pop("hint", None) return d # --------------------------------------------------------------------------- # sudachipy Tokenizer は生成コスト(辞書ロード)が高いので遅延・使い回し。 # --------------------------------------------------------------------------- _tokenizer_obj = None def get_tokenizer(): global _tokenizer_obj if _tokenizer_obj is None: from sudachipy import Dictionary _tokenizer_obj = Dictionary().create() return _tokenizer_obj # --------------------------------------------------------------------------- # 体言止め判定(lint.py の nominal_ending 検出器と outline.py の見出し統計で共用)。 # # TRAILING_SYMBOL_POS / NOUN_ENDING_POS / strip_trailing_symbols() は元々 # lint.py 側だけに定義されていたが、outline.py の見出し統計(体言止め率)でも # 同じ判定ロジックが必要になったため、共有基盤である textcore.py に移設した。 # lint.py は本モジュールから import して使う(値は移設前と完全に同一)。 # --------------------------------------------------------------------------- NOUN_ENDING_POS = {"名詞"} TRAILING_SYMBOL_POS = {"補助記号", "空白"} def strip_trailing_symbols(morphemes: list) -> list: """文末(または見出し末尾)の記号(」など)を除いた実質的な最終形態素列を返す。""" i = len(morphemes) while i > 0 and morphemes[i - 1].part_of_speech()[0] in TRAILING_SYMBOL_POS: i -= 1 return morphemes[:i] # --------------------------------------------------------------------------- # テンプレ見出し語彙カタログ(outline.py の見出し統計「テンプレ見出し検出」で使用)。 # # lint.py の BOILERPLATE_HEADING_WORDS(「まとめ」「おわりに」等、締めの定型句のみ) # より対象を広げ、書き出し側の定型(「はじめに」「背景」)も含む。outline.py は # severity 付きの検出器ではなく統計提示なので、ここでのヒットは「AI臭い」の # 断定ではなく判断材料の一つに過ぎない。拡張前提のカタログとして、見出しの # 前方一致で判定する(例:「まとめと今後の課題」は「まとめ」にも「今後」にも # 一部一致しうるが、判定は startswith のみで十分。カタログはリスト順に評価し、 # 最初に一致した語を採用する)。 # --------------------------------------------------------------------------- TEMPLATE_HEADING_WORDS: list[str] = [ "はじめに", "背景", "概要", "本記事について", "この記事について", "まとめと今後", "今後の展望", "今後の課題", "今後について", "まとめ", "おわりに", "終わりに", "さいごに", "最後に", "結論", "総括", "conclusion", "introduction", "summary", ] # --------------------------------------------------------------------------- # Markdown構造行のマスク処理 # 見出し・リスト項目・コードブロック内・引用ブロックは「文章」ではないため、 # 体言止め判定や翻訳調検出などの対象から外す。行を削除すると後続行の行番号が # ズレてレポートの L<n> が狂うので、該当行は「内容を空文字に置き換える」ことで # 行番号を保ったまま解析対象外にする(マスク方式)。 # --------------------------------------------------------------------------- _HEADING_RE = re.compile(r"^\s*#{1,6}(\s|$)") _LIST_ITEM_RE = re.compile(r"^\s*([-*+]|\d+[.)])(\s|$)") _BLOCKQUOTE_RE = re.compile(r"^\s*>") # フェンス行の検出。開始/終了の判定では「同じ文字種(`` ` `` か `~`)かつ # 長さが開始フェンス以上」であることを別途チェックする(``` と ~~~ の混同や、 # フェンス内に出てくる別種・より短いフェンス様の行での誤クローズを防ぐため)。 _CODE_FENCE_RE = re.compile(r"^\s*(`{3,}|~{3,})") # 表の行判定は保守的に: 「行が `|` で始まり、`|` を2個以上含む」または # 区切り行(`|---|---|` 的な、`-`/`:`/`|`/空白のみで構成される行)に限定する。 # 本文中にたまたま `|` が1個だけ出るケースを誤マスクしないための条件。 _TABLE_ROW_RE = re.compile(r"^\s*\|.*\|") _TABLE_DELIMITER_RE = re.compile(r"^\s*\|?[\s:|-]+\|[\s:|-]*\|?\s*$") # YAML フロントマター(ファイル先頭の `---` ... `---`)。先頭行が単独の `---` の # ときだけフロントマターとみなし、次の単独 `---` までをまとめてマスクする。 _FRONT_MATTER_DELIM_RE = re.compile(r"^---\s*$") # インラインコードスパン(`code` / ``code`` のようにバッククォート1〜2個で # 囲まれた範囲)。CommonMark 完全準拠までは不要だが、コード自体にバッククォートを # 含む場合に使われる `` code `` 記法(主用途: コード中に単一のバッククォートが # 含まれる場合、例: `` `code` ``)程度は拾えるようにする。そのため、ダブル # バッククォート側の中身は「バッククォート以外」または「直後がバッククォートでない # 単独のバッククォート」を許可する(`(?:[^`]|`(?!`))+`)。貪欲になりすぎないよう # `` の直前で止まるようにしている。 # 文解析前に該当部分だけ同じ文字数の空白に置換する(行番号・オフセットを保つため)。 _INLINE_CODE_SPAN_RE = re.compile(r"``(?:[^`\n]|`(?!`))+``|`[^`\n]+`") # インデントコードブロック(4スペース以上のインデント)はマスク対象に含めない。 # 通常の文中でも字下げされた引用・リストの続きなど紛らわしいケースが多く、 # 誤マスクのリスクの方が高いと判断して見送る(要検討事項として明示しておく)。 # Markdown 内のリンク・画像 `[text](url)` / `` の url 部分。 # alt/text 側は自然文の一部として残し、URL のみ空白化する。 _MARKDOWN_LINK_URL_RE = re.compile(r"(\]\()([^)]*)(\))") # 画像 `` は alt も含めて丸ごと空白化する。alt は「image.png」「Screen Shot ...」の # ようなファイル名であることが多く、地の文として数えると文頭の反復などの誤検知になる。 _MARKDOWN_IMAGE_RE = re.compile(r"!\[[^\]\n]*\]\([^)\n]*\)") # 地の文に直接書かれた URL と、HTML のタグ(`<img ...>` `<details>` `</h3>` など)。 _BARE_URL_RE = re.compile(r"https?://[^\s)\]>」』)]+") _HTML_TAG_RE = re.compile(r"</?[A-Za-z][A-Za-z0-9-]*(?:\s[^<>\n]*)?/?>") # かな・漢字を1字も含まない行は、日本語の地の文ではない(英文の引用、URL や画像だけの行、 # コードの断片など)。文の長さや文頭の反復の計算に入れない。 _JAPANESE_CHAR_RE = re.compile(r"[ぁ-んァ-ヶ一-龠々〆ヵヶ]") def _mask_html_comments_in_line(line: str, in_comment: bool) -> tuple[str, bool]: """行内の HTML コメント(`<!-- ... -->`)を同じ長さの空白に置換する。 複数行コメント(前の行から続いている/次の行へ続く)に対応するため、 現在コメント内にいるかどうかを in_comment として受け取り、更新後の状態を 返す。1行に複数のコメントが含まれる場合や、コメントの開始・終了が 同一行内で完結する場合にも対応する。閉じタグ `-->` が見つからないまま 行末に達した場合は、行末までを空白化しコメント継続状態のまま返す (CommonMark の閉じられないコメントは EOF までコメントとみなす扱いに合わせる)。 """ out = [] i = 0 n = len(line) while i < n: if in_comment: close = line.find("-->", i) if close == -1: out.append(" " * (n - i)) i = n else: end = close + 3 out.append(" " * (end - i)) i = end in_comment = False else: start = line.find("<!--", i) if start == -1: out.append(line[i:]) i = n else: out.append(line[i:start]) i = start in_comment = True return "".join(out), in_comment def mask_html_comments(text: str) -> str: """HTML コメント(`<!-- ... -->`)のみを同じ長さの空白に置換したテキストを返す。 Markdown 構造(見出し・リスト・太字など)はマスクしない点が mask_markdown_structure() と異なる。構造検出器(detect_structural_ai_habits)は Markdown の構造そのものを検出対象とするため、構造はマスクせず、コメント内の 誤検知だけを防ぐために使う。行数・行内オフセットは元のテキストと完全に一致させる。 """ lines = text.split("\n") masked_lines = [] in_html_comment = False for line in lines: masked_line, in_html_comment = _mask_html_comments_in_line(line, in_html_comment) masked_lines.append(masked_line) return "\n".join(masked_lines) def _blank_inline_code_spans(line: str) -> str: """行内のインラインコードスパン・Markdownリンク/画像のURL部分を 同じ長さの空白に置換する(オフセット保持)。""" line = _INLINE_CODE_SPAN_RE.sub(lambda m: " " * len(m.group(0)), line) line = _MARKDOWN_IMAGE_RE.sub(lambda m: " " * len(m.group(0)), line) line = _HTML_TAG_RE.sub(lambda m: " " * len(m.group(0)), line) # `](url)` の url 部分だけ空白化し、`](` と `)` はそのまま残す # (text/alt 側は文章の一部として解析対象に残すため)。 line = _MARKDOWN_LINK_URL_RE.sub(lambda m: m.group(1) + " " * len(m.group(2)) + m.group(3), line) line = _BARE_URL_RE.sub(lambda m: " " * len(m.group(0)), line) return line def mask_markdown_structure(text: str) -> str: """見出し・リスト項目・コードブロック内・引用ブロック・表・YAMLフロントマターの行を 空文字に置き換え、さらにインラインコードスパンとリンク/画像URLを空白化したテキストを返す。 行数・行番号(およびインラインコードスパンの行内オフセット)は元のテキストと 完全に一致させる(削除ではなくマスク)。 インデントコードブロック(4スペースインデント)はマスク対象に含めない。 箇条書きの折り返しや引用の字下げ等と見分けがつきにくく、誤マスクのリスクが フェンスコードブロックより高いと判断し、プロトタイプの段階では見送っている。 """ lines = text.split("\n") masked_lines = [] in_code_block = False # 開いているフェンスの (文字種, 長さ)。``` と ~~~ の混同や、フェンス内に # 出てくる別種・より短いフェンス様の行での誤クローズを防ぐため、開始フェンスと # 同じ文字種かつ同じ長さ以上の行でしか閉じない(CommonMark 準拠までは行わない)。 open_fence: tuple[str, int] | None = None # YAML フロントマターは「ファイル先頭行が単独の `---`」の場合のみ認識する。 in_front_matter = False # HTML コメント(<!-- ... -->)。複数行にまたがる場合があるため、 # 行をまたいで開いているかどうかを状態として持つ。 in_html_comment = False for idx, line in enumerate(lines): if idx == 0 and _FRONT_MATTER_DELIM_RE.match(line): in_front_matter = True masked_lines.append("") continue if in_front_matter: masked_lines.append("") if _FRONT_MATTER_DELIM_RE.match(line): in_front_matter = False continue fence_match = _CODE_FENCE_RE.match(line) if fence_match: fence_run = fence_match.group(1) fence_char = fence_run[0] fence_len = len(fence_run) # CommonMark に合わせ、閉じフェンスは「フェンス文字の連続+後続は空白のみ」の # 行に限定する(開始フェンスは ```python のような info string を許容するが、 # 閉じ側でそれを許すと、フェンス内の地の文がたまたま ``` で始まっただけの # 行を誤ってクローズ扱いしてしまう)。 remainder_after_fence = line[fence_match.end() :] is_close_eligible = remainder_after_fence.strip() == "" if open_fence is None: open_fence = (fence_char, fence_len) elif fence_char == open_fence[0] and fence_len >= open_fence[1] and is_close_eligible: open_fence = None # 種類・長さが一致しない行、あるいは後ろに文字が続く行は # 「フェンス内の地の文(例: ```内で ~~ とだけ書いた行や ```これはコード)」 # として扱い、トグルしない。 masked_lines.append("") continue if open_fence is not None: masked_lines.append("") continue line, in_html_comment = _mask_html_comments_in_line(line, in_html_comment) if ( _HEADING_RE.match(line) or _LIST_ITEM_RE.match(line) or _BLOCKQUOTE_RE.match(line) or (_TABLE_ROW_RE.match(line) and line.count("|") >= 2) or _TABLE_DELIMITER_RE.match(line) ): masked_lines.append("") continue line = _blank_inline_code_spans(line) if line.strip() and not _JAPANESE_CHAR_RE.search(line): line = "" masked_lines.append(line) return "\n".join(masked_lines) def iter_lines_with_no(text: str) -> list[tuple[int, str]]: """1-indexed 行番号付きで行を返す。""" return list(enumerate(text.splitlines(), start=1)) def find_line_no(lines: list[tuple[int, str]], needle: str, start_hint: int = 0) -> int: """needle を含む行番号を探す。 start_hint(探索を始めたい行番号、例: 対象段落の開始行)以降を優先的に走査する。 同一内容の段落が文書中に複数回登場する場合、常に先頭から検索すると 最初に出現した行に誤帰属してしまうため、start_hint 以降の一致を優先し、 見つからない場合のみ文書全体(start_hint より前)にフォールバックする。 """ for no, line in lines: if no >= start_hint and needle in line: return no for no, line in lines: if needle in line: return no return start_hint or 1 def iter_paragraphs_with_lines( lines: list[tuple[int, str]], ) -> list[list[tuple[int, str]]]: """行番号付きの行リストを、空行区切りの段落(行のグループ)に分ける。 段落の開始行が呼び出し側に正確に分かるため、re.split(r"\\n\\s*\\n", text) と テキスト検索(find_line_no)による近似の line_cursor 計算に頼らずに済む。 同一内容の段落が複数回登場しても、行番号を直接持っているので誤帰属しない。 """ paragraphs: list[list[tuple[int, str]]] = [] current: list[tuple[int, str]] = [] for no, line in lines: if line.strip(): current.append((no, line)) else: if current: paragraphs.append(current) current = [] if current: paragraphs.append(current) return paragraphs # --------------------------------------------------------------------------- # 文分割 # --------------------------------------------------------------------------- SENTENCE_SPLIT_RE = re.compile(r"[。!?\n]") def split_sentences_with_lines( lines: list[tuple[int, str]], raw_lines_by_no: dict[int, str] | None = None ) -> list[tuple[int, str, str]]: """行番号付きで文を分割する(。!?で分割、行内に複数文があれば同じ行番号を割り当てる)。 マスク済みテキスト(見出し・表マスクやインラインコードスパンの空白置換済み)と 原文(raw_lines_by_no)を同じオフセットで同時に切り出し、 (行番号, マスク済み文, 原文の文) の3要素タプルを返す。 マスク処理は「行の全置換(同じ長さの空文字ではなく行そのものを""にする)」か 「インラインコードスパンを同じ文字数の空白に置換」のいずれかで、 どちらも文字位置を保つため、マスク済みテキストで見つけた区切り位置をそのまま 原文の同じオフセットに適用できる。 見出し・表・コードブロックなどマスクで丸ごと空文字になった行は、マスク済み側が 空になり文が生成されないため、原文にレポートに出したくない構造行の内容が 紛れ込むことはない。 """ sentences = [] for no, line in lines: raw_line = raw_lines_by_no.get(no, line) if raw_lines_by_no else line bounds = [] prev = 0 for m in SENTENCE_SPLIT_RE.finditer(line): bounds.append((prev, m.start())) prev = m.end() bounds.append((prev, len(line))) for s, e in bounds: piece = line[s:e] if piece.strip(): raw_piece = raw_line[s:e] if len(raw_line) >= e else piece sentences.append((no, piece.strip(), raw_piece.strip())) return sentences # --------------------------------------------------------------------------- # 見出し行パーサ(outline.py / terms.py で共用) # --------------------------------------------------------------------------- def _heading_level_and_text(line: str) -> tuple[int, str]: """見出し行から (レベル, 見出しテキスト) を取り出す。 ATX見出しの closing sequence(末尾の `#` 列)は、CommonMark と同様に 「直前に空白がある場合のみ」除去する。空白なしで見出しテキストに直接続く `#`(例: 「# C#」「# F#入門」)は closing sequence ではなくテキストの一部 なので、除去してはいけない(`(?:\\s+#+)?` で closing sequence の手前に 最低1文字の空白を要求することで区別する)。 """ m = re.match(r"^\s*(#{1,6})\s*(.*?)(?:\s+#+)?\s*$", line) if not m: return 0, line.strip() return len(m.group(1)), m.group(2).strip() # --------------------------------------------------------------------------- # ファイル読み込みと入力エラー処理 # # 「文章の中身に関する判断」と「そもそも実行できない入力エラー」は区別する # (lint.py/outline.py/terms.py 共通の方針)。前者は exit 0(判断は人間/AIに委ねる)、 # 後者(ファイル不在・ディレクトリ指定・読み取り不可・非UTF-8等)は exit 1。 # 3つのエントリスクリプトがまったく同じエラーメッセージ・判定順序で読み込めるよう、 # ここに一本化する。 # --------------------------------------------------------------------------- def read_source_file(path: Path) -> tuple[str | None, str | None]: """path を UTF-8 テキストとして読み込む。 成功時は (text, None)、失敗時は (None, error_message) を返す。 呼び出し側は error_message を stderr に出力し、exit code 1 で終了する (このモジュールは exit しない。呼び出し側の CLI が判断する)。 """ if not path.exists(): return None, f"エラー: ファイルが見つかりません: {path}" if path.is_dir(): return None, f"エラー: ディレクトリが指定されました(ファイルを指定してください): {path}" try: return path.read_text(encoding="utf-8-sig"), None except (OSError, UnicodeDecodeError) as exc: return None, f"エラー: ファイルを読み込めません: {path} ({exc})"skills/natural-japanese/references/diagnose.md4.9 KB8f436ac489b9upstream ↗
# 診断モード(score):書き換えずに、AI臭さをスコアと理由で返す 診断モードは文書を一切書き換えず、スコア、その根拠、直すなら何からか、の3点だけを返す。「この文章、AIっぽい?」「どれくらいAI臭いか採点して」という依頼に答えるためのモードで、リライトを求められたら通常の工程(SKILL.md §1〜7)へ切り替える。 ## 3段階の深さ 診断の quick / full / exp は、どこまで深く見るかの指定である。書き換えの工程がないので、SKILL.md の実行モードとは中身が違う。食い違うときは、この節に従う。 - quick(既定):`lint.py --json`(ジャンルが分かれば `--genre`)を1回と、見出しと各段落の先頭文にざっと目を通す。サブエージェントは使わない。30秒程度 - full:quick に加えて `outline.py` と `terms.py` を実行し、構造の点検・読みやすさの点検・文書タイプの照合(SKILL.md §5)の結果を判断に入れる。長い文書を分担して読むと速い場合だけサブエージェントを使ってよい。診断では収束の確認は行わず、1回の評価で終える。数分 - exp:full に加えて 実験的な検出器の `semantic.py --json` を実行する。初回に約1GBのモデルをダウンロードするので、初回は始める前にユーザーに伝える。言い回しを整えたあとにも残る、話題の平板さまで見る ## スコアの算出:機械ベースと判断調整の二層 スコアは0〜100の自然度で、高いほど自然(AI臭が薄い)。ユーザーへ返すときも向きを一言添える。二層で作り、内訳を必ず開示する。 機械ベース(決定的):100点から lint の指摘を文書長で正規化して減点する。critical・warn・info は、lint のテキスト出力では「重大」「警告」「情報」と表示される。 ``` 減点 = (critical×8 + warn×4 + info×0.5) × (1000 / max(文書の文字数, 1000)) 機械ベース = max(100 − 減点, 20) ``` 文書の文字数は本文全体の文字数。改行・Markdown記法込みの len でよい(目安の正規化なので厳密さは要らない)。短い文書ほど1件の重みが大きく、長い文書では件数よりも密度で減点される。係数は、critical の指摘1件が warn 2件、info 16件に当たるように置いた目安である。下限の20は、機械の指摘だけでスコアが0近くまで下がらないようにするための値。exp で semantic_topic_flatness(warn)が出た場合も同じ式に含める。本文が空か実質空(100字未満)の場合はスコアを出さず「診断対象として短すぎる」と返す。 判断調整(±15点の範囲):full / exp では、構造と読みやすさの点検で見つけた問題で調整する。lint では検出できない、次のような構成の癖は減点する。 - どの節も同じ組み立てになっている - 根拠や関係のない箇条書きを並べている - 確信の度合いが書き分けられていない - レポートで、次にすべきことが書かれていない - もともと並列な項目に順位を付けている lint が誤検知気味でも、文脈上自然と判断した指摘は減点を戻す。quick では調整せず機械ベースをそのまま使う(そのぶん「quick の精度は粗い」と明記して返す)。調整後の最終スコアは 0〜100 に切り詰める(min(max(スコア, 0), 100)。機械ベースが100で加点調整しても100を超えない)。 スコアは判断を含む目安であり、同じ文書でも数点は揺れる。CI のゲートに使う数値ではない。この注意は結果に一言添える。 ## バンドと言い方 | スコア | バンド | 伝え方の例 | |---|---|---| | 90〜100 | 自然 | AI臭はほぼ見当たらない。指摘があっても好みの範囲 | | 70〜89 | 軽微 | 数カ所に癖が残るが、読み手が「AIっぽい」と感じる可能性は低い | | 50〜69 | 要修正 | 表層か構造のどちらかに明確なAI臭がある。直す価値がある | | 0〜49 | 濃厚 | 複数のカテゴリで強く検出。リライト推奨 | ## 出力の形式 1. スコアとバンド(機械ベースと判断調整の内訳つき) 2. 主な理由を3〜5個:カテゴリ名でなく中身で書く。「『〜ではなく』の対比が全文の文のうち4%で機械的なリズムになっている(L12ほか)」のように、代表箇所の行番号と、なぜそれがAI臭なのかを一言で 3. 直すなら何から:効果の大きい順に2〜3個。ただし診断モードでは直さない。「リライトしますか(quick/full)」と添えて終える 理由は lint の detail の転記ではなく、文書の文脈に即して言い直す。指摘が多い場合も全部は並べず、スコアをもっとも動かしたものに絞る。skills/natural-japanese/references/doctypes/guide.md14 KB7b4065875942upstream ↗
# 社内ガイド・マニュアル:読み手は迷ったときだけ開く 社内ガイドが答える問いは、いまこの操作をどうやればよいかである。仕組み全体を理解してもらうことは主な目的ではない。読み手の多くは通読せず、目次や検索から目当ての章に飛び、その章だけを読んで作業に戻る。そのため、ガイドの良し悪しは、通読したときの完成度より、一部だけを読まれたときに迷わせないかで決まる。この文書では章立てと章どうしの導線を扱う。文の書き方は SKILL.md §2 に従う。 ## 必須要素 - 冒頭の「まず覚えること」(最低限これだけ守ればよい行動を、番号つきで3〜4個) - 対象の読み手。タイトルか冒頭の一言で分かれば足りる。前提知識は、読み手が自分に合うガイドかを判断するのに要るときだけ書く - 通読する部分と、必要なときに引く部分の区別(冒頭で「1〜3章は初回に通読、4章以降は必要なときに引く」のように書く) - 用語集。読み手が知らない用語が本文に出てくるときに置く。本文中で説明した用語も、末尾に一覧としてもう一度置く - 問い合わせ先(このガイドで解決しない疑問をどこに持ち込むか) このうち抜けやすいのは、通読する部分と引く部分の区別である。書き手は目次を見れば分かるつもりでいるが、読み手は目次だけでは判断できない。冒頭で、どこまで読めば最低限の理解になるかを書いておかないと、読み手は毎回すべての章に目を通すか、必要な章まで読み飛ばすかのどちらかになる。 ## 構成は章の性質で変える すべての章を同じ組み立てで書くと、読み手は章ごとに、どこまで丁寧に読めばよいかを判断し直すことになる。章の性質に合わせて組み立てを変えると、読み手は組み立てを見ただけで読み方を切り替えられる。 - 物語型:入門の章に向く。作業の流れに沿って順に説明する - 逆引き型:「〜したい」に対して手段を示す、対応表に近い組み立て。目的が先に決まっている読み手に向く - ハンズオン型:1操作1ステップで並べ、各ステップの直後に、なぜその操作をするかを一言添える。手順と理由が交互に出てくるので、読み手は暗記でなく理解して操作を追える - リファレンス型:パラメータや設定項目を表で並べる。地の文で説明するものではない どの組み立てでも、次の書き方を基本にする。ガイドは引く文書で、読み手は自分に関わる行を探して読むので、SKILL.md 原則3の「箇条書きは本当に独立して並ぶときだけ」より、こちらを優先する。 - 冒頭は、読み手に向けた一言で始めてよい(新しく加わった人向けなら、歓迎の一言)。続けて「まず覚えること」を番号つきで3〜4個並べ(多いと覚えられない)、そのあとに読む範囲の案内を書く。誰がこのガイドを用意したか、どんな前提で読めるか、のような、読み手が次の行動に使わない前置きは書かない - 見出しは、何についての節かがすぐ分かる短い名前にする(「VPN につながらないとき」「パスワードの再設定」)。結論の文を見出しにして、中身を地の文で書く組み立ては、ガイドでは読み飛ばされる。ガイドでは、SKILL.md §1 の見出しの規則より、こちらを優先する。逆引き型の章だけは、見出しに答えまで書く(後述の例) - 一つの項目(期限のある決まり、一つの操作、一つの例外)には、一つの小見出しを付ける。項目を一つの節にまとめて地の文でつながない。各項目の中身は、箇条書きと番号だけで書き、導入の一文や理由の段落を挟まない。理由が要るときは、その行の末尾に、読点のない一言を括弧で添える。読点が要るほど長くなるなら、次の行に一文で書く - 手順は番号つきで、1ステップに1つの動作を書く。手順の前に、何をする手順かを一文で書く。理由は手順の直後に一言だけ添え、長い説明は別の節に分ける(手順の途中で仕組みの説明を始めない) - 決まり(期限、条件、例外)は箇条書きにする - 「該当の」「当該」「〜の際は」のような硬い言い回しを使わず、ふだん話す言葉で書く(「該当の節を開く」ではなく「その節を開く」) - よくある間違いは、「症状」と「直し方」の2列の表にする(「VPN につながらない|ルーターを再起動してから、もう一度つなぐ」)。読み手は症状から探すので、直し方まで同じ行で分かるようにする。問い合わせ先(困りごと|連絡先)と用語(用語|意味)も表にする - 読み手に向けた文は、主語が読み手になっているかを確かめる。書き手側の事情(誰が配るか、なぜこのガイドを作ったか)を、読み手への指示と一文に混ぜない。「全体会議で共有し、迷ったときに参照してください」は、共有するのは書き手で参照するのは読み手なので、主語がねじれている 込み入った説明は本文に混ぜず、「補足」として章末などに分ける。ただし、補足への導入文を毎回同じ言い回しにすると、それ自体が単調な型になる。章ごとに、何を補足しているかが分かる一言にする。 ## 品質基準 - 目次の見出しだけを見て、目的の章にたどり着ける。「概要」「利用方法」のような中身の分からない名前ではなく、「VPN につながらないとき」のように、何についての節かが分かる名前にする - 前の章を読んでいない読み手が、その節だけを読んで作業できる。「ここまでで〜できました。ここからは〜です」のような章の橋渡しの文は書かない。引く文書では読まれず、節の中身を長くするだけになる。物語型の長い入門の章に限り、前の章との関係を一言書いてよい - 同じ概念を複数の章で説明するとき、あとの章は違いだけを書いている。「詳細は3章を参照。ここでは4章で違う点だけを述べる」のように書く - まだ書けていない章を、ほかの章と同じ厚みの定型文で埋めていない。「準備中」と書いて問い合わせ先だけを示せば十分な章もある - してはいけない操作を、操作と結果の組で書いている。「注意してください」で終わらせず、その操作をすると何が起きるかまで書く ## AI がやりがちな失敗 もっとも多いのは、すべての章を同じ組み立て・同じ文の長さで書き、読み手が章ごとの重さを判断できなくなる失敗である。2行で済む章も10行かかる章も、同じ見出しの階層と節の構成で書いてしまう。書く前に、章ごとにどれだけ書く価値があるかを決めておくと防げる(SKILL.md §1「濃淡」)。 次に多いのが、「詳細は次章で解説します」のような定型の橋渡しを全章に貼る失敗で、橋渡しがあるように見えて、何もつないでいない。もう一つは、確かめていない画面の操作や挙動を断定で書く失敗である。確かめていない手順は「〜と表示される想定」のように確かさを書き分け、断定は、素材やユーザーが確かめた範囲に限る。 ## 特に関わる原則(SKILL.md §2) - 原則2(見出し):ガイドでは、見出しは結論の文ではなく、何についての節かが分かる短い名前にする。逆引き型の章では、各行が「症状や目的 → 手段」の対応になる - 原則7(濃淡):通読する部分は厚く、引く部分は表と短い注釈で軽く書く - 原則8(同じ型を続けない):章の書き出し、深掘りノートの導入文、ほかの章への参照の言い回しが、3回続けて同じ形になっていないかを見る - 原則10(確信の度合い):確かめていない手順や、まだ書けていない章は、その状態をラベルで示す ## 雛形:ガイド一本の形 架空の会社の、社内 VPN の接続ガイドを例にする。 ``` # 社内 VPN 接続ガイド(在宅勤務をする人向け) 在宅勤務を始める方へ。自宅から社内のシステムを使うときは、このガイドの手順で VPN につないでください。 ## まず覚えること 1. 社内のシステムを使う前に、VPN アプリで「接続」を押す 2. パスワードは90日ごとに変わる。期限の7日前に通知が届く 3. つながらないときは、下の「困ったとき」を見る 初回は「はじめての接続」だけを読めば足ります。ほかの節は、必要になったときに開いてください。 ## はじめての接続 1. 社内ポータルから VPN アプリをダウンロードする 2. アプリを開き、社員番号とパスワードを入れる 3. スマートフォンに届く確認コードを入れる ## パスワードの更新 - 90日ごとに更新が必要 - 期限の7日前に、メールで通知が届く - 期限を過ぎると接続できなくなる(情報システム部で再発行が必要) ## 困ったとき | 症状 | 直し方 | |---|---| | 「認証に失敗しました」と出る | パスワードの期限が切れていないか確かめる | | つながるがすぐ切れる | 自宅のルーターを再起動してから、もう一度つなぐ | | 確認コードが届かない | 情報システム部に連絡する | ## 問い合わせ先 | 困りごと | 連絡先 | |---|---| | 接続の操作 | 情報システム部(#it-help) | | 在宅勤務の申請 | 総務部 | 最終更新日:2026年4月1日 ``` この雛形では、冒頭の一言は読み手を主語にした指示だけにし、誰が作ったかは書いていない。一つの項目に一つの小見出しを付け、中身は番号と箇条だけで、地の文の段落はない。症状と直し方、問い合わせ先は表にしている。理由は「(情報システム部で再発行が必要)」のように、行の末尾の括弧で一言にとどめている。 ## 例:経費精算システムの社内ガイド 次の素材から、ガイドの章を書く場合を考える。 素材:申請は領収書1枚につき1件。経理の突き合わせが領収書単位なので、まとめて申請すると差し戻しになる。承認後の振込は自動で、通常は3営業日。月末は遅れることがあるが、どのくらい遅れるかは経理チームに確認中。 中身の分からない見出しと地の文で書いた例: > ## 概要 > 経費精算システムの使い方を説明します。申請は領収書1枚につき1件です。経理の突き合わせが領収書単位で行われるため、まとめて申請すると差し戻しになりますので注意してください。承認後は自動で振り込まれます。 何の節かが分かる見出しと、箇条書きで書いた例: > ## 申請のしかた > - 領収書1枚につき1件で申請する。まとめて申請すると差し戻しになる(経理の突き合わせが領収書単位のため) > > ## 振込 > - 承認後、自動で振り込まれる。通常は3営業日 > - 月末は遅れることがある。どのくらい遅れるかは経理チームに確認中【要確認】 二つの例は同じ素材だけを使っている。あとの例は、見出しで探して、箇条の一行だけを読めば用が済む。理由は括弧で一言にとどめ、確かめていない月末の遅れは、断定せずに【要確認】と書いている。 逆引き型の章では、見出しの形そのものを変える。同じガイドの「困ったとき」の章を、次の素材から書く場合を考える。 素材:領収書をなくしたときは「紛失理由書」フォームから代わりに申請できる。差し戻しの理由は、通知メールの末尾に書いてある。海外出張の外貨の領収書は、申請日のシステム内レートで自動で換算される。 見出しを次のように並べる。 > ## 領収書をなくした → 「紛失理由書」フォームから代わりに申請できる > ## 申請が差し戻された → 差し戻しの理由は、通知メールの末尾に書いてある > ## 海外出張の領収書が外貨 → 申請日のシステム内レートで自動で換算される 物語型の章がひとつの操作の流れを順に説明するのに対し、逆引き型の章では各行が独立した対応になる。読み手は自分の状況に近い行だけを読むので、行どうしのつながりは気にしなくてよい。同じガイドの中でも、章によって組み立てを変えてよい。 ## ガイドは使われながら直していく 社内ガイドは、読み手からの質問がそのまま次の改訂の材料になる文書である。末尾に最終更新日を置き、この章で分からなかった点の問い合わせ先を添えておく。 改訂のたびに全章を書き直す必要はない。質問が集中した章だけを厚くし、質問のない章はそのままでよい。すべての章を同じように更新し続けると、どこが変わったのかが読み手に分からなくなる。 議事録やレポートと違い、社内ガイドは書いた時点の状態を残すための文書ではない。読み手のいまの行動を変えるための文書なので、古い手順が残っていると実際に誤った操作につながる。最終更新日は隠さずに書く。skills/natural-japanese/references/doctypes/memo.md11 KB1713f021ceeeupstream ↗
# リサーチメモ・ディスカッションペーパー:決めたいことを先に書く リサーチメモが答える問いは、この論点について今どこまで分かっていて、何がまだ決まっていないか、そして読んだ人に何を判断してほしいかである。何が起きたかを残す議事録とも、調査結果を確かな情報として伝えるレポートとも違う。結論が固まる前に、たたき台として読み手の判断や議論を引き出すために書く。そのため、仮の結論と、未解決の論点の両方を書く必要がある。 ## 必須要素 - タイトルか冒頭の一文に、中心の主張を置く(「〜について」でなく「〜すべきである」「〜が課題である」の形) - タイトルと冒頭の一文は、本文を読む前でも意味が通る言葉で書く。本文で初めて説明する呼び名(「A案」「第2案」など)を使わず、中身で言う(「A案を採用したい」でなく「紙の申請書をやめて Web フォームにしたい」) - 範囲と対象外(何を論じ、何をあえて論じないか)。対象外は、素材やユーザーの言葉にあるものだけを書く - 背景→問題の設定→提案や論点→未解決の論点→結論、の順に書く - このメモで何を決めたいか(冒頭に書く) ## 構成 冒頭で中心の主張と、決めたいことを示してから、背景と問題の設定に移る。結論がまだ固まっていないときも、「現時点での見立て」であることを書いたうえで、先に示す。背景から順に読まないと主張にたどり着けない構成では、途中で読むのをやめた人には何を言いたいメモだったかが伝わらない。 概念の定義は、用語集として切り出さず、地の文の中で書く。「Xとは〜である」という定義文が段落の先頭に3回続くと、それだけで機械的に見える(SKILL.md §2 原則8)。説明の文を先に書いて、使ったあとで名前をつける形(「この動線を、本メモでは平時導線と呼ぶ」)を混ぜると、同じ型が続かない。長い定義を括弧に挟んで文の途中に入れる形は、読み手が文の筋を見失うので使わない。名前を付けるなら、名前だけで中身が分かるものにする(SKILL.md §2 原則4)。 選択肢を比べるときは、メリットとデメリットを並べるより、軸を決めた比較表のほうが読み手の判断を助ける。「コストが低い/高い」「導入が速い/遅い」のように、選択肢をまたいで同じ軸で並べると、読み手は自分の優先順位に合わせて表を読める。その軸が当てはまらない選択肢のマスは「—」にする。「該当しない」「記載なし」のように、表の都合や素材の都合をそのまま書かない。 範囲と対象外を書かないと、読み手は、なぜこの論点に触れていないのかを疑う。あえて論じない理由(ほかの場で決着している、今回は情報が足りない、など)を一言添えると、書き漏らしでなく意図して外したことが伝わる。ただし、素材にない対象外(「顧客からの問い合わせは含めない」など)を、もっともらしく作って書かない。 ## 書き手の見立てについて メモの価値は、未解決の論点に、書き手の現時点での見立て(「現時点では A 案に傾いている」など)が添えてあることにある。疑問を並べただけでは、議論の起点にならない。 ただし、見立ては書き手のものである。あなたがユーザーのためにメモを書くとき、見立ては素材やユーザーの言葉にあるものだけを書く。なければ、ユーザーにどちらに傾いているかを聞く。既存のメモを直すときに、元にない見立てを書き足してはいけない(SKILL.md の冒頭の規則)。 書き足してはいけないのは、見立てだけではない。「〜と分かったら始めないほうがよい」のような条件付きの判断や、評価の指標、スケジュール、続けるか止めるかの目安、新しい窓口や手順といった計画も、素材になければ書かない。書き手が約束していないことを書き手の計画として書くと、読み手はそれを提案の一部として受け取ってしまう。計画が足りないと思ったら、本文に足さずにユーザーに伝える。 見立ては、論点そのものへの見方であり、論点に「最優先・次点・後回し」のような順位や段階を付けることではない。とくに、どの対象にも同じように当てはまることが主張の中心なら、対象を格付けせず並列のまま書く。未解決の論点も、優先順位でなく種類でまとめられないかを先に考える。 ## 品質基準 - タイトルか冒頭の一文だけで、何を主張するメモかが伝わる。「〜についての検討」のように対象を示しただけで終わっていない - 未解決の論点に、書き手の見立てが添えてある。ただ並べて「今後の検討課題」で締めていない - 選択肢の比較に、読み手が使える軸がある - 一般論でなく、書き手が確かめた事例や数値が中心の主張を支えている。固有名詞や数値を抜いても成り立つ主張なら、素材が足りていない - 読んだ人が、次に何を判断すればよいかが分かる - 素材にない判断や計画(評価の指標、スケジュール、条件付きの判断など)を書き足していない ## AI がやりがちな失敗 もっとも起きやすいのは、概念の整理だけで、書き手が確かめた一次情報や事例がまったく出てこない失敗である。「一般に〜と考えられる」「〜というアプローチが有効である」のような文だけで段落が埋まると、誰が書いても同じ内容になる。扱う論点のうち、素材のある2〜3個に絞って厚く書き、残りは短く書く(SKILL.md §2 原則7)。 もう一つは、未解決の疑問を並べただけで、書き手の見立てがどこにもないまま終わる失敗である。逆に、AI が素材にない見立てや数値をもっともらしく書き足してしまう失敗もある。見立ては素材かユーザーから得る。 ## 特に関わる原則(SKILL.md §2) - 原則1(結論を先に):タイトルと冒頭の一文で中心の主張を示す。「〜について検討する」という前置きは、主張の代わりにならない - 原則3(因果や経緯は地の文で):論点の背景や経緯は地の文で書き、箇条書きは比較の軸や選択肢の一覧のように本当に並列な項目だけに使う - 原則10(確信の度合い):未解決の論点は「未解決」と書いたうえで、見立てを添える - 原則11(事実と意見):一次情報や調査結果と、書き手の見立てを混ぜない。「〜と考える」「〜と推定する」を書き分ける ## 例:防災アプリのコンセプトメモ 次の素材から、メモを書く場合を考える。 素材(ユーザーから受け取ったもの):県内の自治体アプリの利用状況を調べた県の報告書では、ダウンロード数に比べて災害時の起動率が低い。原因は、平時に開く理由がないことだと自分は見ている。通知方式の候補は、プッシュ通知だけの案、サイレンと連動する案、両方を組み合わせる案の3つ。比べる軸は、届く速さ、電池の消費、誤報のときに取り消しやすいか。プッシュ通知だけの案は速いが、誤報のときに不信感を招きやすいので、いまは組み合わせる案に傾いている。高齢者向けの画面をどう検証するかは決まっておらず、社内にユーザーテストの経験がない。外部の使い勝手調査に予算をつけるかを決めたい。 対象を示しただけで、疑問を並べて終わる例: > # 地域防災アプリの検討について > > 近年、災害時の情報伝達手段としてスマートフォンアプリが注目されている。本メモでは地域防災アプリの可能性について検討する。 > > 検討すべき論点は以下の通りである。 > - 通知の仕組みをどうするか > - 高齢者にも使いやすいUIをどう実現するか > - 平時の利用をどう促すか > > これらについては今後さらなる検討が必要である。 主張と見立てを先に書いた例: > # 防災アプリが災害時に開かれない原因は、平時に開く理由がないことだと考える > > 県の報告書によると、県内の自治体アプリは、ダウンロード数に比べて災害時の起動率が低い。筆者は、原因は平時に開く理由がないことにあると考えている。このメモでは、通知方式と高齢者向けの画面について、判断してほしい論点を示す。 > > 通知方式の候補は、プッシュ通知だけ、サイレン連動、その組み合わせの3案で、届く速さ・電池の消費・誤報のときの取り消しやすさで比べられる。プッシュ通知だけの案は速いが、誤報のときに不信感を招きやすい。筆者は現時点では組み合わせる案に傾いている。 > > 未解決なのは高齢者向けの画面の検証方法で、社内にユーザーテストの経験がない。外部の使い勝手調査に予算をつけるかどうかを、このメモで判断してほしい。 主張と見立てを先に書いた例は、素材にある事実と見立てだけを使い、出典(県の報告書)を示して、「考える」「傾いている」で意見を事実と分けている。原因の見立ては、タイトルでも「考える」と書き、事実として言い切っていない。素材にない数値・比較・提案は足していない。 ## 議事録・レポートとの違い リサーチメモは、記録である議事録(→ `minutes.md`)や、確かな事実を伝えるレポート(→ `report.md`)より前の段階で書くもので、議論が始まる前に論点を示す文書である。そのため、末尾には決定事項でなく、判断してほしい論点を置く。この違いを意識しないと、まだ固まっていない論点を確かなことのように書いてしまい、あとで訂正が要る。 メモは、読み手が賛成や反対を返すことを前提に書く。論点ごとに、読み手に何を判断してほしいかを一文で書いておくと、読み手が返答しやすくなる。skills/natural-japanese/references/doctypes/minutes.md8.7 KB815c99c52440upstream ↗
# 議事録:決定と宿題を本文から分けて書く ## この文書が答える問い 議事録が答える問いは、何が決まり、誰が、いつまでに、何をするかであり、発言を記録すること自体は目的ではない。読み手の多くは会議に出ていなかった人か、出ていたが記憶があいまいな人で、決定事項と宿題を数十秒で確かめられればよい。発言を時系列でなぞっただけの記録では、決定事項が本文に埋もれ、読み手は全文を読み直すことになる。 ## 必須要素 会議名・日時・参加者、議題ごとの議論の要点、決定事項、宿題(担当者と期日つき)、継続議題。このうち決定事項・宿題・継続議題の3つは、本文の議論から分けて、冒頭にまとめる。本文に埋めたままだと、読み手が「結局何が決まったのか」を自分で拾い集めることになる。 宿題には担当者と期日を書く。「チーム全員で対応」「なるべく早く」では、誰がいつ動くのかが決まらない。担当者が決まっていなければ「未定」と書く。 既存の議事録を直すときは、元の記録にない担当者や期日を推測で埋めない。元にない列や節(期日の列、継続議題の節など)を足した結果、中身が「未定」ばかりになるなら、その列や節は足さない。 ## 構成 この節の構成は、新しく書くときのものである。既存の議事録を直すときは、節の順序や組み立てを変えない(SKILL.md §3)。決定事項や宿題を前に出したほうが読み手が探しやすいと思ったら、そうすることをユーザーに提案する。 冒頭に会議名・日時・参加者・事前資料を、1項目1行の箇条書きで置く。Markdown では改行しただけの行は表示すると一つの段落につながり、雑多な情報が一塊になって読む気をなくすので、地の文の行を並べない。続けて記録の前提を一段落で書く。文字起こしの精度、録音の有無、発言者の特定がどこまで確かかを最初に示しておくと、読み手は本文をどこまで信じてよいかを自分で判断できる。訂正の連絡先(コメント、Slack など)もここに書く。 その次に、決定事項・宿題・継続議題をまとめる。読み手がまず確かめたいのはここなので、本文より前に置く。決定事項と継続議題は箇条書き、宿題は担当・内容・期日の表か箇条書きにする。 本文は議題ごとに節を分け、見出しにはその議題で何が決まったか、決まらなかったか、何を議論したかの要約を書く。本文の経緯は地の文で書く。2行で済む議題を、10行かかる議題と同じ重さで扱わない。必要なら末尾に「次回に向けたメモ」を添える。このメモには本文の繰り返しでなく、次回に何を変えるかだけを書く。 文体は体言止めと「である」調でよく、丁寧体にそろえる必要はない。核心の発言は、話した人の口調のまま残す。「それ先に言ってよ」を「それを先に言ってほしい」に整えると、発言の勢いと、誰がどう言ったかという情報が消える。 ## 品質基準 - 決定事項の一覧を読むだけで、何がどう変わったかが分かる。「引き続き検討する」は決定ではないので、継続議題に回す - 宿題は、担当者・期日・内容の3つがそろっている。良い例は「田中: 在庫アラートのしきい値案を7/18までに作成」、悪い例は「アラートのしきい値については検討していく」 - 発言者の確かさを書き分けている。文字起こしから話者を推定した箇所には「(佐藤さんと推定)」のように添える - 議論の経緯は地の文で書き、決定と宿題だけを箇条書きにしている。議論には因果と時系列があるためだ。ただし、助言の一覧のように項目が独立していて、あとから特定の項目を探すものは箇条書きのまま残す - 助言や指摘には、相手の反応が一言添えてある。レビューや1on1で助言だけを記録すると、一方向の講義の記録になり、何が合意されたかが分からなくなる。「了承した」「持ち帰って検討する」の一言でよい。元の記録に反応が書かれていなければ、推測で書かない ## AI がやりがちな失敗 議事録を書かせると、全発言を同じ重さで要約し、決定事項が他の意見と同じ重みで埋もれることがもっとも多い。5分で終わった確認と30分議論した論点が同じ行数で並ぶと、読み手はどこが重要だったかを判断できない。発言者の確かさも書き分けられず、全員が言い切るか、全員が「〜と思われる」になりやすい。 決まっていないことを「合意した」と書くのも、よくある失敗である。発言録から決定を抜き出すときに、提案や賛成を決定と取り違えやすい。 もう一つは、「えーと」「まあ」のような言いよどみは消すのに、話し言葉の冗長な言い回しは残すことだ。「その件についてはですね、まあ一旦持ち帰らせていただいて、社内で検討した上でまた改めてご相談させていただければと思うんですけれども」は、「持ち帰って検討する」で足りる。 ## 特に関わる原則(SKILL.md §2) - 原則10(確信の度合いを書き分ける):記録の限界と、発言者の確かさを書き分けることが、議事録の中心の役目になる - 原則3(因果や経緯は地の文で):議論の経緯を箇条書きで並べず、地の文で追う - 原則2(見出しに結論を書く):議題の見出しは「議題1」でなく、その議題で何が決まったかを書く - 原則7(濃淡):軽い議題は一言で済ませ、重い議題だけ厚く書く - 原則6(太字):核心の発言を残すときも、太字にするのはその発言の中心だけにする ## 雛形 架空の SaaS 企業ソラベース社が開発する在庫管理サービス「在庫すいすい」の開発定例を例にする。 ``` # 在庫すいすい開発定例(2026-07-10) - 日時: 2026-07-10 10:00〜10:30 - 出席: 田中(PM)、佐藤(バックエンド)、鈴木(デザイン) - 事前資料: 在庫アラートの誤検知の一覧(6月分) 記録の前提: 会議の録音はなく、田中のメモをもとに構成した。発言者の帰属はおおむね確実だが、推定が入る箇所には「(推定)」と添える。訂正はこのドキュメントへのコメントで受け付ける。 ## 決定事項 - しきい値の算出方法を、在庫数から在庫回転率に変更する ## 宿題 - 田中: 回転率ベースのしきい値案を7/18までに作成 - 佐藤: 現行ロジックの改修範囲を7/15までに見積もる ## 継続議題 - 通知先をSlackに一本化するかは未定。次回、鈴木がUI観点の意見を持ち寄る ## 在庫アラートのしきい値は在庫数でなく在庫回転率で決める 現行のしきい値(在庫数10個未満で通知)は季節商品で誤検知が多いと、佐藤が指摘した。鈴木は、店舗担当者からも同様の苦情が来ていると補足した(推定: どの店舗からかは未確認)。佐藤が在庫回転率を基準にする案を出し、出席者3人が合意した。 ``` ## 発言録を議事録の形に直す例 元の文: > 田中さんから在庫アラートについて説明があり、現行のしきい値だと誤検知が多いという話になった。佐藤さんはそれに対して在庫回転率を使う案を出し、鈴木さんも賛成した。最終的にどう決まったかは次回また相談することになった。 直した文: > 在庫アラートの件は結論が出ず、次回また相談することになった。田中さんから在庫アラートの説明があり、現行のしきい値では誤検知が多いという話になった。佐藤さんが在庫回転率を使う案を出し、鈴木さんも賛成した。 > > 継続議題 > - 在庫アラートの件(次回また相談) 元の文は経緯を時系列でなぞっていて、最後まで読まないと決まらなかったことが分からない。直した文は、結論(持ち越し)を先頭に置き、経緯をその後ろに回している。元の文にない決定・担当者・期日は足しておらず、誰が何を言ったかも元の文のとおりにしている。skills/natural-japanese/references/doctypes/report.md11 KB46f26143e655upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
skills/natural-japanese/references/doctypes/slide.md9.0 KB40e871aee083upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
skills/natural-japanese/references/manual-checklist.md7.7 KB2ec185188115upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
skills/natural-japanese/assets/style-profile-template.md2.3 KB05946a59c8f3upstream ↗
# style-profile.md > このファイルは、ユーザーが自分の文体を学ばせたいと求めたときに、`natural-japanese` スキルがユーザーの過去文章3〜5本をもとに生成する。標本が少ないため、断定は避けて「傾向として」程度の書きぶりに留める。以後の執筆・リライトはこのプロファイルを下敷きにする。 ## 参照した文章 - (タイトル・URL・執筆時期などを列挙) ## 視点 - 一人称は何を使っているか(私/僕/自分/一人称なし、など) - 語り手として、対象とどのくらいの距離を取っているか(当事者として書く/観察者として書く) - 断定と留保のバランス。どのくらい言い切るタイプか ## 文末の癖 - 「だ・である」調か「です・ます」調か、あるいは混在しているか - よく使う文末表現(体言止めの頻度、「〜と思う」「〜のだ」などの特徴的な語尾) - 文末に感情や態度がどの程度にじむか ## リズム - 一文の長さの傾向(短文中心か、長めの文を続けるタイプか) - 段落の長さの傾向とばらつき方 - 句読点の打ち方の癖(読点を多く打つ/少ない、など) ## 語彙 - よく使う具体的な言葉・比喩の傾向 - 避けている(または好んで使う)カタカナ語・専門用語の程度 - 固有名詞や数値をどの程度盛り込むか ## 避ける表現 > 本人が明示的に違和感を示したものだけを書く。一般的な良し悪しへ拡張しない。単語単位で禁じず、問題になった組み合わせと例外を記録する。 - 表現・組み合わせ: - 避ける文脈: - 言い換え候補: - 残してよい例外: - 根拠(本人コメント、修正履歴など): ## 構成 - 書き出しの型(結論から入るか、エピソードから入るか) - 論の運び方(結論先出し/積み上げ型、話の脱線の許容度) - 終わり方の型(まとめて締めるか、余韻を残して終えるか) ## 総評(自由記述) - 上記の観察から、この書き手らしさを一言でまとめると何か - natural-japanese スキルで下書きする際に、特に意識すべき点README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/coji-natural-japanese-skills-natural-japanese.md