AI 需求分析 Agent¶

用 AI 替代传统需求分析中的重复性工作，让需求分析师专注于业务思考和客户沟通。

背景与痛点¶

传统需求分析流程中，需求分析师（BA）大量的精力消耗在文档撰写、模板套用、任务分解等重复性工作上。每次新项目都要从零开始写调研报告、画蓝图、拆用户故事，不仅效率低，而且质量参差不齐。

核心痛点： - 行业知识沉淀难，每个项目都要重新研究行业特点 - 调研问卷每次重写，缺乏结构化模板 - 从调研结果到需求清单、从需求到蓝图、从蓝图到用户故事的链路长，人工转换容易遗漏 - 技能经验（怎么写蓝图、怎么拆迭代）分散在各个人脑子里，没有系统化

解决方案：需求分析 Agent¶

将需求分析师的思维模式和工作流程封装成一个 AI Agent。Agent 知道每个阶段该做什么、产出什么、用什么格式，BA 只需要提供业务信息，Agent 完成文档编制和任务分解。

理论基础：为什么这个 Agent 长这样？¶

业务分析理论依据：BABOK® 指南¶

本 Agent 的结构设计遵循 BABOK® Guide（业务分析知识体系指南），由国际商业分析协会（IIBA）制定，是需求分析领域的全球标准。

BABOK 知识域	本 Agent 对应环节	说明
业务分析规划与监控	初始化 → project.md	确定干系人、范围、方法论
需求启发	行业研究 → 问卷设计 → 调研	通过结构化方法收集信息
需求管理与沟通	需求清单 → 评审记录	需求分类、优先级、评审确认
需求分析与定义	业务方案 → 系统方案	从需求到方案的转换
方案评估	蓝图 → 用户故事 → 迭代计划	方案分解与可行性评估

为什么这样映射？

BABOK 定义了需求分析的标准生命周期。本 Agent 将其中的重复性、模板化的部分交由 AI 完成（问卷生成、文档撰写、任务分解），而需要人做判断的部分（业务决策、方案选择）保留给 BA。人机分工明确。

架构设计理论依据：Agent Skill 规范¶

本 Agent 遵循 Agent Skill 规范，该规范由 Anthropic（Claude 的母公司）原创提出，并作为开放标准发布（Apache 2.0 许可）。

目前已获广泛采用，包括 Clard Code、Claude.ai、GitHub Copilot、Cursor / Trae、OpenClaw、Gemini 等主流 AI 工具和平台。

权威出处：

来源	链接	说明
Agent Skills 开放标准仓库	github.com/agentskills/agentskills	规范定义 + 目录结构 + 元数据要求
官方规范文档	agentskills.io/specification	SKILL.md 格式、YAML frontmatter 字段定义
Anthropic 官方技能仓库	github.com/anthropics/skills	官方示例、模板、最佳实践
Anthropic 工程博客	Equipping agents with Agent Skills	设计哲学与原理解析
规范中文解读	Agent Skills 完全指南	渐进式披露原理 + 实战教程
菜鸟教程中文版	Agent Skills 教程	从入门到创建的完整实操

规范核心内容¶

Agent Skill 的底层格式要求：

skill-name/
├── SKILL.md          ← 必需：YAML frontmatter + Markdown 指令
├── scripts/          ← 可选：可执行脚本
├── references/       ← 可选：参考资料
├── assets/           ← 可选：模板、资源
└── ...               ← 任何其他文件

SKILL.md 的 frontmatter 字段（来自官方规范）：

字段	必需	约束
`name`	是	最长 64 字符，仅小写字母、数字和连字符
`description`	是	最长 1024 字符，描述技能用途和触发条件
`allowed-tools`	否	预授权的工具列表（实验性）
`metadata`	否	自定义键值对

渐进式披露机制（规范定义的核心设计模式）：

层1：元数据（name + description） → 始终在上下文中，用于技能发现
层2：SKILL.md 正文 → 匹配到相关任务后，加载完整指令
层3：附属文件（scripts/references） → 按需读取或执行

本 Agent 如何遵循规范¶

本 Agent 完全遵循 Agent Skill 规范标准：

