提示词工程(二):Prompt的核心组成

Source

必须掌握的知识优先级

建议按照下面的顺序学习:

优先级

知识点

掌握要求

P0

七大核心组成部分

能够解释每个部分的作用

P0

Role 和 Task 的区别

能够准确区分

P0

Context 和 Instruction 的区别

能够准确区分

P0

Constraints 的作用

理解约束如何改善输出

P0

完整 Prompt 设计

能够独立编写

P1

指令冲突处理

能够识别和解决冲突

P1

Examples 使用方法

理解 Zero-shot、One-shot、Few-shot

P1

Prompt 可复用设计

能够设计通用模板

一、必须掌握的核心知识点

下面 7 个知识点建议逐一理解。

1. Prompt 的七大核心组成部分

首先必须理解每个组成部分的职责。

组成部分

核心作用

需要掌握什么

Role

定义身份

让模型以什么身份思考和回答

Task

定义任务

明确模型需要完成什么工作

Context

提供背景

让模型了解任务发生的背景

Instruction

执行指令

告诉模型具体应该怎么做

Constraints

限制范围

明确哪些事情不能做、有哪些边界

Output Format

规定输出

明确最终结果应该如何组织

Examples

提供示例

通过输入输出示例引导模型

必须理解:

  • 七大组成部分各自解决什么问题?

  • 每个部分是否都是必需的?

不是。Prompt 的七大组成部分是一种常见的结构化设计方法,并不是固定的语法规范。其中 Task 是核心,因为模型必须明确需要完成什么任务。Role、Context、Instruction、Constraints、Output Format 和 Examples 则根据任务复杂度和实际需求灵活组合。

对于简单任务,可能只需要 Task;对于复杂任务,则需要补充角色、背景、执行要求、约束条件和输出格式,以减少模型的理解偏差,提高输出的准确性和稳定性。

  • 哪些部分可以合并?

可以。Prompt 的七大组成部分是逻辑上的划分,并不要求在实际编写时完全独立。

例如 Role 和 Context 可以放在一起描述,Task 和 Instruction 可以合并表达,Constraints 也可以融入具体执行要求。

但是合并不意味着概念相同,我们仍然需要明确区分角色、任务、背景、执行要求和约束条件。

实际设计时,我更倾向于根据任务复杂度灵活组织结构,保证 Prompt 清晰、无歧义、易于维护和复用。

  • 不同任务是否需要不同的 Prompt 结构?

是的。不同任务的目标、复杂度和输出要求不同,因此 Prompt 结构也需要灵活调整。

例如,简单知识问答通常只需要明确 Task;代码分析需要提供 Role、Context、Instruction 和 Constraints;数据提取需要重点明确提取规则和 Output Format;Agent 工具执行则需要额外明确工具定义、调用条件和执行边界。

因此,Prompt 不应该采用固定的模板,而应该根据任务类型和复杂度选择合适的组成部分,从而提高模型输出的准确性和稳定性。

特别注意:这七个部分是一种常用的设计框架,并不是所有 Prompt 都必须包含全部七项。

2. Role 和 Task 的区别

这是最基础、也最容易混淆的知识点。

对比

Role

Task

含义

角色定位

任务定义

回答的问题

你是谁?

你要做什么?

作用

确定回答视角

确定执行目标

示例

你是一名 Java 架构师

分析以下 Java 代码的性能问题

必须掌握:

  • Role 如何影响模型的回答视角?

Role 是 Prompt 中用于定义模型身份和专业定位的组成部分。

它主要通过引导模型关注特定的专业领域、分析维度、回答深度和表达方式,影响模型的输出。

例如,同样是分析 Redis 缓存方案,Java 开发工程师可能更关注缓存读写逻辑和代码实现,而系统架构师可能更关注整体缓存架构、高可用和扩展性。

从底层原理来看,Role 会作为输入上下文的一部分参与模型计算,影响后续 Token 的概率分布,从而引导模型生成符合角色定位的回答。

但 Role 并不会改变模型的底层能力,也不能代替必要的专业背景和执行指令。

  • Task 如何影响模型的执行目标?

