【ライティングレビュー ロット10】バッチ設計

[ma91n]

テクニカルライティングガイドラインに沿って、バッチ設計ガイドラインをレビューした。削減を最優先とし、次に構造化、一文一義の順で対応している。

対象は documents/forBatch/batch_guidelines.md の1ファイルのみ。

変更規模

項目	変更前	変更後
文字数	78,266	77,125（-1,141字 / -1.5%）
行数	1,131	1,132

技術的な主張・推奨・理由・注意点は削らない方針のため削減率は控えめ。また本文書は比較表（15個）とフロー図テキストの比重が大きく、散文部分に限ると約2.5%の圧縮となっている。

コミット構成

レビューしやすいよう2コミットに分けている。

1. ライティングレビュー: バッチ設計ガイドライン — 本題
2. ページ内リンク切れの修正とAirflowのparams表記の修正 — 副次的に見つかった不具合の修正（後述）

主な変更

削減

• 「ワークフローが存在しない場合（AWS）」冒頭で、EventBridge Schedulerに関するほぼ同義の2文を統合
• 「〜することができる／〜が可能である」の水増しを一括圧縮（要件表の順序制御・エラー制御・並行分岐・合流・強制終了、導入パターン表の利用コスト、定時連携表の誤送信時の制御など計10箇所）
• 非同期呼び出し比較表の「説明」行3セル（ポーリング／コールバック／イベント通知）、「制限」行、「リソース」行
• パラメータ章リード文、ECS上書きのデメリット箇条書き、入力チェック、ドキュメント章の二重「把握」

構造化

• ワークフロー内部定数の壊れたリストを修復: 本文と「理由」ラベルが1行に混ざり階層も崩れていたため、他節と同じ 管理対象/理由/利用方針/例 の4ラベル構成に揃えた
• ECS上書きの項目リストに導入文がなかったため追加し、環境変数とそれ以外の対比が読み取れる順序に組み替え
• 「未着チェック」の二重括弧の入れ子を解消して2文に分離
• サイクルジョブ末尾の「24個用意する（条件）という条件とすることで」という壊れた構文を2文に再構成
• 「同一時間帯の集中回避」の主述不整合を〈結論→手段〉の順に組み替え
• 箇条書きの並列性を修正（バッチ起動トリガー3項目の文末統一、ユースケース3項目の時制統一）

一文一義

I/Fファイル取り込み冒頭、バッチコントローラ概要、非同期タスク定義、業務日付の定義、オンライン開局とリラン、部分更新+NGリスト表示の背景など、単純接続の「〜が」や定義文と宣言文の融合を分割した。

ついでに直した誤記（抜粋）

修正前	修正後
失敗したタスクが保続するフロー	所属する
初期以降やリカバリー	初期移行
UUID発行 & XComの利用を利用	XComを利用
例えば、例えば以下が	重複を削除
ファンション	ファンクション
MERGE文にした方が早い	速い
業務のクリティカル度にも寄る	よる
何か合ったとき	何かあったとき
16:45分起動	16:45起動
リアルタイム性が求めなければ	求められなければ
主な注意点を上げる	挙げる
影響範囲が大きい重要なジョブを大きく改修	影響範囲が広い
⚠️ecs describe tasks（絵文字がコードスパン内）	コードスパン外へ

用語統一として、導入パターン章の「専用／共用」を比較表の見出しに合わせて「占有／共有」に、「プログラミング内で並列化」を「プログラム内で並列化」に揃えた。ほか助詞の欠落・不整合など計30箇所ほど。

ページ内リンク切れとtypoの修正（2つ目のコミット）

レビュー中に見つかった、レビュー前から存在していた不具合。

• VitePressが生成する見出しIDは濁点・半濁点が分解された形になるため、[バッチ実行モデル](#バッチ実行モデル（AWS）) [ワークフローエンジン導入パターン](#ワークフローエンジン導入パターン) の計3リンクが機能していなかった。見出しに明示アンカー（ASCII）を付与して解消
• 見出し「ワークフロー内部定数（AirflowのDAGのparms等）」を params に修正（Airflowの正式なパラメータ名）

ビルド後のHTMLからIDを抽出し、本文中の全ページ内リンクが解決することを機械的に確認済み。

なお [バッチ実行時のログ出力](/documents/forLog/log_guidelines.html#バッチ実行時のログ出力) も同じ理由で機能していないが、修正対象がログ設計ガイドライン側のため本PRには含めず、別PRで対応する。

検証

• 見出し数: h1=16 / h2=30 / h3=15 で変更前と一致（章・節の欠落なし）
• コンテナ（:::）26、コードブロック（```）16、表の行179 — いずれも変更前と一致
• 削除のみのハンク（追加行ゼロ）なし。3ブロック分割レビューの削減量合計（351+591+199=1,141字）と実測差分が完全に一致しており、並行編集による欠落がないことを確認
• textlint: エラー0
• prettier: 整形済み
• markdownlint: 19件 → 17件（残りはレビュー前から存在）
• VitePressビルド: 成功

著者確認事項（すべて解決済み）

コミット 著者確認反映: 推奨の条件修正、可用性の追記、コネクションプールの移動など8件 で反映済み。未解決の確認事項は残っていない。

#	内容	対応
1	プロダクト選定（AWS）の推奨が直後の節と逆向きに読める	✅ 修正: 「ジョブが少なく依存関係も存在しない場合」→「ジョブが多く依存関係も存在する場合」
2	「ワークフローが存在しない場合（AWS）」比較表・リラン操作行の記号と本文の食い違い	✅ 修正: リラン自体は可能とのことなので✅️は維持し、「✅️ECSやLambdaの画面から再実行する（スケジューラ経由のリランは不可）」と表現を整理
3	バッチ実行モデル比較表の「噂があった」	✅ 対応不要: 事実だが、そう書けない事情があるため意図的に濁している
4	「常にバッチで上書き」節の「画面側でも方式2とすることで」が指すもの	✅ 修正: 「画面側でも後述のケース2とすることで」
5	同節で悲観ロックと楽観ロックの用語が混在	✅ 対応不要: このままで問題なし
6	lock_no に定義がない	✅ 修正: 定義そのものは追加せず、共通カラム | PostgreSQL設計ガイドライン へのリンクを付与
7	入力チェックの「ワークフローエンジン上で指定できるもの」が書きかけに見える	✅ 修正: 意味の通らない項目のため削除。あわせて同節の「「I/F設計ガイドライン（※作成予定）」を参照」を、公開済みのI/F設計ガイドラインへのリンクに差し替え
8	「なお、Web API呼び出しでもTCPコネクションの再利用は効果的」の配置	✅ 修正: ## コネクションプール 節ごと ## 性能 の配下（### コネクションプール）へ移動
9	ワークフローエンジンの要件表「可用性」行の粒度、製品比較表に可用性の行がない	✅ 修正: 要件表を「〜仕組みが必要」→「〜仕組みがあるか」と問いかけ形式に統一。製品比較表にも可用性の行を追加（Step Functions: フルマネージドのサーバーレスのためAWS側が担保 / Airflow: MWAAは異なるAZの2つのプライベートサブネットが必須で、コンテナ障害時は別AZで再構築される）

そのほかの修正

• 導入パターン比較表で、1セルに複数の評価が改行なしで並んでいた箇所（「✅️ライセンス数を抑えられる ✅️サーバ数を抑えられる」など）に <br> を挿入。同種のセルが他に残っていないことも機械的に確認済み

🤖 Generated with Claude Code

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.