first commit
This commit is contained in:
Hermes Agent
@@ -0,0 +1,60 @@
|
||||
# Bug-Fix PRD Pattern
|
||||
|
||||
Bug-fix PRDs are shorter than feature PRDs. Use this structure:
|
||||
|
||||
```markdown
|
||||
# {问题简述}
|
||||
|
||||
> **版本**: v1.0
|
||||
> **日期**: {date}
|
||||
> **状态**: ✅ 已修复 / 📝 待评审
|
||||
|
||||
---
|
||||
|
||||
## 一、问题描述
|
||||
### 1.1 现象
|
||||
### 1.2 复现步骤（编号列表）
|
||||
### 1.3 影响范围
|
||||
|
||||
## 二、根因分析
|
||||
### 2.1 技术细节（贴相关代码片段）
|
||||
### 2.2 问题根因（加粗说明核心原因）
|
||||
|
||||
## 三、解决方案
|
||||
### 3.1 方案对比（表格：方案/实现复杂度/优缺点/推荐度）
|
||||
### 3.2 推荐方案（代码示例）
|
||||
|
||||
## 四、实现细节
|
||||
### 4.1 修改文件
|
||||
### 4.2 具体改动（diff 或代码块）
|
||||
### 4.3 边界情况
|
||||
|
||||
## 五、测试验证
|
||||
### 5.1 测试用例（表格：编号/步骤/预期结果）
|
||||
|
||||
## 六、风险与注意事项
|
||||
|
||||
## 附录
|
||||
### A. 相关文件
|
||||
### B. 参考资料
|
||||
```
|
||||
|
||||
## Key Differences from Feature PRDs
|
||||
|
||||
| Aspect | Feature PRD | Bug-Fix PRD |
|
||||
|--------|-------------|-------------|
|
||||
| User Stories | ✅ Required | ❌ Skip |
|
||||
| Data Model | ✅ Required | ❌ Skip (unless bug is data-related) |
|
||||
| API Design | ✅ Required | ❌ Skip (unless bug is API-related) |
|
||||
| Competitor Analysis | ✅ Required | ❌ Skip |
|
||||
| Root Cause Analysis | Optional | ✅ Critical |
|
||||
| Fix Options Comparison | Optional | ✅ Required |
|
||||
| Regression Test Plan | Optional | ✅ Required |
|
||||
|
||||
## Example
|
||||
|
||||
See `prd-blog-toc-scroll-fix.md` in ephron-ren-qa repo for a real example:
|
||||
- Problem: TOC anchor links scrolled behind fixed navbar
|
||||
- Root cause: `scroll-margin-top` not set on headings
|
||||
- Fix: CSS `scroll-margin-top: 80px`
|
||||
- Testing: 5 test cases covering H2, H3, address bar, rapid clicks
|
||||
@@ -0,0 +1,53 @@
|
||||
# Example: Prompt Service PRD (调用测试 + 集合)
|
||||
|
||||
> This is a real PRD produced for prompt.ephron.ren. It demonstrates the full workflow: codebase analysis → draft → interactive decisions → finalization.
|
||||
|
||||
## Project Context
|
||||
|
||||
- **Tech Stack**: FastAPI + Jinja2 templates + SQLite + vanilla JS
|
||||
- **Design System**: Dark theme, Inter/JetBrains Mono, CSS custom properties
|
||||
- **CSP Policy**: `connect-src 'self'; script-src 'self' 'unsafe-inline'`
|
||||
- **Auth**: Shared `ephron_auth` Cookie across sub-services
|
||||
- **Existing API**: 7 endpoints (public list/detail + service CRUD)
|
||||
|
||||
## Codebase Analysis Approach
|
||||
|
||||
1. `find` to enumerate all files in the prompt service
|
||||
2. Read `src/main.py` → FastAPI app with 4 routers (pages, api, admin, service_api)
|
||||
3. Read `src/services/db.py` → `prompts` + `prompt_versions` tables
|
||||
4. Read `src/services/prompts.py` → full CRUD with version management
|
||||
5. Read `src/routes/api.py` → public API with PromptResponse schema
|
||||
6. Read `src/routes/service_api.py` → service token auth pattern
|
||||
7. Read `src/routes/admin.py` → admin CRUD with CSRF, audit logging
|
||||
8. Read `templates/public/detail.html` → current detail page (view + copy only)
|
||||
9. Read `templates/public/index.html` → grid layout with filter bar
|
||||
10. Read `src/config.py` → env-based config, shared DB path
|
||||
11. Read `prompt-api-spec/api-specification.md` → existing API spec to extend
|
||||
12. Checked `shared/` directory for reusable utilities
|
||||
|
||||
## Decisions Collected (7 items)
|
||||
|
||||
| # | Decision | User's Choice | Notes |
|
||||
|---|----------|---------------|-------|
|
||||
| 1 | LLM Provider | Direct Anthropic API | Admin settings page for model config |
|
||||
| 2 | API Key storage | .env | Model params in DB + admin UI |
|
||||
| 3 | Streaming | SSE | Simple, FastAPI native support |
|
||||
| 4 | Markdown rendering | Frontend (marked.js) | Less server overhead |
|
||||
| 5 | Login required | Yes | Rate limiting + audit |
|
||||
| 6 | Multi-collection membership | Yes | UNIQUE(collection_key, prompt_key) |
|
||||
| 7 | Collection ordering | Manual (sort_order) | Author controls flow |
|
||||
|
||||
## Workflow Notes
|
||||
|
||||
- User preferred decision questions asked ONE AT A TIME (not all at once)
|
||||
- User asked for recommendations before answering — always include your pick
|
||||
- PRD was saved to `prompt-api-spec/prd-test-and-collections.md` (project-relative)
|
||||
- `clarify` tool was not available in this execution context — fell back to direct Q&A
|
||||
|
||||
## Output Stats
|
||||
|
||||
- ~24KB markdown document
|
||||
- 7 tables (data model, API spec, decision record, risk matrix, etc.)
|
||||
- 2 new SQL tables proposed (collections, collection_items)
|
||||
- 6 new API endpoints proposed
|
||||
- 5.5 day estimated implementation
|
||||
@@ -0,0 +1,44 @@
|
||||
# Example: LLM Multi-Provider Config Refactoring PRD
|
||||
|
||||
This PRD demonstrates the pattern for refactoring a single-config settings page into a multi-profile/multi-provider management system. Useful as a reference for similar settings refactoring tasks.
|
||||
|
||||
## Key Design Patterns
|
||||
|
||||
### 1. Profile-based storage without new tables
|
||||
Store multiple config profiles as a JSON array in existing key-value settings table. One key for the profiles array, one key for the active profile ID.
|
||||
|
||||
```
|
||||
settings.active_profile_id → "prof_xxx"
|
||||
settings.profiles → '[{...}, {...}]'
|
||||
```
|
||||
|
||||
### 2. Protocol/behavior follows the item, not the group
|
||||
When a group (provider) can contain items with different behaviors (protocols), put the behavior field on the item level, not the group level. This allows mixing.
|
||||
|
||||
### 3. Global defaults with optional per-profile overrides
|
||||
Keep common parameters (temperature, timeout, etc.) at the global level. Profiles can optionally override, but empty = use global. This reduces config complexity.
|
||||
|
||||
### 4. Migration from old format
|
||||
Detect old keys → convert to new JSON format → delete old keys. Make migration idempotent (INSERT OR IGNORE pattern).
|
||||
|
||||
### 5. Isolate backend changes
|
||||
Refactor the config reader's return format to match what the caller expects. This way downstream consumers (LLM call layer, rate limiter) need zero changes.
|
||||
|
||||
## PRD Structure for Settings Refactoring
|
||||
|
||||
1. Background: current state table + missing capabilities table
|
||||
2. User stories focused on the switching/management pain point
|
||||
3. ASCII wireframe of new UI layout
|
||||
4. API design with JSON payload (not flat form fields for complex nested data)
|
||||
5. Data model: JSON in existing table + migration script
|
||||
6. Security & limits table
|
||||
7. Architecture change diagram (before/after)
|
||||
8. File change inventory with impact level (不动/小/中/大)
|
||||
9. Decision record table
|
||||
10. Risk table
|
||||
|
||||
## Pitfalls Found During This Session
|
||||
|
||||
- Don't make parameters per-profile by default — most users don't need it, adds UI complexity
|
||||
- Test connection endpoint should be AJAX, not form submit, for better UX
|
||||
- Migration must handle the case where both old and new keys exist (already migrated)
|
||||
@@ -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)
|
||||
Reference in New Issue
Block a user