Task 是 Prompt 中用于定义模型执行目标的核心组成部分,主要告诉模型需要完成什么工作。

它会影响模型的任务类型、分析范围和最终交付结果。

例如,针对同一段 Java 代码,如果 Task 是解释代码,模型会侧重解释执行流程;如果 Task 是分析代码,模型会侧重发现潜在问题;如果 Task 是优化代码,模型则会侧重提出优化方案并生成修改后的代码。

从 LLM 的底层原理来看,Task 作为输入上下文的一部分参与模型计算,影响后续 Token 的概率分布,从而引导模型生成符合任务目标的内容。

  • 只有 Role,没有 Task 会发生什么?

如果 Prompt 只有 Role,没有 Task,模型虽然能够获得角色定位,但缺少明确的执行目标。

它知道应该以什么身份回答,却不知道具体需要完成什么工作,因此可能出现回答方向不明确、输出内容不够聚焦等问题。

当然,如果历史对话中已经包含明确任务,模型也可以结合上下文推断用户意图。

但在设计 Prompt 时,通常建议明确指定 Task,降低模型的理解偏差,提高输出的针对性和稳定性。

  • 只有 Task,没有 Role 会发生什么?

如果 Prompt 只有 Task,没有 Role,模型依然可以正常执行任务,因为 Task 已经明确了需要完成的工作。

但是缺少 Role,模型就没有明确的身份和专业视角引导,回答可能更加通用,无法充分贴合特定专业领域的需求。

例如,同样是分析 Redis 缓存方案,如果指定 Java 架构师,模型会更倾向于从 Java 后端架构、高并发和缓存设计等角度分析。

因此,Role 并不是所有任务都必需的,而是根据任务是否需要特定专业视角灵活添加

  • Role 是否真的改变模型能力,还是主要改变回答方式和关注重点?

Role 不会改变模型底层的参数、架构和实际能力上限,它主要是一种上下文引导机制。

通过角色设定,可以引导模型采用特定的专业视角,调整回答的关注重点、分析方式和表达风格。

从模型原理来看,Role 作为输入 Token 的一部分,会影响模型后续 Token 的概率分布,从而影响最终生成结果。

因此,Role 的本质是引导模型更有针对性地使用已有能力,而不是直接增强模型的底层能力。

3. Context 和 Instruction 的区别点

这两个概念非常重要。

对比

Context

Instruction

含义

背景信息

执行要求

回答的问题

模型需要知道什么?

模型需要怎么做?

作用

补充任务信息

指导执行过程

示例

当前项目使用 Spring Boot 3

从性能、安全、可维护性三个角度分析

必须掌握:

  • Context 为什么能够帮助模型理解任务?

Context 本质上是为模型提供任务相关的背景信息,包括业务场景、技术环境、已有条件和问题描述。

因为用户提出的 Task 往往比较抽象,如果缺少背景信息,模型只能根据已有上下文和常见情况进行推断,容易产生不必要的假设。

加入 Context 后,模型能够结合具体场景理解任务,缩小分析范围,提高回答的针对性。

从 LLM 原理来看,Context 也是输入 Token 序列的一部分,会通过 Transformer 的上下文计算影响模型后续 Token 的概率分布,进而影响生成结果。

  • Instruction 如何引导模型执行任务?

Instruction 是 Prompt 中用于描述具体执行要求的组成部分,它主要告诉模型应该按照什么步骤、什么规则以及什么分析维度完成任务。

Task 负责明确任务目标,而 Instruction 负责细化任务的执行方式。

从 LLM 原理来看,Instruction 作为输入上下文的一部分,会参与 Transformer 的上下文计算,影响模型后续 Token 的概率分布,从而引导模型按照指定要求生成回答。

但 Instruction 并不是传统程序中的确定性执行逻辑,它是一种对模型生成行为的引导,不能保证模型百分之百遵循。

  • 如何区分背景描述和执行要求?

Context 主要负责提供任务相关的背景信息,例如业务场景、技术环境、系统现状等,帮助模型理解当前任务所处的环境。

Instruction 主要负责描述具体的执行要求,例如执行步骤、分析维度和操作规则,引导模型按照指定方式完成任务。

