はじめかた

chaff は、文章の読みにくいところを見つける道具です。文章は書き換えません。直すのは書いた人です。まずは手元の文章に一度かけてみます。

npx chaffjs article.md

何も入れずに試すなら、試すのページに文章を貼ります。chaff がブラウザの中で動きます（ブラウザでかける）。

文書の種類を選ぶ

契約書の一文はブログより長く、詩は同じ言葉を繰り返し、発言録は話したとおりに残します。どれもその種類の書き方です。文書の種類（ジャンル）を選ぶと、ルールと閾値をその種類に合わせて見ます。設定は要りません。

npx chaffjs --genre legal/contract 契約書.md    この実行だけ、契約書として見る
npx chaffjs init --genre legal/contract         この場所の chaff.yaml にジャンルを書く
npx chaffjs genres                              ジャンルの一覧と、それぞれ何向けか

文書	ジャンル
仕様書・RFC・設計文書	`technical/spec`
README・開発者向けの説明	`technical/readme`
技術記事（ジャンルを決めないときはこれ）	`blog/tech`
ブログのエッセイ	`blog/essay`
会社や団体が出す記事	`blog/owned-media`
提案書・企画書・計画書	`business/proposal`
報告書・白書・社内文書	`business/report`
仕事のメール・手紙	`business/email`
プレスリリース・お知らせ	`business/press-release`
議事録・議事要旨	`business/meeting-notes`
契約書・利用規約・プライバシーポリシー	`legal/contract`
法令・規則・社内規程・通達	`legal/statute`
判決文・決定	`legal/judgment`
特許の明細書と請求項	`legal/patent`
使い方の説明・手順書・ヘルプ	`docs/manual`
よくある質問	`docs/faq`
用語集	`docs/glossary`
論文と要旨	`academic/paper`
小説・物語	`literature/fiction`
文学としての随筆	`literature/essay`
詩・短歌・俳句	`literature/poetry`
戯曲・脚本	`literature/play`
読み上げるために書いた演説・挨拶	`speech/address`
話したことの記録（会見・国会の会議録）	`speech/transcript`

給与明細、請求書、各種の明細のためのジャンルはありません。business/report を使い、見積書なら business/proposal を使います（給与明細・請求書・各種の明細）。ジャンルごとに見ないルールと足すルールは、ジャンルのページにあります。

ジャンルを決めると、報告の最初にそのジャンルの指針が出ます。その種類のよい文書が満たすことを、下書きを確かめる問いの形で並べたものです。 --no-guide を付けると出ません。chaff.yaml の guide: で中身を変えられます（ジャンルの指針を変える）。

ジャンルを決めていない文書は、技術記事（blog/tech）として見ます。別の種類に見えるときは、1 行目の下にそう出ます。見るジャンルは変えません。

契約書.md   blog/tech · 日本語   ジャンルは既定から
   契約書・規約のようです。--genre legal/contract を試せます

自分の文章にかける

設定ファイルも API key も言語指定も要りません。ファイルを 1 つ渡せば、そのまま見ます。

npx chaffjs article.md           このファイルを見る
npx chaffjs .                    この場所の Markdown を全部見る
npx chaffjs docs/ README.md      ディレクトリもファイルも glob も混ぜてよい

node_modules dist build coverage は見ません。見る対象が 1 つも見つからなければ、失敗にします。何も調べていないのに通ったように見える状態を作らないためです。

画面の読み方

指摘が無いときは、次のように出ます。

$ npx chaffjs article.md

article.md   blog/tech · 日本語   ジャンルは既定から

