Zenn
🔄

Diary-Converterの機能シンプル化 テスト環境統一とロジック簡略化（開発日記 No.032）

に公開
Docker
Python
LLM
開発効率化
idea

関連リンク

はじめに

本日の開発テーマは「Diary-Converterの機能シンプル化」です。開発を進める中で、いくつかの複雑化している箇所が見えてきたため、よりメンテナンスしやすく、理解しやすい構造を目指して改善に取り組みました。

シンプル化の背景と課題

Diary-Converterの開発を進める中で、以下の3つの課題が浮上しました。

  1. テスト環境の複雑化: ユニットテストと統合テストが、ローカル環境とDocker環境の両方で実行可能な状態になっており、どちらを正とするか、また実行手順が煩雑になっていました。
  2. 日記生成ロジックの肥大化: diary_converter.py 内の日記生成ロジックが、テンプレートの解析やプロンプト生成において独自の処理を多く含み、複雑化していました。LLMの能力をより活用し、シンプルな構成にしたいと考えました。
  3. 開発記録の命名規則: 上記の改善と合わせて、開発記録ファイルの命名規則も、より情報を含み、かつ処理しやすい形式に変更する必要がありました。

これらの課題を解決するため、以下の計画でシンプル化を進めることにしました。

  1. テスト環境をDockerに統一する
  2. 日記生成ロジックを、テンプレートとLLMへの指示を主体とする形に簡略化する
  3. 新しい命名規則を導入し、関連する処理とドキュメントを更新する

取り組み1：テスト環境のDocker統一

まず、開発環境やCI/CD環境での実行を容易にし、環境差異による問題をなくすため、テスト実行環境をDockerに一本化しました。

具体的な変更内容は以下の通りです。

  1. Docker用テストスクリプトの作成:
    • Dockerコンテナ内でユニットテストを実行するための run_docker_unit_tests.sh を作成しました。
    • 同様に、統合テストを実行するための run_docker_integration_tests.sh を作成しました。
  2. テスト実行スクリプトの更新:
    • 従来ローカル実行も可能だった run_all_tests.sh を修正し、上記で作成したDocker用スクリプトを呼び出すように変更しました。これにより、すべてのテストがDocker環境で実行されるようになりました。
  3. READMEの更新:
    • プロジェクトのREADMEファイルを更新し、テスト環境がDockerに統一されたこと、および新しいテスト実行手順を明記しました。

これにより、開発者はDockerがインストールされていれば、run_all_tests.sh を実行するだけで、環境差異を気にすることなく全てのテストを実行できるようになりました。

取り組み2：日記生成ロジックの簡略化

次に、日記生成の中核である diary_converter.py のロジック簡略化に取り組みました。目標は、テンプレートファイルにLLMへの指示を直接記述し、Pythonコード側では複雑なプロンプト生成処理を行わないようにすることです。

以下の変更を行いました。

  1. テンプレートファイル (zenn_template.md) の更新:

    • テンプレート内に、LLMへの指示を記述する専用のセクションを設けました。これはHTMLコメント <!-- LLM_INSTRUCTIONS_START --> と <!-- LLM_INSTRUCTIONS_END --> で囲む形式としました。
    • このセクション内に、記事の変換ルール（会話ログのストーリー形式化、所感の充実など）や出力形式の指定を記述しました。
    <!-- zenn_template.md の例 -->
---
title: "{{ title }}"
emoji: "{{ emoji }}"
type: "tech"
topics: ["{{ topics }}"]
published: true
---

<!-- LLM_INSTRUCTIONS_START -->
# LLM変換指示

以下の開発日記を、Zenn公開用の記事に変換してください。

## 変換ルール
1. 「会話ログ」セクションは、対話形式ではなく、ストーリー形式に書き直してください
2. 技術的な内容は保持しつつ、読みやすく整理してください
3. 「所感」セクションを充実させ、開発者の視点や感想を追加してください
4. マークダウン形式を維持し、コードブロックなどは適切に整形してください
5. 記事の先頭には、frontmatterブロックを寸分違わず正確に追加してください (上記frontmatter部分のこと)
6. frontmatterの直後には、メッセージボックスを提供されたテキストのみで追加してください
7. メッセージボックスの直後には、関連リンクセクションを追加してください

## 出力形式
frontmatterを含むマークダウン形式の完全な記事を出力してください。テンプレート構造に従いつつ、開発日記の内容を適切に反映させてください。
以下の点に注意してください：
1. コードブロックは必要な場合のみ使用し、記事全体をコードブロックで囲まないでください
2. 記事の先頭や末尾に余分なコードブロックマーカー（```）を付けないでください
3. 記事の先頭に```markdownなどの言語指定を付けないでください