目录结构：agent.md 等价于 SKILL.md（入口文件），skills/ 下每个技能也是独立的 SKILL.md
元数据：agent.md 头部有完整 YAML frontmatter（name + description）
渐进式披露：agent.md 只定义流程，不包含所有技能细节；技能文件只在执行到对应步骤时才加载
分层资源：参考资料和模板放在独立的子目录中，按需读取

核心设计原则：¶

原则	本 Agent 如何体现
模块化	6 步流程拆分为独立技能（调研/蓝图/迭代/报告），可单独更新、复用
渐进式披露	agent.md 是入口，按需读取 skill 和参考资料，避免一次加载全部内容
关注点分离	手册（agent.md）、知识（参考资料/）、技能（skills/）、项目（项目模板/）各自独立
可复用性	行业知识跨项目复用，技能跨项目复用，项目模板可复制

为什么不是别的结构？

备选方案	为什么不行
单个大 prompt	所有内容塞一个文件，上下文窗口爆炸，且无法跨项目复用行业知识
只有技能没有 agent.md	没有入口文件，AI 不知道先做什么后做什么，缺少流程编排
技能和项目混在一起	技能是复用的，项目是独立的，混在一起每次都要复制所有技能文件
没有项目模板	每个项目从零建目录，没有标准化，产出格式不统一

分层结构的经济学¶

本 Agent 的分层结构是经过精心设计的，核心考量是 上下文窗口效率：

层1（始终加载）：agent.md 的元数据（名称+描述）
    → AI 判断这个 Agent 是否适用，仅 ~50 token
层2（按需加载）：agent.md 正文 + 当前 skill 的 SKILL.md
    → 确定需要后加载完整工作流，约 ~2000 token
层3（按需加载）：参考资料/ 中对应行业的文件
    → 只有行业研究时才触发，约 ~500 token
层4（按需加载）：skills/ 中特定技能的 references/
    → 只有执行到该步骤时才读取

比较： - 单层结构（所有内容塞一起）→ 即使只做调研，也要加载蓝图和报告的完整内容 - 分层结构（渐进式披露）→ 做调研只加载调研相关，做蓝图才加载蓝图相关内容

一个中型项目全流程走完，分层结构比单层结构节省约 60-70% 的上下文空间。

整体架构¶

Agent 模板（可复用）¶

需求分析Agent/
├── agent.md                      ← Agent 行为定义（入口）
├── 参考资料/                     ← 知识库
│   ├── 需求标准规范.md           ← 需求定义、编号、验收条件等标准（保稳定）
│   ├── 行业研究指引.md           ← 通用方法论
│   └── [行业名]/                 ← 各行业特点、术语、数据流
├── skills/                       ← 专业技能
│   ├── 调研技能/
│   ├── 蓝图设计技能/
│   ├── 迭代拆分技能/
│   ├── 详细设计技能/
│   └── 报告撰写技能/
└── 项目模板/                     ← 脚手架，新项目复制用
    └── [项目名]/                 ← 项目目录模板

项目目录（各自独立）¶

[项目名]/
├── project.md                    ← 项目信息卡片
├── 调研产出/
│   ├── 调研记录.md
│   ├── 需求清单.md
│   └── 评审记录.md              ← 调研阶段评审意见
├── 方案设计/
│   ├── 业务解决方案.md
│   ├── 系统解决方案.md
│   └── 评审记录.md              ← 方案阶段评审意见
├── 任务分解/
│   ├── 用户故事.md
│   ├── 功能清单.md
│   ├── 迭代计划.md
│   └── 评审记录.md              ← 任务分解阶段评审意见
└── 输出/
    ├── 需求调研报告.md
    ├── 蓝图设计文档.md
    ├── 详细设计文档.md
    ├── 迭代计划.md
    └── 评审记录.md              ← 文档输出阶段评审意见

多项目管理示意图¶

workspace/
├── 需求分析Agent/               ← 共享模板
└── 工厂A-MES项目/               ← 项目1
└── 零售B-ERP项目/               ← 项目2

Agent 工作流程¶

客户提出需求
    ↓
① 初始化 → 读取 project.md，确认项目信息
    ↓
② 行业研究 → 查阅参考资料，输出行业研究笔记
    → 评审：调研产出/评审记录.md
    ↓
③ 调研与需求提炼 → 设计问卷 → 回收反馈 → 提炼需求清单
    → 输出后按《需求标准规范》质量检查清单自查
    → 评审：调研产出/评审记录.md
    ↓
