企业官网建设流程全解析

決済プロバイダからの Webhook 受信機能を題材にした仕様書ドラフト（リトライ制御とデッドレターキュー＝DLQ の設計）が、yomiyasu によってどのように推敲されたのかを、原文・推敲後・変換原則・検証データの4つの観点から解説します。この記事を読めば、仕様書ドラフトで守るべき要件の書き方と、AI 生成文から「誰が・何を・どうする」を復元する yomiyasu の適用方法を同時に理解できます。

1. この文書の位置づけ：評価コーパスと_blの意味

この記事が扱うのは、tests/corpus/yomiyasu_rewritten/06_spec_draft_sonnet_casual_bl.md です。これは yomiyasu リポジトリの評価コーパスの1ファイルで、AI が生成した仕様書ドラフトを yomiyasu が推敲した後の出力が保存されたものです。

ファイル名の構成を分解すると、情報が読み取れます。

• 06_spec_draft：コーパスのジャンル番号。8つの実務ジャンルのうち「外部決済プロバイダからの Webhook 通知受信機能における、リトライ制御とデッドレターキュー（DLQ）の機能仕様書ドラフト」を指します（scripts/build_corpus.py）。
• sonnet_casual：生成時の文体変種。「スタートアップのテックリード。現場感のある開発者ブログのトーンで記述してください」という指示で生成されています（scripts/build_corpus.py）。
• _bl：blacklist_ai（単語禁止指示付きで生成した AI 出力）を推敲した出力であることを示します。コーパス生成スクリプトで、blacklist_aiディレクトリ由来の推敲ファイルには_blが付与されます（scripts/build_corpus.py）。

コーパス全体は「素の AI 出力（raw_ai）」「AI らしい表現の禁止語を指示した出力（blacklist_ai）」「yomiyasu による推敲出力（yomiyasu_rewritten、48本）」の3群で構成され、人間が書いた文書（human）とエッジケース（edge_cases）を含めて160ファイルが tests/corpus/benchmark_results.json に集計されています。

注意点として、この推敲出力は scripts/build_corpus.py のドキュメントに「現行 SKILL の実走検証には使わない」と明記されている通り、過去の検証用パイプラインで保存された記録です。後述の変換解説では、当時の推敲プロンプト（7原則）と現行の SKILL.md のルールを区別して扱います。

2. 原文と推敲後：何がどう変わったのか

推敲前の原文は tests/corpus/blacklist_ai/06_spec_draft_sonnet_casual.md です。単語禁止の指示（「手触り」「解像度」「地味に効く」「〜側に倒す」「静かに壊れる」「時間を溶かす」などの AI らしい表現を使わない、scripts/build_corpus.py）付きで生成された、比較的まっとうな仕様書ドラフトです。両者を並べると、yomiyasu の推敲の痕跡が明確に見えます。

推敲前（blacklist_ai）の見出しと冒頭

Webhook受信: リトライ制御とDLQ 機能仕様（ドラフト）

目的

決済プロバイダからのWebhookを取りこぼさず処理し、失敗したイベントを運用者が再処理できるようにする。

推敲後（yomiyasu_rewritten/_bl）の見出しと冒頭

Webhook受信のリトライ制御とDLQ機能仕様ドラフト

目的

決済プロバイダから届くWebhookをすべて処理し、処理に失敗したイベントを運用者が再処理できるようにする。

ここから読み取れる変化は次の3点です。

1. 見出しのコロンと空白の整理：Webhook受信: リトライ制御とDLQ 機能仕様（ドラフト）は、コロン・半角空白・補足カッコが使われていました。推敲後はWebhook受信のリトライ制御とDLQ機能仕様ドラフトとなり、装飾的な記号が排除され、見出しが「何の話か」を短く案内する形に整えられています。これは現行 SKILL.md の「装飾記号の排除と太字の表示」「案内用スライドの見出し」の指針と方向が同じです。
2. 主語（動作主）の明確化：「Webhookを取りこぼさず処理し」という主語のない書き方から、「決済プロバイダから届くWebhookをすべて処理し」という受け手側の視点が明確な書き方へ変わっています。
3. 数値・条件の完全な保持：目的文に数値はありませんが、後述のようにリトライ回数・保持期間などは原文の値がそのまま保たれています。

