Claude Code に仕様書や PR の本文、レビューコメント*1を書かせているが、そのままだと読みにくいことがあった。そこで、日本語の文書を書く前に読み手を整理させる writing-japanese というスキルを作ったので、作った経緯と気をつけたことを書く。
困っていたこと
Claude Code が書く日本語の文書には、次の 2 つの症状があった。
- 読む順序への配慮がない
- 用語を定義より先に使っていて、読み進めた先でやっと定義が出てくる
- 各章が「ほかの章も読んだ」前提で書かれている
- 読み手に要らない情報を書く
- 例えば、画面ごとの表示と操作を書いた仕様書(画面仕様書)に、バーコードの読み取りの仕組みの詳細まで書いてくる。同じバーコードを続けて読んだときに無視する時間とか
- 画面仕様書は QA エンジニアがテスト設計に使うものだが、バーコードの読み取りはアプリ全体で共通の部品なので、この画面のテスト設計には要らない。実際、QA エンジニアからはテスト不要ですよね？と確認があった
原因は、書き手が自分の知っていることを忘れられないことだと思っている。Claude Code はコードと会話の文脈を持ったまま文書を書くので、未定義の用語や共通の部品の詳細があっても、書き手からは不自然に見えない。人間でもよくある話だが、コードを読み込んだ直後に書くエージェントだと特に起きやすいと思う。
作ったもの
ステップは次の 3 つだけ。
- 読み手整理メモを書く
- メモを見ながら、執筆規則に従って書く
- 書き終えたら、メモの「読み手が知らないこと」が説明なしで本文に入っていないか、「書かないこと」が本文に入っていないかを確認する
読み手整理メモは、本文を書く前に作る 6 項目のメモで、文書本体には含めない。
- 読み手: 誰が読むか
- 読む目的: 読み手が、この文書を読んで何をするか
- 読み手が知っていること: 説明なしで使ってよい知識
- 読み手が知らないこと: 使うなら説明が要る知識
- 伝えたいこと: 読み終えた読み手に残したいこと。1〜3 文で書く
- 書かないこと: 読み手の目的に要らない内容
さっきの画面の仕様書だと、メモはこんな感じになる。
## 読み手 QA エンジニア ## 読む目的 テスト設計で、表示条件・状態分岐・操作・例外の抜け漏れを防ぐ ## 読み手が知っていること 店舗業務、アプリの画面と操作 ## 読み手が知らないこと コードの構造、バーコード読み取りなどの基盤、内部の区分値 ## 伝えたいこと この画面がどの条件で何を表示し、どの操作で何が起きるか ## 書かないこと 共通の部品（バーコードの読み取り、処理中の表示など）の動作の詳細。画面上で観察できるものも含む
書き手に読み手の立場を言葉にさせるのが狙い。「書かないこと」に「共通の部品（バーコードの読み取り、処理中の表示など）の動作の詳細」と書いておけば、本文に基盤の詳細を書いてしまっても、最後の確認で気づける。
執筆規則は 4 つだけにした。
- 読み手が知らない用語は、初出で定義する。後の章で定義する用語を、先の章で使わない
- 各章は、その章だけを読んでも分かるように書く。ほかの章の内容が必要なら、どの章を見ればよいかを書く
- 「書かないこと」に当たる内容は、本文に入れない。必要なら、根拠のリンクや参照先に回す
- 1 つの文には 1 つの主張を書き、文と文の関係を接続の言葉で示す。「なぜなら」「ただし」「その結果」などで、前の文とどうつながるかを示す
1 と 2 は「読む順序への配慮がない」、3 は「要らない情報を書く」への対策になっている。4 は、関係が分からないまま事柄が並ぶのを防ぐためのもの。
気をつけたこと
- 規則は、実際に見た症状に効くものだけにした
- 文章の規則は増やそうと思えばいくらでも増やせるが、多いと個々の規則が守られにくくなると思う
- 推測は推測と書く、みたいな規則は既に CLAUDE.local.md に書いてあるので、スキルには移していない。ターミナルでの応答にも効いてほしい規則なので、文書を書くときだけ読み込まれるスキルに置くと効く範囲が狭まってしまう
- 文の長さの基準は置かなかった
- 「1 文は 80 文字以内」みたいな数値の基準があると、基準を満たすために文を機械的に切ったり言葉を削ったりして、文と文のつながりが消えてかえって読みにくくなる
- 代わりに規則 4 で、文の長さではなく文と文の関係を示すことを求めている
- 「不要な接続詞は省くべし」というのが一般的なルールっぽいが、斜め読みするときは接続詞を元に重要なポイントを探すので、接続詞がないと自分は読みにくいと感じる
- 文書の種類ごとの基準は、呼び出し元のスキルに任せた
- 今回作成したスキル は仕様書、ADR、PR 本文、レビューコメントのどれにも使う汎用のスキルなので、文書の種類に特有の基準は書かない
- 例えば画面の仕様書の「共通の部品の動作は、画面上で観察できても書かない」という基準は、画面の仕様書を書くスキルが持って、
writing-japaneseに渡す
- 読み手整理をする時に、作業の経緯は読み手の判断を変えるものだけを書くことにした
- エージェントは「最初に A を試したが失敗したので B にした」みたいな経緯をよく書く。なので最初は経緯を一律に書かないことにするつもりだった
- ただ、PR テンプレートには「判断と理由」の欄があって、却下した案とその理由を書いてもらっている。経緯を一律に禁じると、ここと食い違ってしまう
- そこで、却下した案とその理由、誰と合意したかは書く。これで読み手が同じ検討を繰り返さずに済む
- 一方、試した回数や順序、かかった時間、作業中の失敗とその直し方は書かない。これらは読み手の判断を変えない。
効果を確かめた
効果は、Anthropic の skill-creator というスキルの評価の仕組みで確かめた。同じ指示をスキルありとスキルなしで実行して、別のエージェント（判定役）が判定項目ごとに合否を付けてくれる。
事例は、画面の仕様書、ADR、PR 本文、レビューコメント 2 件の計 5 つ。レビューコメントの 2 件は、リポジトリで実際にあったやり取りを材料にした。判定も LLM がやるので結果がぶれると思い、各事例を 3 回ずつ実行した。
| 判定項目 | スキルあり | スキルなし |
|---|---|---|
| 全体の合格率 | 98.1% | 89.3% |
| 仕様書: 各章を単独で読める | 3/3 | 0/3 |
| PR 本文: 試した回数や作業中の失敗を書かない | 3/3 | 1/3 |
| レビューコメント: 理由と結果の関係を接続の言葉で示す | 3/3 | 0/3 |
| ADR: 各章を単独で読める | 1/3 | 1/3 |
ADR の「各章を単独で読める」はスキルありでも 3 回中 1 回しか合格しなかったが、ADR は章を単独で読むことが少ないので対応していない。
やめたこと
- textlint を使うこと
- Claude Codeがtextlintを通すことを目的に書き換えてしまい、逆に読みにくいと感じることが多々あったので採用をやめた
- 使い方が悪い説はある。厳しすぎたとか
- 文体を気にすること
- 自分は仕事で読む文書においては、目的さえ達成出来ればAIっぽくても良いと思っているのでなんでもよい
エージェントの文書が読みにくいのは、書き手となるClaude Codeが自分の文脈を忘れられないからだと思っていて、規則を増やすより書く前に読み手を言語化したほうが効くと考えて作った。とはいえ、結局は人間の編集は必要で、完全に任せるというのは出来ないなという印象。この文書においても writing-japanese を利用して書き、人間が編集した。
*1: /code-review を利用している