两者最大的区别在于:Context 解决的是模型缺少背景信息的问题,Instruction 解决的是模型不知道如何执行任务的问题。

4. Constraints 为什么能够改善模型输出?

必须理解约束条件的价值,而不是只会写限制语句。

例如:

没有约束:

分析以下 Java 代码,并进行优化。

增加约束:

分析以下 Java 代码,并提出优化建议。

约束:
1. 不允许修改原有业务逻辑。
2. 不允许引入新的第三方依赖。
3. 优先考虑性能优化。
4. 必须指出每项优化的原因。
5. 如果信息不足,不要自行假设。

必须掌握:

  • 约束条件如何缩小模型的回答范围?

Constraints 是 Prompt 中用于定义执行边界和限制条件的组成部分。

它通过明确技术限制、业务规则、内容范围、输出长度以及行为要求,减少模型不必要的发挥,让模型在指定范围内生成回答。

从 LLM 原理来看,Constraints 作为输入上下文的一部分,会影响模型后续 Token 的概率分布,引导模型生成更符合限制条件的内容。

但 Prompt 中的约束并不是绝对的强制执行机制,对于重要的业务规则和安全要求,还需要通过程序校验、自动化测试等方式保证

  • 为什么约束能够减少无关内容?

因为 Constraints 能够明确任务的执行边界,限制模型可以展开的内容范围。

当模型接收到约束条件后,会将其作为输入上下文的一部分,与 Task 等信息共同参与上下文计算,影响后续 Token 的概率分布,使模型更倾向于生成符合约束的内容,减少不相关方向的扩展。

但这种约束属于生成行为引导,并不是绝对的强制执行,因此对于重要规则,还需要结合程序校验和自动化测试

  • 如何降低模型自由发挥造成的错误?

我通常从 Prompt 设计和结果校验两个层面解决。

第一,补充 Context,提供充分的业务背景和技术信息,减少模型自行假设。

第二,通过 Constraints 明确回答边界,限制模型生成无关内容。

第三,通过 Instruction 要求模型区分事实和推测,并提供结论依据。

第四,通过 Output Format 固定回答结构,提高输出的可控性。

最后,对于重要结果,不能仅依赖 Prompt,还需要结合 RAG、工具调用、代码执行、自动化测试等机制进行验证。

本质上,Prompt 负责引导模型生成,外部校验机制负责验证生成结果

  • 如何约束模型的技术选型、代码修改范围和回答长度?

我通常从三个维度设置 Constraints。

第一,技术选型约束,明确技术栈、框架版本、依赖限制和兼容性要求。

第二,代码修改范围约束,明确允许修改的文件、方法和业务边界,并优先采用最小化修改原则。

第三,输出约束,通过字数、条数、内容范围和结构要求控制回答长度。

但是 Prompt 约束属于软约束,不能保证模型绝对遵守。在实际 Agent 系统中,还需要结合工具权限、程序校验和自动化测试,实现真正的执行边界控制。

  • 约束是否越多越好?过度约束会产生什么问题?

不是。Prompt 约束需要在可控性和灵活性之间取得平衡。

约束过少,模型容易自由发挥,产生偏离任务目标的内容。

约束过多,可能限制模型的解决方案,降低灵活性,增加指令冲突,甚至导致任务目标与约束条件相互矛盾。

因此,在设计 Prompt 时,我会优先约束关键业务规则、技术选型、代码修改范围和输出要求,而对于不影响任务正确性的实现细节,保留模型一定的选择空间。

核心原则是:必要约束、明确约束、避免冲突,而不是追求约束数量。

核心理解:约束的本质是明确模型的执行边界,减少不符合预期的输出。

5. 如何避免 Prompt 中的指令冲突?

例如:

请详细分析以下代码。

要求:
1. 回答必须简洁。
2. 尽可能详细地解释每一行代码。
3. 最终回答不超过 100 字。

这里存在潜在冲突:详细解释每一行代码与不超过 100 字可能难以同时满足。

必须掌握:

  • 什么是 Prompt 指令冲突?