────────────────────────────────────────────────────────────

  指摘はありません   すべて機械による判定です
              （同じ文章なら何度実行しても同じ結果になります）

  文章は書き換えていません。直すのは書いた人です。

  59 件の rule は動いていません:
      abstract-length（ジャンル blog/tech では見ないため）
      adverb-overuse（ja 向けの rule ではないため）
      adverb-without-negation（ジャンル blog/tech では見ないため）
      agentless-passive（ジャンル blog/tech では見ないため）
      agreement-slip（ja 向けの rule ではないため）
      all-caps-shouting（ja 向けの rule ではないため）
      article-sound（ja 向けの rule ではないため）
      attachment-not-attached（ジャンル blog/tech では見ないため）
      calendar-name-case（ja 向けの rule ではないため）
      citation-reference-mismatch（ジャンル blog/tech では見ないため）
      citation-style-mix（ジャンル blog/tech では見ないため）
      colloquial-opener（ジャンル blog/tech では見ないため）
      concrete-evidence-density（ジャンル blog/tech では見ないため）
      contraction-consistency（ja 向けの rule ではないため）
      cross-doc-broken-link（比べるほかの文書が無いため（ファイルを二つ以上かフォルダを渡すと動きます））
      cross-doc-duplicate-definition（比べるほかの文書が無いため（ファイルを二つ以上かフォルダを渡すと動きます））
      cross-doc-fact-conflict（比べるほかの文書が無いため（ファイルを二つ以上かフォルダを渡すと動きます））
      cross-doc-term-variant（比べるほかの文書が無いため（ファイルを二つ以上かフォルダを渡すと動きます））
      cushion-phrase-density（ジャンル blog/tech では見ないため）
      dangling-participle（ja 向けの rule ではないため）
      defined-name-repeated（ジャンル blog/tech では見ないため）
      defined-term-form（ジャンル blog/tech では見ないため）
      double-keigo（ジャンル blog/tech では見ないため）
      email-greeting-closing（ジャンル blog/tech では見ないため）
      email-subject-length（ジャンル blog/tech では見ないため）
      empty-conclusion（意味を読む検査のため（npx chaffjs test で動きます））
      expletive-construction（ja 向けの rule ではないため）
      figure-reference-order（ジャンル blog/tech では見ないため）
      homophone-slip（ja 向けの rule ではないため）
      hyphen-as-dash（ja 向けの rule ではないため）
      kana-function-word（決まった書き方（chaff.yaml の style）のための rule で、style か rules で動かすため）
      latin-abbreviation-form（ja 向けの rule ではないため）
      less-for-fewer（ja 向けの rule ではないため）
      missing-space-after-comma（ja 向けの rule ではないため）
      numeral-sentence-start（ja 向けの rule ではないため）
      obligation-without-deadline（ジャンル blog/tech では見ないため）
      oxford-comma-consistency（ja 向けの rule ではないため）
      party-order（ジャンル blog/tech では見ないため）
      party-role-name（ジャンル blog/tech では見ないため）
      preamble-length（ジャンル blog/tech では見ないため）
      quote-style-consistency（ja 向けの rule ではないため）
      quote-unnamed-speaker（ジャンル blog/tech では見ないため）
      request-without-deadline（ジャンル blog/tech では見ないため）
      requirement-smell（ジャンル blog/tech では見ないため）
      risk-disclosure（ジャンル blog/tech では見ないため）
      sentence-initial-so（ja 向けの rule ではないため）
      sentence-spacing-consistency（ja 向けの rule ではないため）
      space-before-punctuation（ja 向けの rule ではないため）
      spelling-consistency（ja 向けの rule ではないため）
      step-statement-mix（ja 向けの rule ではないため）
      title-case-consistency（ja 向けの rule ではないため）
      toki-as-condition（ジャンル blog/tech では見ないため）
      undefined-acronym（ジャンル blog/tech では見ないため）
      undefined-term（ジャンル blog/tech では見ないため）
      unknown-word（ja 向けの rule ではないため）
      unsourced-number（ジャンル blog/tech では見ないため）
      vague-deadline（ジャンル blog/tech では見ないため）
      which-that-consistency（ja 向けの rule ではないため）
      yori-as-from（ジャンル blog/tech では見ないため）

AI らしさ: 測っていません（短すぎます: 139 字。500 字から測ります）

指摘があるときは、1 件ずつ区切って出ます。次は、この手引きのために書いた短い記事にかけた例です。

$ npx chaffjs sample.md

sample.md   blog/tech · 日本語   ジャンルは既定から