数値が「すり替わっていない」ことの確認

yomiyasu の最重要ルールは「情報の不増補（勝手に足さない）」です。この仕様書ドラフトのケースでは、3つの生成バージョンで数値が異なっている点が興味深い観察材料になります。

推敲後は、推敲元であるblacklist_ai版の値（8回・30日・閾値）を正確に引き継いでいます。raw_ai版にあった「6回」「14日」「10件」を混入させていません。つまり yomiyasu は「元の文にない数値を足さず、元の文にある数値を落とさない」という条件保持を、このケースでも実行していることがわかります。これは SKILL.md の「情報の不増補（足さない）」、および業務文書向け指針 references/domains/business.md の「条件と結果の1対1対応」に一致します。

3. 仕様書の5つの要件を読み解く

推敲後の本文は、仕様書として欠かせない5つのブロックで構成されています。それぞれの要件が何を意味し、なぜそう書くべきなのかを、推敲後の文を引用しながら解説します。

目的

決済プロバイダから届くWebhookをすべて処理し、処理に失敗したイベントを運用者が再処理できるようにする。

この仕様書の「主たる用件」が1文で宣言されています。要件は2つです。①Webhook の取りこぼしをなくす、②失敗イベントを運用者が再処理できる。以降の4ブロックはすべてこの目的を実現するための手段として位置づけられます。仕様書の目的節は、評価・感想ではなく「実現すべき機能」を書くのが原則で、ここでは「すべて処理し」「再処理できるようにする」という機能要件の形が保たれています。

受信と応答

受信エンドポイントは、署名を検証してイベントIDを保存するところまでを同期で実行し、2xxを返す。業務処理は非同期ワーカーが実行する。イベントIDには一意制約を設定する。プロバイダが同じイベントを再送または重複配信した場合、システムは再処理せずに200を返す。

このブロックには、Webhook 受信設計の3つの要点が詰まっています。

• 同期処理の範囲の明示：「署名を検証してイベントIDを保存するところまで」を同期で行い、2xx を返す。業務処理（決済反映など）は非同期ワーカーに委譲します。受信応答を速くし、プロバイダ側のタイムアウト再送を減らすための典型的なパターンです。
• 一意制約による重複排除：イベントIDに一意制約を設定することで、DB レベルで重複受信を弾きます。プロバイダが同じイベントを再送・重複配信しても、二重処理せずに 200 を返します。ここでは「システムは再処理せずに200を返す」と動作主（システム）と結果（200）が対応づけられて書かれています。
• 冪等性の保証：受信側で一意制約、ワーカー側で後述のイベントIDキー照合、という二段構えで二重反映を防ぎます。

推敲前の原文「受信エンドポイントは署名検証とイベントIDの保存だけを同期で行い、2xxを返す」と比べると、「署名を検証してイベントIDを保存するところまでを同期で実行し」という語順・表現に整えられ、読み手が「どこまでが同期か」を追いやすくなっています。条件（どこまで同期）・対象（署名、イベントID）・結果（2xx）の対応関係が保たれたままの書き換えです。

リトライ

ワーカーは処理に失敗すると、指数バックオフにジッタを加えて再実行する。初回の待機時間は30秒、上限は1時間で、最大8回まで試行する。5xxやタイムアウトなどの一時的なエラーはリトライする。ペイロード不正やスキーマ違反などの恒久的なエラーはリトライせず、ただちにDLQへ送る。

リトライ設計の核心は「何を、何回、どういう間隔で、どのエラーに対して再試行するか」を一意に決めることです。この仕様書のパラメータを整理すると次の通りです。

指数バックオフは「待機時間を倍々に伸ばす」方式で、ジッタ（ランダムな揺らぎ）を加えることで、大量のワーカーが同時に再試行して DB や外部 API に負荷が集中する「thundering herd」を防ぎます。一方で「何度やっても結果が変わらない」恒久エラー（ペイロード不正、スキーマ違反など）をリトライし続けるのは無駄なので、即座に DLQ へ送るという設計です。