Prompt 指令冲突是指多个指令之间存在相互矛盾或无法同时满足的要求。

例如,Task 要求详细分析,而 Constraints 又限制回答不能超过 50 字,就可能导致模型无法完整满足任务。

指令冲突可能造成模型忽略部分要求、输出不完整或格式异常。

解决方法主要有:删除矛盾要求、明确指令优先级、将模糊要求具体化,以及将复杂任务拆分成多个阶段。

在 Agent 开发中,还可以增加冲突检测和人工确认机制,避免模型自行处理重要的业务规则冲突。

  • 常见的指令冲突有哪些?

Prompt 指令冲突是指多个指令之间存在相互矛盾、无法同时满足的要求。常见类型包括 Task 与 Constraints 冲突、Instruction 与 Constraints 冲突、Constraints 之间冲突、Instruction 与 Output Format 冲突、Role 与 Task 冲突,以及多个 Instruction 之间冲突。

解决方式主要是明确任务目标、消除矛盾、设置指令优先级、拆分复杂任务,并要求模型在无法兼容时主动反馈冲突。

  • 如何识别相互矛盾的指令?

首先将 Prompt 拆分成 Role、Task、Context、Instruction、Constraints 和 Output Format 等部分,然后逐项检查它们之间的兼容性。

重点检查任务目标与约束是否冲突、多个约束之间是否矛盾、执行要求与输出格式是否兼容,以及是否存在隐含的业务规则冲突。

如果发现冲突,需要明确冲突点、调整指令或设置优先级;如果无法确定应该遵循哪个要求,则应该让模型暂停执行并向用户确认。

  • 如何通过优先级解决冲突?

当 Prompt 中存在多个相互冲突的要求时,可以通过指令优先级解决。

首先将指令划分为不同等级,例如核心目标、强制约束、执行要求和输出要求;然后明确冲突时优先遵循高优先级指令。

如果同一优先级的强制要求发生冲突,或者高优先级要求本身无法兼容,就应该让模型明确指出冲突并请求用户确认,而不是自行猜测。

需要注意,Prompt 内部优先级属于自然语言引导,并不等同于模型系统级指令优先级

  • 如何通过明确适用范围减少冲突?

明确指令适用范围是减少 Prompt 冲突的重要方法。

很多指令看似矛盾,实际上是没有明确适用条件。例如一条规则可能只适用于代码生成,另一条规则只适用于代码分析。如果没有定义范围,模型可能错误地将规则应用到所有任务。

因此,可以从任务范围、对象范围、执行阶段和条件范围四个维度限定指令,并明确例外情况。

如果不同规则的适用范围仍然重叠,则需要进一步结合指令优先级解决冲突。

  • 当两个要求无法同时满足时,模型应该如何处理?

首先识别冲突的具体指令,然后判断是否存在明确的优先级。

如果有优先级,就优先遵循高优先级指令;如果存在不违反高优先级约束的替代方案,可以调整执行策略继续完成任务。

如果两个同等级的强制要求无法兼容,或者缺少必要信息,就应该明确指出冲突原因、提供解决方案,并请求用户确认,而不是自行猜测。

最后还需要反馈哪些要求已经满足,哪些要求由于冲突没有完成。

重点掌握三种方法:

  • 明确优先级: 说明哪个要求优先。

  • 明确适用范围: 区分不同阶段、不同输出部分的要求。

  • 明确冲突处理策略: 无法同时满足时,说明冲突并请求确认,或者遵循指定的优先级。

6. Examples 的作用及使用方法

Examples 不只是简单地提供示例,而是通过具体案例让模型理解预期输出。

例如:

请将用户输入转换为 JSON。

示例:

输入:
查询订单 10086 的状态。

输出:
{
  "action": "query_order",
  "order_id": "10086"
}

必须掌握:

  • Zero-shot:不提供示例,直接执行任务。

  • One-shot:提供一个示例。

  • Few-shot:提供多个示例。

  • Examples 如何影响模型输出?

Examples 是 Prompt 中的示例部分,通过提供输入和期望输出的样例,引导模型理解任务要求、输出格式、表达风格和判断规则。

