lowly-writing-framework

開発成果物のための執筆フレームワーク

PR の説明文、イシュー本文、ディスカッション、レビューコメント、ドキュメント、コードコメント、要件の構成と仕組みです。PR の説明文はレビュアーへの配慮であり、ドキュメントやコメントは次に読む人への配慮です。このスキルでは、成果物に何を含める必要があるか、どのように構成するかを決めます。どのような文体にするかではありません。

対象範囲

このスキルが扱うのは構造と仕組みだけです。成果物に何を含めるか、各セクションをどこに配置するか、参照が自動リンクされるか、どの grep で見落としを検出できるか、といった内容です。対象となるすべてのトピックを、以下のルーティング表に示します。

語り口、トーン、ユーモア、句読点の好み、言い回しの好みは対象外です。別途インストールしたボイスパックのスキルで、これらを追加できます。両方がインストールされている場合、同じ成果物に両方が適用されます。このスキルは内容の配置を、ボイスパックは文章の読み味を担当します。

以下の書式、絶対に削らない項目、境界、アンチパターンは、すべてに適用されます。PR、レビューコメント、ドキュメント／コメントに固有の内容については、成果物を書き始める際に該当するリファレンスファイルを開いてください。

• PR のタイトルまたは本文を作成する → references/pr-writing.md（タイトル、Issue のクローズルール、テストに関する誠実さ、デフォルトで注釈付き行コメントとして投稿する差分への作成者注釈、AI の透かし）
• Issue の本文を作成する → references/issue-writing.md（タイトル、テンプレートの選択、関連作業への参照、本文に解決策案を含めないこと）
• Discussion の投稿、コメント、返信を作成する、または回答としてマークする → references/discussions.md（投稿の種類、リポジトリで実際に使われているカテゴリからの選択、スレッド化と回答マークの仕組み、文章で結果をまとめること、「+1」コメントではなく賛成票を使うこと）
• PR、Issue、Discussion の投稿で共通する本文の構成（テンプレートへの記入、Context セクション、PR にすでに含まれているドキュメントへのリンク、長さの上限、図）→ references/body-writing.md。上記のうち該当するものと併せて読んでください
• PR／Issue の本文またはドキュメントに mermaid 図を追加する → references/diagrams.md（GitHub でのレンダリングの仕組み、既知の GitHub の制約、テーマ／スタイル、色分けした図の凡例）
• 他の人の PR をレビューする → references/review-comments.md（レビューの順序と優先度、提示方法：段階的なレビュー、注釈付き行コメント、PR レベルのコメント、標準的なコメントラベル、修正案）
• 自分の PR に対するレビューフィードバックに返信する、スレッドを解決する、またはレビューを再依頼する → references/review-replies.md（返信の形式、レビュアーのラベルに合わせること、投稿前にユーザーがレビューすること、返信前に主張を調査すること、根拠を示して異議を唱えること、解決するかレビュアーに確認するかの判断、レビューラウンド後の更新）
• README、ドキュメント、コードコメントを編集する → references/docs-and-comments.md（現在形のルール）
• 設計ドキュメント、RFC、振り返りを書く → セクション構成については references/body-writing.md、時制については references/docs-and-comments.md を参照してください。長文の文章における文単位の構成はボイスパックの対象であり、ここでは扱いません
• PR の本文、ドキュメント、コメントの完成後にセルフチェックを行う → references/self-check.md
• 専用の要件ドキュメント、またはコメント／PR／コミット内で、要件や受け入れ基準を定義、明確化、実装する → references/requirements-ears.md（EARS 構文、ドキュメントモードとインラインモード）
• 草案に禁止された AI 時代の表現がないか確認する → references/banned-phrases.md
• 人間名義だが、実際の行為者は別の AI である成果物を作成する。明示的に指示された場合（「肉体プロキシモード」）→ references/meat-proxy-mode.md
• gh CLI から直接投稿または編集する → references/gh-cli.md（編集前の取得、シェルのエスケープ、-f／-F、再取得による確認、行を指定した修正案、レビューコメントの返信と解決、gh discussion と GraphQL のみで可能な Discussion の変更）
• PR、Issue、Discussion の本文を作成する → references/calibration-examples.md の Bodies セクションも読み、PR の場合は PR Testing section と PR author annotations セクションも読んでください（判断が必要なルールの変更前／変更後の例です。レビューコメント、コードコメント、ドキュメントではこのファイルを読む必要はありません）。肉体プロキシモードでは、Meat proxy mode セクションも読んでください

