Zenn
📝

Zenn公開用記事フォーマット改善（継続）（開発日記 No.030）

に公開
プログラミング
開発日記
idea

関連リンク

Zenn公開用記事フォーマットの改善（継続）

はじめに

昨日は、開発日記をZenn記事として自動生成するためのフォーマット改善に取り組みました。しかし、生成された記事にはいくつかの問題点が残っていました。今日は、昨日の作業を引き継ぎ、これらの問題点を修正し、より安定した自動生成プロセスを目指します。

背景と目的

開発日記の自動生成プロセスにおいて、昨日の成果物であるZenn記事 (Docs/articles/2025-03-29-dev-diary.md) を確認したところ、以下の問題点が発覚しました。

  1. 記事冒頭のメッセージボックスに、削除したはずの開発サイクルに関する記述が残っている。
  2. 前回の開発日記へのリンクURLに仮の文言が含まれている。
  3. 記事のタイトルが意図したものと異なる。

これらの問題は、自動生成プロセスの信頼性を損なうものです。今回の目的は、これらの不具合を修正し、開発日記からZenn記事への変換プロセスをより正確かつ堅牢にすることです。

検討内容

課題の整理

昨日の成果物と自動生成プロセス全体をレビューし、以下の課題を特定しました。

  1. LLMへの指示不足: diary_converter.py 内のプロンプトが、指定されたfrontmatterやメッセージボックステンプレートを厳密に守るようにLLMへ指示できていない。
  2. テンプレートファイルの不整合: Zenn記事のテンプレートファイルが Diary-Converter リポジトリ (Diary-Converter/templates/zenn_template.md) と Docs リポジトリ (Docs/dev-docs/zenn_template.md) の両方に存在し、内容が異なっている。
  3. 設定の重複: diary_converter.py スクリプト内に、テンプレートファイル (zenn_template.md) と重複する可能性のある設定情報が含まれている。
  4. CI/CDパイプライン設定の問題:
    • Docs リポジトリのGitHub Actionsワークフロー (Docs/.github/workflows/diary-convert.yml) で、使用するテンプレートパスが指定されている（またはデフォルト値が期待通りでない）。
    • 同ワークフローで、前回の記事スラッグがハードコードされているか、動的に取得する仕組みがない。
    • Diary-Converter の action.yml に不要な引数 (cycle_article) が残っている。
    • プロジェクト名やIssue番号がハードコードされているか、外部からパラメータとして渡す必要があり、自動化の妨げになっている。

解決アプローチ

これらの課題を解決するために、以下のステップで修正を進めることにしました。

  1. プロンプトの強化: diary_converter.py のプロンプト生成ロジックを修正し、LLMに対して提供されたテンプレートとfrontmatterをより厳密に守るよう指示を強化する。
  2. テンプレートの一本化: Diary-Converter/templates/zenn_template.md を正とし、Docs/dev-docs/zenn_template.md を削除する。これにより、テンプレート管理を一元化する。
  3. 設定の整理: diary_converter.py 内の設定を見直し、テンプレートファイルとの重複を排除、またはコメントで明確化する。
  4. CI/CDパイプラインの修正:
    • Docs/.github/workflows/diary-convert.yml を修正し、テンプレートパスの指定を削除（デフォルト値を使用）、前回の記事スラッグを自動検出するステップを追加、不要なパラメータ (project_name, issue_number) を削除する。
    • Diary-Converter/action.yml を修正し、不要な cycle_article 引数を削除、プロジェクト名とIssue番号をリポジトリ情報やコミットメッセージなどから自動検出するロジックを追加する。

実装内容

上記アプローチに基づき、以下の修正作業を行いました。

変更点1: プロンプト修正と再生成テスト

