writing-standards

name	writing-standards
description	Markdown・README・技術文書・API文書・CHANGELOGなどのドキュメント、 各種プログラムやスクリプトのコメントの新規作成・修正・計画・レビュー時に最初に必ず呼び出す。 Claude Code設定系ファイル（`CLAUDE.md`・`.claude/rules/`・`.claude/skills/`・hooks関連）の 編集時は`agent-toolkit:claude-code-standards`を併用して呼び出す。

ドキュメント品質

プロダクションレベルのドキュメント品質を保つための共通ベース指示。 一般ドキュメント（Markdown・README・技術文書・API文書・CHANGELOGなどのドキュメント、 各種プログラムやスクリプトのコメント）を対象とする。

Claude Code設定ファイル（CLAUDE.md・.claude/rules/・.claude/skills/・hooks関連ファイルなど）も対象に含む。 ただし当該ファイル編集時はagent-toolkit:claude-code-standardsを併用し、Claude Code固有の追加原則を同スキルで補う。

対象範囲とプロジェクト規約優先

プロジェクト固有の規約（CLAUDE.md・.claude/配下など）が優先で、本スキルは不足分を補う。 文体・対象読者・敬体常体・推奨表現・行動指示の述部・表記ルールは配布ルールのstyles.mdをSSOTとする。 本スキルでは章構成・改訂運用・Markdown細則を扱う。

ドキュメント編集ワークフロー

編集前→編集中→ドラフト後検証の3段階で進める。

• 編集前: styles.mdの「対象読者と文体」節で対象読者と粒度を確認し、既存の章構成と整合を見積もる
• 編集中: styles.mdの指針（文体の核・推奨表現・行動指示の述部・表記ルールなど）を順守する。 比喩動詞・営業フレーズなどの対比例が必要なときのみreferences/tone-examples.mdを条件付きで参照する

ドラフト後検証

ドラフト後検証はメインエージェントが起動条件に応じて使い分ける。

• agent-toolkit:plan-implのレビュー有り使用時: plan-impl-reviewerがwriting-standards観点を担うため、 writing-reviewerを重複起動しない
• agent-toolkit:plan-implのレビュー無し使用時かつagent-toolkit:plan-mode経由で計画ファイル合意済みの場合の追加手順。 textlint設定があればwriting-reviewer起動前にtextlintを単発実行する。 例: uvx pyfltr run-for-agent --commands=textlint <対象パス> writing-reviewerは機械チェック項目を扱わないため、textlint違反がpre-commitで初めて露見する事象を防ぐ。 そのうえでメインエージェントからwriting-reviewerサブエージェントをAgentツールで起動する。 対象範囲（ファイル・差分）と計画ファイルパスをプロンプトで渡す。 詳細仕様はwriting-reviewerの本文（特に出力節）に従う
• plan-mode未経由の軽微編集（誤字修正・1〜数行の文言調整）では起動しない

構成・構造

• 対象読者を明確にする。1つのドキュメントが複数の読者層を対象にする場合はセクションを分ける
• 冒頭にドキュメントの目的・概要を置き、読者が「読むべきか」を即座に判断できるようにする
• 前提条件（必要な知識・ツール・環境）は本題の前に配置する
• 目次はページの長さと構造に応じて判断する。見出しが5つ以上ある場合や、スクロールが必要な長さでは目次を付ける
• 見出しの階層は3段（## / ### / ####）までを目安とする。それ以上は構造の見直しを検討する
• 関連する内容は近くにまとめ、読者が文書内を往復しなくて済むようにする
• コマンド例やコードスニペットはコピー&ペーストでそのまま動くことを前提に書く。 省略やプレースホルダーを使う場合は明示する
• 外部リソースへのリンクは、リンク切れのリスクを考慮し、要点を本文にも記載する

ディレクトリ構成

OSSプロジェクトの典型的なドキュメント配置パターンを示す。 プロジェクト方針がある場合はそちらに従う。

• ルート直下の定番ファイル: README.md、LICENSE
• docs/配下のレイアウト: ガイド・リファレンス・チュートリアルなど種別ごとにサブディレクトリを設ける
  • 例: docs/guide/（利用者向け手順）、docs/development/（開発者向け情報）、docs/api/（API仕様）
• ファイル粒度: 1ファイル1トピックを基本とする。1ファイルが300行を超えたら分割を検討する
• ファイル命名: ケバブケース（setup-guide.md）を基本とする。定番ファイル（README.md等）は大文字の慣例に従う
• サブディレクトリの入口index（docs/development/index.md等）: 静的サイトジェネレーター（mkdocs等）の nav機能で目次を自動生成できる場合は不要。手動メンテのリンク集index.mdは陳腐化しやすいため設けない