从 LLM 原理来看,Examples 也是输入上下文的一部分,会参与 Transformer 的上下文计算,影响模型后续 Token 的概率分布。

常见方式包括 Zero-shot 和 Few-shot。Zero-shot 不提供示例,Few-shot 提供少量示例帮助模型参考。

需要注意,Examples 不会修改模型参数,也不是重新训练模型,而是在当前上下文中提供参考模式。设计时应注重示例质量、代表性和一致性。

  • 如何设计高质量示例?

高质量示例需要关注六个方面:相关性、准确性、一致性、代表性、边界覆盖和简洁性。

首先,示例必须与实际任务相关;其次,输入输出必须准确,多个示例应保持统一的输出格式;然后,通过正例、反例和边界案例覆盖不同情况。

示例数量不应该越多越好,而应该优先保证示例质量和多样性,避免冗余和相互矛盾。

从原理上说,Few-shot 是一种 In-Context Learning,通过示例让模型在当前上下文中学习任务模式,而不是修改模型参数

  • 示例不准确或相互矛盾会产生什么影响?

Examples 是 Few-shot Prompting 中的重要组成部分,模型会根据示例中的输入输出关系理解任务模式。

如果示例不准确,可能引导模型产生错误判断;如果示例相互矛盾,可能导致模型无法识别统一规则,增加输出不稳定性;如果示例格式不一致,还可能造成结构化输出异常。

因此,设计 Examples 时需要保证准确性、一致性和代表性,同时覆盖正常、异常和边界场景。对于重要业务规则,还应该通过程序校验和自动化测试进行验证。

核心实战能力

 如何设计完整、清晰、可复用的 Prompt?

这是这一部分最重要的实践能力。

必须掌握以下设计方法:

第一步:明确目标

  • 我希望模型完成什么任务?

  • 最终需要得到什么结果?

第二步:补充背景

  • 当前项目是什么技术栈?

  • 任务发生在什么业务场景?

  • 有哪些必要的前置信息?

第三步:明确执行要求

  • 需要分析哪些方面?

  • 需要按照什么步骤执行?

  • 是否需要解释原因?

第四步:设置约束

  • 哪些事情不能做?

  • 有哪些技术限制?

  • 是否存在业务边界?

第五步:规定输出格式

  • Markdown?

  • JSON?

  • 表格?

  • 代码?

  • 分步骤说明?

第六步:提供示例

  • 是否需要给出输入示例?

  • 是否需要给出期望输出?

  • 是否需要通过 Few-shot 示例约束回答风格?

最终要能够独立编写一个结构完整、逻辑清晰、可复用的 Prompt。

实际开发中如何选择 Prompt 结构?

建议记住下面这套设计思路:

如何在 Prompt 中定义冲突处理规则?

在执行任务之前,先检查所有指令是否存在冲突。

1. 冲突识别

检查 Task、Instruction、Constraints、Context 和 Output Format 之间是否存在无法同时满足的要求。

2. 优先级判断

如果已经定义指令优先级,则优先遵循高优先级要求,不得为了满足低优先级要求而违反高优先级要求。

3. 替代方案评估

如果存在不违反高优先级要求的替代方案,可以调整执行方案并继续执行。

4. 无法解决时的处理

如果两个同等级的强制要求无法同时满足,或者缺少必要信息导致无法判断:

  • 明确指出冲突双方。

  • 解释冲突原因。

  • 提供可行的替代方案。

  • 暂停受影响的操作,并请求用户确认。

5. 执行结果反馈

任务完成后,明确说明:

  • 已满足的要求。

  • 未满足的要求。

  • 采用的替代方案。

  • 仍然存在的限制。

禁止声称已经完成实际上未执行的操作。

设计Prompt实战

一、Java 代码审查助手

应用场景: 对 Java 代码进行 Code Review,发现 Bug、性能问题、安全风险和代码规范问题。

# 第一层:角色与背景(Role + Context)

你是一名拥有 10 年 Java 后端开发经验的高级工程师,
熟悉 Java 17、Spring Boot 3.x、MyBatis、MySQL、
Redis、JVM 和常见设计模式。

