この記事で解決できること

LLMがfrontmatterテンプレートを守れないことによるCI連続失敗の根本原因
push前に決定論的ゲート（validate-frontmatter.sh）を差し込む実装方針
ローカルのSKILLファイルを直しても自動化が直らない理由

環境

Claude Codeクラウドルーチン（content-executor）で記事を自動生成
Qiita CLI + GitHub Actions（qiita-publish.yml）で自動投稿
事故発生日: 2026-06-19頃

問題：Qiita/Zenn CIが再び連続失敗した

2026-05-17にQiita/Zenn CIのfrontmatter欠落事故が発生し、CIに検証ガードを入れた。そのガードが「設計通りに」働いてpushを止め続けた——つまり再発した。

原因は以下の構造だった。

層	動作	限界
テキスト指示（プロンプト）	LLMに「このフォーマットで」と伝える	守る「努力」はするが保証はない
CIガード（push後）	壊れた記事を検出して止める	pushは通る。失敗ログが積み上がる
push前ゲート（今回の解決策）	生成直後・push前に機械的に検証する	壊れた状態でpushされることを原理的に防ぐ

原因：LLMはfrontmatterテンプレートを「守ろうとするが保証しない」

content-executorがQiita/Zenn向けのadapted記事を生成する際、LLMはfrontmatterテンプレートを「知っている」。しかし確実に守るわけではない。

フィールドを一部省略する
過去に見た形式（published: false や published_at: など）を混入させる

これはプロンプトの問題ではなくLLMの構造的な動作だ。指示文を厚くするアプローチには限界がある。

解決策：Step5にvalidate-frontmatter.shを埋め込む

content-executorのStep5（外部配信adapted生成後）にvalidate-frontmatter.shを必ず通す構成に変更した。

# Step5の処理順（変更後）
# 1. Qiita向けadapted記事を生成（LLM）
# 2. cd Qiita && git pull --rebase

# 3. push前ゲート（新設）
bash scripts/validate-frontmatter.sh public/{slug}.md
# → NGなら自動補完を試みてexit0まで繰り返す
# → 通らなければpushをスキップ

# 4. exit0確認後にpush

validate-frontmatter.shは以下をチェックする:

必須フィールドの存在（updated_at、id、organization_url_name、slide）
禁止フィールドの不在（published、published_at）
id: null ではなく id: '' であること

これで「LLMが正しく出力したか」をLLMに確認させるのではなく、機械が検証する境界を作れる。

付記：ローカルのSKILLファイルを直しても何も変わらなかった

生成側を修正しようとしてローカルのSKILL.mdを書き換えたが、何も変わらなかった。

実際に記事を生成しているのはクラウド上で稼働しているcontent-executorルーチンだった。ローカルのSKILL.mdは参照されていない。authoritativeな設定はクラウド側のスケジュール設定にある。

自動化の設計では「どのファイルが実際に参照されているか」を事前に把握しておくことが必須だ。

まとめ：守らせたい制約はゲートに昇格させる

指示文 → ゲート への昇格基準:
- 崩れたとき下流システム（CI）が止まる制約
- 機械的に検出・検証できる制約
- 同じ崩れが2回以上発生した制約

プロンプトを厚くするより、push前のシェルスクリプト1本の方が信頼できる。

AI ツールを業務に組み込む設計の実験ログを書いています。 https://masatoman.net