─── 7 行目 ───────────────────────────────────────────────────

    データを作るのに要るもの（スキーマ・生成スクリプト・初期値・設定・環境変数・依存の一覧・Node の版）を一つのハッシュにまとめ、キャッシュの鍵にしました。

  ·  中黒で並べすぎている

     この文に中黒が 6 個あります（5 個まで）
     中黒の並列は 1 組なら読めますが、1 文に何組も入ると、どの項目がどの組に属するのか追えなくなります。実文書では 1 文 4 個までは普通に読めていました。行頭の「・」は箇条書きの印なので数えません。

     → 文を割るか、箇条書きにしてください。組の切れ目がはっきりします。

     このルールをゆるめる:  npx chaffjs relax no-nakaguro-parallel


─── 9 行目 ───────────────────────────────────────────────────

    鍵が変わらない限りデータを作り直さずにキャッシュから戻すようにしたので、ふつうの pull request でデータを作る段がほとんどの場合で数秒のうちに終わるようになり、テストを待つ時間がずいぶん短くなったとチームの皆が感じていて、週に何…

  ·  一文が長すぎる

     この文は 166 文字あります（160 文字まで）
     長い文は、読んでいるうちに主語を見失います。

     → 接続助詞のところで 2 文に割ってください。それだけで読めるようになります。

     このルールをゆるめる:  npx chaffjs relax max-sentence-length


────────────────────────────────────────────────────────────

  参考 2 件   すべて機械による判定です
              （同じ文章なら何度実行しても同じ結果になります）

  文章は書き換えていません。直すのは書いた人です。

  59 件の rule は動いていません:
      abstract-length（ジャンル blog/tech では見ないため）
      adverb-overuse（ja 向けの rule ではないため）
      adverb-without-negation（ジャンル blog/tech では見ないため）
      agentless-passive（ジャンル blog/tech では見ないため）
      agreement-slip（ja 向けの rule ではないため）
      all-caps-shouting（ja 向けの rule ではないため）
      article-sound（ja 向けの rule ではないため）
      attachment-not-attached（ジャンル blog/tech では見ないため）
      calendar-name-case（ja 向けの rule ではないため）
      citation-reference-mismatch（ジャンル blog/tech では見ないため）
      citation-style-mix（ジャンル blog/tech では見ないため）
      colloquial-opener（ジャンル blog/tech では見ないため）
      concrete-evidence-density（ジャンル blog/tech では見ないため）
      contraction-consistency（ja 向けの rule ではないため）
      cross-doc-broken-link（比べるほかの文書が無いため（ファイルを二つ以上かフォルダを渡すと動きます））
      cross-doc-duplicate-definition（比べるほかの文書が無いため（ファイルを二つ以上かフォルダを渡すと動きます））
      cross-doc-fact-conflict（比べるほかの文書が無いため（ファイルを二つ以上かフォルダを渡すと動きます））
      cross-doc-term-variant（比べるほかの文書が無いため（ファイルを二つ以上かフォルダを渡すと動きます））
      cushion-phrase-density（ジャンル blog/tech では見ないため）
      dangling-participle（ja 向けの rule ではないため）
      defined-name-repeated（ジャンル blog/tech では見ないため）
      defined-term-form（ジャンル blog/tech では見ないため）
      double-keigo（ジャンル blog/tech では見ないため）
      email-greeting-closing（ジャンル blog/tech では見ないため）
      email-subject-length（ジャンル blog/tech では見ないため）
      empty-conclusion（意味を読む検査のため（npx chaffjs test で動きます））
      expletive-construction（ja 向けの rule ではないため）
      figure-reference-order（ジャンル blog/tech では見ないため）
      homophone-slip（ja 向けの rule ではないため）
      hyphen-as-dash（ja 向けの rule ではないため）
      kana-function-word（決まった書き方（chaff.yaml の style）のための rule で、style か rules で動かすため）
      latin-abbreviation-form（ja 向けの rule ではないため）
      less-for-fewer（ja 向けの rule ではないため）
      missing-space-after-comma（ja 向けの rule ではないため）
      numeral-sentence-start（ja 向けの rule ではないため）
      obligation-without-deadline（ジャンル blog/tech では見ないため）
      oxford-comma-consistency（ja 向けの rule ではないため）
      party-order（ジャンル blog/tech では見ないため）
      party-role-name（ジャンル blog/tech では見ないため）
      preamble-length（ジャンル blog/tech では見ないため）
      quote-style-consistency（ja 向けの rule ではないため）
      quote-unnamed-speaker（ジャンル blog/tech では見ないため）
      request-without-deadline（ジャンル blog/tech では見ないため）
      requirement-smell（ジャンル blog/tech では見ないため）
      risk-disclosure（ジャンル blog/tech では見ないため）
      sentence-initial-so（ja 向けの rule ではないため）
      sentence-spacing-consistency（ja 向けの rule ではないため）
      space-before-punctuation（ja 向けの rule ではないため）
      spelling-consistency（ja 向けの rule ではないため）
      step-statement-mix（ja 向けの rule ではないため）
      title-case-consistency（ja 向けの rule ではないため）
      toki-as-condition（ジャンル blog/tech では見ないため）
      undefined-acronym（ジャンル blog/tech では見ないため）
      undefined-term（ジャンル blog/tech では見ないため）
      unknown-word（ja 向けの rule ではないため）
      unsourced-number（ジャンル blog/tech では見ないため）
      vague-deadline（ジャンル blog/tech では見ないため）
      which-that-consistency（ja 向けの rule ではないため）
      yori-as-from（ジャンル blog/tech では見ないため）