まず、Diary-Converter/src/diary_converter/diary_converter.py 内のプロンプト生成部分を修正しました。LLMに対し、提供されたfrontmatterとメッセージボックスのテンプレート構造を厳密に守るように指示を強化しました。
この修正の効果を確認するため、昨日の開発日記 (Docs/dev-records/2025-03-29-development.md) を用いて再度Zenn記事 (Docs/articles/2025-03-29-dev-diary.md) を生成し、冒頭部分の問題（メッセージボックス、リンクURL、タイトル）が解消されることを（暫定的に）確認しました。

変更点2: テンプレートファイルの一本化

次に、テンプレートファイルの重複問題を解決しました。Docs/dev-docs/zenn_template.md をリポジトリから削除し、今後は Diary-Converter/templates/zenn_template.md のみを唯一のテンプレートとして使用するように関連設定を更新しました。

変更点3: GitHub Actionsワークフロー (Docs) の修正

Docs/.github/workflows/diary-convert.yml に対して以下の修正を行いました。

  • テンプレートパスを指定する引数を削除し、Diary-Converter アクション側のデフォルトパス (Diary-Converter/templates/zenn_template.md) が使用されるようにしました。
  • ワークフロー内で前回の記事に対応するMarkdownファイル名（スラッグ）を自動的に特定するステップを追加し、それを Diary-Converter アクションの prev_article パラメータに渡すようにしました。
  • 不要となった project_name と issue_number パラメータの受け渡しを削除しました。
# Docs/.github/workflows/diary-convert.yml (修正イメージ)
steps:
  # ... checkout など
  - name: Get previous article slug
    id: get_prev_slug
    run: |
      # ここで前回の記事スラッグを取得するロジックを実行
      echo "::set-output name=slug::$(find Docs/articles -name '????-??-??-dev-diary.md' | sort | tail -n 2 | head -n 1 | sed 's|Docs/articles/||' | sed 's|.md||')"
  - name: Convert Diary
    uses: ./Diary-Converter # ローカルアクションを使用する場合
    with:
      diary_file: ${{ github.event.inputs.diary_file }} # トリガーからの入力を想定
      output_dir: Docs/articles
      prev_article: ${{ steps.get_prev_slug.outputs.slug }}
      # template_path: は削除
      # project_name: は削除
      # issue_number: は削除

変更点4: Diary-Converter Action の修正

Diary-Converter/action.yml に対して以下の修正を行いました。

  • 不要な cycle_article 引数を定義から削除しました。
  • アクション内で、実行されているリポジトリ名から project_name を自動的に取得するロジックを追加しました。
  • アクション内で、コミットメッセージやブランチ名などから issue_number を自動的に抽出するロジックを追加しました（具体的な実装は今後の検討）。

変更点5: diary_converter.py の修正

diary_converter.py に対して以下の修正を行いました。

  • cycle_article 引数に関連する処理コードを削除しました。
  • テンプレートファイルから読み込む内容と重複する可能性のあるデフォルト値設定部分を見直し、テンプレートへの依存を明確にするためのコメントを追加しました。

技術的なポイント

今回の修正における技術的なポイントは以下の通りです。

  • プロンプトエンジニアリングの重要性: LLMに期待通りの出力をさせるためには、指示（プロンプト）の明確さと具体性が非常に重要であることを再認識しました。特に、テンプレート構造の厳守を求める指示は効果的でした。
  • 設定とコードの一元管理 (DRY): テンプレートファイルの重複や、スクリプト内の設定重複は、不整合やメンテナンス性の低下を招きます。テンプレートを一本化し、設定情報を適切な場所（テンプレート、Action定義、ワークフロー）に集約することで、DRY (Don't Repeat Yourself) 原則を適用しました。
  • CI/CDにおける動的パラメータ: 前回の記事スラッグやプロジェクト名、Issue番号など、実行ごとに変化する可能性のある値をハードコードせず、ワークフローやアクション内で動的に取得・設定することが、自動化の柔軟性と堅牢性を高める鍵となります。GitHub Actionsの機能（
GitHubで編集を提案

Discussion