書式

• バッククォートを使うのは、読者が入力、貼り付け、検索する文字列、またはツールがそのまま解析する文字列に限ります。コマンド、フラグ、設定キーと値、環境変数、コード識別子、正確なエラーテキスト、読者が開く必要のあるファイルパスなどです。それぞれについて、読者がターミナル、エディター、検索ボックスにコピーするかどうかを確認してください。そうでなければ、通常のテキストにします。例外は課題／プルリクエストの参照です（owner/repo#123）。これをバッククォートで囲むと GitHub の自動リンクが無効になります。詳しくは、以下の「課題の参照」ルールを参照してください
• URL（http://、https://、www.で始まるもの）は、localhost やプレースホルダーの URL も含め、絶対にバッククォートで囲まないでください。インラインコードは自動リンクされず、リンクのないテキストとして表示されます。上記のコピペ確認は URL には適用されません。リンク先をそのまま記載するか、名前付きの Markdown リンクにするか、通常のテキストとして記載してください。フェンス付きコードブロック内や、読者が貼り付けるコマンドライン内の URL は、そのまま記載します
• 名前はコードではありません。リポジトリ、組織、GitHub Apps、チーム、サービス、クラウドのロールやアカウント、製品、ワークフロー名やジョブ名などの固有名詞は、ハイフンを含む場合や小文字の場合も、通常のテキストにします。変更内容について説明するためだけに言及するファイル名も同様です。読者が開いたり編集したりする必要があるパスはバッククォートで囲みます
• 用語は初出時、または正確さが重要な箇所（コマンド内のパス、完全一致が必要な値など）でバッククォートで囲み、繰り返しのたびには囲みません。段落内でおよそ3回、本文で8回を超えたら、各箇所についてもう一度確認してください
• バッククォートを重ねすぎないでください。カンマ区切りの識別子が4つ以上並ぶと、書式設定がない場合と同じくらい読みづらくなります。項目ごとにネストしたサブ箇条書きを使うか、リソースの種類を一度だけ本文で示し、レビュー担当者が推測に頼らざるを得ない語句だけをバッククォートで囲んでください
• 複数行の項目が続く平坦なリストより、ネストした箇条書きを優先してください（階層は2段まで）
• 信頼できる情報源には、名前付きの Markdown リンクをインラインで付け、URL をそのまま記載しないでください（例外は、GitHub がリッチな owner/repo#123 参照として表示する課題／プルリクエストの URL と、行アンカー付きのコードへのパーマリンクです。後者はそのまま貼り付けた場合に限り、コードプレビューとして展開されます）。変更に貢献した人は名前を記載してください。ユーザーが GitHub のユーザー名なしで名前を挙げた場合は、references/gh-cli.md の「人物名の確認」に従って特定してください
• 課題の参照：同じリポジトリ内の場合も含め、言及するたびに必ず完全な owner/repo#123 形式を使ってください。これにより、同じリポジトリ内の参照に何を適用するかを都度判断せずに済みます。#123だけの記載や、オーナー名なしのreponame#123は使わないでください。owner/repoの部分だけを含め、どこにもバッククォートを使わないでください。GitHub が自動リンクするのは、バッククォートで分断されていない連続したプレーンテキストだけです。このページのバッククォートは構文を示すためのものです。プルリクエスト自体の URL を元に URL を手作業で組み立てないでください。.../pull/456#issue-<id>は課題へのリンクではありません。正しい URL はgh issue view 123 --json urlで取得してください
• リンク先が主張の根拠となる場合は、関連する一文をリンクの横に引用してください。404 やバージョン更新後も残る、永続的な根拠となります
• 話題ごとに段落を分け、段落ごとに要点を一つにしてください。複数の要点を論じる段落や、4～5文を超える段落は分割してください
• 1文につき要点は一つにしてください。括弧書きや読点で節をつなぎ、仕組み、トレードオフ、結論を盛り込んだ文（「～という代償を伴い」「特に～なので」など）は、文末が一つでも複数の要点を含んでいます。それぞれの節を別の文にするか、列挙できる内容なら別々の箇条書きにしてください。長文向けのスタイルガイドではこのルールを緩和する場合がありますが（設計文書、RFC など）、プルリクエスト／課題本文、レビューコメント、コードコメントには適用されます
• リンク先がコードの場合は、ファイルだけではなく、正確な行範囲へのパーマリンクを使ってください（ブランチではなくコミット SHA を使い、#L10-L20を付けます）。行アンカー付きのパーマリンクは GitHub 上でコードプレビューとして表示されますが、ファイルだけへのリンクでは表示されません
  • 形式：github.com の blob URL を使い、/blob/FULL-SHA/PATH#L10-L20で終わる URL を単独の行にそのまま記載すると、プレビューが展開されます（Markdown ファイルへのリンクや名前付きリンクは通常のリンクとして表示されます）。ブランチ名や短縮 SHA は変更される可能性があるため使わないでください。SHA を特定できない場合は、ブランチにリンクせず、その旨を伝えてください
  • SHA：gh api repos/<owner>/<repo>/commits/<ref> --jq .sha（現在のリポジトリではgit rev-parse HEAD）。失敗が表示されるよう、2>nullではなく2>&1を使ってください
  • 行番号：記憶や手作業で数えず、その SHA のファイルから取得してください。gh api -H "Accept: application/vnd.github.raw" "repos/<owner>/<repo>/contents/<path>?ref=<sha>"をgrep -n '<pattern>'にパイプします（PowerShell ではSelect-Stringと.LineNumberを使います）。パイプを使い、作業ツリーに一時ファイルを作らないでください。また、URL に-f ref=ではなく?ref=を使ってください。-f ref=を使うと POST になります