AI らしさ: 測っていません（短すぎます: 333 字。500 字から測ります）

上から順に、次のことが書かれています。

画面の部分	読み方
1 行目	ファイル名、ジャンル、言語と、そのジャンルに決めた根拠です
`─── 7 行目 ───`	ここから 1 件の指摘です。数字は指摘された行を表します
字下げした文	指摘された文そのものです
`·` と `⚠`	指摘の重さを表す記号です（`·` は参考、`⚠` は注意）。その横に、指摘の見出しが続きます
見出しの下の 2 行	何が起きているかと、それがなぜ読みにくいかです
`→` で始まる行	直しかたです
このルールをゆるめる	そのルールを自分たちに合わせるコマンドです
最後の件数	指摘の数と、どれも機械による判定であることを示します
動いていない rule	今回見なかったルールと、見なかった理由の一覧です

同じ文章なら、何度かけても同じ結果が出ます。動いていないルールも理由つきで並ぶので、何を見て何を見なかったのかが分かります。

指摘されたら、道は 3 つ

どれを選んでもかまいません。

道	どんなとき	やること
直す	指摘がもっともなとき	文章を書き直す
この箇所だけ黙らせる	指摘は正しいが、ここは意図的なとき	`<!-- stet: rule-id — 理由 -->` を書く
ルールを変える	自分たちの方針に合わないとき	`npx chaffjs relax rule-id --why "理由"` を打つ

大事なのは 3 つ目があることです。ルールを変える道が無いと、「うるさいから使わない」で終わってしまいます。

黙らせる範囲を選ぶ

stet は、指摘を黙らせる印です。Markdown のコメントとして書くので、読み手の画面には出ません。黙らせる範囲は 3 つから選びます。

書き方	黙らせる範囲
`<!-- stet: bold-density — 用語集なので意図的 -->`	すぐ下の段落（見出し・箇条書き・表なら、その 1 つ）
`<!-- stet-section: bold-density — 一覧なので -->`	次の見出しまで
`<!-- stet-file: ai-tell, rule-of-three — 引用が多い -->`	ファイル全体

— の後ろには理由を書きます。後から読んだ人が、なぜ黙らせたのかを追えるようにするためです。同じルールを何度も黙らせているなら、ルールを変える道を選ぶ時期です。

次に読むページ

社内規程や報告書に chaff が何をするのかは、実例とともに文書の種類ごとにできることにあります。
chaff が見つけられることは、例と実際の出力つきでリファレンスに一覧にしてあります。
ルールの強さやジャンルをチームに合わせるには、設定を読みます。
使えるコマンドとオプションの一覧は、コマンドにまとめてあります。