④ 方案设计 → 业务方案 → 系统方案（模块级架构）
    → 评审：方案设计/评审记录.md
    ↓
⑤ 详细设计 → 接口定义、数据表设计、状态机、伪代码
    → 评审：方案设计/评审记录.md
    ↓
⑥ 任务分解 → 用户故事 → 功能清单 → 迭代计划
    → 评审：任务分解/评审记录.md
    ↓
⑦ 文档输出 → 调研报告 / 蓝图文档 / 详细设计 / 迭代计划
    → 评审：输出/评审记录.md

每个阶段产出后先评审，通过后再进入下一阶段。

设计分界原则¶

整个 Agent 的需求→方案→设计链路遵循三层粒度递进：

层级	产出物	目标读者	关注点
业务方案	业务解决方案.md	业务方	流程、角色、规则（"谁做什么事"）
系统方案（蓝图）	系统解决方案.md	架构师	模块划分、职责、关系（"系统分几块"）
详细设计	详细设计.md	开发者	接口、表结构、伪代码（"每块怎么实现"）

系统方案只写到模块级别，模块内部的接口、表、逻辑全部交给详细设计技能处理。

异常处理¶

Agent 遇到以下分支情况时按规则处理：

范围变更： 新增需求→记入清单末尾；修改已有需求→更新+记录变更原因；范围扩大→回退初始化阶段更新 project.md。

评审不通过： 少量局部修改→改完即过；结构性大改→进入新轮次重新评审；连挂 3 次→暂停与用户确认方法论。

需求冲突： 记录两个对立诉求标注"待仲裁"，Agent 仅做权衡分析，仲裁权交给用户。

信息不足： 先查参考资料，再用 web_search 补充，仍不足时间用户说明缺少什么，不编造内容。

评审记录格式¶

评审记录各阶段独立保存，按「评审轮次」组织。一场评审会记为一轮：

编号	关联内容	评审意见	提出人	状态
CR-01	需求 R-03	库存预警阈值需要配置化	张三	已采纳
CR-02	需求 R-07	审批流程缺少超时自动跳过	李四	已采纳

状态流转： 待处理 → 已采纳（修改后更新） / 已驳回（说明理由）

技能详解¶

调研技能¶

设计 5 模块标准化问卷（基本信息、业务模式、数据流、业务分工、系统需求）
支持按行业适配问卷内容（制造业突出工单/BOM/排产，零售业突出门店/SKU/促销）
从问卷结果按标准规则提炼需求清单
需求清单必须遵循《需求标准规范》：统一编号规则（R/D/N-项目缩写-流水号）、4 类分类、P0~P3 优先级
每条需求附带验收条件（Given-When-Then 格式）

蓝图设计技能¶

需求聚类 → 按业务域分组
现状分析（As-Is）→ 目标设计（To-Be）→ 流程对比
系统方案：功能架构、技术架构、数据流设计
标准蓝图文档结构（8 个章节）

迭代拆分技能¶

蓝图 → 用户故事（格式：作为/想要/以便 + 验收条件，验收条件遵循《需求标准规范》Given-When-Then 格式）
用户故事 → 功能清单
功能清单 → 迭代计划（MVP → 完善 → 优化）

报告撰写技能¶

4 份标准交付物模板
每份文档有完整章节结构
文档间数据可追溯（需求→方案→设计→计划）

详细设计技能¶

根据蓝图（系统解决方案）编写详细设计文档
包含：模块拆分、接口定义（API/服务）、数据库表结构设计、字段说明、状态机设计、核心逻辑伪代码
与上下游关联：需求 → 蓝图 → 详细设计，逐层细化，每个模块可追溯回对应需求
产出物：详细设计文档，按模块组织，供开发直接使用

项目模板¶

项目模板/[项目名]/ 目录下预置了所有文件的 placeholder，新项目启动时： 1. 复制模板目录，重命名为项目名 2. 填写 project.md（名称、行业、干系人、范围） 3. 通知 Agent 开始执行

project.md 核心字段：

项目名称 / 所属行业 / 项目规模 / 项目类型
干系人（发起人、业务负责人、技术负责人）
项目范围（目标、边界、里程碑）
行业参考（关联参考资料目录）

跨平台落地：相同 Agent，一致效果¶

