引言：一项关键技能的演变
历史上，问题描述（PD）是系统分析中的基础工件。它作为推导用例的单一事实来源，业务流程模型（BPMN）、类图和数据库架构。模糊的问题描述意味着范围蔓延；精确的问题描述则意味着成功构建。
如今，随着生成式 AI 的出现，问题描述并未过时；它已演变为提示词.
AI 模型本质上是“需求引擎”。它们无法读取你的思想，但如果指令被构建为严谨的问题描述，它们就能以超人的速度执行指令。为 AI 编写问题描述所需的分析纪律与为开发团队编写时相同，但需增加关于输出格式, 约束条件以及迭代优化.
本指南连接了传统系统分析与现代 AI 提示技术，提供了一个全面的框架，用于编写能够生成高质量图表、代码和战略洞察的问题描述。
1. 有效问题描述的关键概念
无论是面向人类分析师还是大型语言模型（LLM），四个支柱支撑着稳健的问题描述：
1. 情境锚定
-
传统方法：业务背景、利益相关者、监管环境。
-
AI 应用：角色定义、领域专业水平、输出内容的目标受众。
-
重要性：缺乏情境时，AI 会默认采用通用平均值。“设计一个登录系统”会产生学生项目；而“为数字素养较低的老年用户设计符合 HIPAA 合规要求的患者门户登录系统”则会产生专门的架构模式。
2. 结构分解
-
传统方法：将问题分解为功能性/非功能性需求、参与者和实体。
-
AI 使用：思维链（CoT）结构化、分步推理请求、模块化提示。
-
为何重要：AI 难以应对单体复杂性。将产品描述（PD）分解有助于模型在生成长输出时保持连贯性。
3. 约束规范
-
传统方法：预算、时间表、技术栈、合规标准。
-
AI 使用：输出格式（Mermaid、PlantUML、JSON）、风格指南、禁止模式、令牌限制。
-
为何重要：约束能激发创造力与精确性。无约束的 AI 会生成冗长且往往不可用的产物。
4. 验收标准
-
传统方法：完成定义、测试用例、关键绩效指标（KPIs）。
-
AI 使用：验证检查、自我修正提示、预期结构验证。
-
为何重要：在生成开始前，必须明确“良好”的标准，以实现有效迭代。
2. 框架：用于 AI 问题描述的 C.R.E.F.O. 模型
改编自传统需求收集方法，请在 AI 任务中使用此模板：
| 组件 | 传统对应项 | AI 提示元素 | 示例 |
|---|---|---|---|
| C上下文 | 商业案例 / 干系人分析 | 角色 + 领域 + 受众 | “扮演一位为金融科技公司初创企业设计的高级企业架构师……” |
| R需求 | 功能/非功能需求 | 任务 + 具体目标 | “生成一个显示带有 MFA 回退机制的 OAuth2 流程的序列图……” |
| E实体 | 领域模型 / 术语表 | 关键术语 + 定义 | “关键实体：用户、身份验证提供者、会话令牌、审计日志……” |
| F格式 | 交付物标准 | 输出语法 + 风格 | “以 Mermaid.js 语法输出。使用正交边路由……” |
| O输出检查 | 质量保证 / 测试 | 验证 + 优化 | “确保所有生命线都有激活框。验证不存在循环依赖……” |
3. 使用案例与示例
案例 A：生成UML 类图
挑战：当提供模糊的领域描述时，AI 经常生成过于复杂或语法错误的图表。
❌ 薄弱的问题描述
“为电子商务系统创建一个类图。”
✅ 全面的问题描述
上下文：您是一位领域驱动设计专家。我们正在构建一个 B2B 批发电子商务平台，其定价基于合同而非目录。
需求：对核心订购界限上下文进行建模。重点关注合同、价格表、产品和订单之间的关系。请勿对 UI 或支付处理进行建模。
实体与规则：
- 合同：具有生效日期，归属于一个客户账户
- 价格表：与合同关联，包含分级定价规则
- 订单项：在创建时必须验证价格与当时有效的合同是否一致
- 客户账户：可以拥有多个合同（当前/历史）
格式：Mermaid classDiagram 语法。包含可见性修饰符 (+/-/#)。在所有关联上显示多重性。对复杂的业务规则使用注释。
约束：最多 12 个类。应用 SOLID 原则。继承深度不超过 2 层。优先使用组合而非继承。
验证：生成后，列出该模型中 3 个潜在的设计弱点。
案例 B：业务流程建模（BPMN）
挑战：AI 混淆了 BPMN 符号，并遗漏了异常路径。
✅ 全面的问题描述
背景：健康保险理赔处理。受众：合规审计员和初级开发人员。语气：正式且精确。
任务：为“预先授权请求”创建一个符合 BPMN 2.0 标准的过程图。
流程范围：
开始：医生通过电子健康记录（EHR）集成提交授权请求
结束：决策结果回传至 EHR + 向成员发送通知
关键决策点：
1. 该程序是否在成员的保险计划覆盖范围内？（如果否 → 自动拒绝 + 申诉路径）
2. 临床文档是否完整？（如果否 → 转交护士审核员待处理）
3. 是否需要医疗总监审核？（阈值：超过 5 万美元或属于实验性项目）
异常处理：为每个审核阶段建模超时事件（48 小时服务等级协议 SLA）。如果违反 SLA，则建模升级路径。
格式：使用类 BPMN 样式的 Mermaid 流程图。使用子图表示“临床审核”和“行政验证”泳道。
输出要求：提供图表代码，并提供一个 Markdown 表格，将每个决策节点映射到管辖该节点的具体政策文档章节。
案例 C：推导用户故事与验收标准
挑战：AI 生成的用户故事过于通用，缺乏可测试性。
✅ 全面的问题描述
背景：敏捷团队正在将传统的 COBOL 工资系统迁移到云原生架构。团队使用 Gherkin/Cucumber 行为驱动开发（BDD）。
输入：[粘贴旧系统规范摘录或访谈记录]
任务：提取“税款预扣计算”模块的用户故事。
每个故事的要求：
- 遵循 INVEST 原则
- 标题格式：作为 [角色]，我想要 [功能]，以便 [业务价值]
- 验收标准：每个故事至少包含 5 个 Gherkin 场景
- 包含边缘情况：跨州员工、追溯性薪资调整、工资扣押上限、税收条约豁免
约束条件：每个故事必须在 ≤3 天内完成。对于看起来过大的故事，标记"[需要拆分]"标签。
格式：结构化 Markdown，包含 YAML 前置元数据，内容如下：
- story_id（故事 ID）
- priority（优先级，采用 MoSCoW 方法）
- estimated_points（估算点数）
- dependencies（依赖项）
案例 D：系统架构决策记录（ADR）
挑战：让 AI 进行权衡推理，而不仅仅是列出选项。
✅ 全面的问题描述
背景：我们正在为物联网遥测数据选择事件流平台（1000 万台设备，峰值 5 万条消息/秒）。团队拥有丰富的 Kafka 经验，但管理层希望降低运维开销。
任务：撰写一份 ADR，比较 Apache Kafka、AWS Kinesis 和 Pulsar。
结构（遵循 Michael Nygard 的 ADR 模板）：
1. 标题与状态
2. 背景（包含以下具体约束）
3. 决策驱动因素（加权）
4. 考虑选项（优缺点矩阵）
5. 决策及理由
6. 后果（正面和负面）
决策驱动因素（加权）：
- 运维复杂度（35%）- 团队规模小（3 名工程师）
- 规模化成本（25%）
- 消息顺序保证（20%）
- 供应商锁定风险（15%）
- 社区/生态系统（5%）
约束：对缺点要直言不讳。不要仅基于流行度进行推荐。如果没有合适的选项，请明确指出并建议替代方案。
语气：技术性、基于证据、无营销语言。
4. 技巧与窍门
🎯 精准技巧
-
首先定义您的本体论：在要求生成任何图表之前，先让 AI 创建术语表或领域模型。在术语上达成一致，在生成工件之前。“首先，用要点形式定义关键实体及其关系。在生成图表之前等待我的批准。”
-
负面约束非常有效：告诉 AI 不要做什么，往往比告诉它要做什么更有效。“不要在序列图中包含 CRUD 操作。不要使用继承。不要假设同步通信。”
-
提供反例：展示糟糕的输出是什么样的。“这是上周我们拒绝的一个过于复杂的图表示例 [粘贴]。避免这种模式，因为……”
-
使用结构化输入格式：将需求以 YAML、JSON 或编号列表的形式提供，而不是散文形式。AI 解析结构化数据更为可靠。
-
迭代优化协议：切勿接受复杂图表的首次生成结果。请在问题描述（PD）中内置优化环节：“生成后，请依据以下 5 项质量标准自我评估输出结果，随后针对所有已识别问题重新生成。”
⚠️ 常见陷阱与规避建议
| 陷阱 | 失败原因 | 解决方案 |
|---|---|---|
| 过度指定实现细节 | 限制了人工智能寻找最优方案的能力 | 明确说明“做什么”和“为什么”，由人工智能提出“如何做” |
| 假设存在共享知识 | 人工智能不了解贵组织的惯例 | 始终包含相关标准或模板 |
| 为复杂系统使用单一巨型提示词 | 上下文窗口退化，导致连贯性丧失 | 将其分解为具有明确交接点的链式提示词 |
| 忽略非功能性需求 | 生成缺乏架构深度的输出结果 | 在决策驱动因素中明确赋予非功能性需求权重 |
| 将人工智能输出视为最终结果 | 符号或语法幻觉现象较为常见 | 始终验证语法与语义的正确性 |
5. 指南检查清单
在向人工智能提交任何“问题描述”前，请核实：
-
已定义角色/人设具备相应的专业水平
-
业务背景已提供（不仅限于技术规格）
-
范围边界已明确说明（在范围内/范围外）
-
关键实体/术语 已定义或引用
-
输出格式 已指定语法/版本详情
-
约束条件 已列出（技术、业务、风格）
-
质量标准 已定义用于自我评估
-
边缘情况/异常 已处理
-
分解策略 已为复杂输出制定计划
-
迭代协议 已建立
6. 元技能：将问题描述作为思维工具
最重要的见解：为 AI 撰写问题描述，本质上是一项澄清自身思维的练习。
如果你难以写出清晰的问题描述（PD），那么你面临的不是提示词问题，而是需求问题。AI 只是暴露了那些本就会在下游引发问题的模糊之处。
请使用以下工作流：
-
起草你的问题描述
-
向 AI 提问：“要完美地完成这项任务，你需要回答哪些问题？”
-
回答这些问题，并据此完善你的问题描述
-
然后才请求实际交付成果
这将使 AI 转变为需求获取伙伴而不仅仅是一个生成引擎。你的问题描述的质量始终如一，仍是成功的最关键预测因素——无论你的协作者是人类还是人工智能。
7. 工具聚焦：Visual Paradigm 作为 AI 到工件的桥梁
虽然 AI 擅长生成图表代码（Mermaid、PlantUML、JSON），它无法原生生成企业级、可编辑的建模文件。这正是 Visual Paradigm（VP）充当了 AI 生成的问题描述与专业系统文档之间的关键中间件。VP 原生的AI 集成以及强大的导入功能，使其成为上述工作流程的理想验证与优化层。
为何Visual Paradigm 适用于 AI 生成的图表?
| 功能 | 与 AI 问题描述工作流的关联性 |
|---|---|
| AI 辅助建模 | 内置的 LLM 集成，可从工具内自然语言问题描述直接生成UML/BPMN（无需外部工具） |
| 多格式导入 | VPasCode 支持 Mermaid、PlantUML、JSON 和 XMI——实现 AI 输出的无缝导入 |
| 模型仓库 | 将扁平化图表转换为集中式、可查询的模型数据库，并实现跨图表的一致性 |
| 双向工程 | 将 AI 生成的类图与实际代码库同步，以进行验证 |
| 标准合规性 | 强制执行UML 2.5, BPMN 2.0, ArchiMateAI 经常违反的语法 |
| 协作与版本控制 | 支持团队对 AI 生成的工件进行审查，并具备变更跟踪功能 |
集成工作流：PD → AI → Visual Paradigm
步骤 1：通过 AI PD 生成结构化输出
使用 C.R.E.F.O. 框架提示您的 AI，但明确针对与 VP 兼容的格式:
格式要求：使用与 Visual Paradigm 导入兼容的 PlantUML 语法生成类图。包含所有构造型注解（<<entity>>、<<service>>、<<repository>>）。仅使用 VP 支持的关系表示法。请勿使用自定义扩展或非标准装饰器。
💡 专业提示：Visual Paradigm 的 PlantUML 导入器在处理构造型、注释和包结构方面优于其 Mermaid 导入器。对于复杂的 UML，建议将 PlantUML 作为 AI 输出的目标格式。
步骤 2：在 Visual Paradigm 中导入并验证
-
通过以下方式将 AI 生成的代码复制到 VP：文件 → 导入 → PlantUML/Mermaid
-
运行模型验证（工具 → 模型验证）以检测 AI 幻觉：
-
关联上缺少多重性
-
构造型使用无效
-
孤立元素
-
命名规范违规
-
-
使用查找与替换根据项目术语表标准化 AI 不一致的术语
步骤 3：利用 VP 的原生 AI 进行优化
无需返回外部大语言模型进行迭代，请使用 VP 内置的 AI 助手：
-
“优化此图表”: 选择元素并请求 VP 的 AI 根据更新后的 PD 约束进行重构
-
“生成文档”: 从导入的图表自动创建需求追溯矩阵
-
“建议改进”: 获取基于 VP 建模最佳实践的模式化建议（而非通用大语言模型训练数据）
步骤 4：建立跨图表的模型一致性
这正是 VP 提供外部 AI 无法比拟的价值之处。当您导入由 AI 生成的类图时：
-
实体变为一等模型元素而不仅仅是图形
-
在类图中更新类名会自动传播至序列图、状态机和实体关系图（ERD）
-
由 AI 生成的用例可以与需求关联在 VP 的需求管理模块中
-
交叉引用会被验证：如果 AI 编造了您仓库中不存在的类，VP 会立即标记
实际示例：在 VP 中修正 AI 输出
AI 生成（通过 PD）：
class OrderService {
+processOrder(order: Order): void
}
class Order {
+orderDate: Date
}
OrderService --> Order : uses
VP 验证中检测到的问题：
-
❌
Order缺失<<entity>>构造型，以符合项目标准 -
❌ 关联缺少角色名和多重性
-
❌ 不依赖于
OrderRepository（违反来自 PD 的分层架构约束）
在 VP 中优化（使用 AI 辅助 + 人工修正）：
<<service>> 类 OrderService {
+processOrder(order: Order): void
}
<<entity>> 类 Order {
+orderDate: Date
}
<<repository>> 类 OrderRepository {
+findById(id: UUID): Optional<Order>
}
OrderService --> OrderRepository : 依赖于
OrderService ..> Order : 使用 [1..* 创建]
优化后的版本现在已通过 VP 验证，符合原始 PD 中指定的架构约束，并完全集成到项目模型仓库中。
何时使用 Visual Paradigm 与纯 AI 输出
| 场景 | 推荐方法 |
|---|---|
| 快速探索/头脑风暴 | AI → Markdown 编辑器中的 Mermaid |
| 利益相关者演示草稿 | AI → 内联渲染的 Mermaid/PlantUML |
| 正式需求文档 | AI → PlantUML → Visual Paradigm |
| 带图表的架构决策记录 | AI → VP（原生 ADR 模板 + 嵌入式图表） |
| 代码生成/逆向工程 | AI PD → VP → 与 IDE 双向同步 |
| 带版本控制的团队协作 | AI → VP → VP 服务器/Git 集成 |
| 监管/合规交付物 | AI → VP（验证 + 审计追踪为必需） |
关键要点
Visual Paradigm 将AI 生成的图表 从 一次性工件 到 活体模型资产问题描述始终是智力基础，AI 提供生成加速，而 Visual Paradigm 确保输出符合专业建模标准，保持跨工件的一致性，并融入贵组织更广泛的系统工程生命周期。切勿将 AI 生成的图表视为最终结果——始终将其通过适当的建模工具进行验证、优化和治理。
本指南综合了传统系统分析（IEEE 830、BABOK、UML 规范）与现代 AI 提示工程研究的最佳实践。请根据您的组织背景调整这些框架，并基于输出质量的反馈循环持续优化。