mirror of
https://github.com/cexll/myclaude.git
synced 2026-02-16 03:33:12 +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
|
||||
Reference in New Issue
Block a user