🛠️ TDDによるmarkdown_utilsモジュール実装と開発手順標準化（開発日記 No.044）

この記事はgemini-2.0-flash-001によって自動生成されています。

関連リンク

• 前回の開発日記

はじめに

昨日は、note-converterプロジェクトのテスト駆動開発によるコア機能実装を行いました。今日は、TDDアプローチによるmarkdown_utilsモジュールの実装と、テスト駆動開発手順の標準化に取り組みます。

背景と目的

これまでTDDによる開発基盤を構築してきましたが、新しい機能を実装する際に、どのファイルにテストを追加し、どのテストを実行すればよいか、手順が明確ではありませんでした。そこで、TDDに関する手順を標準化し、開発プロセスガイドに追記することで、今後の開発における一貫性を確保します。また、markdown_utilsモジュールを実装することで、マークダウン処理に関する機能を一箇所に集約し、コードの再利用性と保守性を高めます。

検討内容

まず、これまでのTDD開発基盤を確認し、新しい機能を実装する際のファイル構造とワークフローを整理しました。具体的には、ユニットテストと統合テストのディレクトリ構造、命名規則、実行コマンドなどを明確化しました。

次に、markdown_utilsモジュールに必要な機能を検討しました。マークダウンの解析、見出しやリストの抽出、コードブロックの抽出、note.com向けのフォーマット最適化、不要な書式の整理など、具体的な機能要件を定義しました。

また、システムの各モジュールの役割と処理フローを視覚化し、詳細設計書に追記することにしました。特に、LLM処理の前後でマークダウン解析と整形を行う理由について、改めて整理しました。

実装内容

まず、TDDの標準手順を@development_process_guide.mdに追記しました。ディレクトリ構造、テストの種類、命名規則、実行コマンド、具体的な実装フローを詳細に記載しました。

次に、markdown_utils.pyの実装を進めました。TDDアプローチに従い、まずテストファイルtests/unit/test_markdown_utils.pyを作成し、必要な機能のテストケースを実装しました。その後、docker-compose run --rm test-unitを実行し、テストが失敗することを確認しました。

scripts/utils/markdown_utils.pyモジュールを作成し、テストで指定した機能を実装しました。実装の際には、正規表現を活用してマークダウンの各要素を適切に抽出し、階層構造を持つデータ（見出し、ネストされたリスト）を適切に処理しました。また、コードブロックの特殊処理（言語指定の抽出とコードコンテンツの保持）、note.com向けのフォーマット最適化、ログ出力による処理状況の可視化なども行いました。

実装後、再度テストを実行したところ、clean_markdown関数の一部テストが失敗しました。デバッグ情報を追加し、テストの期待値と実際の出力を比較した結果、リスト項目の処理部分に問題があることが判明しました。修正後、すべてのテストが正常に通過しました。

docker-compose run --rm test-coverageでカバレッジレポートを生成したところ、markdown_utils.pyのコードカバレッジは96%と高い水準を達成できました。

最後に、システムの各モジュールの役割と処理フローを視覚化し、詳細設計書に追記しました。フローチャートと説明図を作成し、システム全体の流れを明確にしました。

技術的なポイント

• 正規表現: マークダウンの各要素を抽出するために、高度な正規表現を駆使しました。特に、ネストされたリストやコードブロックの抽出には、再帰的なパターンを使用しました。
• 階層構造の処理: 見出しやリストの階層構造を適切に処理するために、再帰的な関数を使用しました。これにより、複雑なマークダウン構造も正確に解析できます。
• テスト駆動開発: TDDアプローチを採用することで、機能要件に基づいた明確なテストを先に作成し、それらを通過する実装を行うことができました。これにより、高品質かつ保守性の高いコードを実現できました。

所感

今回の開発では、TDDアプローチの重要性を改めて認識しました。テストを先に書くことで、実装すべき機能が明確になり、無駄なコードを書くことを防ぐことができます。また、テストが自動化されているため、リファクタリングも安心して行うことができます。

特に苦労したのは、clean_markdown関数のリスト項目の処理部分です。テストがなかなか通らず、デバッグに時間がかかりました。しかし、デバッグ情報を追加し、テストの期待値と実際の出力を比較することで、問題箇所を特定し、修正することができました。

今回の開発で、マークダウン処理に関する知識が深まりました。また、TDDアプローチの実践的なスキルも向上しました。

LLM処理の前後でマークダウン解析と整形を行うことのメリットを改めて整理したことで、システム全体の設計思想を再確認できました。各処理段階で責任を分離し、トークン消費を最適化し、処理の安定性を向上させることの重要性を理解しました。

今後の課題

• markdown_utilsモジュールのさらなる機能拡充（テーブルの処理、画像の処理など）
• テストカバレッジの100%達成
• OpenRouter API連携の実装

まとめ

今日は、TDDアプローチの標準手順を開発プロセスガイドに追記し、markdown_utilsモジュールをTDDで実装し、システムの各モジュールの役割と処理フローを詳細設計書に視覚的に追記しました。これらの成果により、今後の開発がより効率的に進められるようになります。