作業ログを公開記事へ変える品質ゲートの作り方

2026年05月11日から2026年05月17日の週は、個人技術ブログ kenRp-blog と、その下書き生成を支える worklog-blogger をまとめて見直した。ブログ側は Markdown を記事データとして扱う個人ブログリポジトリ、草稿生成スキルは Codex の作業ログと Git 履歴から日次ワークログと週次ナレッジ記事を下書き化する自作スキルである。

この週の論点は、記事を「書ける」だけでなく「読める形で出せる」状態へ寄せることだった。前半は日次ワークログの運用を繰り返して不足を洗い出し、後半で weekly knowledge 記事の構造要件と GitHub Pages の配信権限を実際に修正した。

この記事で解決すること

作業ログをブログ記事に転用するとき、単に「何をしたか」を並べるだけでは読者の役に立ちにくい。この記事では、次の悩みを解く。

• 日次の作業メモを、公開できる技術記事へ変える最低条件を決めたい。
• 記事の品質基準と GitHub Pages の公開導線を分けて確認したい。
• 自動生成した下書きが薄い要約で終わらないよう、検証ルールを置きたい。

実施した改善

週の前半では、ブログ側 に保存する日次ワークログを連日生成し、公開向けの Markdown として不足している点を確認した。特に weekly knowledge 記事の dry-run は、要件を並べるだけで、読者が再利用できる技術記事としては薄くなりやすいことが分かった。

そこで codex-skills というスキル群を管理するリポジトリ側で、草稿生成スキルの weekly knowledge 出力要件を更新した。表と Mermaid 図を必須化し、利用した技術 から 導入手順 までを、記事生成プロセスではなく「実際に変更したアプリやリポジトリ」を主語に書く前提を強めた。

並行してブログ側では、GitHub Pages 配信用 GitHub Actions workflow に contents: write 権限を追加した。これにより、テストとビルドを通過した後に peaceiris/actions-gh-pages が配信先ブランチへ push できる構成へ寄せている。

確認できた成果

この事例の成果は、週次記事の品質基準と、公開パイプラインの成立条件を同じ週に揃えられたことだった。片方だけでは不十分で、記事の構造が良くても公開できなければ運用に乗らず、公開できても記事が薄ければ知見として蓄積しにくい。

判断と進め方

05-13 から 05-15 にかけては、ブログ側の _data/blog に日次ワークログを保存する運用自体を回し続けた。この段階では、ワークログとしては成立していても、週次記事に変換したときに「何を学べばよいのか」が見えにくいという課題が残っていた。

その気づきが、05-16 の 草稿生成スキル 要件更新につながった。週次記事で比較やフローを説明するなら、本文だけではなく表と図を要求したほうが判断や構造を伝えやすい。また、記事生成ツールの説明に逃げず、変更対象のアプリやリポジトリを主役に据えるルールも必要だった。

同じ日にブログ側の Pages workflow も調整したのは、下書き生成と公開運用を別々の問題として扱わなかったためである。記事の品質基準を上げても、公開ジョブが権限不足で止まるなら継続運用にならない。週次記事の質と公開導線を同じ公開運用の問題としてまとめて解いた一週間だった。

使った技術

この事例の変更で中心になった技術は、コンテンツ生成側と配信側で明確に分かれていた。草稿生成スキル 側では Markdown、Mermaid、そして SKILL.md での品質ゲート定義が中心で、記事構造の契約を更新した。ここでの変更対象は Python スクリプトではなく、週次記事の出力要件そのものだった。

ブログ側では GitHub Actions を使い、actions/checkout@v4、actions/setup-node@v4、npm ci、npm test、npm run build、npx playwright install --with-deps chromium、npm run test:e2e、peaceiris/actions-gh-pages@v3 という既存の配信フローを維持したまま、workflow token の権限だけを補強した。

構成

今回の構成は、知見を整える「記事設計レイヤー」と、記事を実際に公開可能にする「配信レイヤー」の二段に分けて考えると理解しやすい。草稿生成スキルは前者で、入力されたワークログをどういう形の記事に変えるかを決める。ブログ側の workflow は後者で、できあがった Markdown をサイトとして安全に出せるかを担う。

flowchart LR
  A["日次ワークログ"] --> B["草稿生成スキルの週次記事要件"]
  B --> C["weekly knowledge Markdown"]
  C --> D["ブログリポジトリ の build / test / E2E"]
  D --> E["Pages workflow の deploy"]
  E --> F["GitHub Pages 公開"]

