--- name: writing-standards description: > Markdown・README・技術文書・API文書などのドキュメント、 各種プログラムやスクリプトのコメントの新規作成・修正・計画・レビュー時に最初に必ず呼び出す。 フィードバック・TBDの本文起草時も最初に必ず呼び出す。 # 編集時の注意点: # コード編集時はcoding-standards・本スキル両方を読み込むが、ドキュメントのみの編集時は本スキルのみ。 # コーディングエージェント向け文書固有のガイドはagent-standardsスキルへ分離した。 # 本スキルではClaude Code固有事項を扱わない。 # 対象読者と文体の基本方針は`agent-toolkit/rules/01-agent.md`「日本語」節に集約。 --- # ドキュメント品質 本スキルは、一般ドキュメント（Markdown・README・技術文書・API文書、コメント類）の品質基準を提供する。 コーディングエージェント向け文書も対象に含むが、その編集時は`agent-toolkit:agent-standards`を併用する。 ## 読み手別の追加注意点 - エンドユーザー向け: 内部実装は知らない前提とし、専門用語は初出時に補足する - 対話型UIは操作・状態・対処を端的に伝え、エラーは原因と対処を一組で示す - ドキュメントは「何ができるか」「どう使うか」を中心に書く - 行動指示は終止形で結ばず、常体は「〜を参照」、敬体は「〜を参照してください」の形で書く（説明文との混同を避けるため） - 説明文は主語・述語のそろった1文を基本とし、体言止め断片の連なりで構成しない （例外: 用語定義の見出しは体言止めで統一してよい） - 開発者向け: 前提知識を共有する開発者を想定し初歩説明は省くが、コード識別子レベルの詳細は扱わない - 「なぜそう設計したか」「どこに注意が必要か」を中心に書く - 行動指示・体言止めの扱いはエンドユーザー向けに準じる - コーディングエージェント向け文書: 前置き・自己紹介・書き手目線の解説は不要とし、判断に必要な情報のみ直接記述する - 行動要求は主体・対象・拘束力を読み取れる形（命令形・依頼形・体言止め・規定文など）で示し、 拘束力を読み取れない動作説明文で要求を代用しない - 箇条書きの体言止め列挙は許容する ## ユーザー入力素材の取扱い ユーザーが事情・経緯・背景を説明しながら作業を指示する場合、提示文面の全体を成果物へ無加工で転記してはならない。 成果物ごとの対象読者と要求粒度に応じて、要件として咀嚼すべき情報と参考に留めるべき情報を区別する。 入力素材を成果物へ取り込む時点では、次を守る。 - 計画ファイルでは、フィードバック本文とTBD本文を複製せず、正本のファイル名だけを記載する。 本セッションで実際に受領したユーザー発言は、計画ファイル（メイン）の変更履歴へ原文のまま`text`コードブロックで記録する。 委譲文、質問を作成したエージェントの文面及びフィードバック本文をユーザー発言へ変換しない。 - キューにない素材の逐語本文・回答全文は計画外の明示入力として調査、起草、初回レビュー、再レビューへ保持し、計画本文へ転記しない - ただし、本セッションで直接受領したユーザー指示・合意は、計画ファイル（メイン）の変更履歴へ逐語記録する。 - 既存計画の素材IDと`text`フェンスによる旧形式は読み取り互換として扱うが、新規生成の根拠にはしない - 上記以外の成果物には対象読者が必要とする情報粒度へ要約・抽出してから取り込む - 対象例: 実装コード・コメント・ドキュメント本文・コミットメッセージ・サブエージェントへの指示・PR説明 - ユーザー提示のセッション固有事情・自セッション観測事象・個人名指しは恒久的な規範・公開成果物に書き残さない - 取捨に迷う場合は対象読者の判断に必要かを基準とし、必要でない情報は省く 生成後の成果物にも、制作過程の痕跡を残さない。 以下は新規作成・変更する成果物へ適用し、既存文書の未変更箇所への遡及修正は求めない。 - 実装上の制約・除外したツール・回避した代替案・要求の経緯は、成果物の構成・語彙・手順の選択へ反映し、 成果物本文へ制約への言及・免責文の形で書かない（対象読者がその制約自体を知る必要がある場合を除く） - 修正指示への対応表明・前版との差分説明・変更理由の弁明を成果物本文へ残さない。 変更経緯はcommitメッセージ・計画ファイル・レビュー応答など、経緯の記録場所だけへ書く - 意図伝達のために提示された例は抽象度・対象読者・粒度の推定に使い、 成果物自体が当該例を必要とする場合を除き成果物へ転記しない - 完成時に、会話の経緯を知らない読者として成果物を通読し、経緯の説明文・作成者向けの注記・ 複数回の修正で生じた文体・用語・前提の不整合を除去する - 計画ファイル・フィードバック・TBDを除くプロジェクト成果物では、コーディングエージェントとユーザーの対話に由来する経緯を、経緯を知らない読者への説明として残さない。必要な事実は、要件・挙動・根拠へ変換して記述する ## 構成・構造 - 対象読者を明確にし、冒頭に目的・概要を置く - 前提条件（必要な知識・ツール・環境）は本題の前に配置する - 見出しの階層は3段（`##` / `###` / `####`）までを目安とする - 関連する内容は近くにまとめ、読者が文書内を往復しなくて済むようにする - コマンド例やコードスニペットはコピー&ペーストでそのまま動くことを前提に書く - 外部リソースへのリンクは、リンク切れリスクを考慮して要点を本文にも記載する - トップダウン（段階的詳細化）で構成し、追記時も末尾追加でなく既存記述との粒度・配置の整合性を確認する - 前方参照は段落末・節末へ配置し、章冒頭・節導入では過剰な詳細を書かず、詳細は後続節で展開する - 計画ファイルの起草で新しい概念名・識別子を導入する場面、命名場面、または同名・同種の対象を 複数の主体間で記述する場面では、本文着手前に中心概念の指示対象と役割を確定する。 作業ラベル（目的・対象・判断を省いた抽象名詞句）や無定義の新語を使わず、 詳細な書式は`references/referent-table.md`を`Read`で読み込む ## 日本語の書き方 書き方の上位原則は`agent-toolkit/rules/01-agent.md`「日本語」節に従う。 - 規定の常体語尾は義務・禁止・許可・推奨の別を読み取れる規範述語で結び、 事実の記述は文意に応じた自然な形を選ぶ。自然な「〜する」形を「〜とする」へ機械的に変換しない - 比喩動詞・カタカナ造語の動詞化比喩・カタカナ用語の口語的省略形を避け、 観測できる事実を表す標準的な日本語動詞・正式表記を使う （「例外を送出する」「プロセスを終了する」「設定を読み込む」など。一般的に確立した技術用語・略称は例外） - 消費主体が読む成果物では、同じ対象を1つの呼称で通し、同一文書内で複数の名で呼ばない - 文書の種類や工程を問わず、ユーザーの用語、対象リポジトリの識別子及び公開仕様で確立した用語を優先する。 該当する語が無ければ対象と内容を具体的に記述し、一度しか使わない分類名又は複数の意味をまとめた新語を導入しない。 同じ文章内で繰り返し参照する場合だけ新しい用語を導入し、初出で対象と意味を定義する。 確定手順と用語対応表の適用条件は`references/referent-table.md`に従う - 結論・要点・規定の中身を文の前方に置く。種別や分類のラベルを機械的に前置きしない - 動作主・対象は、文脈から一意に読み取れる場合に限り省略できる。一意に読み取れない場合は主語・助詞を補い、 決定・指示・是正・承認など人の行為は行為者を明示するか規範・事実の内容を直接書く （努力目標。新規記述・変更箇所に適用し、既存文書の未変更箇所への遡及修正は求めない） - ユーザー向けの発話・文章は簡潔に書く。簡潔化によって対象の特定に必要な情報を省略せず、読み手が文脈上の対象を一意に判別できる状態を保つ。 対象を一意に判別できない抽象語への置換は、簡潔化として扱わない。 - 同一節内で並列する同種の規定の間では述部形式を揃える （規定と説明・手順の間の形式差は混在に含めない） - 見出しは名詞句で書く（命題型・問い掛け型・断定型を避ける） - 列挙が事象全体を網羅しない可能性がある場合は「〇〇や××などの、△△（上位概念）」形式を用いる。 全事象を100%網羅できると確認できる場合のみ閉じた列挙を許容し、迷う場合は開いた列挙を選ぶ - 説明的文書（README・ガイド・解説文など）は進行だけを伝える文（例:「ここでは〜について述べる」）を避け、事実・データ・挙動・手順を更新する文で書く - 列挙した性質・分類は具体的な内容（データ・事例・該当箇所）へ対応づける - 節・文章全体の結びは抽象論のまま終えず、既出の具体的な内容（事例・数値・手順）へ対応づける - 読者の理解に必要な文脈（対象範囲・観点・比較対象・未確定事項）は、文を短くする目的だけで削除しない。保持する文脈は1文へ集約せず、独立した文または後続の節へ分けて置く - 主観の演出（読者の疑問を未解決のまま維持する、断定と留保を交互に配置する等の手法）は採用しない。 主観的評価を排し観測可能な事実に基づく表現を選ぶ - 「説明的文書」項目配下の各規定は、従うと不自然・不明瞭な文になる場合は自然さと明瞭さを優先し破ってよい ## 論証品質 ### 論証の厳密さ - 推量・可能性・読者の疑念を示す述部を根拠なく断定へ変えない。本文内の根拠で確定している場合に限り断定へ整える - 複数要因が関係する事象を単一原因に還元せず、要因別に切り分けて記述する - 異なる対象（別々の決定・別々の原因・種類の違う問題）を同一の語でまとめない - 似た語（例: 境界条件／境界事例、実装／実施、規範／規定）を意味を変えて同一文書内で使い分けている場合は書き換えまたは語彙統一をする（努力目標。新規記述・変更箇所に適用し、既存文書の未変更箇所への遡及修正は求めない） - 因果の機構、対句否定（「AではなくB」型）で否定する命題と根拠、環境に依存しない文書 （チェックリスト・観点集・ガイドなど）の性能・挙動の断定の成立条件は、 当該の主張を本文が推奨・手順・結論の根拠として用いる場合に限り添える。 同一文書内に既にある記載は繰り返さず参照する。添える場合は1文へ集約せず独立した文で書く - 主張は挙げた例が支える範囲に揃える。例が一部しか支えないときは主張の範囲を例に合わせて狭める - 論を一方向に進め、結論→反論→言い直しで主張を揺り戻さない。譲歩や逆接で段落を閉じて結論を宙吊りにしない 文書を書き終えて表記を検査する時点で`references/notation-rules.md`を全文読む。 ## 改訂・保守 READMEとコーディングエージェント向け文書が重複する場合はREADMEを正とし、 コーディングエージェント向け文書からは参照するか要点のみ再掲する。 - 追記の粒度・形式・構造（リスト記法・改行規則・記号運用）が既存記述と整合するよう確認し、不整合部分・章構成も改訂範囲に含める - 異なる節・ファイル間で相互参照するフォーマット要素（テーブル列名・節名・キー名）を執筆完了前に相互照合する - 陳腐化した記述は削除する（残置は情報不在より有害）。SSOTを維持し、重複が避けられない場合はどちらが正かを明記する - 本文と連動する従属箇所（コードブロック・目次・入口列挙・件数表記・要約・出力例等）は本文変更時に同時更新する - 同一文書内の列挙・表から数えて導出できる件数（母集団数・該当数・内訳数など）を地の文・要約・表のcellへ明記しない （列挙・表を正本とし、複製された件数が編集で実態とずれる事態を防ぐ。機械チェックは新設しない） - 列挙へ対応しない件数を書く場合は、`agent-toolkit/rules/01-agent.md`「調査と検証」の規定に従い集計コマンドとその出力を典拠として併記する - 推奨例・違反例リストの語の追加・削除、新設ラベル・キーワードは対象ファイル内を`grep -n`で照合し自己整合と既存表記を確認する - 単体では自然な語で頻度・多用時だけ問題になる表現は、禁止語彙リスト・機械検査辞書へ単純追加しない。 頻度条件を規定本文へ明記するか、採用を見送る（頻出語の機械検出は誤検出が多発するため） - 「原則として」「可能な限り」等の例外を許容する修飾語は削除するか、または例外条件を明示形に書き換える - 節・段落・規範文の移設・分離・参照化では判断基準（数値条件・発動条件・限定条件）を再評価し現行状態と整合する形へ更新する。 パス移行時は旧パス残存物の扱い（移行スクリプト実行・削除・並行検査のいずれか）を計画段階で本文へ明記する - 外部素材（記事・gist・他リポジトリ文書等）を再構成してスキル・規範文書へ取り込む場合、素材内の数値閾値・ 適用単位・規定本文と点検手順の項目対応の内部整合を転記前に検証し、不整合は取り込み方針を確定してから転記する 口調の自己点検では、執筆者とレビュアーが次の参照資料を全文読み、該当する表現を成果物へ持ち込んでいないか確認する。 - 口調の自己点検時は`agent-toolkit/skills/writing-standards/references/tone-examples.md`を全文読む - 口調の自己点検時は`agent-toolkit/skills/writing-standards/references/tone-examples-llm-tone.md`を全文読む 表記、lint及び口調を検査する時は、対象に応じて次の資料を全文読む。 - 表記検査時は`agent-toolkit/skills/writing-standards/references/notation-rules.md`を全文読む - lint違反の対処時は`agent-toolkit/skills/writing-standards/references/textlint-violations.md`を全文読む - lint設定を緩和する時は`agent-toolkit/skills/writing-standards/references/lint-relax-criteria.md`を全文読む ## コメントの記述粒度 コード・スクリプトへコメントを書く前に`references/comment-granularity.md`を`Read`で読み込む。