• GitHub が Markdown として表示する場所（プルリクエスト本文、プルリクエストのレビューコメント、README／Wiki ドキュメント）では、読者が読み飛ばすべきでない重要な注意を示す場合、単独のNote:／Warning:という接頭辞ではなく、GitHub の注意書き構文> [!NOTE]、> [!TIP]、> [!IMPORTANT]、> [!WARNING]、> [!CAUTION]を使ってください。通常はプレーンな文を使い、補足事項すべてを注意書きで囲まないでください。GitHub Markdown が表示されない場所（コミットメッセージ、ターミナル／CLI の出力、GitHub 以外のトラッカー）では注意書き構文を使わず、Note:と記載してください
• 取り消し線は、レビュー後に方針が変わり、その変化を本文中に残す必要がある、長期間参照されるプルリクエスト本文では使って構いません。誤字や表現の修正には使わないでください
• 段落を一定の文字数で折り返さないでください。ソース内では各段落を1行で記述します。GitHub は段落内の改行をスペースに置き換えるため、折り返すと生のソース（gh pr viewの出力、エディター、差分）が崩れて見えます。行を分けるのはブロック要素（見出し、リスト項目、コードフェンス）の間と、段落の境界だけにしてください

決して削ってはいけないもの

冗長な表現は削っても、内容は削りません。成果物が長くなっても、次の内容は必ず残します。

• 破壊的変更と、利用者が対応する必要のある事項
• 手動で実行するものも含め、移行とロールバックの手順
• データ損失とセキュリティリスク。注意事項として和らげず、リスクとして明記します
• 運用上の影響範囲。本番環境で何に影響するか、問題が起きた場合に誰に通知が届くか
• references/pr-writing.md のテストルールに沿った、既知の不足点と未テストの経路
• 観測された症状。正確なエラーテキスト、失敗した実行やインシデントへのリンク、根本原因の仕組み
• 読者から明示的に求められた内容。依頼された手順説明、フェーズごとの注記、レビュアーの質問への直接的な回答には、すべて詳しく答えます。簡潔さに関するルールが適用されるのは、依頼されていない文章です

適用範囲

このスキルが対象とするのは文章の作成であり、変更内容ではありません。文章を短くするために差分を組み替えたり、コミットを削除したり、適用範囲を狭めたりしてはいけません。変更の説明に長文が必要なら、長文で記述します。