改訂・保守

• 追記する内容の粒度が既存の記述と整合しているか確認する。必要に応じて既存部分や章構成の変更も行い、全体の一貫性を保つ
• 陳腐化した記述は積極的に削除する。「古い情報が残っている」ことは「情報がない」より有害である
• SSOTを維持する。同じ情報を複数箇所に書かず、正規の場所からリンクする。やむを得ず重複する場合はどちらが正とするかを明記する
• ドキュメントの変更がコードの変更と連動する場合は、同じコミットまたはPRに含める
• 同一ファイル内に本文（仕様・規定の記述）と例（フォーマット例・コードブロック）が併存する場合、 本文の規定（見出しレベル・セクション構成・命名規則など）と例の整合を必ず確認する。 本文を変更したら例も合わせて更新し、片方だけが更新されて矛盾が残らないようにする

Markdown記述スタイル

行幅・句点位置・口語表現などの細則はmarkdownlint・textlintで自動検証される。 違反を発見したら以下の方針で対処する。

• **は強調したい箇所のみとし、箇条書きの見出しなどでの使用は禁止する

• markdownlintが通るように書く。特に注意するルール:

  • MD022: Headings should be surrounded by blank lines
  • MD031: Fenced code blocks should be surrounded by blank lines
  • MD040: Fenced code blocks should have a language specified

• 1行の表示幅は半角換算で127を上限とする（全角文字は2、半角文字は1として計算）。 超過した場合は改行や書き換えで対応する

  • 例外: フェンス付きコードブロック内は対象外（原文の正確性維持のため）
  • 表・frontmatterも上限の対象。表が長くなる場合は箇条書き・定義リストなどに切り替え、 frontmatterが長くなる場合はYAML複数行記法（>など）で収める
  • 1文ごと（。ごと）に改行する。箇条書きの各項目も1行で収まるようにする。 1項目内で127幅を超える場合は2行目以降をインデント継続して折り返してよい
  • 機械チェック手段: 本スキル配布のscripts/check_line_width.pyで対象Markdownを検査できる。 Python標準ライブラリのみで動作する。 違反行をstderrへpath:line 幅=width …抜粋…形式で列挙し、違反があれば終了コード1を返す。 --widthで閾値を変更できる。 用途は実装時の補助に限り、レビュー時には使用しない

• 口語的な日本語表現の混入は本スキル配布のscripts/check_colloquial.pyで検査できる。 辞書はagent-toolkit同梱の_colloquial_words.txtと_colloquial_words_allow.txt。 用途は実装時の補助に限り、レビュー時には使用しない

  • 使用例: 変更ファイル単位で次のコマンドを実行する。 違反はpath:line:col [match] …抜粋…形式でstderrへ出力される

    uv run --script ~/dotfiles/agent-toolkit/skills/writing-standards/scripts/check_colloquial.py path/to/file.md
    

  • 検出範囲: .md・.py・.txt・.yaml・.yml・.tomlを対象に、フェンス付きコードブロック内のコメントも検査対象に含む。 TOMLやシェルの#行などが該当する。これらコードブロック内コメントも修正対象として扱う

  • 本文・コメント中で禁止表現を直接例示しない。 インラインコード（`禁止語`形式）も検出対象に含むため、 denylistパターン説明として禁止表現を例示すると当該箇所が違反として循環検出される。 抽象的な説明（カジュアルな語尾・俗語の混入など）または別の代替例で記述する

• 辞書（_colloquial_words.txt・_colloquial_words_allow.txt）の更新は同じコミットで違反一掃まで完了させる。 辞書を共有する関連プロジェクト全体に対しcheck_colloquial.pyを再実行する。 辞書更新と既存違反一掃を別タスクへ分離すると、違反が残ったまま辞書だけ拡張されて検出基準と現状が乖離する

• textlintのja-technical-writing/sentence-length（既定120字上限）は句点までを1文として連結判定する。 箇条書きの継続行を改行で繋ぐだけで句点を打たないと120字超過が起きやすい。 意味の切れ目で句点を打って分割する（改行や行頭インデントだけでは判定はすり抜けない）

  • NG例（句点が末尾のみで超過判定される）:

    - 設定ファイルが存在する場合は内容を読み込んで設定値を解決し、
      存在しない場合はデフォルト値を採用して以降の処理を続行する
    

  • OK例（途中で句点を打って分割する）:

    - 設定ファイルが存在する場合は内容を読み込んで設定値を解決する。
      存在しない場合はデフォルト値を採用して以降の処理を続行する
    

