mirror of
https://github.com/cexll/myclaude.git
synced 2026-02-14 03:31:58 +08:00
Add requirements-clarity Claude Skill
- Create .claude/skills/requirements-clarity/SKILL.md (571 lines) - Automatic activation for vague requirements - 100-point scoring system (功能清晰度/技术具体性/实现完整性/业务背景) - Interactive Q&A clarification process - PRD generation with 需求描述/设计决策/验收标准/执行Phase structure - Bilingual support (Chinese headers + mixed content) - Create comprehensive README with testing guide and examples - Update .gitignore to allow .claude/skills/ directory Implements Issue #17 - Transform /clarif command into proactive Claude Skill for automatic requirements clarification. Generated by swe-agent
This commit is contained in:
swe-agent[bot]
310
.claude/skills/requirements-clarity/README.md
Normal file
310
.claude/skills/requirements-clarity/README.md
Normal file
@@ -0,0 +1,310 @@
|
|||||||
|
# Requirements Clarity Skill
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
This Claude Skill automatically detects vague requirements and transforms them into crystal-clear Product Requirements Documents (PRDs) through systematic clarification.
|
||||||
|
|
||||||
|
**Key Difference from `/clarif` Command**:
|
||||||
|
- **Command**: User must type `/clarif <requirement>` explicitly
|
||||||
|
- **Skill**: Claude automatically detects unclear requirements and activates clarification mode
|
||||||
|
|
||||||
|
## How It Works
|
||||||
|
|
||||||
|
### Automatic Activation
|
||||||
|
|
||||||
|
The skill activates when Claude detects:
|
||||||
|
|
||||||
|
1. **Vague Feature Requests**
|
||||||
|
```
|
||||||
|
User: "add login feature"
|
||||||
|
User: "implement payment system"
|
||||||
|
User: "create user dashboard"
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Missing Technical Details**
|
||||||
|
- No technology stack mentioned
|
||||||
|
- No architecture or constraints specified
|
||||||
|
- No integration points identified
|
||||||
|
|
||||||
|
3. **Incomplete Specifications**
|
||||||
|
- No acceptance criteria
|
||||||
|
- No success metrics
|
||||||
|
- No edge cases or error handling
|
||||||
|
|
||||||
|
4. **Ambiguous Scope**
|
||||||
|
- Unclear boundaries ("user management" - what exactly?)
|
||||||
|
- No distinction between MVP and future features
|
||||||
|
|
||||||
|
### Clarification Process
|
||||||
|
|
||||||
|
```
|
||||||
|
User: "我要做一个用户登录功能"
|
||||||
|
↓
|
||||||
|
Claude detects vague requirement
|
||||||
|
↓
|
||||||
|
Auto-activates requirements-clarity skill
|
||||||
|
↓
|
||||||
|
Initial assessment: 35/100 clarity score
|
||||||
|
↓
|
||||||
|
Round 1: Ask 2-3 targeted questions
|
||||||
|
↓
|
||||||
|
User responds
|
||||||
|
↓
|
||||||
|
Score update: 35 → 72
|
||||||
|
↓
|
||||||
|
Round 2: Continue clarifying gaps
|
||||||
|
↓
|
||||||
|
User responds
|
||||||
|
↓
|
||||||
|
Score update: 72 → 93 ✓ (≥90 threshold)
|
||||||
|
↓
|
||||||
|
Generate PRD files:
|
||||||
|
- ./.claude/specs/user-login/prd.md
|
||||||
|
- ./.claude/specs/user-login/clarification-log.md
|
||||||
|
```
|
||||||
|
|
||||||
|
## Scoring System (100 points)
|
||||||
|
|
||||||
|
| Dimension | Points | Criteria |
|
||||||
|
|-----------|--------|----------|
|
||||||
|
| **功能清晰度** (Functional Clarity) | 30 | Clear inputs/outputs (10), User interaction (10), Success criteria (10) |
|
||||||
|
| **技术具体性** (Technical Specificity) | 25 | Tech stack (8), Integration points (8), Constraints (9) |
|
||||||
|
| **实现完整性** (Implementation Completeness) | 25 | Edge cases (8), Error handling (9), Data validation (8) |
|
||||||
|
| **业务背景** (Business Context) | 20 | Problem statement (7), Target users (7), Success metrics (6) |
|
||||||
|
|
||||||
|
**Threshold**: ≥ 90 points required before PRD generation
|
||||||
|
|
||||||
|
## Output Structure
|
||||||
|
|
||||||
|
### 1. Clarification Log
|
||||||
|
`./.claude/specs/{feature-name}/clarification-log.md`
|
||||||
|
|
||||||
|
Documents the entire clarification conversation:
|
||||||
|
- Original requirement
|
||||||
|
- Each round of questions and answers
|
||||||
|
- Score progression
|
||||||
|
- Final assessment breakdown
|
||||||
|
|
||||||
|
### 2. Product Requirements Document
|
||||||
|
`./.claude/specs/{feature-name}/prd.md`
|
||||||
|
|
||||||
|
Structured PRD with four main sections:
|
||||||
|
|
||||||
|
#### 需求描述 (Requirements Description)
|
||||||
|
- 背景 (Background): Business problem, target users, value proposition
|
||||||
|
- 功能概述 (Feature Overview): Core functionality, boundaries, user scenarios
|
||||||
|
- 详细需求 (Detailed Requirements): Inputs/outputs, interactions, data, edge cases
|
||||||
|
|
||||||
|
#### 设计决策 (Design Decisions)
|
||||||
|
- 技术方案 (Technical Approach): Architecture, components, data storage, APIs
|
||||||
|
- 约束条件 (Constraints): Performance, compatibility, security, scalability
|
||||||
|
- 风险评估 (Risk Assessment): Technical, dependency, timeline risks
|
||||||
|
|
||||||
|
#### 验收标准 (Acceptance Criteria)
|
||||||
|
- 功能验收 (Functional): Checklistable feature requirements
|
||||||
|
- 质量标准 (Quality): Code quality, testing, performance, security
|
||||||
|
- 用户验收 (User): UX, documentation, training
|
||||||
|
|
||||||
|
#### 执行 Phase (Execution Phases)
|
||||||
|
- Phase 1: 准备阶段 (Preparation) - Environment setup
|
||||||
|
- Phase 2: 核心开发 (Core Development) - Core implementation
|
||||||
|
- Phase 3: 集成测试 (Integration & Testing) - QA
|
||||||
|
- Phase 4: 部署上线 (Deployment) - Release
|
||||||
|
|
||||||
|
## Testing Guide
|
||||||
|
|
||||||
|
### Test Case 1: Vague Login Feature
|
||||||
|
|
||||||
|
**Input**:
|
||||||
|
```
|
||||||
|
"我要做一个用户登录功能"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Expected Behavior**:
|
||||||
|
1. Claude detects vague requirement
|
||||||
|
2. Announces activation of requirements-clarity skill
|
||||||
|
3. Shows initial score (~30-40/100)
|
||||||
|
4. Asks 2-3 questions about:
|
||||||
|
- Login method (username+password, phone+OTP, OAuth?)
|
||||||
|
- Functional scope (remember me, forgot password?)
|
||||||
|
- Technology stack (backend language, database, auth method?)
|
||||||
|
|
||||||
|
**Expected Output**:
|
||||||
|
- Score improves to ~70+ after round 1
|
||||||
|
- Additional questions about security, error handling, performance
|
||||||
|
- Final score ≥ 90
|
||||||
|
- PRD generated in `./.claude/specs/user-login/`
|
||||||
|
|
||||||
|
### Test Case 2: Ambiguous E-commerce Feature
|
||||||
|
|
||||||
|
**Input**:
|
||||||
|
```
|
||||||
|
"add shopping cart to the website"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Expected Behavior**:
|
||||||
|
1. Auto-activation (no tech stack, no UX details, no constraints)
|
||||||
|
2. Questions about:
|
||||||
|
- Cart behavior (guest checkout? save for later? quantity limits?)
|
||||||
|
- User experience (inline cart vs dedicated page?)
|
||||||
|
- Backend integration (existing inventory system? payment gateway?)
|
||||||
|
- Data persistence (session storage, database, local storage?)
|
||||||
|
|
||||||
|
**Expected Output**:
|
||||||
|
- Iterative clarification (2-3 rounds)
|
||||||
|
- Score progression: ~25 → ~65 → ~92
|
||||||
|
- PRD with concrete shopping cart specifications
|
||||||
|
|
||||||
|
### Test Case 3: Technical Implementation Request
|
||||||
|
|
||||||
|
**Input**:
|
||||||
|
```
|
||||||
|
"Refactor the authentication service to use JWT tokens"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Expected Behavior**:
|
||||||
|
1. May NOT activate (already fairly specific)
|
||||||
|
2. If activates, asks about:
|
||||||
|
- Token expiration strategy
|
||||||
|
- Refresh token implementation
|
||||||
|
- Migration plan from existing auth
|
||||||
|
- Backward compatibility requirements
|
||||||
|
|
||||||
|
### Test Case 4: Clear Requirement (Should NOT Activate)
|
||||||
|
|
||||||
|
**Input**:
|
||||||
|
```
|
||||||
|
"Fix the null pointer exception in auth.go line 45 by adding a nil check before accessing user.Email"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Expected Behavior**:
|
||||||
|
- Skill does NOT activate (requirement is already clear)
|
||||||
|
- Claude proceeds directly to implementation
|
||||||
|
|
||||||
|
## Comparison: Command vs Skill
|
||||||
|
|
||||||
|
| Aspect | `/clarif` Command | Requirements-Clarity Skill |
|
||||||
|
|--------|-------------------|----------------------------|
|
||||||
|
| **Activation** | Manual: `/clarif <requirement>` | Automatic: Claude detects vague specs |
|
||||||
|
| **User Awareness** | Must know command exists | Transparent, no learning curve |
|
||||||
|
| **Workflow** | User → Type command → Clarification | User → Express need → Auto-clarification |
|
||||||
|
| **Discoverability** | Requires documentation | Claude suggests when appropriate |
|
||||||
|
| **Use Case** | Explicit requirements review | Proactive quality gate |
|
||||||
|
| **File Location** | `commands/clarif.md` + `agents/clarif-agent.md` | `.claude/skills/requirements-clarity/SKILL.md` |
|
||||||
|
|
||||||
|
## Benefits of Skill Approach
|
||||||
|
|
||||||
|
1. **Proactive Quality Gate**: Prevents unclear specs from proceeding to implementation
|
||||||
|
2. **Zero Friction**: Users describe features naturally, no command syntax needed
|
||||||
|
3. **Context Awareness**: Claude recognizes ambiguity patterns automatically
|
||||||
|
4. **Persistent Mode**: Stays active throughout clarification conversation
|
||||||
|
5. **Better UX**: Natural conversation flow vs explicit command invocation
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
No configuration needed - the skill is automatically discovered by Claude Code when present in `.claude/skills/requirements-clarity/`.
|
||||||
|
|
||||||
|
**Skill Metadata** (in SKILL.md frontmatter):
|
||||||
|
```yaml
|
||||||
|
name: requirements-clarity
|
||||||
|
description: Automatically clarify vague requirements into actionable PRDs
|
||||||
|
activation_triggers:
|
||||||
|
- User describes feature without technical details
|
||||||
|
- Request lacks acceptance criteria
|
||||||
|
- Scope is ambiguous
|
||||||
|
- Missing technology stack
|
||||||
|
tools: Read, Write, Glob, Grep, TodoWrite
|
||||||
|
```
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Skill Not Activating
|
||||||
|
|
||||||
|
**Problem**: Claude doesn't enter clarification mode for vague requirements
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
1. Verify `.claude/skills/requirements-clarity/SKILL.md` exists
|
||||||
|
2. Check YAML frontmatter is valid
|
||||||
|
3. Ensure activation_triggers are defined
|
||||||
|
4. Try more explicit vague requirement: "add user feature"
|
||||||
|
|
||||||
|
### Premature PRD Generation
|
||||||
|
|
||||||
|
**Problem**: PRD generated before score reaches 90
|
||||||
|
|
||||||
|
**Solution**: This is a bug - SKILL.md explicitly requires ≥90 threshold. Review the clarification log to see actual score.
|
||||||
|
|
||||||
|
### Over-Clarification
|
||||||
|
|
||||||
|
**Problem**: Claude asks too many questions for simple features
|
||||||
|
|
||||||
|
**Expected**: This is by design - better to over-clarify than under-specify. If the requirement is truly simple, answer questions quickly to reach 90+ score faster.
|
||||||
|
|
||||||
|
## Migration from `/clarif` Command
|
||||||
|
|
||||||
|
The `/clarif` command in `development-essentials/commands/clarif.md` can coexist with this skill:
|
||||||
|
|
||||||
|
- **Skill**: Automatic activation for new, unclear requirements
|
||||||
|
- **Command**: Explicit review of existing requirements
|
||||||
|
|
||||||
|
**Recommended Workflow**:
|
||||||
|
1. User describes feature naturally
|
||||||
|
2. Skill auto-activates and generates PRD
|
||||||
|
3. (Optional) User runs `/clarif <existing-prd>` to review/refine
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
### Example 1: Login Feature (Full Flow)
|
||||||
|
|
||||||
|
See full example in SKILL.md under "Example Clarification Flow"
|
||||||
|
|
||||||
|
**Summary**:
|
||||||
|
- Input: "我要做一个用户登录功能"
|
||||||
|
- Round 1: Login method, scope, tech stack → Score 35→72
|
||||||
|
- Round 2: Security, error handling, performance → Score 72→93
|
||||||
|
- Output: Complete PRD with bcrypt, JWT, PostgreSQL, Go backend
|
||||||
|
|
||||||
|
### Example 2: API Endpoint
|
||||||
|
|
||||||
|
**Input**: "create an API to get user profile"
|
||||||
|
|
||||||
|
**Round 1** (Score: 28/100):
|
||||||
|
```
|
||||||
|
Q1: What information should the API return? (name, email, avatar, preferences?)
|
||||||
|
Q2: Authentication required? (JWT, session, API key?)
|
||||||
|
Q3: Response format? (JSON, XML?) Any pagination?
|
||||||
|
```
|
||||||
|
|
||||||
|
**Round 2** (Score: 75/100):
|
||||||
|
```
|
||||||
|
Q1: Error handling: What if user not found? (404, custom error?)
|
||||||
|
Q2: Performance: Caching strategy? Expected QPS?
|
||||||
|
Q3: Privacy: Any fields that should be filtered based on requester?
|
||||||
|
```
|
||||||
|
|
||||||
|
**Round 3** (Score: 91/100):
|
||||||
|
```
|
||||||
|
PRD Generated:
|
||||||
|
- Endpoint: GET /api/v1/users/:id
|
||||||
|
- Auth: JWT required
|
||||||
|
- Response: JSON with name, email, avatar, bio
|
||||||
|
- Caching: Redis, 5min TTL
|
||||||
|
- Rate limit: 100 req/min per user
|
||||||
|
```
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
- **Claude Skills Documentation**: https://docs.claude.com/en/docs/claude-code/skills
|
||||||
|
- **Anthropic Skills Announcement**: https://www.anthropic.com/news/skills
|
||||||
|
- **Original `/clarif` Command**: `development-essentials/commands/clarif.md`
|
||||||
|
- **Original Clarification Agent**: `development-essentials/agents/clarif-agent.md`
|
||||||
|
|
||||||
|
## Changelog
|
||||||
|
|
||||||
|
### v1.0 (2025-10-20)
|
||||||
|
- Initial skill implementation
|
||||||
|
- Ported clarification logic from `/clarif` command
|
||||||
|
- Added automatic activation triggers
|
||||||
|
- Implemented 100-point scoring system
|
||||||
|
- Created bilingual PRD template (需求描述/设计决策/验收标准/执行Phase)
|
||||||
|
- Added comprehensive test cases and examples
|
||||||
522
.claude/skills/requirements-clarity/SKILL.md
Normal file
522
.claude/skills/requirements-clarity/SKILL.md
Normal file
@@ -0,0 +1,522 @@
|
|||||||
|
---
|
||||||
|
name: requirements-clarity
|
||||||
|
description: Automatically detect vague requirements and transform them into crystal-clear Product Requirements Documents (PRDs) through systematic clarification
|
||||||
|
activation_triggers:
|
||||||
|
- User describes a feature without technical details
|
||||||
|
- Request lacks acceptance criteria or success metrics
|
||||||
|
- Scope is ambiguous (e.g., "add authentication", "implement user management")
|
||||||
|
- Missing technology stack or implementation constraints
|
||||||
|
- No edge cases or error handling mentioned
|
||||||
|
- Vague action verbs without specifics ("add", "create", "improve", "fix")
|
||||||
|
tools: Read, Write, Glob, Grep, TodoWrite
|
||||||
|
---
|
||||||
|
|
||||||
|
# Requirements Clarity Skill
|
||||||
|
|
||||||
|
## When to Activate
|
||||||
|
|
||||||
|
This skill should automatically activate when Claude detects:
|
||||||
|
|
||||||
|
1. **Vague Feature Requests**
|
||||||
|
- User says: "add login feature", "implement payment", "create dashboard"
|
||||||
|
- Missing: How, with what technology, what constraints?
|
||||||
|
|
||||||
|
2. **Missing Technical Context**
|
||||||
|
- No technology stack mentioned
|
||||||
|
- No integration points identified
|
||||||
|
- No performance/security constraints
|
||||||
|
|
||||||
|
3. **Incomplete Specifications**
|
||||||
|
- No acceptance criteria
|
||||||
|
- No success metrics
|
||||||
|
- No edge cases considered
|
||||||
|
- No error handling mentioned
|
||||||
|
|
||||||
|
4. **Ambiguous Scope**
|
||||||
|
- Unclear boundaries ("user management" - what exactly?)
|
||||||
|
- No distinction between MVP and future enhancements
|
||||||
|
- Missing "what's NOT included"
|
||||||
|
|
||||||
|
## Skill Behavior
|
||||||
|
|
||||||
|
Upon activation, this skill transforms vague requirements into actionable PRDs through systematic clarification.
|
||||||
|
|
||||||
|
### Core Principles
|
||||||
|
|
||||||
|
1. **Systematic Questioning**
|
||||||
|
- Ask focused, specific questions
|
||||||
|
- One category at a time (2-3 questions per round)
|
||||||
|
- Build on previous answers
|
||||||
|
- Avoid overwhelming users
|
||||||
|
|
||||||
|
2. **Quality-Driven Iteration**
|
||||||
|
- Continuously assess clarity score (0-100)
|
||||||
|
- Identify gaps systematically
|
||||||
|
- Iterate until ≥ 90 points
|
||||||
|
- Document all clarification rounds
|
||||||
|
|
||||||
|
3. **Actionable Output**
|
||||||
|
- Generate concrete specifications
|
||||||
|
- Include measurable acceptance criteria
|
||||||
|
- Provide executable phases
|
||||||
|
- Enable direct implementation
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Clarification Process
|
||||||
|
|
||||||
|
### Step 1: Initial Requirement Analysis
|
||||||
|
|
||||||
|
**Input**: User's requirement description
|
||||||
|
|
||||||
|
**Tasks**:
|
||||||
|
1. Parse and understand core requirement
|
||||||
|
2. Generate feature name (kebab-case format)
|
||||||
|
3. Create output directory: `./.claude/specs/{feature_name}/`
|
||||||
|
4. Perform initial clarity assessment (0-100)
|
||||||
|
|
||||||
|
**Assessment Rubric**:
|
||||||
|
```
|
||||||
|
功能清晰度 (Functional Clarity): /30 points
|
||||||
|
- Clear inputs/outputs: 10 pts
|
||||||
|
- User interaction defined: 10 pts
|
||||||
|
- Success criteria stated: 10 pts
|
||||||
|
|
||||||
|
技术具体性 (Technical Specificity): /25 points
|
||||||
|
- Technology stack mentioned: 8 pts
|
||||||
|
- Integration points identified: 8 pts
|
||||||
|
- Constraints specified: 9 pts
|
||||||
|
|
||||||
|
实现完整性 (Implementation Completeness): /25 points
|
||||||
|
- Edge cases considered: 8 pts
|
||||||
|
- Error handling mentioned: 9 pts
|
||||||
|
- Data validation specified: 8 pts
|
||||||
|
|
||||||
|
业务背景 (Business Context): /20 points
|
||||||
|
- Problem statement clear: 7 pts
|
||||||
|
- Target users identified: 7 pts
|
||||||
|
- Success metrics defined: 6 pts
|
||||||
|
```
|
||||||
|
|
||||||
|
**Initial Response Format**:
|
||||||
|
```markdown
|
||||||
|
我已经理解您的需求。让我帮您完善这个需求规格。
|
||||||
|
|
||||||
|
**当前清晰度评分**: X/100
|
||||||
|
|
||||||
|
**已明确的部分**:
|
||||||
|
- [List what's clear]
|
||||||
|
|
||||||
|
**需要澄清的部分**:
|
||||||
|
- [List gaps]
|
||||||
|
|
||||||
|
让我开始系统性地澄清这些内容...
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2: Gap Analysis
|
||||||
|
|
||||||
|
Identify missing information across four dimensions:
|
||||||
|
|
||||||
|
**1. 功能范围 (Functional Scope)**
|
||||||
|
- What is the core functionality?
|
||||||
|
- What are the boundaries?
|
||||||
|
- What is out of scope?
|
||||||
|
- What are edge cases?
|
||||||
|
|
||||||
|
**2. 用户交互 (User Interaction)**
|
||||||
|
- How do users interact?
|
||||||
|
- What are the inputs?
|
||||||
|
- What are the outputs?
|
||||||
|
- What are success/failure scenarios?
|
||||||
|
|
||||||
|
**3. 技术约束 (Technical Constraints)**
|
||||||
|
- Performance requirements?
|
||||||
|
- Compatibility requirements?
|
||||||
|
- Security considerations?
|
||||||
|
- Scalability needs?
|
||||||
|
|
||||||
|
**4. 业务价值 (Business Value)**
|
||||||
|
- What problem does this solve?
|
||||||
|
- Who are the target users?
|
||||||
|
- What are success metrics?
|
||||||
|
- What is the priority?
|
||||||
|
|
||||||
|
### Step 3: Interactive Clarification
|
||||||
|
|
||||||
|
**Question Strategy**:
|
||||||
|
1. Start with highest-impact gaps
|
||||||
|
2. Ask 2-3 questions per round
|
||||||
|
3. Build context progressively
|
||||||
|
4. Use user's language
|
||||||
|
5. Provide examples when helpful
|
||||||
|
|
||||||
|
**Question Format**:
|
||||||
|
```markdown
|
||||||
|
我需要澄清以下几点以完善需求文档:
|
||||||
|
|
||||||
|
1. **[Category]**: [Specific question]?
|
||||||
|
- 例如: [Example if helpful]
|
||||||
|
|
||||||
|
2. **[Category]**: [Specific question]?
|
||||||
|
|
||||||
|
3. **[Category]**: [Specific question]?
|
||||||
|
|
||||||
|
请提供您的答案,我会基于此继续完善 PRD。
|
||||||
|
```
|
||||||
|
|
||||||
|
**After Each User Response**:
|
||||||
|
1. Update clarity score
|
||||||
|
2. Document new information in clarification log
|
||||||
|
3. Identify remaining gaps
|
||||||
|
4. If score < 90: Continue with next round of questions
|
||||||
|
5. If score ≥ 90: Proceed to PRD generation
|
||||||
|
|
||||||
|
**Score Update Format**:
|
||||||
|
```markdown
|
||||||
|
感谢您的补充!
|
||||||
|
|
||||||
|
**清晰度评分更新**: X/100 → Y/100
|
||||||
|
|
||||||
|
**新增明确的内容**:
|
||||||
|
- [Summarize new information]
|
||||||
|
|
||||||
|
**剩余需要澄清的点**:
|
||||||
|
- [List remaining gaps if score < 90]
|
||||||
|
|
||||||
|
[If score < 90: Continue with next round of questions]
|
||||||
|
[If score ≥ 90: "完美! 我现在将生成完整的 PRD 文档..."]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 4: PRD Generation
|
||||||
|
|
||||||
|
Once clarity score ≥ 90, generate comprehensive PRD.
|
||||||
|
|
||||||
|
**Output Files**:
|
||||||
|
|
||||||
|
1. **Clarification Log**: `./.claude/specs/{feature_name}/clarification-log.md`
|
||||||
|
2. **Final PRD**: `./.claude/specs/{feature_name}/prd.md`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## PRD Document Structure
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# {Feature Name} - 产品需求文档 (PRD)
|
||||||
|
|
||||||
|
## 需求描述 (Requirements Description)
|
||||||
|
|
||||||
|
### 背景 (Background)
|
||||||
|
- **业务问题**: [描述要解决的业务问题]
|
||||||
|
- **目标用户**: [目标用户群体]
|
||||||
|
- **价值主张**: [此功能带来的价值]
|
||||||
|
|
||||||
|
### 功能概述 (Feature Overview)
|
||||||
|
- **核心功能**: [主要功能点列表]
|
||||||
|
- **功能边界**: [明确包含和不包含的内容]
|
||||||
|
- **用户场景**: [典型使用场景描述]
|
||||||
|
|
||||||
|
### 详细需求 (Detailed Requirements)
|
||||||
|
- **输入/输出**: [具体的输入输出规格]
|
||||||
|
- **用户交互**: [用户操作流程]
|
||||||
|
- **数据要求**: [数据结构和验证规则]
|
||||||
|
- **边界条件**: [边界情况处理]
|
||||||
|
|
||||||
|
## 设计决策 (Design Decisions)
|
||||||
|
|
||||||
|
### 技术方案 (Technical Approach)
|
||||||
|
- **架构选择**: [技术架构决策及理由]
|
||||||
|
- **关键组件**: [主要技术组件列表]
|
||||||
|
- **数据存储**: [数据模型和存储方案]
|
||||||
|
- **接口设计**: [API/接口规格]
|
||||||
|
|
||||||
|
### 约束条件 (Constraints)
|
||||||
|
- **性能要求**: [响应时间、吞吐量等]
|
||||||
|
- **兼容性**: [系统兼容性要求]
|
||||||
|
- **安全性**: [安全相关考虑]
|
||||||
|
- **可扩展性**: [未来扩展考虑]
|
||||||
|
|
||||||
|
### 风险评估 (Risk Assessment)
|
||||||
|
- **技术风险**: [潜在技术风险及缓解方案]
|
||||||
|
- **依赖风险**: [外部依赖及备选方案]
|
||||||
|
- **时间风险**: [进度风险及应对策略]
|
||||||
|
|
||||||
|
## 验收标准 (Acceptance Criteria)
|
||||||
|
|
||||||
|
### 功能验收 (Functional Acceptance)
|
||||||
|
- [ ] 功能点1: [具体验收条件]
|
||||||
|
- [ ] 功能点2: [具体验收条件]
|
||||||
|
- [ ] 功能点3: [具体验收条件]
|
||||||
|
|
||||||
|
### 质量标准 (Quality Standards)
|
||||||
|
- [ ] 代码质量: [代码规范和审查要求]
|
||||||
|
- [ ] 测试覆盖: [测试要求和覆盖率]
|
||||||
|
- [ ] 性能指标: [性能测试通过标准]
|
||||||
|
- [ ] 安全检查: [安全审查要求]
|
||||||
|
|
||||||
|
### 用户验收 (User Acceptance)
|
||||||
|
- [ ] 用户体验: [UX验收标准]
|
||||||
|
- [ ] 文档完整: [文档交付要求]
|
||||||
|
- [ ] 培训材料: [如需要,培训材料要求]
|
||||||
|
|
||||||
|
## 执行 Phase (Execution Phases)
|
||||||
|
|
||||||
|
### Phase 1: 准备阶段 (Preparation)
|
||||||
|
**目标**: 环境准备和技术验证
|
||||||
|
- [ ] 任务1: [具体任务描述]
|
||||||
|
- [ ] 任务2: [具体任务描述]
|
||||||
|
- **产出**: [阶段交付物]
|
||||||
|
- **时间**: [预估时间]
|
||||||
|
|
||||||
|
### Phase 2: 核心开发 (Core Development)
|
||||||
|
**目标**: 实现核心功能
|
||||||
|
- [ ] 任务1: [具体任务描述]
|
||||||
|
- [ ] 任务2: [具体任务描述]
|
||||||
|
- **产出**: [阶段交付物]
|
||||||
|
- **时间**: [预估时间]
|
||||||
|
|
||||||
|
### Phase 3: 集成测试 (Integration & Testing)
|
||||||
|
**目标**: 集成和质量保证
|
||||||
|
- [ ] 任务1: [具体任务描述]
|
||||||
|
- [ ] 任务2: [具体任务描述]
|
||||||
|
- **产出**: [阶段交付物]
|
||||||
|
- **时间**: [预估时间]
|
||||||
|
|
||||||
|
### Phase 4: 部署上线 (Deployment)
|
||||||
|
**目标**: 发布和监控
|
||||||
|
- [ ] 任务1: [具体任务描述]
|
||||||
|
- [ ] 任务2: [具体任务描述]
|
||||||
|
- **产出**: [阶段交付物]
|
||||||
|
- **时间**: [预估时间]
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**文档版本**: 1.0
|
||||||
|
**创建时间**: {timestamp}
|
||||||
|
**澄清轮数**: {clarification_rounds}
|
||||||
|
**质量评分**: {quality_score}/100
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Clarification Log Structure
|
||||||
|
|
||||||
|
`./.claude/specs/{feature_name}/clarification-log.md`
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Requirements Clarification Log
|
||||||
|
|
||||||
|
## Original Requirement
|
||||||
|
[User's initial input]
|
||||||
|
|
||||||
|
## Clarification Rounds
|
||||||
|
|
||||||
|
### Round 1 (Score: X/100)
|
||||||
|
**Questions**:
|
||||||
|
1. ...
|
||||||
|
2. ...
|
||||||
|
|
||||||
|
**User Responses**:
|
||||||
|
1. ...
|
||||||
|
2. ...
|
||||||
|
|
||||||
|
**Score Update**: X → Y points
|
||||||
|
|
||||||
|
**Gaps Addressed**:
|
||||||
|
- [List what became clear]
|
||||||
|
|
||||||
|
### Round 2 (Score: Y/100)
|
||||||
|
...
|
||||||
|
|
||||||
|
## Final Clarity Assessment
|
||||||
|
- 功能清晰度 (Functional Clarity): X/30
|
||||||
|
- 技术具体性 (Technical Specificity): X/25
|
||||||
|
- 实现完整性 (Implementation Completeness): X/25
|
||||||
|
- 业务背景 (Business Context): X/20
|
||||||
|
- **Total**: X/100 ✓
|
||||||
|
|
||||||
|
## Key Decisions Made
|
||||||
|
1. [Important decision 1]
|
||||||
|
2. [Important decision 2]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quality Assurance
|
||||||
|
|
||||||
|
### Before PRD Generation
|
||||||
|
- [ ] Clarity score ≥ 90 points
|
||||||
|
- [ ] All four dimensions addressed
|
||||||
|
- [ ] Functional requirements complete
|
||||||
|
- [ ] Technical constraints identified
|
||||||
|
- [ ] Acceptance criteria defined
|
||||||
|
- [ ] Execution phases concrete
|
||||||
|
|
||||||
|
### PRD Completeness Check
|
||||||
|
- [ ] All sections filled with substance
|
||||||
|
- [ ] Checkboxes for acceptance criteria
|
||||||
|
- [ ] Concrete tasks in each phase
|
||||||
|
- [ ] Time estimates provided
|
||||||
|
- [ ] Deliverables specified
|
||||||
|
- [ ] Quality score documented
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Behavioral Guidelines
|
||||||
|
|
||||||
|
### DO
|
||||||
|
- Ask specific, targeted questions
|
||||||
|
- Build on previous answers
|
||||||
|
- Provide examples to guide users
|
||||||
|
- Maintain conversational tone
|
||||||
|
- Document all clarification rounds
|
||||||
|
- Use Chinese for section headers
|
||||||
|
- Generate concrete specifications
|
||||||
|
- Stay in clarification mode until score ≥ 90
|
||||||
|
|
||||||
|
### DON'T
|
||||||
|
- Ask all questions at once
|
||||||
|
- Make assumptions without confirmation
|
||||||
|
- Generate PRD before 90+ score
|
||||||
|
- Skip any required sections
|
||||||
|
- Use vague or abstract language
|
||||||
|
- Proceed without user responses
|
||||||
|
- Exit skill mode prematurely
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Example Clarification Flow
|
||||||
|
|
||||||
|
```
|
||||||
|
User: "我要做一个用户登录功能"
|
||||||
|
|
||||||
|
Claude: (Detects vague requirement → Auto-activates requirements-clarity skill)
|
||||||
|
|
||||||
|
我已经理解您的需求。让我帮您完善这个登录功能的需求规格。
|
||||||
|
|
||||||
|
**当前清晰度评分**: 35/100
|
||||||
|
|
||||||
|
**已明确的部分**:
|
||||||
|
- 需要实现用户登录功能
|
||||||
|
|
||||||
|
**需要澄清的部分**:
|
||||||
|
- 登录方式和技术实现
|
||||||
|
- 功能边界和用户交互
|
||||||
|
- 安全性和性能要求
|
||||||
|
|
||||||
|
让我开始系统性地澄清这些内容:
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
我需要澄清以下几点以完善需求文档:
|
||||||
|
|
||||||
|
1. **用户交互**: 用户将通过什么方式登录?
|
||||||
|
- 例如: 用户名+密码, 手机号+验证码, 第三方OAuth (Google/GitHub)等
|
||||||
|
|
||||||
|
2. **功能范围**: 除了基本登录,是否需要:
|
||||||
|
- 记住登录状态 (Remember Me)?
|
||||||
|
- 忘记密码功能?
|
||||||
|
- 多设备登录管理?
|
||||||
|
|
||||||
|
3. **技术约束**:
|
||||||
|
- 后端技术栈是什么? (Go/Node/Python/Java等)
|
||||||
|
- 是否已有用户数据库?
|
||||||
|
- 是否需要JWT token认证?
|
||||||
|
|
||||||
|
请提供您的答案,我会基于此继续完善 PRD。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
[User responds: "用户名+密码, 需要记住登录和忘记密码, 后端用Go, 已有PostgreSQL, 需要JWT"]
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Claude: 感谢您的补充!
|
||||||
|
|
||||||
|
**清晰度评分更新**: 35/100 → 72/100
|
||||||
|
|
||||||
|
**新增明确的内容**:
|
||||||
|
- 登录方式: 用户名+密码
|
||||||
|
- 功能范围: 基本登录 + 记住登录 + 忘记密码
|
||||||
|
- 技术栈: Go后端 + PostgreSQL + JWT认证
|
||||||
|
|
||||||
|
**剩余需要澄清的点**:
|
||||||
|
- 安全性要求
|
||||||
|
- 错误处理策略
|
||||||
|
- 性能指标
|
||||||
|
|
||||||
|
继续澄清:
|
||||||
|
|
||||||
|
1. **安全性**:
|
||||||
|
- 密码加密方式有要求吗? (bcrypt/argon2/scrypt)
|
||||||
|
- 是否需要限制登录尝试次数? (防暴力破解)
|
||||||
|
- JWT token过期时间? (例如: 24小时, 7天)
|
||||||
|
- Remember Me token有效期?
|
||||||
|
|
||||||
|
2. **错误处理**:
|
||||||
|
- 登录失败时如何提示用户? (显示具体错误 vs 模糊提示)
|
||||||
|
- 是否需要审计日志记录登录行为?
|
||||||
|
|
||||||
|
3. **性能要求**:
|
||||||
|
- 预期并发登录用户数?
|
||||||
|
- 响应时间要求? (例如: 登录接口 < 500ms)
|
||||||
|
|
||||||
|
请继续补充,我们快完成了!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
[User responds with security and performance details]
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Claude: 完美!
|
||||||
|
|
||||||
|
**清晰度评分更新**: 72/100 → 93/100 ✓
|
||||||
|
|
||||||
|
**新增明确的内容**:
|
||||||
|
- 安全: bcrypt加密, 5次失败锁定15分钟, JWT 24小时过期
|
||||||
|
- 日志: 记录所有登录尝试
|
||||||
|
- 性能: 支持1000并发, 响应 < 300ms
|
||||||
|
|
||||||
|
需求已经非常清晰,我现在将生成完整的 PRD 文档...
|
||||||
|
|
||||||
|
[Creates ./.claude/specs/user-login/ directory]
|
||||||
|
[Generates clarification-log.md]
|
||||||
|
[Generates prd.md]
|
||||||
|
|
||||||
|
✅ **PRD 已生成**:
|
||||||
|
|
||||||
|
1. **需求文档**: `./.claude/specs/user-login/prd.md`
|
||||||
|
2. **澄清记录**: `./.claude/specs/user-login/clarification-log.md`
|
||||||
|
|
||||||
|
**文档概览**:
|
||||||
|
- 需求描述: 完整的功能、用户场景、技术方案
|
||||||
|
- 设计决策: Go + PostgreSQL + JWT + bcrypt架构
|
||||||
|
- 验收标准: 12项功能验收 + 8项质量标准
|
||||||
|
- 执行Phase: 4个阶段,预估2-3周完成
|
||||||
|
|
||||||
|
您可以查看文档并确认是否需要调整。如果满意,我可以立即开始实施! 🚀
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Success Criteria
|
||||||
|
|
||||||
|
- Clarity score ≥ 90/100
|
||||||
|
- All PRD sections complete with substance
|
||||||
|
- Acceptance criteria checklistable (使用 `- [ ]` 格式)
|
||||||
|
- Execution phases actionable with concrete tasks
|
||||||
|
- User approves final PRD
|
||||||
|
- Ready for development handoff
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Important Notes
|
||||||
|
|
||||||
|
1. **Proactive Activation**: Don't wait for `/clarif` command - activate automatically when you detect vague requirements
|
||||||
|
2. **Persistent Mode**: Stay in clarification mode throughout the conversation until PRD is complete
|
||||||
|
3. **Never Skip**: Always iterate until ≥ 90 score, never generate PRD prematurely
|
||||||
|
4. **Document Everything**: Save both clarification-log.md and prd.md
|
||||||
|
5. **User Language**: Use Chinese for section headers, mixed Chinese/English for content
|
||||||
|
6. **Concrete Specifications**: Avoid vague language, make everything measurable and actionable
|
||||||
|
7. **Build Context**: Each question round builds on previous answers
|
||||||
|
8. **Quality Gate**: Requirements clarity is a quality gate - prevent unclear specs from proceeding to implementation
|
||||||
3
.gitignore
vendored
3
.gitignore
vendored
@@ -1,3 +1,4 @@
|
|||||||
CLAUDE.md
|
CLAUDE.md
|
||||||
|
|
||||||
.claude/
|
.claude/*
|
||||||
|
!.claude/skills/
|
||||||
|
|||||||
Reference in New Issue
Block a user