codex-skills で更新したのは B の部分で、表と Mermaid を含む構造化された weekly knowledge Markdown を要求する契約である。ブログ側で更新したのは E の部分で、deploy step が GITHUB_TOKEN で publish できるようにする認可設定だった。つまり、本文の品質を上げる変更と、配信を通す変更が別レイヤーで噛み合っている。

採用理由と代替案

weekly knowledge 記事に表と Mermaid 図を入れる方針を採ったのは、導入手順、比較、フロー説明を長文だけで処理すると再利用性が落ちるためである。特に 利用した技術、アーキテクチャ、選定理由 を読者が後から参照するなら、視覚的な構造化があったほうが要点を拾いやすい。

一方で、ブログ側の Pages workflow では、Node のバージョンや deploy action を差し替えるより先に contents: write を追加した。理由は単純で、今回の差分から見える問題は build 構成ではなく deploy 権限だったからである。原因が認可層にあると分かっているなら、公開パイプライン全体をいじるより最小変更で直すほうが保守しやすい。

また、この 2 つを同じ週に扱ったのは合理的だった。記事品質の改善だけでは運用が閉じず、公開権限の修正だけでは週次記事の価値が上がらない。書き方の契約と出し方の契約を同時に整えることで、次週以降の worklog 運用が初めて再利用可能な形になる。

検証結果

確認した観点は、品質ゲートの仕様変更と Pages workflow の権限調整を同じ公開運用として扱った点にある。確認した主なコマンドと観点は次の通り。

npm test
npm run build
npm run test:e2e
# GitHub Actions: contents: write を付けた Pages deploy

contents: write は deploy step の認可不足に対する最小変更として扱い、記事側では表・図・対象リポジトリ中心の説明を品質条件にした。

導入手順

この事例の変更は、以下の順で進めると再現しやすい。

1. まず日次ワークログを数日分見返し、weekly knowledge 記事にしたときに不足する説明を特定する。今回は「テキストだけで構造が見えないこと」と「対象アプリではなく生成プロセスの説明に寄りやすいこと」が論点だった。
2. 次に codex-skills の skills/草稿生成スキル/SKILL.md を更新し、weekly knowledge 記事へ必須セクション、表、Mermaid 図、品質ゲートを追加する。これで週次記事の完成条件を先に固定する。
3. そのうえでブログ側の .github/workflows/pages.yml を見直し、既存の npm test、npm run build、npm run test:e2e の流れを壊さずに、deploy に必要な permissions: contents: write を追加する。
4. 最後に dry-run と実ファイルを見比べ、frontmatter、必須セクション、図表、参考ワークログ、秘密情報の有無を確認して draft のまま保存する。

導入順をまとめると次のようになる。

制約と残課題

一つ目の課題は、週の前半が運用レビュー中心で、実装変更の密度が高い日が 05-16 に偏っていたことだった。この場合、dry-run の週次記事は抽象的になりやすく、手動でテーマを絞らないと薄い要約に見えやすい。

二つ目は、草稿生成スキルの仕様変更だけでは既存スクリプト出力が自動的に改善されるとは限らない点である。今回も dry-run の素の出力は、対象アプリより記事生成手順の説明に寄っていたため、仕様と生成結果のズレを人手で埋める必要があった。

三つ目は、Pages workflow の権限追加が妥当でも、CI の実行結果を別途確認しない限り deploy 成功までは断言できないことだった。権限不足は解消方向だが、Node.js や Playwright 側の別要因まで同時に片付くわけではない。

次の改善候補

まず collect_worklog.py 側でも、weekly knowledge 記事の表や Mermaid 図の雛形を自動生成できるようにして、SKILL.md の契約と実出力の差を縮めたい。今のままでは仕様強化の効果が人手編集に依存しやすい。

次にブログ側の Pages workflow は、contents: write 追加後の GitHub Actions 実行結果を追い、deploy step が安定して通るかを確認したほうがよい。必要なら artifact 保存やログ整理も追加して、失敗時の切り分けを早くするべきである。

最後に、日次ワークログへ「実装」「運用」「調査」のような種別を持たせると、週次記事で主題を絞りやすくなる。この事例のように運用レビューと実変更が混ざる週では、後続の再構成コストを下げる効果が大きい。