wassden

# Dogfooding Findings - 実験ランナー仕様作成での問題点と改善案 ## 概要 実験ランナーコンポーネントの仕様作成において、wassden自身を使ったdogfooding（自己利用）を実施した際に発見された問題点と改善案をまとめる。この記録は今後のwassden品質向上のための重要な知見として活用する。 ## 実施内容 - **対象**: 実験ランナーコンポーネントの仕様作成 - **期間**: 2025年8月21日 - **使用機能**: prompt-requirements, validate-requirements, prompt-design, validate-design, prompt-tasks, validate-tasks, get-traceability - **成果物**: specs/requirements.md, specs/design.md, specs/tasks.md ## 発見された問題と再現方法 ### 1. プロンプト生成の問題 #### 1.1 情報充足性判定の過度な厳格さ **問題**: `prompt-requirements`が十分な情報が提供されていても「情報不足」と判定することがある **再現方法**: ```bash uv run wassden prompt-requirements --userInput "実験ランナーコンポーネントを実装したい。検証フレームワークの実験機能として、EARS適用率測定、検証パフォーマンス測定、言語検出精度測定、比較実験などを行うモジュールです。" ``` **結果**: 十分な説明があるにも関わらず、ユーザー、制約、スコープについて追加質問される **改善案**: - 情報充足性の判定基準を緩和 - 文字数や含まれるキーワードによる定量的判定の導入 - 段階的な情報収集（最低限→詳細）アプローチの採用 #### 1.2 プロンプト生成の冗長性 **問題**: `prompt-requirements`, `prompt-design`, `prompt-tasks`の生成プロンプトが冗長で実際の作業に使いにくい **再現方法**: 任意の要件でプロンプト生成を実行し、出力されるプロンプトの長さと実用性を確認 **改善案**: - プロンプトテンプレートの簡潔化 - 必須項目と推奨項目の明確な分離 - ユーザーレベル（初心者/上級者）による出力調整 ### 2. 検証機能の問題 #### 2.3 設計コンポーネント参照の厳格すぎる要求 **問題**: design.mdの全ての単語がコンポーネントとして認識され、tasks.mdでの参照が要求される **再現方法**: 1. design.mdに「Risk」「Mitigation」などの一般的な単語を使用 2. `validate-tasks`を実行 **結果**: これらの単語が設計コンポーネントとして認識され、tasks.mdでの参照不足としてエラー **改善案**: - 設計コンポーネントの定義を明確化（特定の記法のもののみ） - 一般的な単語の除外リスト作成 - コンポーネント抽出ロジックの改善 ### 3. 言語検出の問題 #### 3.1 英語文書の検出精度 **問題**: 英語の仕様例文書が日本語として誤検出される場合がある **再現方法**: ```bash uv run wassden validate-requirements --requirementsPath docs/en/spec-example/requirements.md ``` **結果**: 英語文書にも関わらず日本語のEARS検証が適用される（修正済み） **改善案**: - 言語検出パターンの充実化 - セクションヘッダーによる言語判定の強化 - pycld2による検出結果との組み合わせ最適化 ### 4. トレーサビリティ機能の問題 #### 4.1 カバレッジ計算の不正確さ **問題**: 設計コンポーネントの抽出が過度に広範囲で、実際のカバレッジが正確に測定できない **再現方法**: 任意のdesign.mdとtasks.mdで`get-traceability`を実行し、抽出されるコンポーネントを確認 **改善案**: - コンポーネント抽出ルールの明確化 - 手動でのコンポーネント指定機能 - カバレッジ計算ロジックの改善 ## 成功した点 ### 1. EARS検証機能 - REQ-IDプレフィックスの除去機能が正常に動作 - 日本語・英語両方のEARSパターン検証が機能 - マークダウンからの要件抽出が高精度 ### 2. プロンプト生成品質 - 生成されるプロンプトの構造が整理されている - 必要な項目が網羅されている - トレーサビリティを意識した内容 ### 3. 統合ワークフロー - 要件→設計→タスクの一連の流れが機能 - 完全なトレーサビリティが確保可能 - dogfoodingによる実用性検証が成功 ### 4. タスクレビューの品質ガードレール違反によるタスク復帰 - TODOと実装されていた箇所を検知 - 修正可否をagentから確認された - agentの誤った完了判断に対する適切なレビューが成功 ## 改善の優先度 ### 高優先度 1. EARS検証の誤検出防止（受け入れ観点の除外） 2. TASK-ID検証の改善（説明文での誤検出防止） 3. 設計コンポーネント抽出ロジックの改善 ### 中優先度 1. プロンプト生成の簡潔化 2. 情報充足性判定の調整 3. 言語検出精度の向上 ### 低優先度 1. トレーサビリティ計算の最適化 2. ユーザーレベル別の出力調整 3. 検証除外エリアの設定機能 ## 実装方針 ### 短期改善（次回リリース） - EARS検証での受け入れ観点除外機能 - TASK-ID検証パターンの改善 - 一般的な単語の除外リスト追加 ### 中期改善（今後数ヶ月） - プロンプトテンプレートの見直し - 言語検出アルゴリズムの改善 - 設定による検証レベル調整機能 ### 長期改善（将来的検討） - AI支援による情報充足性判定 - ユーザー学習による最適化 - 高度なコンテキスト解析機能 ## 新機能に関する追加課題 ### 5. prompt-code機能の問題 #### 5.1 実装ガイドラインの実効性不足 **問題**: prompt-code機能で生成される実装ガイドラインが詳細だが、実際の開発時に無視される傾向がある **再現方法**: ```bash uv run wassden prompt-code ``` **結果**: - 品質レビュー手順が明示されるが、実際に実行されない - リンターエラーを「適切」と判断して修正を回避する - 必須手順（tasks.mdのチェックマーク追加）が実行されない **改善案**: - 実装ガイドラインの強制力強化 - 品質ゲートの自動化検討 - プロンプトの簡潔化と重要部分の強調 #### 5.2 品質基準の曖昧性 **問題**: 「統計実装として適切」など主観的判断でリンターエラーを容認する **再現方法**: 統計計算実装時のTRY003、PLR2004エラーの処理過程を確認 **改善案**: - 品質基準の客観的指標化 - 例外許可の明文化とその条件 - レビュープロンプトでの判定基準明確化 #### 5.3 agentのコール判断 **問題**: タスク開始時にprompt_codeではなく、generate_review_promptがよばれる **再現方法**: タスクを再開させる **改善案**: - 不明。提案求む ### 6. generate-review-prompt機能の問題 #### 6.1 品質ガードレールの実効性不足 **問題**: レビュープロンプトで厳格なチェック項目を提示するが、実際に守られない **再現方法**: ```bash uv run wassden generate-review-prompt TASK-01-03 ``` **結果**: - 「全項目PASS」が要求されるが、リンターエラーを容認して合格判定 - tasks.mdのチェックマーク追加が実行されない - 品質基準違反を「実装として適切」で正当化 **改善案**: - レビュー合格条件の厳格化 - 自動チェック機能の追加 - 段階的品質ゲートの導入 #### 6.2 完了手順の遵守不足 **問題**: レビュープロンプトで「tasks.mdにチェックマーク✅を追加」と明示されるが実行されない **再現方法**: TASK-01-03完了時の手順確認 **改善案**: - 完了手順のチェックリスト化 - 自動化可能な手順の特定 - 手順遵守状況のトラッキング機能 ## 改善された点 ### 実装後の振り返りと品質確認 **良い点**: 実装完了後の振り返りが非常に丁寧で品質が高い **具体的な良い例**: - リンターやテストの実行結果を明確に提示 - 設計仕様に対応した実装済みコンポーネントの明確な整理 - 受け入れ観点の達成状況の詳細な確認 - 次のタスクへの明確な移行準備 **活用価値**: - レビュアーが実装状況を迅速に把握可能 - 品質確認の透明性が高い - 実装の完了度が客観的に判断できる ## まとめ 今回のdogfoodingにより、wassdenの実用性と問題点が明確になった。特にEARS検証機能の高い有効性と、検証ロジックの過度な厳格さという課題が浮き彫りになった。 **新機能（prompt-code、generate-review-prompt）については**: - 機能自体の設計は優秀だが、実行時の品質管理に課題 - リンターエラー容認など、品質基準の主観的解釈が問題 - 完了手順の遵守不足が開発プロセスの品質を低下させる **改善の方向性**: - 品質基準の客観化と自動化 - 必須手順の強制実行メカニズム - レビュープロンプトの実効性向上 これらの知見を基に、より実用的で使いやすいツールとして改善を進める。 dogfooding自体は非常に有効なアプローチであり、今後も新機能追加時には積極的に実施すべきである。 --- コメントメモ: - tasks.mdのタスク順序について: ユニットテストは実装フェーズの各機能追加時点でやったほうがよさそう。テストフェーズでやるなら結合テストだけがよさそう。2度手間になっている - テストケースを緩和させてしまうことが散見される。テストに対する受け入れ基準を具体的にしたほうがいいかも。あとでテストケースを緩和されないためにはどうすればいい？？？reviewで気付けるか？？？？ - generate_review_prompt: TODO, FIXMEだけじゃなく、ignoreも検知した方がよさそう - generate_review_prompt: よびだすときに引数毎回間違ってる - 実装コード上に、REQ IDやTR IDを書いている。これは消してほしいが、reviewの邪魔か？review後に消させる？