【要約】根拠付きドキュメントを書いたら、未検証の回帰ケースが2件見つかった [Zenn_Python] | Summary by TechDistill
> Source: Zenn_Python
Execute Primary Source
// Problem
開発者が
agent-cost のドキュメントを改善しようとした際、記述内容が実際に検証されているかを保証できない課題に直面した。従来のドキュメント作成では、以下の問題が発生していた。- ・文章による記述は、テストとの整合性を強制しない。
- ・ドキュメントが「検証済み」か「著者の推測」かを区別できない。
- ・既存テストが境界値のみをカバーし、中間ケースの検証が漏れていた。
- ・リファクタリング時に、テストがない箇所が静かに壊れるリスクがあった。
// Approach
著者は
evidence-docs を用い、ドキュメントの主張を構造化データ（Claim Corpus）として定義する手法を採用した。具体的には以下のステップで検証を行う。- ・
epistemic_statusにより、検証の厳密さを固定語彙で明示する。 - ・
provenanceに、根拠となるテスト名やソースのハッシュを記録する。 - ・主張に対して具体的なテストを紐付けるプロセスを強制する。
- ・検証時に、記録されたハッシュと実際のコードが一致するかを機械的にチェックする。
// Result
この手法により、実装は正しいがテストが欠落していた2件の回帰ケース（GAP-01, GAP-02）を特定し、修正した。
- ・GAP-01: キャッシュ書き込みの内訳に関する中間ケースのテストを追加。
- ・GAP-02: 価格ステータスの優先順位に関するテスト4件を追加。
- ・結果として、将来のリファクタリングによるデグレのリスクを低減した。
- ・ドキュメントとテストの乖離を、記述プロセスの中で強制的にあぶり出すことに成功した。
Senior Engineer Insight
> ドキュメントを「検証可能な仕様」に変える強力な手法だ。テストの欠落を記述プロセスで強制的にあぶり出す設計は、品質保証として極めて合理的である。ただし、記述コストは非常に高い。全機能への適用は非現実的だ。計算ロジックやセキュリティ要件など、失敗が許されないクリティカルな領域に限定して運用すべきである。