この節は推敲前とほぼ同内容ですが、「ワーカーは処理に失敗すると」「恒久的なエラーはリトライせず、ただちにDLQへ送る」と動作主（ワーカー）と動作（送る）が明記されています。yomiyasu の SKILL.md「主語と目的語の明確化」は「誰が・何を・どうした」を追えるようにする指針ですが、仕様書では特に条件と結果の1対1対応（業務ドメイン指針の「条件と結果の1対1対応」）が重要になります。「初回30秒」「上限1時間」「最大8回」といった境界条件が、省略も追加もなく保持されています。

DLQ

システムは、最大試行回数を超えたイベントと恒久的なエラーが発生したイベントをDLQへ移す。DLQにはイベントID、元のペイロード、エラー内容、試行履歴を保存し、30日間保持する。DLQの件数が閾値を超えると、システムはSlackへ通知する。

DLQ（デッドレターキュー）の役割は、処理しきれなかったイベントを「隔離して記録を残す」ことです。ここでは以下の仕様が確定しています。

• 対象：最大試行回数を超えたイベント＋恒久エラーが発生したイベント
• 保存項目：イベントID、元のペイロード、エラー内容、試行履歴
• 保持期間：30日
• 監視：件数が閾値を超えたら Slack へ通知

保存項目に「元のペイロード」と「試行履歴」を含めるのは、後の原因調査と再処理に必要な情報を残すためです。運用者（人間）が DLQ の中身だけで「どのイベントが、なぜ失敗し、何回試行したか」を再現できるようにする設計です。

「システムは…DLQへ移す」「システムはSlackへ通知する」と、非生物主語でありながら客観的な動作の記述として主語が明示されています。yomiyasu の「擬人化の解消」は「道具や概念に感情や意志を持たせる表現」だけを直す指針であり、システムの客観的な動作を述べる非生物主語は残す、という方針に沿った書き方です。

再処理

運用者は、管理画面またはCLIからDLQのイベントを個別にも一括でも再投入できる。冪等キーにイベントIDを使うので、再投入しても決済が二重に反映されることはない。

DLQ に隔離したイベントは、原因を調査・修正した後に再処理できる必要があります。ここでは次の2点が確定しています。

• 再投入手段：管理画面（GUI）または CLI、個別でも一括でも可能
• 二重反映の防止：冪等キーにイベントIDを使用するため、同じイベントを再投入しても決済が二重に反映されない

「運用者は…再投入できる」と動作主（運用者）が明記され、「冪等キーにイベントIDを使うので」という理由と結果のつながりが明示されています。冒頭の「受信と応答」で述べた一意制約・イベントID照合と合わせて、受信→リトライ→DLQ→再処理の全経路でイベントIDが冪等キーとして一貫していることが読み取れます。

4. 変換の裏側：yomiyasu のどの原則が働いたか

この推敲出力は scripts/build_corpus.py 内のYOMIYASU_REWRITE_PROMPT（当時の検証用プロンプト、7原則）で生成されたものです。その内容を現行の SKILL.md の原則と突き合わせると、次の対応が確認できます。

注意したいのは、現行の SKILL.md は「ラベルと値の対応を示すコロンは文末の装飾と区別し、元の区切りを残す」「元の書式や指定されたスタイルを保つ」と、より慎重なルールに進化している点です。このコーパス出力は過去の検証用パイプラインの産物であり、現行ルールの合格例として扱うべきではないことは README.md にも明記されています（「現在の版を実行した結果ではなく、現行の意味保持ルールの合格例としては扱いません」）。

一方で、意味保持の4点（主張・比重・言い切りの強さ・文の働き）は、この推敲でも一貫して守られています。仕様書としての主張（Webhook をすべて処理し再処理可能にする）、比重（リトライ vs DLQ の振り分け）、言い切りの強さ（すべて断定調）、文の働き（すべて「決まり」＝仕様の提示）が、推敲前後で変動していません。これは現行 SKILL の「文書の立場と文末」における「決まり」の文書としても妥当な形です。業務文書向け指針 references/domains/business.md の「条件・採否の基準・責任の所在を明確にする」「境界条件や責任主体を明確に」とも整合します。

5. コーパスとベンチマークによる検証

この文書が属するコーパスは、scripts/benchmark_corpus.py によって集計されます。同スクリプトは、単純な正規表現（ナイーブ版）による比喩動詞候補の検出と、scripts/yomiyasu_lint.py の検出を各ファイル・各グループで集計し、tests/corpus/benchmark_results.json を生成します。

