write-docs

write-docs

成果物を選び、そのファイルを読んでから書きます。一度に読み込むファイルは1つだけにしてください。規約はそれぞれ異なり、混ぜると誰の役にも立たない文書になります。

執筆するもの…	読むもの	対象読者
公開ライブラリ、CLI、エージェントツールの README	READMES.md	これを使うかどうかを30秒で判断しようとしている人
開発者ガイド、チュートリアル、運用手順書、移行ガイド、非推奨化の案内	GUIDES.md	推測せずにタスクを完了しようとしている人
CLI フラグ、サブコマンド、--help、エラーテキスト、出力仕様	CLI.md	プロンプトに入力する人と、それらをラップするスクリプト
コードコメント、docstring、インラインの理由説明	COMMENTS.md	障害対応中にこれを読むメンテナー
AGENTS.md / CLAUDE.md 運用ガイド	AGENTSMD.md	プロジェクトの情報を何も覚えていないエージェント
コミットメッセージ、PR の説明、変更履歴	PR.md	2年後に git log を実行するメンテナー

このスキルの対象外：ブログ記事やエッセイ（blog-review を使用）、設計ドキュメント、ADR（grill-me を使用）、社内サービスの Wiki、スキルの作成（write-skill を使用）。

ワークフロー

1. 事実を裏付ける実装、スキーマ、テスト、--help、または差分を読みます。
2. 読者と、この文書で可能にする必要がある行動を明確にします。
3. 繰り返し登場する概念ごとに、代表用語を1つ選びます。正確な API 名と識別子はそのまま維持します。
4. 選んだ成果物の観点に沿って草案を作成します。
5. すべての主張、コマンド、注意事項、制約が引き続き原典と一致しているか確認します。
6. 以下の明瞭さモードを適用してから、チェッカーを実行します。ヒューリスティックによる指摘は、自動修正するのではなく疑問として扱います。

明瞭さモード

• 厳格 — 手順、安全規則、エージェントのワークフロー、CLI のヘルプ、復旧手順に適用します。読者が追加の質問をできない文章にも適用します。たとえば、ツールや関数の説明、エラーメッセージ、別のエージェントやスクリプトが解析する出力などです。コマンドの前に条件を示します。命令形の手順を使い、各手順では1つの操作だけを扱います。直接的な動詞と単純な時制を使い、1文は20語以内にします。
• 自然 — README の説明、解説、コメント、PR の理由説明に適用します。用語と行為者を明確にしつつ、短縮形、セミコロン、文のリズム、行為者が不明または重要でない場合の受動態も使えます。

内容のブロックごとにモードを適用します。README のクイックスタートには厳格モードを、動機の説明には自然モードを使うこともできます。

共通ルール

• 読者の目標と最短の手順から始めます。来歴や経緯は後に回すか、省略します。
• 誠実に書きます。確信を装う宣伝資料ではなく、メンテナーが読者を手助けするように書きます。
• 品質を表す形容詞ではなく、根拠を示します。主張の裏付けとなる測定値、例、制約を示します。
• 1つのものには1つの名称を使います。別の概念を示すのでない限り、同義語を使い回しません。
• 文の最初の8語以内に、行為者と行動を示します。主語が抽象名詞（the configuration of、the handling of）だと行為者が隠れます。行為者を主語にして、行動を動詞で示します。
• 1文につき1つの考えを扱います。読者がすでに把握している内容から始め、新しい名称や値で締めくくります。これは能動態より優先されます。10語を超える条件は独立した手順にします。
• 4語以上の名詞の連なりを分解します。「connection resistance calibration procedure」ではなく、「calibration of the connection resistance」とします。
• 事実はそれぞれ1度だけ述べます。読者の次の行動を変えないテンプレートの節は省略します。
• 予告や安心させるためだけの語句（This document describes、simply、obviously）を削ります。読者は強調語句の反対を想定します。また、手順に失敗したとき、simply は読者のせいにする表現になります。
• 手順における曖昧な表現は、条件が欠けていることを示します。you may need to do Y ではなく、if X, do Y と書きます。解説では、曖昧な表現を1つ使えば不確実性を示せますが、1文に2つ使うと内容がぼやけます。
• 対応していないケースやトレードオフを明示します。簡潔な表現にするために、技術的な意味の正確さを損なってはいけません。

下書きを確認する

python3 scripts/prose_lint.py --mode strict <path>
python3 scripts/prose_lint.py --mode natural <path>

標準入力には - を、構造化された指摘には --json を使用します。終了コード 1 は厳格なエラーを意味し、レビューのみの指摘では 0 が返されます。1 行を無視するには `` を追加します。このチェッカーでは、プロジェクトのコンテキストがないと類義語の入れ替えを検出できないため、用語は手動で確認してください。これは STE 認証ではなく、事実確認の代わりにもなりません。理由と出典については、CLARITY-REFERENCE.md を参照してください。

既存のドキュメントを書き直す

• 構成を変更する前に、ドキュメントから引用された文字列をテストや CI で検索してください。テストが文言を固定している場合は、完全一致のテキストではなく、要件（順序やリンクの有無）を検証するように変更してください。PR では、変更したアサーションを明記してください。
• そこから派生したコピー（パッケージの README、ドキュメントサイト、翻訳など）を探してください。それらも更新するか、対象外であることを明記してください。

執筆ではなくレビューを行う

同じ視点を逆向きに適用します。成果物を原文と照合したうえで、対象読者にできないこと、信頼できないこと、または二度読まなければならないことを報告してください。称賛ではなく、欠陥とその箇所を最初に述べてください。