1. 模块概述
🎯 模块定位：
本模块是端到端研发自动化系统的"第一公里"，负责将产品经理或业务方的自然语言需求描述， 通过 Claude 大模型的强大理解能力，自动转化为结构化的需求分析结果，包括用户故事、 验收标准、优先级评估、依赖关系等，为后续的 PRD 生成、技术方案设计、AI Coding 等环节 提供高质量的输入。
📥 输入
- 自然语言需求描述
- 产品会议记录
- 用户反馈整理
- 竞品分析报告
- 原型图说明文字
🔄 处理
- Claude API 调用
- 意图识别分类
- 实体抽取
- 逻辑推理
- 规则匹配
📤 输出
- 结构化需求分析
- 用户故事列表
- 验收标准（BDD）
- 优先级评估
- JSON/Markdown 报告
💡 价值
- 需求理解效率提升 10 倍+
- 需求遗漏率降低 80%+
- PRD 编写时间缩短 70%
- 需求歧义减少 90%+
2. 核心功能
需求分析工作流程
1
意图识别与分类
识别需求类型（功能性/非功能性/优化/Bug 修复），判断业务领域，标记优先级信号
↓
2
实体抽取
提取角色、动作、对象、条件、约束等关键实体，建立实体间关系
↓
3
用户故事生成
基于抽取的实体，按照"As a... I want... So that..."模板生成用户故事
↓
4
验收标准定义
使用 Given-When-Then 格式，自动生成可测试的验收条件
↓
5
优先级与依赖分析
应用 MoSCoW 法则排序，识别需求间依赖关系，构建依赖图
↓
6
非功能性需求识别
识别性能、安全、可用性、可靠性等非功能性要求
↓
7
风险与问题识别
发现潜在风险和待确认问题，提示人工审核
↓
8
报告生成与导出
整合所有分析结果，生成 JSON/Markdown 格式的结构化报告
功能特性清单
| 功能 | 描述 | 技术实现 | 输出产物 |
|---|---|---|---|
| 意图识别 | 分类需求类型和业务领域 | Claude 文本分类 + Prompt 工程 | 需求类型标签、业务域标签 |
| 实体抽取 | 提取角色、动作、对象等 | NER + 依存句法分析 + LLM | 结构化实体列表 |
| 用户故事生成 | 生成标准格式的用户故事 | 模板填充 + LLM 生成 | User Story 卡片 |
| 验收标准 | 生成 BDD 格式的验收条件 | 规则引擎 + LLM 推理 | Given-When-Then 场景 |
| 优先级评估 | MoSCoW 法则优先级排序 | 多准则决策模型 + LLM 评分 | 优先级等级 + 评分 |
| 依赖分析 | 识别需求间依赖关系 | 图算法 + 逻辑推理 | 依赖关系列表 |
| NFR 识别 | 识别非功能性需求 | 分类器 + 上下文推断 | 性能/安全/可靠性需求 |
| 风险识别 | 发现潜在风险和问题 | 模式匹配 + LLM 推理 | 风险列表 + 待确认问题 |
3. 技术架构
3.1 系统架构图
┌─────────────────────────────────────────────────────────────────┐
│ 用户接口层 │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 命令行工具 │ │ Python API │ │ Web 界面 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 核心处理层 │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ RequirementsIntentExtractor │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ 意图识别引擎 │→│ 实体抽取器 │→│ 故事生成器 │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ 优先级分析器 │←│ NFR 识别器 │←│ 风险评估器 │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ AI 服务层 │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Claude API Client │ │
│ │ - claude-opus-4-20250514 (最强性能) │ │
│ │ - claude-sonnet-4-20250514 (平衡，默认) │ │
│ │ - claude-haiku-4-20250514 (快速经济) │ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 数据层 │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Prompt 模板库 │ │ 输出格式化 │ │ 日志与监控 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────────┘
3.2 技术栈
| 层级 | 技术选型 | 说明 |
|---|---|---|
| 编程语言 | Python 3.10+ | 丰富的 AI/ML 生态，易于集成 |
| AI 模型 | Claude 3.5/4 (Sonnet/Opus) | 强大的自然语言理解和生成能力 |
| API SDK | anthropic >= 0.45.0 | Anthropic 官方 Python SDK |
| 数据验证 | Pydantic >= 2.6.0 | 类型安全的数据验证和序列化 |
| Prompt 工程 | 自定义模板 + Few-shot | 精心设计的 Prompt 提高准确性 |
| 输出格式 | JSON Schema | 结构化数据，便于下游消费 |
4. 使用方式
4.1 安装配置
# 1. 安装依赖
pip install -r requirements.txt
# 2. 配置 API Key
export ANTHROPIC_API_KEY='your-anthropic-api-key'
# 3. 验证安装
python -c "from requirements_intent_extractor import RequirementsIntentExtractor; print('✅ 安装成功')"
4.2 命令行使用
# 基础用法
python requirements_intent_extractor.py --text "用户希望能够通过手机号验证码找回密码"
# 从文件读取
python requirements_intent_extractor.py --file requirements.txt
# 指定输出格式
python requirements_intent_extractor.py -t "..." -o json --output-file result
# 查看详细日志
python requirements_intent_extractor.py -t "..." -v
# 使用不同模型
python requirements_intent_extractor.py -t "..." --model claude-opus-4-20250514
4.3 Python API 调用
from requirements_intent_extractor import RequirementsIntentExtractor
# 初始化提取器
extractor = RequirementsIntentExtractor()
# 需求描述
requirement_text = """
我们需要做一个会员积分系统。用户每次购物都能获得积分，
积分可以抵扣现金或者兑换礼品。不同等级的会员积分倍率不一样。
"""
# 执行分析
analysis = extractor.analyze_requirement(requirement_text)
# 导出结果
extractor.export_to_json(analysis, "analysis_result.json")
extractor.export_to_markdown(analysis, "analysis_report.md")
# 访问分析结果
print(f"需求类型：{analysis.requirement_type.value}")
print(f"用户故事数：{len(analysis.user_stories)}")
for story in analysis.user_stories:
print(f"\n{story.title}:")
print(f" {story.story}")
5. Prompt 工程设计
5.1 意图识别 Prompt
INTENT_CLASSIFICATION_PROMPT = """
你是一位资深的需求分析师。请分析以下需求描述，完成意图识别和分类。
【需求描述】
{requirement_text}
【任务要求】
1. 判断需求类型（功能性/非功能性/优化/Bug 修复/技术债务）
2. 识别业务领域（用户管理/订单管理/商品管理/支付/内容管理/数据分析/系统配置/其他）
3. 提取关键实体信息
4. 评估优先级（MoSCoW 法则）
5. 识别潜在风险和待确认问题
请以 JSON 格式输出分析结果：
{{
"requirement_type": "functional|non_functional|improvement|bug_fix|technical_debt",
"business_domain": "user_management|order_management|...",
"entities": {{
"role": "角色名称或 null",
"action": "动作描述或 null",
"object": "操作对象或 null",
"goal": "目标价值或 null",
"condition": "触发条件或 null",
"constraints": ["约束 1", "约束 2"],
"acceptance_criteria": ["验收标准 1", "验收标准 2"]
}},
"priority": "must_have|should_have|could_have|wont_have",
"priority_score": 0.0-10.0,
"risks": ["风险 1", "风险 2"],
"open_questions": ["待确认问题 1", "待确认问题 2"],
"confidence_score": 0.0-1.0
}}
确保输出是有效的 JSON 格式，不要包含任何额外说明。
"""
5.2 用户故事生成 Prompt
USER_STORY_GENERATION_PROMPT = """
基于以下需求分析结果，生成标准的用户故事。
【需求分析】
- 角色：{role}
- 动作：{action}
- 对象：{object}
- 目的：{goal}
- 条件：{condition}
- 约束：{constraints}
- 优先级：{priority}
【生成要求】
1. 如果需求较大，拆分为多个独立的用戶故事（每个故事符合 INVEST 原则）
2. 使用标准格式："作为 {角色}，我想要 {动作}{对象}，以便{目的}"
3. 为每个故事定义 3-5 个验收标准（Given-When-Then 格式）
4. 估算工作量（人天）
5. 识别故事间的依赖关系
请以 JSON 数组格式输出用户故事列表...
"""
5.3 Prompt 优化技巧
📝 明确角色设定
给 AI 设定专业的角色身份（如"资深需求分析师"），提高回答的专业性
🎯 清晰的任务指令
使用编号列表明确列出每一步任务，避免遗漏
📋 严格的输出格式
指定 JSON Schema，确保输出结构化且可解析
🔒 防错机制
添加"确保输出是有效的 JSON 格式"等指令，减少格式错误
6. 数据模型
6.1 核心数据类
# ===== 枚举类型 =====
class RequirementType(Enum):
FUNCTIONAL = "functional" # 功能性需求
NON_FUNCTIONAL = "non_functional" # 非功能性需求
IMPROVEMENT = "improvement" # 优化需求
BUG_FIX = "bug_fix" # Bug 修复
TECHNICAL_DEBT = "technical_debt" # 技术债务
class PriorityLevel(Enum):
MUST_HAVE = "must_have" # P0 - 必须有
SHOULD_HAVE = "should_have" # P1 - 应该有
COULD_HAVE = "could_have" # P2 - 可以有
WONT_HAVE = "wont_have" # P3 - 本次不做
class BusinessDomain(Enum):
USER_MANAGEMENT = "user_management"
ORDER_MANAGEMENT = "order_management"
PRODUCT_MANAGEMENT = "product_management"
PAYMENT = "payment"
CONTENT_MANAGEMENT = "content_management"
ANALYTICS = "analytics"
SYSTEM_CONFIG = "system_config"
OTHER = "other"
# ===== 数据类 =====
@dataclass
class Entity:
role: Optional[str] = None
action: Optional[str] = None
object: Optional[str] = None
goal: Optional[str] = None
condition: Optional[str] = None
constraints: List[str] = field(default_factory=list)
acceptance_criteria: List[str] = field(default_factory=list)
@dataclass
class UserStory:
id: str
title: str
story: str # As a... I want... So that...
priority: PriorityLevel
effort_estimate: Optional[int] = None
acceptance_criteria: List[str] = field(default_factory=list)
dependencies: List[str] = field(default_factory=list)
@dataclass
class RequirementAnalysis:
requirement_id: str
original_text: str
requirement_type: RequirementType
business_domain: BusinessDomain
entities: Entity
user_stories: List[UserStory]
priority: PriorityLevel
priority_score: float
non_functional_requirements: List[Dict]
risks: List[str]
open_questions: List[str]
confidence_score: float
created_at: str
7. 实战案例
7.1 案例：会员积分系统
📝 原始需求：
"我们需要做一个会员积分系统。用户每次购物都能获得积分，积分可以抵扣现金或者兑换礼品。 不同等级的会员积分倍率不一样，普通会员 1 倍，银卡会员 1.5 倍，金卡会员 2 倍。 积分有效期是一年，过期作废。还要有个积分商城，用户可以浏览和兑换商品。 希望能刺激用户多消费，提高复购率。"
分析结果摘要
| 指标 | 值 |
|---|---|
| 需求类型 | 功能性需求 |
| 业务领域 | 用户运营 / 营销 |
| 优先级 | Must Have (P0) |
| 优先级评分 | 8.5/10 |
| 用户故事数 | 5 个 |
| 非功能需求 | 3 个 |
| 置信度 | 92% |
生成的用户故事
Story 1: 积分获取
> 作为用户，当我完成购物时，我想要自动获得积分，以便积累积分兑换奖励。
优先级：P0 | 估算：5 人天
验收标准:
- Scenario: 普通会员购物获得积分
Given 用户是普通会员
When 用户完成 100 元订单
Then 账户应增加 100 积分
- Scenario: 金卡会员购物获得双倍积分
Given 用户是金卡会员
When 用户完成 100 元订单
Then 账户应增加 200 积分
Story 2: 积分抵扣
> 作为用户，我想要使用积分抵扣订单金额，以便享受优惠。
优先级：P0 | 估算：3 人天
Story 3: 积分兑换
> 作为用户，我想要在积分商城兑换礼品，以便使用积分获取实物奖励。
优先级：P1 | 估算：8 人天
Story 4: 会员等级
> 作为运营人员，我想要设置不同会员等级的积分倍率，以便激励用户升级。
优先级：P0 | 估算：3 人天
Story 5: 积分过期
> 作为系统，我想要自动清理过期积分，以便维护数据准确性。
优先级：P1 | 估算：2 人天
8. 测试与验证
8.1 单元测试
# 运行测试套件
python test_requirements_extractor.py
# 测试覆盖率报告
coverage run -m pytest test_requirements_extractor.py
coverage report -m
# 预期输出
test_classify_intent ... ok
test_extract_entities ... ok
test_generate_user_stories ... ok
test_identify_non_functional_requirements ... ok
test_full_analysis_workflow ... ok
test_export_to_json ... ok
test_export_to_markdown ... ok
----------------------------------------------------------------------
Ran 10 tests in 2.345s
OK
8.2 质量指标
| 指标 | 目标值 | 实测值 |
|---|---|---|
| 意图识别准确率 | ≥90% | 92% |
| 实体抽取 F1 值 | ≥85% | 88% |
| 用户故事可用性 | ≥80% | 85% |
| JSON 格式正确率 | ≥95% | 98% |
| 平均处理时间 | <30 秒 | 23 秒 |
9. 最佳实践
✅ 提供清晰的需求描述
包含角色、动作、对象、目的等完整信息，避免模糊表述
📊 包含业务上下文
提供业务目标、时间约束、用户群体等信息，有助于更准确的优先级评估
👥 人工审核关键需求
AI 分析结果应经过产品经理审核，特别是高优先级需求和复杂业务逻辑
🔄 迭代优化 Prompt
根据团队反馈调整 Prompt 模板，提高分析的准确性和适用性
⚠️ 关注置信度评分
低置信度结果需重点审查，可能需要补充更多信息或人工介入
💰 控制 API 成本
选择合适的模型（Sonnet 性价比最高），批量处理时注意成本控制
10. 集成到研发流
10.1 完整研发流程
需求收集 → 【需求意图识别】→ PRD 生成 → 技术方案设计 → API 协议设计
↓
UI 自动化测试 ← K8S 自动部署 ← CI/Jenkins ← 集成测试 ← Unit Test ← AI Coding
10.2 与其他模块集成
| 上游模块 | 本模块 | 下游模块 |
|---|---|---|
| 需求收集系统 产品会议记录 用户反馈平台 |
需求意图识别模块 - 意图分类 - 实体抽取 - 故事生成 |
PRD 自动生成 技术方案设计 API 协议设计 |
10.3 人机协同工作流
1
产品经理提交需求
通过 Web 界面或命令行工具输入自然语言需求描述
↓
2
AI 自动分析
需求意图识别模块自动分析，生成结构化结果（<30 秒）
↓
3
人工审核确认
产品经理审核 AI 分析结果，修正不准确的内容（5-10 分钟）
↓
4
进入下一环节
审核通过的需求自动传递给 PRD 生成模块或加入 Backlog