Agent Skill 的底层格式是纯 Markdown + 目录结构，所有主流 AI 工具都支持。同一份 agent.md + skills/ 目录，在不同工具中的工作方式完全一致。

在 Claude Code 中使用¶

Claude Code 是 Anthropic 推出的终端 AI 编程助手。它原生支持 .claude/skills/ 目录。

安装：

# 进入你的项目目录
cd my-project

# 将需求分析 Agent 放入 Claude Code 的 skills 目录
cp -r 需求分析Agent .claude/skills/

# 或者从 Gitee 直接拉取
git clone https://gitee.com/zhuo-jiyun/lingsige.git tmp-lingsige
cp -r tmp-lingsige/需求分析Agent .claude/skills/

使用：

# 启动 Claude Code
claude

# 对话中直接说：
# "开始 工厂MES项目 的需求分析"
# Agent 自动按 6 步流程执行

原理： Claude Code 在启动时自动扫描 .claude/skills/ 下所有 SKILL.md 的元数据（name + description），当用户指令匹配时，自动加载 agent.md 正文。整个流程不需要手写任何 prompt。

在 Trae（原 Cursor）中使用¶

Trae 是字节跳动的 AI IDE，与 Cursor 类似，支持 .cursor/skills/ 目录（Agent Skill 标准目录）。

安装：

# 项目级安装
cp -r 需求分析Agent .cursor/skills/

# 或者全局安装（所有项目通用）
cp -r 需求分析Agent ~/.cursor/skills/

使用：

# 在 Trae 的对话面板中直接输入：
# "开始 工厂MES项目 的需求分析"
# Trae 自动匹配 agent.md 中的 name/description，加载工作流

效果验证： 同样的提示词，Trae 执行的是完全相同的 6 步流程，因为驱动 Agent 的是同一个 agent.md + 4个 skill 文件。文件相同，AI 的行为就一致。

在 OpenClaw 中使用¶

OpenClaw 是开源的 Agent 网关，支持 workspace 级别的 skills/ 目录。

安装：

# 将需求分析 Agent 放入 workspace 的 skills 目录
cp -r 需求分析Agent /home/admin/.openclaw/workspace/skills/
# 重启 OpenClaw
openclaw gateway restart

使用：

直接在飞书/企业微信/微信等渠道对话：

"开始工厂MES项目的需求分析"

OpenClaw 自动匹配 skill，执行完整工作流。

在 Claude.ai / ChatGPT App 中使用¶

# 1. 将 需求分析Agent/ 整体压缩为 zip
# 2. 在 Claude.ai 或 ChatGPT 的设置 → Skills 中上传 zip
# OR
# 3. 直接在对话中说：
#    "我上传了一个需求分析 Agent，请先阅读 agent.md，然后按流程执行"
# 4. 把 需求分析Agent/ 目录整个拖入对话

为什么各平台效果一致？¶

核心原因有三：

① 标准化格式 所有平台都遵循 Agent Skill 规范，使用统一的 SKILL.md + 目录结构。元数据（name + description）+ 正文（Markdown 指令）是通用语言。

② 文件共享，而非 prompt 共享 传统做法是将 prompt 从一个工具复制到另一个工具，不同工具的 prompt 处理方式不同，效果会走样。本方案共享的是文件本身，所有工具读取的是同一份代码，输出自然一致。

③ AI 模型能力对齐 主流 AI 模型（Claude、GPT、DeepSeek）对 Markdown 指令的理解能力已经趋近一致。只要指令清晰、结构分明，模型对同一份 agent.md 的解读和执行不会出现实质性偏差。

设计 Agent 的经典踩坑清单¶

这些坑来自本 Agent 的设计过程和反思，可以作为"反面教材"在设计分享时参考。

🕳️ 坑 1：agent.md 和 skill 写的是同一件事¶

现象： agent.md 里写着"第 3 步：需求聚类→业务方案→系统方案"，skills/蓝图设计技能/SKILL.md 里也写着"第一步需求聚类，第二步业务方案……"。AI 同时读到两份指令，不知道该听谁的。

本质： 把 agent.md 当成了"完整说明书"，而非"流程编排器"。

解决思路： agent.md 只负责阶段划分和转换条件——什么条件下从阶段 A 走到阶段 B。具体怎么做，一句话委托给 skill："读取 skills/蓝图设计技能/SKILL.md 执行"。两套指令不打架，AI 上下文里也少一堆重复内容。

