factory-writing

Factoryが生成する日本語の文章(要件定義書、監査レポートと改善提案、PR本文、レビューの指摘、修正の返信、Issue化の提案、コミットメッセージ)を書くときに使う。すべての生成フローのheadless Claude実行に注入され、成果物ごとのスキルが定める章立てと出力形式の前提になる共通の書き方を定める。

SKILL.md

GitHub

Factoryの文章の書き方(factory-writing)

このスキルは、Factoryが生成するすべての文章に共通する書き方を定める。 生成する文章の書き方は、このスキルだけを正本とする。 成果物ごとの章立て、長さ、出力形式は、一緒に注入される成果物のスキルに従う。 両者が食い違うときは成果物のスキルを優先する。

文体

  • GitHubに投稿して人が読むものは、すべて敬体(です・ます)で書く。PR本文、PRへのコメント、レビューの指摘と要約、修正の返信、Issue化の提案、監査の改善提案がこれに当たる。
  • 要件定義書、監査レポート、コミットメッセージは常体で書く。
  • 1つの文章の中で常体と敬体を混ぜない。

文と段落

  • 1文は60字を目安に短くし、100字を超えない。
  • 1段落には1つの話題だけを書く。段落は3文まで。
  • 1文は1行に書く。「。」の後で改行する。
  • 要点が複数あるときは、1文に詰め込まず、箇条書きで並べる。
  • 主語と述語が対応するように書く。誰が(人か、Factoryか、CIか)何をするのかを書き分ける。
  • 「適切に」「必要に応じて」「など」で条件をぼかさない。分からないことは、分からないと書く。
  • 前置き、言い訳、締めのあいさつ、自分の作業の宣言(「確認しました」「以下に示します」)を書かない。

書かないもの

  • 決定や変更の日付、誰が決めたか、以前の形(「旧形式」「以前は」「方針変更」)。ただし、変更そのものを伝える欄(PR本文の変更内容、コミットメッセージ、要件定義書の「変更履歴」章)には、今回の変更を書く。
  • 入力に無い事実、数値、名称、原因。推測で補わない。
  • 絵文字、装飾のための記号、強調のための太字。

記法

  • コード表記(バッククォート)は、コマンド、ファイルパス、設定キー、関数や変数の名前、入力する値に使う。製品名、概念、日本語の語句、強調には使わない。成果物のスキルがコード表記を禁じている場合はそれに従う。
  • 識別子は、初めて出てくるところで言葉と一緒に1回示し、それ以降は言葉で書く。
  • 見出しにはコード表記、日付、括弧の注釈を入れない。
  • 箇条書きは短い項目を並べるときだけ使い、1項目は2文までにする。それより長くなるなら段落か表にする。
  • 英字や数字と日本語の間にスペースを入れない(「3件」と書き、「3 件」とは書かない)。
  • 画面の文言、ボタンの名前、メッセージなど、別の文体の文をそのまま引くときは「」で囲む。囲まないと、文体の混在として検査に当たる。

出力の検査

Factoryは、出力をこのスキルの規則で機械的に検査する。書き終えたら、上の規則を満たすか自分で確かめる。

  • 要件定義書と監査レポート: 見出しのコード表記を、成果物のスキルが定める検査と一緒に見る。問題があれば、その内容を伝えて1回だけ書き直しを求める。直らなければ出力は採用されない。常体と敬体の混在は、ログに記録されるが、出力は採用される。
  • 監査の改善提案: 絵文字や太字などの禁止の記法、HTMLコメント、許可されていないURL、見出しのコード表記を見る。問題があれば1回だけ書き直しを求め、直らなければ出力は採用されない。敬体で書いているかは、ログに記録されるが、出力は採用される。
  • PR本文、レビューの指摘、修正の返信、Issue化の提案、コミットメッセージ: 太字、絵文字、長すぎる行、常体と敬体の混在を見る。問題はログに記録されるが、出力は採用される。