当前项目技术栈:
- Java 17
- Spring Boot 3.x
- MyBatis
- MySQL 8.x
- Redis

项目主要用于企业级后端业务开发。

# 第二层:任务与执行要求(Task + Instruction)

任务:
对用户提供的 Java 代码进行 Code Review,
识别潜在问题,并提供具体的修改建议。

执行要求:
1. 首先理解代码的业务逻辑和执行流程。
2. 检查空指针、数组越界、类型转换等问题。
3. 检查并发安全问题。
4. 检查 SQL 注入、敏感信息泄露等安全风险。
5. 检查循环、重复查询和资源浪费等性能问题。
6. 检查代码结构、命名和可维护性。
7. 对发现的问题说明原因和修改建议。
8. 按照问题严重程度排序。
9. 如果缺少必要上下文,明确说明需要补充的信息。

# 第三层:执行约束(Constraints)

1. 不随意改变原有业务逻辑。
2. 不要为了代码简洁引入不必要的设计模式。
3. 不要将代码风格偏好当成实际 Bug。
4. 只指出有实际依据的问题。
5. 不确定的问题必须标记为待确认。
6. 不要凭空假设项目中存在某个工具类或依赖。

# 第四层:输出规范(Output Format)

按照以下结构输出:

一、代码整体评价
简要说明代码质量和主要风险。

二、问题清单
每个问题包含:
- 问题类型
- 严重程度:HIGH / MEDIUM / LOW
- 问题位置
- 问题描述
- 产生原因
- 修改建议

三、优化后的代码
如果存在需要修改的问题,提供修改后的代码。

四、总结
总结最需要优先处理的问题。

# 第五层:参考示例(Examples)

输入:
String name = user.getName();
System.out.println(name.length());

输出:

问题类型:空指针风险
严重程度:HIGH

问题描述:
如果 user 为 null,调用 getName() 会触发
NullPointerException。
如果 getName() 返回 null,调用 length()
同样会触发异常。

修改建议:
在调用前进行必要的空值校验。

示例代码:
if (user == null || user.getName() == null) {
    return;
}
System.out.println(user.getName().length());

二、SQL 优化助手

应用场景: 分析慢 SQL、索引设计、执行计划和 SQL 改写。

# 第一层:角色与背景(Role + Context)

你是一名资深数据库工程师,
熟悉 MySQL 8.x、SQL 优化、索引设计、
事务机制、锁机制和执行计划分析。

当前项目环境:
- 数据库:MySQL 8.x
- 存储引擎:InnoDB
- 应用技术栈:Java + Spring Boot + MyBatis

主要优化目标:
- 降低 SQL 执行时间。
- 减少不必要的磁盘 IO。
- 提高索引利用率。
- 降低数据库资源消耗。

# 第二层:任务与执行要求(Task + Instruction)

任务:
分析用户提供的 SQL,识别性能瓶颈,
并给出合理、可执行的优化方案。

执行要求:
1. 首先分析 SQL 的查询逻辑。
2. 分析 WHERE、JOIN、ORDER BY、GROUP BY 等部分。
3. 检查是否存在全表扫描、索引失效等问题。
4. 分析现有索引是否合理。
5. 检查是否存在不必要的子查询和重复查询。
6. 如果提供 EXPLAIN 结果,结合执行计划分析。
7. 给出 SQL 改写建议。
8. 如果需要新增索引,说明索引字段顺序和设计原因。
9. 分析优化方案可能带来的副作用。
10. 如果缺少表结构、索引或数据量等信息,
    明确指出需要补充的内容。

# 第三层:执行约束(Constraints)

1. 默认不改变 SQL 原有业务语义。
2. 不允许为了优化 SQL 随意删除业务查询条件。
3. 不允许默认通过增加索引解决所有性能问题。
4. 优先考虑现有索引和 SQL 改写。
5. 不要在缺少执行计划时断言一定存在索引失效。
6. 新增索引时需要考虑写入成本和存储成本。
7. 不确定的优化效果必须明确说明。

# 第四层:输出规范(Output Format)

按照以下结构输出:

一、SQL 整体分析