一句话自查： 把 agent.md 里所有 skill 的部分删掉，靠 skill 文件能不能独立执行？如果能——说明边界对了。

🕳️ 坑 2：两个相邻技能覆盖的是同一个设计粒度¶

现象： 蓝图技能写"模块划分、功能描述"，详细设计技能也写"模块划分、接口定义"。AI 写蓝图时顺手把接口也写了——因为它觉得"写了也没错"。

本质： 没有在每个技能中明确设计边界——写到什么粒度为止。

解决思路： 给每一对相邻技能定义一张"分界表"：

层级	本技能做什么	不做什么
系统方案	模块划分、职责、关系	模块内部的接口、表、逻辑
详细设计	接口、表、伪代码	不能新增/合并模块

"不做什么"比"做什么"更重要——AI 不会自己判断边界，你不写它就越界。

🕳️ 坑 3：没有异常处理，AI 在岔路口靠自己猜¶

现象： 调研中发现需求范围变了，agent.md 没写怎么处理——AI 要么自己决定改范围，要么卡死。评审被驳回了，AI 不知道是改完就走还是重新走一遍流程。

本质： Agent 只有"快乐路径"（happy path），没有"异常路径"（exception path）。

解决思路： 至少定义 4 种高频异常的兜底规则：范围变更、评审不通过、需求冲突、信息不足。每种都写明触发条件、Agent 做什么、什么情况下必须交给用户。

关键原则： 异常路径不需要覆盖所有情况，但高频的那几种必须写。AI 在未知岔路口的决策，80% 都不对。

🕳️ 坑 4：知识库挂在旁边但 AI 不记得去看¶

现象： 参考资料/里有一份《需求标准规范》，第 9 节是质量检查清单（10 项自查）。但 AI 产出需求清单后不会主动去翻——它没这个"本能"。

本质： 知识库和流程指令在文件系统中是两类东西。AI 会主动读指令（SKILL.md），但不会主动去翻知识库（参考资料/）。

解决思路： 在流程指令中显式写"读取参考资料"的锚点。比如调研技能的末尾：

## 质量检查
需求清单产出后，读取参考资料/需求标准规范.md 第 9 节逐条自查

这不是冗余——这是告诉 AI："现在该去拿知识了，去那边。"

🕳️ 坑 5：项目数据和 Agent 指令混在一起¶

现象： 把项目 A 的调研记录、需求清单、方案设计全放在 skills/ 目录下，和技能文件放一个目录。

本质： 没有区分"复用资产"和"项目数据"。

解决思路： 严格分离——Agent 模板（agent.md + skills/ + 参考资料/）只存一份，每个项目独立建目录。新项目 = cp 项目模板 + 改 project.md，不需要复制任何技能文件。

量化对比： 混合存放 → 做 5 个项目后 skills/ 膨胀 5 倍；分离 → 做 100 个项目 skills/ 大小不变。

🕳️ 坑 6：缺少自检——写完了不知道怎么验¶

现象： Agent 写完后没有自检机制，每次都要靠人肉跑一遍才知道有没有 bug。

本质： 缺少"这个 Agent 怎么验证"的设计。

解决思路： 每个技能末尾内置质量自查清单（checklist），产出后 AI 先自检再提交。至少覆盖：完整性（有没有漏项）、一致性（和上游对应）、格式合规（是否遵循规范）。即使 AI 写错了，自检阶段也能自己发现并修正。

适用场景¶

制造业信息化项目：MES、ERP、WMS、APS（高级计划排程）、DM（需求管理） 等系统的需求分析
企业数字化转型：业务流程重组与系统实施
定制化软件开发：甲方有明确需求但缺乏专业 BA 支撑
咨询项目交付：管理咨询 + IT 实施一体化项目

使用方式¶

# 1. 新项目启动
cp -r 项目模板/工厂MES ./factory-mes
# 2. 编辑 factory-mes/project.md
# 3. 触发 Agent：开始 factory-mes 的需求分析
# Agent 自动执行 6 步流程

后续扩展方向¶

支持与飞书/企业微信集成，自动发送调研问卷
接入知识图谱，实现跨项目需求关联分析
提供可视化报表，展示需求分布与迭代进度
支持多语言，适配国际化项目