ワークフロー

• ユーザーが明示的に草案の作成・修正・レビューを依頼したかどうかにかかわらず適用されます。発動の条件は、文章の作成依頼ではなく、成果物（PRの文章、ドキュメント、コメント、要件）を作成しようとしていることです
• セッションの主な作業が「PRの作成」ではなく、コード、インフラ、設定の作業であっても、次の作業を行う前に毎回このスキルを適用します。
  • create_pull_request、update_pull_request
  • add_pr_review_comment、edit_pr_review_comment、reply_to_comment、reply_to_review_thread、reply_and_resolve_review_thread
  • コードコメントまたはドキュメントの行の作成や編集。差分に説明文が紛れ込む前に、その都度適用します
  • 成果物の種類を問わず、要件や受け入れ基準の定義、明確化、実装。この場合は references/requirements-ears.md を使用します
• 長いセッションでは、このルールをシステムプロンプトから覚えていることに頼らないでください。上記の各作業を、何ターン経過したか、無関係なツール呼び出しが何度あったかにかかわらず、新たな発動条件として扱います
• 既存のPRのタイトルや本文（またはGitHub上の公開済みコメントやドキュメント）を編集する前に、必ず現在の内容を取得します。会話内の以前の草案を基に編集してはいけません。references/gh-cli.md に従ってください
• PR本文を作成する際は、差分に、行に紐づく補足や、本筋から外れた付随的な変更（references/body-writing.md に定める、適用範囲内の実質的な作業ではないもの）がないか確認します。それぞれ本文ではなく注釈にします。PRの作成とプッシュ後に注釈を投稿します。既存のPRでは、投稿者を先に確認します。ユーザーが作成者である場合は、特に依頼がなくても、保留中のレビューや add_pr_review_comment ではなく、注釈付きの行コメントとして投稿します。references/pr-writing.md の「作成者の注釈」に従ってください
• 作業完了を宣言する直前に、PR本文と、変更したコメント・ドキュメント・説明文のすべてについて、references/self-check.md のセルフチェックを実施します。その後に修正があるたび、現在の全文を対象に必ず再実施します。すべての update_pull_request 呼び出しは後続の修正に当たるため、構造化ツールを使う場合も、送信する本文にセルフチェックを実施します
• gh を直接使って（create_pull_request などの構造化ツールを使わずに）PRやIssueのタイトル、本文、コメントを投稿または編集する場合、固有の失敗要因があります。シェルのエスケープ処理、-f と -F の使い分け、投稿内容の未検証については、references/gh-cli.md を参照してください
• コミットメッセージのスタイルは、references/pr-writing.md のタイトル規則に合わせます

アンチパターン

見つけたらすぐに却下してください。

• 差分をファイルごとに言い直す、冗長な要約
• 例外を挙げずにカテゴリを一度示せば済むのに、影響を受けた項目をすべて名前付きで列挙する箇条書き
• 理由を説明せず、方法だけを説明すること。動機を示すべきところで実装の詳細を述べること
• 内部のやり取りが漏れ出ていること。開発中の応酬、セッションメモ、「議論したとおり」、ツールやエージェントによる説明
• 採用しなかった案を列挙すること。却下したアプローチ、取り消した実験、最終的な差分に関係のない「Xをしないことにした」
  • 例外：採用したアプローチが一見すると誤っている、または分かりにくい場合の一行の理由説明。これは列挙ではなく、references/body-writing.md の Anticipated reviewer questions パターンです
• ないことを説明すること。リンク先のサブ課題や追跡課題ですでに示されているスコープについて、「ここでは扱っていません」と改めて述べること。課題の関連図が構造として示しているため、文章で言い直しても、クリックして確認できる以上の情報はレビュアーに伝わりません
• リポジトリで求められていない、網羅的な自動生成チェックリスト
• 既存のテンプレートに追加された、独自の太字のセクション見出し
• 古くなった検証の主張。後の編集で対象が変わったにもかかわらず、再確認されていないテストやステータスに関する記述です。捏造ではなくても、いずれにせよ嘘のように読めるため、references/self-check.md に従って現在の差分を再検証してください