2025-03-11 開発日記: zenn公開用日記テンプレート改善
zenn公開用日記テンプレート改善
はじめに
昨日はdiary_converter.pyの動作確認のためのDocker環境構築に取り組みました。今日は、その流れでZenn公開用日記のテンプレートを改善し、より読みやすく魅力的な記事を自動生成できるようにする開発を進めました。
背景と目的
開発日記をZenn記事として公開するためのテンプレートが必要でしたが、既存のテンプレートには改善の余地がありました。特に、記事の透明性を高めるために自動生成に関する情報を明記することや、読者にとって価値のある構成にすることが重要だと考えました。また、LLMとの協業をよりスムーズにするための行動指針も整備する必要がありました。
検討内容
課題の整理
開発を進める中で、以下の課題が明らかになりました：
- 特定のLLMツール（Cline）に依存した記述が汎用性を損なっていた
- Zenn公開用日記テンプレートの構成が硬く、読みにくかった
- 各セクションの書き方に関するガイドラインが不十分だった
- diary_converter.pyが新しいテンプレート構成に対応していなかった
- LLMが勝手に判断して作業を進めてしまう問題があった
- 記事がLLMによって自動生成されていることが明記されていなかった
- diary_converter.pyでLLMモデル名と開発サイクル紹介記事リンクを記事に含める機能がなかった
- テンプレート部分がスクリプト内にハードコードされていた
解決アプローチ
これらの課題を解決するために、以下のアプローチを採用しました：
- ドキュメントの汎用化：特定のLLMツールに依存しない記述に変更
- テンプレート構成の改善：より自然な流れになるようセクション構成を見直し
- 記述ガイドラインの充実：各セクションの目的と内容を明確に定義し、文字数の目安や具体例を追加
- diary_converter.pyの機能拡張：テンプレートファイルを読み込む機能などを追加
- LLMの行動指針の明確化：ユーザー主導の開発プロセスを明確に定義
- 自動生成情報の追加：記事冒頭に自動生成に関する情報を明記する仕組みを実装
- テンプレートの外部化：スクリプト内のテンプレート部分を完全に外部ファイル化
実装内容
変更点1: Auto_Logging_Guideの汎用化
まず、Cline_Auto_Logging_Guide.mdを汎用的なAuto_Logging_Guide.mdに変更しました。ファイル名だけでなく、内容からも「Cline」という単語を削除し、様々なLLMモデルが自分への指示として認識できるよう表現を調整しました。
また、LLMが勝手に判断して作業を進めてしまう問題に対応するため、「重要な行動指針」セクションを追加しました。ここでは以下のような指針を明記しています：
- 常にユーザーの指示を待つ
- 勝手な判断をしない
- 質問を活用して不明点を明確にする
- 段階的に確認しながら進める
- 提案は質問形式で行う
変更点2: Zenn公開用日記テンプレートの改善
Zenn公開用日記のテンプレートを見直し、より読みやすく魅力的な構成に変更しました。新しいテンプレートでは、以下のセクション構成を採用しています：
- はじめに
- 背景と目的
- 検討内容
- 課題の整理
- 解決アプローチ
- 実装内容
- 変更点ごとの詳細
- 技術的なポイント
- 所感
- 今後の課題
- まとめ
各セクションには具体的な例を追加し、記述ガイドラインも充実させました。文字数の目安や品質向上のポイントなども記載し、より質の高い記事が作成できるようにしました。
変更点3: diary_converter.pyの機能拡張
diary_converter.pyを修正して、新しいテンプレートを使用できるようにしました。主な変更点は以下の通りです：
- テンプレートファイルを読み込む機能の追加
def read_template(template_path):
"""テンプレートファイルを読み込む"""
try:
with open(template_path, 'r', encoding='utf-8') as file:
content = file.read()
return content
except Exception as e:
print(f"エラー: テンプレートファイル読み込み中にエラーが発生しました: {e}")
print(f"テンプレートファイル '{template_path}' が見つかりません。")
sys.exit(1)
- コマンドライン引数の追加
parser.add_argument("--template", default="Documents/zenn_template.md", help="使用するテンプレートファイルのパス")
parser.add_argument("--cycle-article", default="", help="開発サイクルの紹介記事へのリンク")
- LLMモデル名と開発サイクル紹介記事リンクを記事に含める機能の追加
llm_model_info = f"この記事は{model_name}によって自動生成されています。"
cycle_article_info = ""
if cycle_article_link:
cycle_article_info = f"私の毎日の開発サイクルについては、{cycle_article_link}をご覧ください。"
変更点4: テンプレートの外部化
diary_converter.pyに直接記述されていたテンプレート部分を完全に外部化しました。これにより、テンプレートの変更がスクリプトの変更に依存しなくなり、より柔軟な運用が可能になりました。
テンプレートファイルが必須になるよう変更し、テンプレートが見つからない場合はエラーを表示して終了するようにしました：
if not template_content:
print("エラー: テンプレート内容が提供されていません")
sys.exit(1)
また、テスト用のテンプレートファイルも作成し、テストがメインのテンプレートファイルに依存しないようにしました。
技術的なポイント
今回の実装で特に重要だったポイントは以下の通りです：
-
関心の分離: テンプレート部分をスクリプトから分離することで、それぞれを独立して変更できるようになりました。これはソフトウェア設計の基本原則である「関心の分離」を実践したものです。
-
エラーハンドリングの強化: テンプレートファイルが見つからない場合のエラーハンドリングを強化し、ユーザーにわかりやすいエラーメッセージを表示するようにしました。
-
テスト環境の整備: テスト用のテンプレートファイルを作成し、テストスクリプトを更新することで、テストの信頼性を向上させました。
-
コマンドライン引数の拡張: 新しいコマンドライン引数を追加することで、ユーザーがより柔軟に設定を変更できるようになりました。
所感
今回のテンプレート改善作業を通じて、技術記事の構成について改めて考える機会になりました。特に、読者の視点に立って情報を整理することの重要性を実感しました。
最初は単純な作業だと思っていましたが、実際に取り組んでみると奥が深く、自分自身の文章力も試されている気がしました。特に、各セクションの目的と内容を明確に定義し、文字数の目安を設定する作業は、記事の質を向上させるために非常に重要だと感じました。
また、LLMとの協業においては、明確な行動指針を設定することの重要性も学びました。ユーザー主導の開発プロセスを明確に定義することで、より効率的かつ意図に沿った開発が可能になります。
今後の課題
今回の開発で解決しきれなかった課題や、今後取り組むべき課題は以下の通りです：
- テンプレートのカスタマイズ機能の強化（ユーザーごとに異なるテンプレートを使用できるように）
- 複数のLLM APIに対応したテンプレート変換機能の実装
- 変換品質の評価と改善のためのフィードバックシステムの構築
- 画像や図表の効果的な活用方法の検討
- SEO対策の強化
- LLMの行動指針の継続的な改善と詳細化
- 開発サイクル紹介記事の作成と公開
特に、開発サイクル紹介記事の作成は優先度が高く、次回の開発で取り組む予定です。
まとめ
今回は、Zenn公開用日記のテンプレートを改善し、より読みやすく魅力的な構成にすることができました。Auto_Logging_Guide.mdの汎用化、テンプレート構成の見直し、記述ガイドラインの充実、diary_converter.pyの機能拡張など、多岐にわたる改善を行いました。
特に、テンプレート部分を完全に外部化したことで、テンプレートの変更がスクリプトの変更に依存しなくなり、より柔軟な運用が可能になりました。また、LLMの行動指針を明確化したことで、ユーザー主導の開発プロセスが実現しやすくなりました。
これらの改善により、開発日記からZenn公開用の記事への変換がより効率的かつ高品質になり、記事の透明性も向上することが期待されます。今後も継続的に改善を行い、より良い開発サイクルを構築していきたいと思います。
Discussion