# 入力された開発日記
{{ diary_content }}
<!-- LLM_INSTRUCTIONS_END -->

{{ llm_response }}

  2. TemplateManager クラスの簡略化:

    • 従来行っていた複雑なテンプレート解析処理を削除しました。
    • prepare_template メソッドを簡略化し、主にプレースホルダー（例: {{ title }}）の置換のみを行うように修正しました。LLMへの指示抽出は DiaryConverter 側で行うように役割分担しました。

  3. DiaryConverter クラスの generate_prompt メソッドの簡略化:

    • テンプレートファイルから <!-- LLM_INSTRUCTIONS_START --> と <!-- LLM_INSTRUCTIONS_END --> で囲まれた指示部分を抽出するロジックを追加しました。
    • 抽出した指示部分と、入力された開発日記の内容 (diary_content) を組み合わせて、最終的なプロンプトを生成するように変更しました。これにより、Pythonコード側でプロンプトの構造を細かく制御する必要がなくなりました。

これらの変更により、日記生成のロジックが大幅にシンプルになりました。LLMへの指示変更が必要な場合も、テンプレートファイルを修正するだけで対応可能となり、柔軟性とメンテナンス性が向上しました。

取り組み3：開発記録の命名規則変更

最後に、開発記録ファイルの命名規則を以下の形式に変更しました。

yyyy-mm-dd-[通し番号]-[テーマ名]-[プロジェクト名].md

例: 2025-04-01-001-機能シンプル化-Diary-Converter.md

この新しい命名規則には、日付、一意な通し番号、開発テーマ、関連プロジェクト名が含まれており、ファイル名から多くの情報を得られるようにしました。

この変更に伴い、以下の修正を行いました。

  1. ドキュメントの更新:
    • Docs/dev-docs/Auto_Logging_Guide.md に記載されている命名規則のガイドを、新しい規則に合わせて修正しました。
  2. diary_converter.py の修正:
    • 新しいファイル名の形式から、テーマ名 (extract_theme_from_filename)、プロジェクト名 (extract_project_name_from_filename)、通し番号 (extract_issue_number_from_filename) を正規表現などを用いて抽出するメソッドを追加しました。
    • convert メソッド内でこれらの抽出メソッドを呼び出し、得られた情報をテンプレート (zenn_template.md) のプレースホルダー（例: {{ title }}, {{ issue_number }} など）に埋め込むように修正しました。これにより、ファイル名に基づいて記事のメタ情報などを自動的に設定できるようになりました。

所感

今回のシンプル化作業を通じて、いくつかの重要な気づきがありました。

まず、テスト環境の統一は、開発体験の向上に直結すると実感しました。環境差異を気にせず、誰でも同じ手順でテストを実行できることは、特にチーム開発やCI/CD連携において非常に重要です。Dockerへの一本化は、そのための有効な手段でした。

次に、LLMを活用する上での役割分担の見直しです。当初はPython側で多くのロジックを組んでいましたが、LLMへの指示をテンプレートに含める形にしたことで、コードの見通しが格段に良くなりました。LLMが得意な「指示に基づくテキスト生成」に処理を寄せ、Pythonコードはデータの準備やLLMとの連携に集中させることで、よりシンプルで変更に強い構成を実現できたと感じています。

ファイル命名規則の変更も、地味ながら効果的な改善でした。ファイル名自体が持つ情報量を増やすことで、ファイルを見ただけで内容を推測しやすくなり、また、その情報をプログラムで利用することで、記事生成の自動化もよりスムーズになりました。

全体として、今回のシンプル化は、コードの可読性、保守性、そして開発効率の向上に繋がったと考えています。複雑化の兆候が見えた段階でリファクタリングに取り組むことの重要性を再認識しました。今後も、定期的にコードや設計を見直し、より良い状態を維持していきたいと思います。

まとめ

本日はDiary-Converterの機能シンプル化に取り組み、テスト環境のDocker統一、日記生成ロジックの簡略化、開発記録の命名規則変更を行いました。これにより、プロジェクト全体の保守性と開発効率が向上しました。特に、LLMへの指示をテンプレートに移行したことで、ロジックが大幅にシンプルになり、今後の機能拡張や変更にも柔軟に対応しやすくなったと考えています。

GitHubで編集を提案

Discussion