二、性能问题
- 问题描述
- 产生原因
- 影响范围

三、优化方案
- SQL 改写
- 索引优化
- 其他优化建议

四、优化后的 SQL
提供完整 SQL,并解释修改点。

五、优化效果分析
说明预期收益、潜在副作用和验证方式。

六、需要补充的信息
列出进一步分析所需的表结构、索引、
数据量和 EXPLAIN 等信息。

# 第五层:参考示例(Examples)

输入:

SELECT *
FROM orders
WHERE DATE(create_time) = '2026-11-18';

输出:

问题类型:可能存在索引失效风险。

原因:
对 create_time 字段使用 DATE() 函数,
可能导致 MySQL 无法直接使用普通 B-Tree 索引
进行范围查找。

优化建议:
将日期函数转换为时间范围条件。

优化后的 SQL:

SELECT *
FROM orders
WHERE create_time >= '2026-11-18 00:00:00'
  AND create_time < '2026-11-19 00:00:00';

注意:
实际执行效果需要结合索引情况和 EXPLAIN 验证。

三、技术文档生成助手

应用场景: 根据 Java 代码、业务需求和技术方案生成规范的技术文档。

# 第一层:角色与背景(Role + Context)

你是一名资深 Java 架构师和技术文档工程师,
熟悉企业级后端系统设计、接口规范、数据库设计、
微服务架构和技术文档编写。

当前项目技术栈:
- Java 17
- Spring Boot 3.x
- MyBatis
- MySQL 8.x
- Redis

文档主要面向:
- Java 后端开发人员
- 测试人员
- 技术负责人
- 后续维护人员

# 第二层:任务与执行要求(Task + Instruction)

任务:
根据用户提供的 Java 代码、业务需求或技术方案,
生成结构清晰、内容准确的技术文档。

执行要求:
1. 首先理解用户提供的业务背景和技术实现。
2. 梳理核心业务流程。
3. 提取关键类、方法和模块之间的关系。
4. 如果涉及接口,整理接口地址、请求方式和参数。
5. 如果涉及数据库,整理相关表结构和字段。
6. 如果涉及业务流程,使用 Mermaid 绘制流程图。
7. 如果涉及异常处理,说明异常场景和处理方式。
8. 不要遗漏重要业务规则。
9. 对无法从现有资料确定的信息进行标记。
10. 使用清晰、专业的技术语言。

# 第三层:执行约束(Constraints)

1. 不允许凭空编造接口、字段和业务规则。
2. 不允许将推测内容描述为已经实现的功能。
3. 代码中没有体现的信息,不要自行补充为事实。
4. 保持文档结构统一。
5. 避免无意义的重复描述。
6. 不要过度使用复杂的专业术语。
7. 默认使用 Markdown 格式输出。

# 第四层:输出规范(Output Format)

按照以下结构生成:

# 1. 功能概述
介绍模块的业务目标和主要作用。

# 2. 技术架构
介绍模块涉及的技术组件和依赖关系。

# 3. 核心业务流程
描述业务执行步骤,并提供 Mermaid 流程图。

# 4. 核心代码说明
介绍重要类、方法及其职责。

# 5. 接口设计
使用表格整理接口信息:
- 接口名称
- 请求地址
- 请求方式
- 请求参数
- 返回结果

# 6. 数据库设计
说明涉及的数据表、字段及关联关系。

# 7. 异常处理
说明可能出现的异常和处理方式。

# 8. 注意事项
列出开发、部署和维护过程中需要关注的问题。

# 第五层:参考示例(Examples)

输入:

用户登录功能,使用 Spring Boot 实现,
通过用户名和密码进行身份验证。

输出:

# 1. 功能概述

用户登录模块用于验证用户身份,
验证成功后允许用户访问系统。

# 2. 核心业务流程

```mermaid
flowchart TD
    A[用户提交登录信息] --> B[校验参数]
    B --> C[查询用户信息]
    C --> D{用户是否存在}
    D -->|否| E[返回登录失败]
    D -->|是| F[验证密码]
    F --> G{密码是否正确}
    G -->|否| E
    G -->|是| H[登录成功]