tests/corpus/benchmark_results.json のグループ別サマリ（2026年時点の保存値）は次の通りです。

注意点が2つあります。1つ目に、scripts/benchmark_corpus.py のドキュメントにある通り「検出件数の比は精度や誤検出率ではない」こと。2つ目に、スコアはリンターの静的指標に基づくものであり、意味が保たれていることの証明ではありません（README も「静的検査で指摘がないことも、意味が保たれていることを示しません」と明記）。この仕様書ドラフトの「8回」「30日」といった数値が元の条件と一致していることは、本文の突き合わせで確認する必要があります。

リンターのカテゴリ分けは tests/test_benchmark_categories.py で回帰テストされています。例えば「仕様が壊れます。」のような比喩動詞はmetaphor_verbsとして別カテゴリに計上され（tests/test_benchmark_categories.py）、記号（コロン・絵文字・括弧）と書式（太字・箇条書き・否定対比）は別々に数えられます。この仕様書ドラフトには比喩動詞・記号・過剰な書式が検出されておらず、リンターの観点ではクリーンな状態です。

6. 実際に試す：ツールの実行とドメイン指定

仕様書ドラフトの推敲を自分で再現・検証するには、同梱の検査ツールが使えます。いずれも Python 標準ライブラリのみで動作します。

# この仕様書ドラフトを静的検査（AIっぽさ・太字構文・文末コロンなど） python3 scripts/yomiyasu_lint.py tests/corpus/yomiyasu_rewritten/06_spec_draft_sonnet_casual_bl.md # 推敲前（blacklist_ai）と推敲後（_bl）の差分を検査 python3 scripts/yomiyasu_diff.py tests/corpus/blacklist_ai/06_spec_draft_sonnet_casual.md tests/corpus/yomiyasu_rewritten/06_spec_draft_sonnet_casual_bl.md --stance=決まり

• --stanceには文書の主たる立場を指定します。この仕様書ドラフトは「決まり・手順を伝える文書」（運用ルール、手順書、仕様）に該当するため決まりが適切です。決めきれない場合は省略します（SKILL.md の Step 4）。
• 差分スクリプトは語の増減、文末の種類や立場の変化、太字の表示を点検する候補を出力しますが、「意味が同じかどうかを自動で確定するものではありません」（README.md）。

現行スキルを実際に使う場合のドメイン指定は次の通りです。この仕様書のような業務・仕様文書はbusinessドメインが対応します。

この文章を業務仕様向けに読みやすくして。 （ここに修正したい文章を貼り付け）

businessドメインの指針（references/domains/business.md）は、比喩をふだんの言葉に直す、条件・採否の基準・責任の所在を明確にする、過剰な装飾を減らして内容とつながりを簡潔に書く、という3本柱です。本記事で見た推敲後の仕様書は、まさにこの指針の典型例といえます。

なお、コーパスの再生成スクリプト scripts/build_corpus.py は実行すると既存の Markdown を削除・再生成し、scripts/benchmark_corpus.py は実行すると tests/corpus/benchmark_results.json を上書きします。保存済みコーパスを読み物として検証・参照する用途では、これらのスクリプトを実行せずに保存ファイルを直接確認するのが安全です。

まとめ

決済 Webhook のリトライ制御と DLQ 機能仕様ドラフトは、仕様書の書き方の良い教材です。目的 → 受信と応答 → リトライ → DLQ → 再処理という5つのブロックで、境界条件（初回30秒・上限1時間・最大8回・30日保持・イベントID冪等キー）が一意に定義されています。そして yomiyasu の推敲は、この条件と数値を一切損なわずに、動作主の明示・見出しの整理・つながりの改善を行うことで、AI 生成文を「読み手が追える仕様書」へ整えています。

この事例から得られる実務上の教訓は、次の2点です。①仕様書の数値・条件は推敲の前後で必ず突き合わせる（yomiyasu は情報不増補の原則でこれを守る）、②仕様書の推敲は比喩の排除だけでなく、誰が何をどうするか（動作主・対象・条件の対応）を復元することが本質である。実際の運用では、リンターや差分チェッカーの指摘を参考にしながら、人間が最終的な意味確認を行うことが推奨されます。