• 箇条書き複数行記法（preset-jtf-style 1.1.3.箇条書き）では項目内の文末表記を統一する（句点ありとなしの混在禁止）。 shouldUsePoint: false設定下では、途中行末のみ句点を打ち、最終行末は句点を付けない

  • NG例（最終行末にも句点が付き混在判定される）:

    - 設定ファイルが存在する場合は内容を読み込んで設定値を解決する。
      存在しない場合はデフォルト値を採用して以降の処理を続行する。
    

  • OK例（最終行末は句点を付けない）:

    - 設定ファイルが存在する場合は内容を読み込んで設定値を解決する。
      存在しない場合はデフォルト値を採用して以降の処理を続行する
    

  • 補足: ファイル内に既存の箇条書きで最終行末に句点を付ける書き方が広く使われている場合、 shouldUsePoint: false設定下でもtextlintは項目間の文末表記の混在を警告することがある。 既存項目を一律修正できないなら、新規追加項目も既存表記に合わせる

• 同一bullet項目内に複数文を書くと、途中文末の句点と最終文末（句点なし）が 項目内の文末表記混在としてpreset-jtf-style 1.1.3.箇条書き違反に判定されるケースがある

  • NG例（1項目内で句点付き短文と句点なし最終文が混在する）:

    - 設定値はAPIから取得する。取得失敗時は既定値を使う
    

  • 回避策1（各文を独立した別bullet項目へ分割する）:

    - 設定値はAPIから取得する
    - 取得失敗時は既定値を使う
    

  • 回避策2（2文目以降をsubbulletとして階層化し、各項目の文末表記を独立に揃える）:

    - 設定値はAPIから取得する
      - 取得失敗時は既定値を使う
    

• textlintとprettierを併用するときは、prettierの再フォーマット後にtextlintを再実行して整合を確認する。 prettierがtextlintのsafe fixで挿入した差分を打ち消す場合があるため

• 図はMermaid記法で書く

• 別のMarkdownファイルへのリンクは用途によって書き分ける

  • Markdownソースのまま読まれる想定のファイル（README.md・CLAUDE.md・GitHub閲覧前提のdocsなど）では、次の形式で書く
    • 形式: [プロジェクトルートからのパス](記述個所からの相対パス)
    • 利点: 閲覧者がリンク先のパスを一目で把握できる
    • 例: docs/api.mdからdocs/guide/setup.mdへリンク → [docs/guide/setup.md](guide/setup.md)
  • ドキュメント生成ツール（mkdocs等）でHTMLに変換される想定のファイルでは、自然な表現でリンクテキストを書く
    • 対象はmkdocs・Sphinx・Docusaurusなどの変換系ツール
    • 変換後の利用者には内部パスが無意味なため
    • 例: [セットアップ手順](guide/setup.md)

• テーブルは列数が多い場合や内容が長い場合は箇条書きへの変換を検討する。 特定列のみ長文化する場合は、セル内をキー単語に留めて表下の補足文へ退避する書き方も選択肢になる

README規約

READMEはプロジェクトのトップレベルに配置するファイルで、初見の読者が最初に参照する。

• 標準構成パターン（プロジェクト方針がない場合の例。プロジェクトの規模と性質に応じて取捨選択する）:
  1. プロジェクト名と一文の概要
  2. 主な機能・特徴（箇条書き）
  3. インストール・セットアップ手順
  4. 基本的な使い方（コード例やコマンド例）
  5. ドキュメントへのリンク
• CLAUDE.mdとの役割分担: READMEは人間の読者向け、CLAUDE.mdはClaude Code向け
  • READMEにClaude固有の指示を書かない
  • 両者で重複する情報（ビルド手順など）はREADMEを正とし、CLAUDE.mdからはREADMEを参照するか要点のみ再掲する

技術文書の書き方

文書の種別ごとに求められる構成と注意点が異なる。

• 手順書（セットアップ・デプロイ・移行など）:
  • 番号付きリストで手順を示す。各ステップは1つの動作に限定する
  • 前提条件・事前準備を冒頭に明記する
  • 成功時の期待結果を各ステップまたは末尾に記載する
  • 失敗時の対処やロールバック手順も含める
• トラブルシューティング:
  • 症状 → 原因 → 対処の3要素で構成する
  • よくある問題から順に並べる
  • エラーメッセージは検索しやすいように正確に引用する
• API文書:
  • エンドポイント・パラメーター・レスポンスを網羅する
  • リクエスト/レスポンスの具体例を必ず付ける
  • エラーケースとそのレスポンスも記載する
• コミットメッセージ:
  • 読者はエンドユーザーである。内部リファクタリングなどの詳細は不要
  • プロジェクト方針があればそれに従う