first commit

software-development/prd-writing/references/prd-review-example.md

@@ -0,0 +1,64 @@
+# PRD Review Example: Prompt Service Test & Collections
+
+This is a real review output from a PRD for adding "prompt testing" and "collections" features to a prompt management service. Use as a reference for review structure and common findings.
+
+## Review Structure
+
+```markdown
+## 评审意见
+
+**🔴 必须修改（N 项）**
+1. **{issue title}** — {why critical, with concrete fix}
+
+**🟡 建议修改（N 项）**
+N. {issue} — {impact and suggestion}
+
+**整体结论**：🟢/🟡/🔴 — {one-line summary}
+```
+
+## Common Findings from This Review
+
+### 🔴 1. Missing Table Definitions
+**Issue**: Decision record says "模型配置放数据库 settings 表" but no `settings` schema was provided.
+**Fix**: Add CREATE TABLE statement + initial data rows.
+**Pattern**: When a PRD references a table by name, verify the DDL exists in the data model section.
+
+### 🔴 2. Display Value → Identifier Mapping Gap
+**Issue**: DB stores `recommended_model = "Claude"` but API call needs `claude-sonnet-4-20250514`. No mapping defined.
+**Fix**: Add explicit mapping table.
+**Pattern**: Any time user-facing labels differ from system identifiers, check for a mapping definition.
+
+### 🔴 3. Placeholder Syntax Undefined
+**Issue**: Template variables use `{{var}}` in some places, `「text」` in others. No convention documented.
+**Fix**: Define syntax explicitly (e.g., `{{变量名}}`), add migration requirements for existing content.
+**Pattern**: Template/variable systems need explicit syntax documentation.
+
+### 🟡 4. SSE Error Events Missing
+**Issue**: SSE protocol defines `start`, `delta`, `done` but no `error` event type.
+**Fix**: Add `error` event with `detail` and `code` fields; document client disconnect handling.
+
+### 🟡 5. Code Examples Contradict Decisions
+**Issue**: Decision says "Anthropic only" but code shows 3 providers (anthropic, openai, deepseek).
+**Fix**: Align code with decision, add comment for future extension.
+
+### 🟡 6. Injection Risk Not Addressed
+**Issue**: User input reaches LLM prompt without sanitization or boundary markers.
+**Fix**: Add `<user_input>` wrapper, system message boundary, anomaly logging.
+
+### 🟡 7. Cost Estimation Missing
+**Issue**: Feature calls paid LLM API but no cost analysis.
+**Fix**: Estimate per-call cost × rate limits × expected usage frequency.
+
+### 🟡 8. Timeline Too Optimistic
+**Issue**: 5.5 days for single full-stack dev, no buffer for integration testing.
+**Fix**: Adjust to 7-8 days with explicit buffer phase.
+
+## PRD Update Workflow
+
+After review, update the PRD:
+1. Read full document (don't work from memory)
+2. Fix all 🔴 issues first
+3. Fix 🟡 issues
+4. Update version (v1.0 → v1.1) and status (📝 → ✅)
+5. Commit and push
+6. Report summary of changes (not full diff)