From a012083cbbe05299df691d3f86c4e288d1f946e2 Mon Sep 17 00:00:00 2001 From: Klein Date: Thu, 11 Dec 2025 10:41:02 +0800 Subject: [PATCH] =?UTF-8?q?add(docs):=20=E6=96=B0=E5=A2=9E=E6=96=B0?= =?UTF-8?q?=E7=9A=84Prompt=E6=96=87=E6=A1=A3=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Prompt模板/01_架构设计与分析模板库.md | 596 ++++++++++++++++++ Prompt模板/02_代码实现与重构模板库.md | 595 ++++++++++++++++++ Prompt模板/03_审查与质量保障模板库.md | 727 ++++++++++++++++++++++ Prompt模板/04_文档编写与知识管理模板库.md | 524 ++++++++++++++++ Prompt模板/05_Agent优化与修改模板库.md | 381 ++++++++++++ Prompt模板/06_Agent创造与生成模板库.md | 428 +++++++++++++ 6 files changed, 3251 insertions(+) create mode 100644 Prompt模板/01_架构设计与分析模板库.md create mode 100644 Prompt模板/02_代码实现与重构模板库.md create mode 100644 Prompt模板/03_审查与质量保障模板库.md create mode 100644 Prompt模板/04_文档编写与知识管理模板库.md create mode 100644 Prompt模板/05_Agent优化与修改模板库.md create mode 100644 Prompt模板/06_Agent创造与生成模板库.md diff --git a/Prompt模板/01_架构设计与分析模板库.md b/Prompt模板/01_架构设计与分析模板库.md new file mode 100644 index 0000000..2f80d84 --- /dev/null +++ b/Prompt模板/01_架构设计与分析模板库.md @@ -0,0 +1,596 @@ +#### A. 类别一：架构设计与分析 (Architecture & Design) + +**模板索引 (Index)** + +| 模板ID | 核心用途 | 使用场景 / 关键词 | +| :--- | :--- | :--- | +| **A-1: 需求与约束** | | | +| **[`A1`](#A1)** | 技术方案对比 | `gRPC vs REST`, `CUDA vs OpenCL`, `Kafka vs RabbitMQ`, 选型报告 | +| **[`A2`](#A2)** | NFR（非功能性）验证 | 瓶颈计算, 性能估算, 延迟验证, `PCIe`, 带宽, 信封计算 | +| **[`A3`](#A3)** | 需求澄清 (苏格拉底) | 需求模糊, 启动新模块, 收集约束, 提问模式 | +| **A-2: 高层架构 (HLD)** | | | +| **[`A4`](#A4)** | API 接口设计与评审 | `gRPC`, `REST`, `.proto`, `OpenAPI`, 接口定义, 评审 | +| **[`A5`](#A5)** | 流程/架构图生成 | `Mermaid`, `PlantUML`, 文本转图表, 数据流图, 序列图 | +| **[`A6`](#A6)** | 体系架构模式选型 | `微服务 vs 单体`, `事件驱动`, `CQRS`, 架构选型 | +| **[`A7`](#A7)** | 部署拓扑设计 | `Kubernetes`, `AWS`, `私有化`, 高可用 (HA), 部署图 | +| **[`A8`](#A8)** | 技术风险与威胁建模 | `STRIDE`, `DREAD`, 风险分析, 安全审查, 架构证伪 | +| **[`A9`](#A9)** | 成本与资源估算 | 容量规划, 成本模型, `TCO`, 资源预估, `AWS 估价` | +| **A-3: 低层设计 (LLD)** | | | +| **[`A10`](#A10)** | 数据模型/数据库选型 | `SQL vs NoSQL`, `时序数据库`, `Schema设计`, `CREATE TABLE` | +| **[`A11`](#A11)** | 组件间交互模式 | `同步 vs 异步`, `共享内存`, `gRPC vs 消息队列`, 接口契约 | +| **[`A12`](#A12)** | 系统级策略设计 | 错误处理, 日志规范, 重试策略, 幂等性, 横切关注点 | +| **A-4: 评审与迭代** | | | +| **[`A13`](#A13)** | 遗留系统重构 | 架构评审, 现代化, 绞杀者模式, 增量重构 | +| **[`A14`](#A14)** | 多方案优劣对比 | Pros/Cons, 决策矩阵, 方案对比 | + +----- + +**子类别 A-1: 需求与约束分析 (Discovery & Requirement)** + + + +----- + +**模板名称：** `A1: 技术方案对比` +**适用场景：** 在架构设计（HLD）早期，当面临多个技术选项（如 `CUDA vs. OpenCL`, `gRPC vs. REST`, `Kafka vs. RabbitMQ`）时，需要一份客观、全面、且基于团队特定需求的对比分析报告。 +**内嵌原则：** `[原则七：结构化输出]` (强制使用Markdown表格), `[原则五：上下文即燃料]` (依赖用户提供的精确需求), `[原则二：玻璃盒心态]` (要求AI列出分析依据)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通 [领域，例如：异构计算/分布式系统] 的资深系统架构师。 + +任务：为我的团队提供一份关于 [技术选项A] 与 [技术选项B] 的技术选型对比报告。 + +== 核心业务上下文 == +我们的核心需求是： +1. [关键需求1，例如：极低延迟 (L_latency <= 100μs)] +2. [关键需求2，例如：海量并行运算] +3. [团队现状，例如：团队有C++基础，但GPU经验为零] +4. [其他关键约束，例如：成本预算、部署环境等] + +== 分析维度 == +你必须从以下维度进行分析，并以Markdown表格形式呈现： +1. [对比维度1，例如：性能与延迟]：(必须结合我们的[关键需求1]进行分析) +2. [对比维度2，例如：开发复杂度与学习曲线]：(必须结合我们的[团队现状]进行分析) +3. [对比维度3，例如：生态系统与维护成本] +4. [对比维度4，例如：可扩展性与弹性] + +== 最终交付 == +1. Markdown对比表格。 +2. 基于上述所有分析的、明确的最终选型建议，并详细说明推荐理由。 +``` + +**填充指南：** + + - `[领域]`：替换为AI需要扮演的专家角色，如“分布式系统”、“高性能计算”。 + - `[技术选项A/B]`：替换为具体技术，如 `gRPC` vs `RESTful API`。 + - `[核心业务上下文]`：**此部分至关重要**。必须提供清晰、量化的需求（NFRs）和团队现状，AI的分析质量与此强相关（原则五）。 + - `[对比维度]`：可根据实际需求增删，维度越具体，分析越深入。 + + + +----- + +**模板名称：** `A2: 非功能性需求（NFR）验证` +**适用场景：** 在架构设计早期，用于对关键的非功能性需求（NFR）进行“信封背面计算”（Back-of-the-envelope calculation），以快速验证架构假设的可行性（如 `2.2.2` 的PCIe瓶颈分析）。 +**内嵌原则：** `[原则二：玻璃盒心态]` (强制要求展示计算步骤), `[原则五：上下文即燃料]` (所有计算依赖精确的上下文输入)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通 [相关领域，例如：HPC/网络/数据库] 的性能分析专家。 + +== 架构上下文 == +1. [组件A，例如：x86 CPU (Host)] +2. [组件B，例如：NVIDIA GPU (Device)] +3. [连接方式，例如：PCIe Gen 4.0 (x16通道)] +4. [数据流描述，例如：一个 256 MB 的数据块] + +== 待验证的NFR（非功能性需求）== +* [关键指标，例如：端到端延迟 L_latency <= 100μs] + +== 任务 == +基于上述上下文，请对 [待分析的瓶颈，例如：PCIe数据传输延迟] 进行量化计算： + +1. 计算 [组件/连接] 的理论峰值 [指标，例如：带宽 (GB/s)]。（请列出基准值） +2. 计算处理 [数据流描述] 所需的理论最小 [指标，例如：延迟 (μs)]。 +3. 分析结论： 基于你的计算结果，分析 [待分析的瓶颈] 是否会突破我们的 [关键指标] 预算，或构成系统性能瓶颈。 +4. 必须展示你的所有计算步骤和引用的公式/基准值。 +``` + +**填充指南：** + + - `[相关领域]`：替换为AI需要扮演的专家角色。 + - `[架构上下文]`：必须提供所有相关的、**量化**的参数。 + - `[待验证的NFR]`：明确指出你的性能红线。 + - `[待分析的瓶颈]`：明确告知AI需要计算“什么”。 + + + +----- + +**模板名称：** `A3: 需求澄清与约束分析 (Socratic Mode)` +**适用场景：** 对应痛点3。当接到一个模糊的新需求（如“做一个日志模块”），在开始设计（HLD）之前，用于暴露工程师的思维盲点、强制AI收集完整上下文。 +**内嵌原则：** `[原则三：苏格拉底模式]` (核心), `[痛点3：苏格拉底模式的非持久性]` (使用“状态机”模式解决)。 + +**[Prompt 模板]** + +```txt +角色：你现在是一个“资深系统需求分析师”，不是一个“解决方案生成器”。 + +== 你的唯一目标 == +从我这里获取关于 [我的模糊需求，例如：设计一个新的“XX”模块] 的完整、无歧义的需求规格。 + +== 你的行动循环（状态机） == +1. [提问] 你向我提出一组（不多于5个）最关键的问题，以收集必要信息。 +2. [等待] 我会回答你。 +3. [审查] 你必须审查我的回答。 +4. [循环/退出] + - IF（信息不全）： 如果我的回答缺少关键信息（例如：性能、并发、数据、安全等约束），你必须回到[提问]状态，并只能向我追问缺失的特定信息。 + - IF（信息完整）： 只有当你确认所有NFR都已明确，你才能退出循环，并回复“需求收集完整，已准备好进行下一步设计。” + +== 关键约束 == +* 严禁在信息收集完整之前，提供任何解决方案、代码或设计建议。 +* 如果你追问了3次，我仍然没有提供A，你应停止并报告：“我缺少A信息，无法继续。” + +开始吧： +我的任务是 [我的模糊需求，例如：“我需要为我们的雷达系统设计一个日志模块”] 。 +请开始你的[提问]。 +``` + +**填充指南：** + + - `[我的模糊需求]`：替换为你接到的原始、模糊的任务描述。 + - **使用指南：** 工程师的角色是“回答者”。此模板的核心是“强制AI追问”。如果AI在中途“放弃”并提供了方案，请立即提醒它：“你违反了‘关键约束’，请继续提问。” + +----- + +**子类别 A-2: 高层架构设计 (High-Level Design)** + + +----- + +**模板名称：** `A4: API 接口设计与评审` +**适用场景：** + +1. **设计 (Creation):** 当你需要为新模块或服务从零开始设计一个健壮的、可扩展的API时（如 `gRPC`, `RESTful OpenAPI`）。 +2. **评审 (Review):** 当你有一个已存在的API定义（如 `.proto`, `yaml` 或 `.h` 文件），需要AI扮演评审专家，分析其设计缺陷。 + **内嵌原则：** `[原则七：结构化输出]` (强制生成代码/Schema), `[原则八：自我批判]` (在评审模式下), `[原则五：上下文即燃料]` (必须提供业务需求)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通 [技术栈，例如：gRPC/RESTful API] 和 [领域，例如：C++高性能服务] 的系统架构师。 + +== 核心业务上下文 == +* 模块/服务名称：[例如：RadarTrackService] +* 核心功能：[例如：负责接收、查询和管理雷达航迹数据] +* 关键NFRs：[例如：查询QPS高，写入延迟低，接口必须强类型] + +== 任务 (二选一) == + +[任务A：设计新接口] +1. 请为该服务设计一套 [技术栈，例如：gRPC (.proto)] 接口。 +2. 必须包含 [功能点1，例如：一个 CreateTrack RPC]。 +3. 必须包含 [功能点2，例如：一个 GetTrackByID RPC]。 +4. 设计必须考虑 [关键设计点，例如：幂等性、错误处理]。 +5. 交付 [技术栈] 的完整代码定义。 + +[任务B：评审现有接口] +1. 这是我现有的接口定义：[粘贴你的.proto/OpenAPI yaml/.h文件内容] +2. 请严格审查此设计，识别所有潜在的设计缺陷。 +3. 审查重点： + - [评审点1，例如：API的健壮性/错误处理（Error Handling）] + - [评审点2，例如：接口的幂等性（Idempotency）] + - [评审点3，例如：命名规范与一致性] + - [评审点4，例如：是否易于扩展（Extensibility）] +4. 以结构化列表形式返回 [缺陷]、[风险] 和 [修改建议]。 +``` + +**填充指南：** + + - `[技术栈]`：明确指定，如 `gRPC (.proto)` 或 `RESTful API (OpenAPI 3.1 Spec)`。 + - `[领域]`：明确AI的专业背景。 + - `[核心业务上下文]`：必须提供，AI的设计质量依赖于此。 + - `[任务 (二选一)]`：使用时，请删除你不用的那个任务（A或B）。 + - `[评审点]`：在评审时，提供你最关心的审查维度。 + + + +----- + +**模板名称：** `A5: 流程/架构图生成` +**适用场景：** 在架构设计或文档编写时，需要将非结构化的文本描述（如会议纪要、设计思路）快速转换为结构化的、可维护的“代码图”（Diagrams as Code）。 +**内嵌原则：** `[原则七：结构化输出]` (输出必须是代码), `[原则五：上下文即燃料]` (输入是文本描述)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通 "Diagrams as Code" 工具的系统架构师。 + +任务：请将以下非结构化的“流程描述”，严格转换为 [图表工具] 语法的代码。 + +== 流程描述 == +[粘贴你的流程描述文本。例如： +“数据首先进入ADC进行采样，采样后的I/Q数据被送到FPGA进行数字下变频和滤波。FPGA处理完的数据通过PCIe总线发送给CPU。CPU端的接收服务（Receiver Service）负责数据包的解包和重组，然后将数据块（Data Block）放入一个共享内存队列。GPU端的信号处理流水线（Signal Processing Pipeline）从队列中获取数据，依次执行脉冲压缩、多普勒处理（FFT），最后进行CFAR检测并输出目标列表。” +] + +== 输出约束 == +1. 图表工具：[例如：Mermaid] +2. 图表类型：[例如：Flowchart (graph TD)] +3. (可选) 视觉要求：[例如：请将FPGA、CPU、GPU相关的组件分别放入不同的子图(subgraph)中] +4. 严禁返回除 [图表工具] 代码块之外的任何解释性文字。 +``` + +**填充指南：** + + - `[流程描述]`：**描述越清晰，AI的布局越准确。** + - `[图表工具]`：明确指定，如 `Mermaid` 或 `PlantUML`。 + - `[图表类型]`：明确指定，如 `Flowchart (graph TD)`, `Sequence Diagram`, `Component Diagram` 等。 + - `[视觉要求]`：可选，但非常有用。你可以用它来指导AI的布局和分组。 + + + +----- + +**模板名称：** `A6: 体系架构模式选型` +**适用场景：** 在HLD（高层设计）阶段，当面临（如 微服务 vs. 模块化单体）等根本性的架构模式抉择时，需要AI辅助分析不同模式在特定业务场景下的优劣。 +**内嵌原则：** `[原则七：结构化输出]` (强制表格), `[原则五：上下文即燃料]` (业务场景是关键), `[原则二：玻璃盒心态]` (解释依据)。 + +**[Prompt 模板]** + +```txt +角色：你是一名资深的企业架构师，精通各种软件架构模式。 + +== 核心业务上下文 == +- 项目背景：[例如：构建一个大型、长生命周期的雷达信号处理与C2系统] +- 业务特征：[例如：包含多个独立的、功能复杂的领域（如：波形生成、信号处理、数据显示、航迹管理）] +- 团队结构：[例如：多个（~5个）小型、跨职能的开发团队] +- 关键NFRs：[例如：不同模块的可靠性（SLA）要求不同；信号处理模块需要独立扩展] + +== 任务 == +请对比 [架构模式A，例如：微服务架构] 与 [架构模式B，例如：模块化的单体架构] 在上述核心业务上下文中的适用性。 + +== 分析维度 (必须以此为准) == +1. 性能与延迟 (Performance & Latency) +2. 可扩展性与弹性 (Scalability & Resilience) +3. 开发复杂度 (Development Complexity) +4. 团队认知负荷 (Team Cognitive Load) (必须结合[团队结构]分析) +5. 运维复杂度 (Operational Complexity) +6. 故障隔离能力 (Fault Isolation) + +== 最终交付 == +1. 一个包含上述所有维度的、详细的Markdown对比表格。 +2. 一个明确的选型建议，并详细阐述其为什么最适合我们的[业务特征]和[团队结构]。 +``` + +**填充指南：** + + - `[核心业务上下文]`：必须提供。AI的选型质量100%取决于你对业务和团队的描述是否准确。 + - `[架构模式A/B]`：替换为具体模式，如 `事件驱动架构` vs. `请求-响应架构`，`分层架构` vs. `CQRS`。 + - `[分析维度]`：可根据需求增删。 + + + +----- + +**模板名称：** `A7: 部署拓扑设计` +**适用场景：** 当HLD（高层设计）完成后，需要为系统设计一个满足特定NFR（特别是HA、DR、成本）的部署架构。 +**内嵌原则：** `[原则五：上下文即燃料]` (NFR是设计的唯一依据), `[原则七：结构化输出]` (返回结构化列表)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通 [技术栈，例如：Kubernetes/AWS] 的DevOps架构师（SRE）。 + +== 架构与NFRs（非功能性需求）== +- 系统架构：[例如：一个由 3个微服务 + 1个GPU密集型处理服务 + 1个PostgreSQL数据库 组成的C++系统] +- 部署环境：[例如：私有化数据中心（On-premise）的裸金属服务器] +- 关键NFR 1 (HA)：[例如：必须实现高可用性，能容忍单台服务器物理故障] +- 关键NFR 2 (Scalability)：[例如：GPU密集型服务必须能独立、水平扩展] +- 关键NFR 3 (Cost)：[例如：成本受限，优先利用现有硬件] + +== 任务 == +基于上述所有约束，请为该系统设计一个推荐的部署拓扑。 + +== 最终交付 == +请结构化地返回以下信息： +1. 推荐的编排技术： [例如：K3s (轻量级Kubernetes), Docker Swarm, 或 纯Systemd管理] 并说明选择理由。 +2. 核心组件拓扑： + - (例如) 接入层：[如何实现，例如：使用Nginx/HAProxy做L4负载均衡和健康检查] + - (例如) 无状态服务(3个)：[如何部署，例如：作为K8s Deployment, 副本数=3] + - (例如) GPU密集型服务：[如何部署，例如：使用K8s的NVIDIA Device Plugin, 部署为DaemonSet或特定NodePool] + - (例如) 数据库(PostgreSQL)：[如何部署，例如：使用Patroni/Stolon构建主从复制（HA）集群] +3. 关键风险： 指出此拓扑方案的一个主要风险点或运维难点。 +``` + +**填充指南：** + + - `[技术栈]`：明确AI的专业背景，如 `Kubernetes`, `AWS`, `Azure` 或 `边缘计算`。 + - `[架构与NFRs]`：**必须提供。** 尤其是“部署环境”（公有云/私有化/边缘）和“NFRs”，这是拓扑设计的核心依据。 + + + +----- + +**模板名称：** `A8: 技术风险与威胁建模` +**适用场景：** 对一个已提出的架构设计方案（HLD或LLD）进行“证伪”和“压力测试”，主动识别其设计盲点、技术风险和安全威胁。 +**内嵌原则：** `[原则八：自我批判]` (AI扮演评审专家), `[原则二：玻璃盒心态]` (强制AI分析)。 + +**[Prompt 模板]** + +```txt +角色：你是一名资深的、吹毛求疵的首席工程师，精通技术风险识别和安全威胁建模。 + +== 架构方案上下文 == +[粘贴你的架构设计方案描述。例如： +“我们设计了一个数据摄取服务。它暴露一个gRPC API (IngestData) 接收数据，数据首先被写入Kafka集群（TopicA），然后由一个GPU消费者（ConsumerA）订阅TopicA，进行处理后，将结果写入PostgreSQL数据库。” +] + +== 任务 == +请严格审查以上架构方案，从“技术风险”和“安全威胁”两个维度进行分析。 + +== 交付1：技术风险分析 == +请识别此架构中潜在的技术风险（非安全类），至少包括： +1. [风险1，例如：单点故障 (SPOF)] +2. [风险2，例如：性能瓶颈] +3. [风险3，例如：可扩展性限制] +(对每一项，请说明风险点和可能的缓解措施) + +== 交付2：安全威胁建模 (STRIDE) == +请使用 STRIDE 模型，分析此架构（特别是gRPC API和Kafka）的潜在安全威胁： +1. Spoofing (仿冒)： +2. Tampering (篡改)： +3. Repudiation (否认)： +4. Information Disclosure (信息泄露)： +5. Denial of Service (拒绝服务)： +6. Elevation of Privilege (权限提升)： +(对每一项，请分析可能的攻击向量和缓解措施) +``` + +**填充指南：** + + - `[架构方案上下文]`：**必须提供。** 描述越详细（组件、协议、数据流），AI分析越精确。 + - `[STRIDE]`：你也可以替换为 `DREAD` 或其他威胁建模框架，或者直接让AI“分析所有安全威胁”。 + + + +----- + +**模板名称：** `A9: 成本与资源估算` +**适用场景：** 在架构设计或预算规划阶段，需要对一个架构方案进行（通常是粗略的）硬件或云资源需求估算。 +**内嵌原则：** `[原则二：玻璃盒心态]` (强制AI展示其估算依据), `[原则五：上下文即燃料]` (估算依赖于负载输入)。 + +**[Prompt 模板]** + +```txt +角色：你是一名资深的云架构师和容量规划（Capacity Planning）专家。 + +== 架构方案 == +[粘贴你的架构设计方案，例如： +1. gRPC网关服务 (C++) +2. GPU信号处理服务 (CUDA C++) +3. PostgreSQL数据库 (用于元数据) +] + +== 预估负载（NFRs）== +1. [指标1，例如：并发请求数: 1000 QPS (峰值)] +2. [指标2，例如：日处理数据量: 10TB/day] +3. [指标3，例如：GPU处理时延: < 50ms per block] +4. [指标4，例如：数据保留周期: 30天] + +== 任务 == +基于上述架构和预估负载，请为我估算部署此系统（以满足NFRs）所需的核心资源。 + +== 交付（结构化列表） == +请返回一个估算列表，并必须说明你的估算依据（Rationale）： +1. GPU处理服务： + - (估算) GPU型号/数量：[例如：NVIDIA T4 / A100，xx卡] + - (估算) 显存(VRAM)：[xx GB] + - (估算) 服务器RAM：[xx GB] + - (Rationale)：[解释你为什么这么估算，例如：基于[指标3]和[指标2]...] +2. gRPC网关服务： + - (估算) CPU核数/RAM：[xx vCPU / xx GB] + - (Rationale)：[解释，例如：基于[指标1]处理网络I/O...] +3. PostgreSQL数据库： + - (估算) 存储空间：[xx TB] + - (Rationale)：[解释，例如：基于[指标4]...] +``` + +**填充指南：** + + - `[预估负载（NFRs）]`：**估算质量的唯一依据。** 你提供的数字越精确，AI的估算越有价值。如果缺少数据，AI的回答也会是“幻觉”。 + - `[Rationale]`：强制AI解释其计算过程，这是“玻璃盒”原则的体现，能让你判断它的估算是否合理。 + +----- + + +**子类别 A-3: 低层模块设计 (Low-Level Design)** + + +----- + +**模板名称：** `A10: 数据模型与数据库选型` +**适用场景：** 在LLD（低层设计）阶段，需要为特定数据（如：雷达航迹、I/Q原始数据、配置参数）设计存储Schema，并对比不同数据库技术（如 时序库 vs. 关系库 vs. 缓存）的适用性。 +**内嵌原则：** `[原则七：结构化输出]` (强制Schema和表格), `[原则五：上下文即燃料]` (数据特征是关键), `[原则二：玻璃盒心态]` (解释依据)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通数据建模和数据库架构的专家（DBA）。 + +== 数据特征与业务上下文 == +1. 数据类型：[例如：雷达目标航迹数据] +2. 核心实体与字段：[例如：Track (TrackID, x, y, z, vx, vy, vz, timestamp)] +3. 主要读操作：[例如：高频的“按时间范围”和“按TrackID”查询] +4. 主要写操作：[例如：高并发、持续的“追加写入”（Append-only）] +5. 数据量/增长率：[例如：每天新增 1 亿条航迹点] +6. 一致性要求：[例如：最终一致性即可] + +== 任务 == +基于上述特征，请完成以下工作： +1. 技术选型： 对比 [技术A, 例如：时序数据库 InfluxDB] 和 [技术B, 例如：关系型 PostgreSQL] 在此场景下的优劣（以Markdown表格呈现）。 +2. 选型建议： 给出明确的选型推荐及理由。 +3. Schema设计： 基于你的推荐，为 [核心实体] 设计一个推荐的数据模型或Schema（例如：InfluxDB的Line Protocol, 或PostgreSQL的CREATE TABLE语句）。 +``` + +**填充指南：** + + - `[数据特征与业务上下文]`：**此部分至关重要**。你对读/写操作、数据量、一致性要求的描述，将直接决定AI的选型质量。 + - `[技术A/B]`：明确你正在纠结的选项。 + - `[Schema设计]`：此项强制AI将其选型“落地”为具体实现，避免空谈。 + + + +----- + +**模板名称：** `A11: 组件间交互模式定义` +**适用场景：** 在LLD（低层设计）阶段，需要明确定义两个模块（如 模块A 和 模块B）之间的通信机制和数据契约（Data Contract）。 +**内嵌原则：** `[原则七：结构化输出]` (强制.proto或API定义), `[原则五：上下文即燃料]` (交互需求是关键)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通C++和分布式系统设计的软件架构师。 + +== 交互上下文 == +* 发送方 (Caller)：[例如：模块A (RadarControlService)] +* 接收方 (Callee)：[例如：模块B (GpuProcessingService)] +* 交互内容：[例如：模块A需要向模块B下发“处理配置参数”] +* 关键NFRs： + 1. [NFR 1, 例如：低延迟（< 1ms）] + 2. [NFR 2, 例如：强类型校验，防止配置错误] + 3. [NFR 3, 例如：需要支持异步调用] + +== 任务 == +1. 模式对比： 基于上述NFRs，对比 [模式A, 例如：同步gRPC] 和 [模式B, 例如：异步消息队列 (Kafka)] 的优劣（Markdown表格）。 +2. 模式推荐： 给出明确的推荐及理由。 +3. 接口定义： 基于你的推荐（假设推荐gRPC），请为 [交互内容] 设计一个 [接口定义文件，例如：.proto] 文件，包含必要的服务和消息定义。 +``` + +**填充指南：** + + - `[交互上下文]`：必须清晰定义谁调用谁、干什么、有什么要求。 + - `[模式A/B]`：替换为具体的交互模式，如 `共享内存` vs. `gRPC`，`RESTful` vs. `WebSocket`。 + - `[接口定义文件]`：强制AI生成“数据契约”，这是LLD的核心产出。 + + + +----- + +**模板名称：** `A12: 系统级策略设计` +**适用场景：** 在LLD（低层设计）阶段，用于设计跨多个模块的“横切关注点”（Cross-Cutting Concerns），如日志、错误处理、重试等，以确保系统行为一致性。 +**内嵌原则：** `[原则六：示例优先]` (提供示例), `[原则七：结构化输出]` (输出规范)。 + +**[Prompt 模板]** + +```txt +角色：你是一名资深的C++首席工程师，负责制定团队的工程规范。 + +任务：请为我们的系统设计一个统一的 [策略名称，例如：错误处理策略]。 + +== 策略要求 == +1. 背景：[例如：我们的系统是基于现代C++20构建的，但混合了部分C库] +2. 目标：[例如：统一C++层和C库层的错误，提供清晰的、可被上游服务消费的错误信息] +3. 禁止：[例如：禁止使用裸错误码（Magic Numbers），尽量避免过度使用异常（Exceptions）] + +== 交付产出 == +1. 推荐的策略： [例如：推荐使用 std::expected (C++23) 或类似的 Either Monad] +2. 设计理由： 为什么此策略优于 [其他方案，例如：纯异常 或 纯错误码]？ +3. 代码示例 (✅)： 提供一个“最佳实践”的代码示例，展示函数应如何返回错误。 +4. 代码示例 (❌)： 提供一个“反模式”的代码示例，展示应避免的写法。 +5. 规范定义： 提供一份简短的Markdown规范，供团队成员遵守。 +``` + +**填充指南：** + + - `[策略名称]`：替换为你需要设计的策略，如 `日志记录规范`, `分布式跟踪策略`, `幂等性实现策略`, `断路器设计`。 + - `[策略要求]`：提供你对该策略的约束和目标。 + - `[代码示例 ✅/❌]`：这是“示例优先”原则的应用，强制AI提供清晰的“Do / Don't”指南。 + +----- + +----- + +**子类别 A-4: 评审与迭代 (Review & Iteration)** + + +----- + +**模板名称：** `A13: 现有架构评审与重构建议` +**适用场景：** 当需要接手或重构一个遗留系统时，用于快速分析其架构现状、识别核心痛点，并提出一个可行的、渐进式的重构方案。 +**内嵌原则：** `[原则八：自我批判]` (AI扮演评审委员会), `[原则五：上下文即燃料]` (现状描述是关键), `[原则二：玻璃盒心态]` (分析问题根源)。 + +**[Prompt 模板]** + +```txt +角色：你是一个由多名资深架构师组成的“架构评审委员会”。 + +== 遗留系统上下文 == +[粘贴你对遗留系统的描述。例如： +“我们有一个C++单体应用（LegacySystem），它有20万行代码。所有模块（数据采集、信号处理、界面显示）都耦合在同一个进程中。 +核心痛点： +1. 编译时间极长（> 30分钟）。 +2. 信号处理模块（高CPU）和界面显示（低CPU）无法独立扩展。 +3. 任何小修改都可能导致全局不稳定，测试回归成本极高。” +] + +== 任务 == +请基于上述上下文，对该遗留系统进行架构评审。 + +== 交付（结构化报告） == +1. 核心问题诊断 (Diagnosis)： + - (AI分析) [例如：1. 高度耦合（Coupling）；2. 缺乏清晰的模块边界...] +2. 长期重构目标 (Target State)： + - (AI建议) [例如：建议演进为“模块化单体”或“微服务”架构] +3. 渐进式重构方案 (Incremental Plan)： + - (AI建议) [例如：推荐采用“绞杀者无花果模式”（Strangler Fig Pattern）。 + - 步骤1：[例如：在单体应用前部署一个“反向代理”（Proxy）...] + - 步骤2：[例如：将第一个模块（如“界面显示”）拆分为新服务，由Proxy路由...] + - 步骤3：[...]] +4. 主要风险： 指出此重构方案的最大风险。 +``` + +**填充指南：** + + - `[遗留系统上下文]`：**必须提供。** 描述越详细，尤其是“核心痛点”越清晰，AI的诊断和建议越有价值。 + - `[渐进式重构方案]`：这是此模板的核心。它要求AI提供的不是一个“推倒重来”的方案，而是一个可执行的、渐进的计划。 + + + +----- + +**模板名称：** `A14: 多方案优劣对比 (Pros/Cons Analysis)` +**适用场景：** 一个通用的“决策辅助”模板。当工程师在多个（已知的）选项之间犹豫不决时，用于代替（或补充）`A1`模板，快速获取一份无偏见的、结构化的对比矩阵。 +**内嵌原则：** `[原则七：结构化输出]` (强制表格), `[原则五：上下文即燃料]` (选项和场景是关键)。 + +**[Prompt 模板]** + +```txt +角色：你是一名客观、严谨的技术分析师。 + +== 决策上下文 == +- 我们的目标：[例如：实现一个高可用的PostgreSQL数据库] +- 我们的约束：[例如：部署在私有化K8s集群上] + +== 待评估的选项 == +- 选项A：[例如：使用 Patroni (基于Etcd/Consul)] +- 选项B：[例如：使用 Stolon (基于Etcd/Consul)] +- 选项C：[例如：使用云厂商（如AWS）的RDS Operator] + +== 任务 == +1. 请为我生成一个详细的Markdown对比表格，比较上述三个选项。 +2. 对比维度必须包括： + - [维度1，例如：架构复杂度] + - [维度2，例如：社区活跃度/成熟度] + - [维度3，例如：自动故障切换（Auto-Failover）能力] + - [维度4，例如：与K8s的集成度] +3. 根据我们的 [约束]，给出每个选项的“推荐指数”（例如：高/中/低）并说明理由。 +``` + +**填充指南：** + + - `[待评估的选项]`：由工程师（你）提供。 + - `[对比维度]`：由工程师（你）提供。 + - **使用指南：** 此模板与`A1`的区别在于，`A1`更侧重于“技术选型”（从0到1），而`A14`更侧重于“方案决策”（从1到N），即你心中已有几个备选方案。 diff --git a/Prompt模板/02_代码实现与重构模板库.md b/Prompt模板/02_代码实现与重构模板库.md new file mode 100644 index 0000000..f18024f --- /dev/null +++ b/Prompt模板/02_代码实现与重构模板库.md @@ -0,0 +1,595 @@ +#### B. 类别二：代码实现与重构 (Implementation & Refactoring) + +**模板索引 (Index)** + +| 模板ID | 核心用途 | 使用场景 / 关键词 | +| :--- | :--- | :--- | +| **B-1: 环境配置与脚手架** | | | +| **[`B1`](#B1)** | 构建系统与依赖配置 | CMake, 依赖管理, 构建脚本 | +| **[`B2`](#B2)** | 类/模块脚手架生成 | 头/源骨架, Doxygen, OOP | +| **B-2: 核心功能实现** | | | +| **[`B3`](#B3)** | 规格到代码实现 | 需求转代码, 伪代码, 算法实现 | +| **[`B4`](#B4)** | 串行代码并行化 | C++->CUDA, Kernel转换, 并行优化 | +| **[`B5`](#B5)** | 复杂API/SDK集成 | MWE示例, 第三方库, 初始化/释放 | +| **[`B6`](#B6)** | 防御性编码（接口依赖未就绪） | Stub, TODO, 假设注释, 接口占位 | +| **B-3: 性能优化与重构** | | | +| **[`B7`](#B7)** | 代码重构与现代化 | 智能指针, 模式重构, C++17/20 | +| **[`B8`](#B8)** | 性能瓶颈分析与优化 | 热点函数, 复杂度, 优化策略 | +| **[`B9`](#B9)** | CUDA Kernel 性能调优 | 显存访问, Occupancy, Warp | +| **B-4: 健壮性与并发安全** | | | +| **[`B10`](#B10)** | 错误处理与异常安全 | RAII, std::expected, 异常策略 | +| **[`B11`](#B11)** | 并发安全分析与实现 | Data Race, mutex/atomic, 线程安全 | +| **[`B12`](#B12)** | 日志与可观测性注入 | spdlog, tracing, 入口/出口日志 | +| **[`B13`](#B13)** | 跨语言代码转译 | MATLAB->C++, Python->C++, 代码迁移 | + +**子类别 B-1: 环境配置与脚手架 (Setup & Scaffolding)** + + + +----- + +**模板名称：** `B1: 构建系统与依赖配置` +**适用场景：** 在项目或模块初始化的第一步，需要为C++/CUDA项目生成一个健壮、可维护的`CMakeLists.txt`构建脚本。 +**内嵌原则：** `[原则七：结构化输出]` (输出必须是CMake代码), `[原则五：上下文即燃料]` (项目需求是关键)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通现代CMake (3.15+) 和C++/CUDA项目构建的专家。 + +任务：请为我的新项目/模块生成一个 `CMakeLists.txt` 文件。 + +== 项目需求 == +1. 项目名称：[例如：RadarProcessor] +2. 目标类型：[例如：动态链接库 (SHARED Library) / 静态链接库 (STATIC Library) / 可执行文件 (Executable)] +3. 目标名称：[例如：libRadarProcessor / radar_app] +4. 源文件：[例如：src/*.cpp, src/cuda/*.cu] (可以使用通配符) +5. C++ 标准：[例如：17] +6. (可选) CUDA 标准：[例如：11] +7. 依赖库 (使用 find_package)： + - [依赖1, 例如：Boost 1.80 REQUIRED COMPONENTS system thread] + - [依赖2, 例如：CUDA 12.0 REQUIRED] + - [依赖3, 例如：OpenCV 4 REQUIRED] +8. (可选) 包含目录 (Include Directories)：[例如：include/, ${Boost_INCLUDE_DIRS}] +9. (可选) 链接库 (Link Libraries)：[例如：${Boost_LIBRARIES}, ${CUDA_LIBRARIES}, ${OpenCV_LIBS}] + +== 输出要求 == +- 生成一个完整、格式良好、包含必要注释的 CMakeLists.txt 文件。 +- 必须使用现代CMake的最佳实践（例如，使用 target_link_libraries, target_include_directories）。 +``` + +**填充指南：** + + - `[项目需求]` 各项：**必须**根据你的实际项目情况进行精确填充。依赖库的查找方式（如 `find_package` 的 `COMPONENTS`）需要特别注意。 + - **使用指南：** 此模板生成的是基础配置。对于更复杂的构建（如条件编译、安装规则），可以在此基础上应用 `[原则一：敏捷提示]` 进行迭代式求精。 + + + +----- + +**模板名称：** `B2: 类/模块脚手架生成` +**适用场景：** 根据LLD（低层设计）或接口定义，快速生成C++类或模块的`.h`（头文件）和`.cpp`（源文件）骨架，包含必要的成员、方法声明/定义以及Doxygen注释模板，减少重复性劳动。 +**内嵌原则：** `[原则七：结构化输出]` (输出必须是C++代码), `[原则五：上下文即燃料]` (设计是关键)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通现代C++ (例如 C++17) 和面向对象设计的软件工程师，熟悉Doxygen注释规范。 + +任务：请为我生成一个C++类的完整脚手架（.h 和 .cpp 文件）。 + +== 类设计规格 == +1. 类名：[例如：DataProcessor] +2. (可选) 继承：[例如：public IProcessor] +3. (可选) 命名空间：[例如：namespace radar::processing { ... }] +4. 头文件 (.h) 要求： + - 包含必要的 #include (基于继承和成员类型猜测)。 + - 包含类的声明。 + - 包含 [构造函数/析构函数声明，例如：显式默认构造函数、虚析构函数]。 + - 包含 [成员变量声明，例如：private: std::vector buffer_;]。 + - 包含 [成员函数声明，例如：public: bool process(const InputData& data) override;]。 + - **必须**为类、构造/析构函数、成员变量、成员函数添加Doxygen注释模板（包含 @brief, @param, @return 等）。 +5. 源文件 (.cpp) 要求： + - 包含必要的 #include。 + - 包含所有成员函数的空实现（stub implementation），返回默认值（如false, 0, nullptr）。 + - **必须**在实现上方包含对应的Doxygen注释。 + +== 输出要求 == +* 分别提供 .h 文件和 .cpp 文件的完整内容，使用Markdown代码块包裹。 +``` + +**填充指南：** + + - `[类设计规格]` 各项：**必须**根据你的LLD进行填充。特别是继承关系和需要实现的成员函数列表。 + - **使用指南：** 此模板旨在生成“骨架”。AI生成的空实现仅为占位符，需要工程师后续填充具体逻辑。Doxygen注释也需要工程师补充详细描述。 + +----- + +**子类别 B-2: 核心功能实现 (Core Feature Implementation)** + + + +----- + +**模板名称：** `B3: 从“规格”到“代码”` +**适用场景：** 这是最通用的“新需求开发”模板，用于将任何形式的清晰“规格”描述（Specification）——无论是数学公式、伪代码、Jira票据描述、还是自然语言步骤——转化为具体的工程代码。 +**内嵌原则：** `[原则五：上下文即燃料]` (规格质量决定代码质量), `[原则二：玻璃盒心态]` (可选：要求解释复杂逻辑), `[原则七：结构化输出]` (输出代码)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通 [目标语言，例如：C++17] 和 [相关领域，例如：信号处理算法] 的专家。 + +任务：基于以下“规格”，请实现 [目标功能，例如：CFAR检测算法] 的核心逻辑。 + +== 规格 (Specification) == +[粘贴你的规格描述。可以是： +1. 数学公式 (LaTeX 格式) +2. 伪代码 (如 2.3.1 中的 CFAR 伪代码) +3. 清晰的自然语言步骤描述 +4. Jira Ticket / Requirement 文档片段 +] + +== 实现约束 == +1. 目标语言：[例如：C++17] +2. (可选) 依赖库：[例如：必须使用 std::vector, 禁止使用 Boost] +3. (可选) 性能要求：[例如：代码必须高效，避免不必要的内存分配] +4. (可选) 健壮性要求：[例如：必须健壮地处理边界条件/错误输入] +5. (可选) 接口要求：[例如：请将实现封装在一个函数/类中，函数签名/类定义如下：...] + +== 输出要求 == +- 提供 [目标语言] 的完整、可编译的代码实现。 +- (可选) 请在关键逻辑处添加必要的注释。 +- (可选, 应用玻璃盒原则) 如果算法复杂，请简要解释你的实现思路或关键步骤。 +``` + +**填充指南：** + + - `[目标语言]` 和 `[相关领域]`：明确AI的角色。 + - `[规格]`：**这是核心燃料。** 规格越清晰、无歧义，AI生成的代码越符合预期。 + - `[实现约束]`：用于精确控制AI的输出。例如，指定接口可以确保AI生成的代码能直接集成到你的项目中。 + + + +----- + +**模板名称：** `B4: 串行代码并行化 (C++ -> CUDA)` +**适用场景：** 解决团队核心痛点（痛点2）。用于将已在CPU上验证的、计算密集的C++串行算法（通常是循环），安全、高效地迁移为CUDA Kernel，并理解其并行化逻辑。 +**内嵌原则：** `[原则五：上下文即燃料]` (输入C++代码), `[原则二：玻璃盒心态]` (强制解释并行化逻辑), `[原则七：结构化输出]` (输出CUDA代码)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通CUDA C++ (例如 CUDA 12.0) 和并行计算优化（特别是针对NVIDIA GPU）的专家。 + +任务：请将以下C++串行代码改写为高性能的CUDA Global Kernel函数。 + +== C++ 串行代码上下文 == +// [粘贴你的C++串行代码，例如 2.2.3 中的pulse_compression_cpu 函数] +// 必须包含函数签名和核心逻辑实现。 +// 最好包含关于输入/输出数据规模的注释。 + +== CUDA Kernel 要求 == +1. Kernel函数名：[例如：pulse\_compression\_kernel] +2. 性能优化： + - [优化点1，例如：必须正确处理数据边界] + - [优化点2，例如：必须使用 Shared Memory 缓存 [某数据]，以减少 Global Memory 访问] + - (可选) [优化点3，例如：考虑使用 [某CUDA特性，如 warp intrinsics]] +3. 启动配置建议：请为 Grid 和 Block 的维度划分提供一个合理的启动配置建议（基于假设的数据规模）。 +4. **解释要求 (玻璃盒原则)：** + - 请解释你为什么选择这样的 Grid/Block 划分。 + - 请解释 [优化点2] (例如 Shared Memory) 的使用如何提升性能。 + - 请在代码关键位置（如同步点 __syncthreads()）添加注释解释其必要性。 + +== 输出要求 == + - 提供完整的 CUDA Kernel 函数定义 (__global__ void ...)。 + - 提供启动配置建议。 + - 提供上述要求的解释。 +``` + +**填充指南：** + + - `[C++ 串行代码上下文]`：提供完整的、可工作的C++代码片段。 + - `[CUDA Kernel 要求]`：**明确告知AI你的性能目标**。例如，显式要求使用Shared Memory，比让AI自己猜测效果更好。 + - `[解释要求]`：**强制要求AI解释其并行化策略**，这是确保你理解并能维护该CUDA代码的关键（玻璃盒原则）。 + + + +----- + +**模板名称：** `B5: 复杂API/SDK集成` +**适用场景：** 当你需要在一个新项目中使用一个不熟悉的第三方库或SDK（如 `libtorch`, `cuFFT`, `gRPC Client`, `AWS SDK`）时，快速获取一个“最小可用示例”（Minimal Working Example, MWE），以理解其基本用法（初始化、核心调用、资源释放）。 +**内嵌原则：** `[原则五：上下文即燃料]` (指定库和目标任务), `[原则六：示例优先]` (AI生成示例), `[原则七：结构化输出]` (输出代码)。 + +**[Prompt 模板]** +```txt +角色：你是一名精通 [目标库/SDK，例如：cuFFT v11.0] 和 [目标语言，例如：C++17] 的专家。 + +任务：请为我生成一个使用 [目标库/SDK] 完成 [具体任务，例如：执行一个1D复数到复数的FFT变换] 的最小可用示例 (MWE) 代码。 + +== 代码要求 == +1. 语言：[例如：C++17] +2. 必须包含所有必要的 #include 语句。 +3. 必须展示： + - [步骤1，例如：如何正确初始化cuFFT Plan (cufftPlan1d)] + - [步骤2，例如：如何在GPU上分配输入/输出缓冲区 (cudaMalloc)] + - [步骤3，例如：如何将数据从CPU拷贝到GPU (cudaMemcpy HostToDevice)] + - [步骤4，例如：如何执行核心函数调用 (cufftExecC2C)] + - [步骤5，例如：如何将结果从GPU拷贝回CPU (cudaMemcpy DeviceToHost)] + - [步骤6，例如：如何进行必要的错误检查 (检查CUDA API返回值)] + - [步骤7，例如：如何释放所有分配的资源 (cufftDestroy, cudaFree)] +4. 代码应尽可能简洁，只包含完成 [具体任务] 所必需的步骤。 +5. 请添加必要的注释解释关键步骤。 + +== 输出要求 == +- 提供一个完整的、可直接编译（假设依赖已安装）的 [目标语言] 代码文件。 +``` + +**填充指南：** + + - `[目标库/SDK]`：**越精确越好**，最好包含版本号。 + - `[目标语言]`：明确语言。 + - `[具体任务]`：**明确告知AI你想用这个库做什么**。任务越具体，示例越有用。 + - `[步骤1-7]`：列出你认为必须包含的关键步骤，指导AI生成完整的流程。 + + + +----- + +**模板名称：** `B6: 面向接口的防御性编码` +**适用场景：** 对应痛点4。当你正在实现模块A，而它依赖的模块B（通过接口 `IModuleB`）尚未完成时，用于强制AI生成包含明确假设、TODO标记和存根（Stub）的代码，严禁其“幻觉”出模块B的具体实现。 +**内嵌原则：** `[原则五：上下文即燃料]` (注入“模块B未完成”的元信息), `[原则七：结构化输出]` (强制特定的注释和存根格式)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通“面向接口设计”和“防御性编码”的C++专家。 + +== 上下文 == +- 我正在编写 [模块A，例如：DataProcessor 类]。 +- [模块A] 依赖于 [接口B，例如：IDataSource 接口]。 +- 关键元信息： [接口B] 的具体实现类 目前尚未完成。 + +== 任务 == +请为我编写 [模块A] 中的 [某个函数/方法，例如：process() 方法] 的实现。 +该方法需要调用 [接口B] 的 [某个方法，例如：getData(int id)]。 + +== 黄金法则 (必须严格遵守) == +当你编写的代码需要调用 [接口B] 的方法时： +1. 严禁“幻想” 或编造 [接口B] 实现类的任何内部逻辑。 +2. 你必须在调用的地方，按顺序插入以下三项内容： + - (a) 假设注释： // ASSUMPTION: 假设 [接口B] 的 [某个方法] 将返回 [预期行为/类型]。 + - (b) TODO标记： // TODO ([模块B负责人姓名/Ticket号]): 待 [接口B] 实现完成后，此处需要解开注释/移除存根并正式耦合。 + - (c) 占位符/存根： auto result = dataSource->getData(id); // <--- STUB: 返回模拟数据或注释掉 + +== 开始吧 == +请根据以下需求，编写 [某个函数/方法] 的实现： +[粘贴你的需求描述，例如：“process() 方法需要根据输入的id，调用dataSource->getData(id) 获取原始数据，然后...”] +``` + +**填充指南：** + + - `[模块A]`, `[接口B]`, `[某个函数/方法]`：替换为你的具体名称。 + - `[关键元信息]`：明确告知AI依赖未完成。 + - `[黄金法则]`：**这是此模板的核心**。它提供了一个清晰的“替代模式”，阻止AI进行“幻觉补全”。 + - `(a), (b), (c)` 中的占位符：根据实际情况填写，特别是TODO标记应指向负责人或关联的Jira Ticket。 + +----- + +**子类别 B-3: 性能优化与重构 (Optimization & Refactoring)** + + + +----- + +**模板名称：** `B7: 代码重构与现代化` +**适用场景：** 当需要对现有代码进行现代化改造（如 `C++98 -> C++17`）、应用设计模式（如 将`if-else`重构为策略模式）、或简化复杂函数（如 提取方法）以提高可读性、可维护性时。 +**内嵌原则：** `[原则五：上下文即燃料]` (输入旧代码), `[原则七：结构化输出]` (输出新代码), `[原则二：玻璃盒心态]` (要求解释改动)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通现代C++ (例如 C++17/20) 和代码重构（Refactoring）模式的专家。 + +任务：请将以下“遗留代码”重构为更现代化、更清晰、更易维护的版本。 + +== 遗留代码 (Legacy Code) == +// [粘贴你需要重构的C++代码片段] +// 最好包含必要的上下文注释，例如它属于哪个类/模块。 + +== 重构要求 == +1. 目标C++标准：[例如：C++17] +2. 核心重构指令：[例如： + - 将所有裸指针（new/delete）替换为智能指针（std::unique\_ptr 或 std::shared\_ptr）。 + - 将所有手动索引for循环改为范围for循环。 + - 将这个长函数分解为多个职责单一的小函数（应用Extract Method模式）。 + - 将这个复杂的if-else/switch语句重构为[某个设计模式，例如：策略模式或工厂模式]。 + ] +3. 保持功能等价性（Functionally Equivalent）。 +4. 提高代码的可读性和可维护性。 + +== 输出要求 == +1. 提供重构后的完整代码片段。 +2. **必须**简要说明你所做的关键改动及其理由（玻璃盒原则）。 +``` + +**填充指南：** + + - `[遗留代码]`：提供清晰的代码片段。 + - `[核心重构指令]`：**这是关键**。你必须明确告知AI你期望的“重构目标”或“应用的模式”。指令越具体，结果越好。不要只说“请优化它”。 + - `[目标C++标准]`：明确标准。 + + + +----- + +**模板名称：** `B8: 性能瓶颈分析与优化` +**适用场景：** 当通过性能剖析（Profiling）确定某段代码（“热点函数”）是性能瓶颈时，用于分析瓶颈原因（如 算法复杂度、内存访问模式）并获取优化建议。 +**内嵌原则：** `[原则二：玻璃盒心态]` (强制分析复杂度、瓶颈), `[原则五：上下文即燃料]` (输入热点代码), `[原则七：结构化输出]` (输出优化代码和分析)。 + +**[Prompt 模板]** +```txt +角色：你是一名C++性能优化专家，精通算法、数据结构和底层系统（如缓存、内存）。 + +任务：请分析并优化以下被确定为性能瓶颈的C++“热点函数”。 + +== 热点函数代码 == +// [粘贴你的热点函数代码] +// 最好包含关于输入数据规模和调用频率的注释。 + +== 分析与优化要求 == +1. 复杂度分析： 请分析此函数的时间复杂度（Big-O notation）和空间复杂度。 +2. 瓶颈识别： 请指出这段代码的主要性能瓶颈在哪里？（例如：算法本身低效？循环内内存分配？缓存未命中？数据结构选择不当？） +3. 优化建议： 请提供一个优化后的C++版本。 +4. 优化说明： 必须解释你的优化策略及其预期效果（玻璃盒原则）。 + +== 输出要求 == +1. 复杂度分析结果。 +2. 瓶颈识别说明。 +3. 优化后的代码。 +4. 优化说明。 +``` + +**填充指南：** + + - `[热点函数代码]`：提供代码，并尽可能附带性能上下文（如 “此函数每秒调用1万次，输入向量大小可达10万”）。 + - **使用指南：** 此模板侧重于CPU侧代码。对于GPU Kernel，应使用 `B9` 模板。 + + + +----- + +**模板名称：** `B9: CUDA Kernel 性能调优` +**适用场景：** `B8` 的GPU特化版。当需要对一个已有的CUDA Kernel进行深度性能分析和优化时，用于识别GPU特有的瓶颈（如 显存访问、线程束发散、占用率低）。 +**内嵌原则：** `[原则二：玻璃盒心态]` (强制分析GPU瓶颈), `[原则五：上下文即燃料]` (输入Kernel代码), `[原则八：自我批判]` (AI扮演HPC专家审查)。 + +**[Prompt 模板]** +```txt +角色：你是一名顶级的CUDA性能优化专家（HPC工程师），精通NVIDIA GPU架构（如 Ampere/Hopper）。 + +任务：请严格审查并优化以下CUDA Kernel代码的性能。 + +== CUDA Kernel 代码 == +// [粘贴你的CUDA Kernel代码 (__global__ void ...)] +// 最好包含关于启动配置 (Grid/Block大小) 和目标GPU型号的注释。 + +== 性能审查与优化要求 == +请扮演“性能评审专家”，从以下GPU特定角度进行分析： +1. 显存访问模式 (Memory Access Patterns)： + - Global Memory：是否存在非合并访问（Non-Coalesced Access）？如何改进？ + - Shared Memory：是否存在岸冲突（Bank Conflicts）？如何规避？ + - L1/L2 Cache：利用率如何？ +2. 计算与指令 (Compute & Instructions)： + - 线程束发散（Warp Divergence）：是否存在？如何减少？ + - 指令吞吐（Instruction Throughput）：是否存在瓶颈（如 __syncthreads() 过多）？ + - 特殊单元利用：是否可以利用 Tensor Cores 或其他专用单元？ +3. 占用率 (Occupancy)： + - 当前代码的理论占用率如何？（基于Block大小、寄存器使用量、共享内存使用量） + - 是否存在优化空间以提高占用率？ + +== 输出要求 == +1. 针对上述3个方面的详细性能分析报告。 +2. 提供一个优化后的CUDA Kernel代码版本。 +3. 必须解释你所做的每一项关键优化及其背后的GPU架构原理（玻璃盒原则）。 +``` + +**填充指南：** + + - `[CUDA Kernel 代码]`：提供完整的Kernel实现。 + - `[启动配置/GPU型号]`：提供这些信息有助于AI进行更精确的占用率和性能分析。 + - **使用指南：** 这是D2模板中最复杂的一种。AI的回答质量高度依赖于其训练数据中CUDA优化的深度。建议结合NVIDIA Nsight Compute等工具进行验证。 + +----- + +**子类别 B-4: 健壮性与并发安全 (Robustness & Concurrency)** + + + +----- + +**模板名称：** `B10: 错误处理与异常安全` +**适用场景：** 当需要为一个仅实现了“理想路径”（Happy Path）的函数或类，添加健壮的错误处理逻辑，或者需要将C风格的错误码处理重构为现代C++的异常安全（RAII）或 `std::expected` 模式时。 +**内嵌原则：** `[原则五：上下文即燃料]` (输入原代码), `[原则七：结构化输出]` (输出健壮代码), `[原则六：示例优先]` (可选：提供期望的错误处理模式示例)。 + +**[Prompt 模板]** +```txt +角色：你是一名精通C++错误处理和异常安全（Exception Safety）设计的专家。 + +任务：请为以下C++代码添加健壮的错误处理逻辑，或将其错误处理模式重构为 [目标模式]。 + +== 原始代码 (仅Happy Path) == +// [粘贴你的原始C++代码片段] +// 例如，一个包含 fopen, malloc, 或可能失败的外部调用的函数。 +FILE* open_and_process(const char* filename) { + FILE* fp = fopen(filename, "r"); + // 假设此处没有检查 fp 是否为 NULL + // ... 其他处理 ... + return fp; // 假设调用者负责 fclose +} + +== 错误处理要求 == +1. 目标模式：[例如：C++异常 (throw/catch), std::expected\ (C++23), 返回错误码 (int/enum), RAII (Resource Acquisition Is Initialization)] +2. 必须处理 [潜在错误点1，例如：fopen 返回 NULL 的情况]。 +3. 必须处理 [潜在错误点2，例如：malloc 返回 NULL 的情况]。 +4. (对于RAII/异常) 必须确保资源（如文件句柄、内存）在错误发生时被正确释放（无泄漏）。 + +== (可选) 期望的错误处理风格示例 (✅) == +// [粘贴一个你期望的错误处理风格的代码片段] + +== 输出要求 == +1. 提供添加/重构了错误处理逻辑后的完整代码。 +2. 简要说明你采用的错误处理策略。 +``` + +**填充指南：** + + - `[原始代码]`：提供代码。 + - `[目标模式]`：**明确告知AI你期望的错误处理范式**。这是最重要的输入。 + - `[潜在错误点]`：列出你已知的、需要处理的错误源。 + - `[期望风格示例]`：可选，但强烈推荐（原则六）。提供一个示例能极大提高AI输出的风格一致性。 + + + +----- + +**模板名称：** `B11: 并发安全分析与实现` +**适用场景：** 针对新架构的多线程痛点。用于审查一个C++类或函数，分析其在多线程环境下的安全性，并自动添加必要的同步机制（如 `mutex`, `atomic`）。 +**内嵌原则：** `[原则二：玻璃盒心态]` (强制分析竞态条件), `[原则五：上下文即燃料]` (输入代码), `[原则七：结构化输出]` (输出线程安全代码和分析)。 + +**[Prompt 模板]** +```txt +角色：你是一名精通C++并发编程（Multithreading）和内存模型（Memory Model）的专家。 + +任务：请严格审查以下C++代码在多线程环境下的安全性，并将其修改为线程安全版本。 + +== 待审查的代码 == +// [粘贴你的C++类或函数代码] +// 例如，一个包含被多个方法读写的成员变量的类。 +class Counter { +public: + void increment() { count_++; } + int get() const { return count_; } +private: + int count_ = 0; // 风险点：非原子操作 +}; + +== 并发安全要求 == +1. 分析： 请识别代码中所有潜在的“数据竞争”（Data Races）或“竞态条件”（Race Conditions）。明确指出哪些变量或操作在并发访问下是不安全的。 +2. 修复： 请提供一个线程安全（Thread-Safe）的版本。 +3. 同步机制选择： 请优先使用 [偏好的机制，例如：std::mutex / std::atomic / std::shared\_mutex]。 +4. 性能考量： (可选) 在保证线程安全的前提下，尽量减少锁的粒度或使用无锁（Lock-Free）技术（如果适用且安全）。 + +== 输出要求 == +1. 并发安全问题的分析报告。 +2. 修复后的线程安全代码。 +3. 简要说明你选择的同步机制及其理由。 +``` + +**填充指南：** + + - `[待审查的代码]`：提供代码。 + - `[偏好的机制]`：指定你团队倾向使用的同步原语，可以提高一致性。 + - `[性能考量]`：可选。如果你对性能有极致要求，可以加入此项，但AI提供无锁代码的可靠性需要仔细验证。 + + + +----- + +**模板名称：** `B12: 日志与可观测性代码注入` +**适用场景：** 自动化软件开发中的重复性劳动。用于为指定函数或类的所有关键路径（入口、出口、错误分支）自动注入符合团队规范的日志或分布式跟踪代码。 +**内嵌原则：** `[原则七：结构化输出]` (输出注入代码), `[原则五：上下文即燃料]` (输入原代码和规范)。 + +**[Prompt 模板]** +```txt +角色：你是一名熟悉 [日志库/跟踪库，例如：spdlog/OpenTelemetry C++] 和代码自动生成的工具开发者。 + +任务：请为以下C++函数自动注入 [日志/跟踪] 代码。 + +== 原始函数代码 == +// [粘贴你的原始C++函数代码] +bool processData(const Input& input, Output& output) { + if (!input.isValid()) { + // 需要注入错误日志 + return false; + } + // 需要注入入口日志/Trace Span开始 + + auto result = externalCall(input); + if (result.hasError()) { + // 需要注入外部调用错误日志 + return false; + } + + output = result.data; + // 需要注入出口日志/Trace Span结束 + return true; +} + +== 注入规范 == +1. 日志库/跟踪库：[例如：spdlog] +2. 日志级别：[例如：入口/出口使用 info, 错误使用 error] +3. 日志格式：[例如：必须包含函数名、输入参数的关键值、返回值/错误信息] +4. (可选) 跟踪要求：[例如：在函数入口创建名为 "processData" 的 Span, 在所有出口结束 Span, 并在错误时设置 Span 状态为 Error] + +== 输出要求 == + - 提供注入了 [日志/跟踪] 代码后的完整函数实现。 + - 不要修改原始的业务逻辑。 +``` + +**填充指南：** + + - `[日志库/跟踪库]`：明确指定你团队使用的库。 + - `[注入规范]`：**越详细越好**。提供你团队的日志格式、级别约定、跟踪要求等，AI才能生成符合规范的代码。 + + + +----- + +**模板名称：** `B13: 跨语言代码转译` +**适用场景：** 在算法预研或迁移阶段，需要将一种语言（通常是原型语言如 `MATLAB`, `Python/Numpy`）的代码逻辑，翻译为目标生产语言（如 `C++`, `CUDA`）。 +**内嵌原则：** `[原则五：上下文即燃料]` (输入源语言代码), `[原则七：结构化输出]` (输出目标语言代码), `[原则二：玻璃盒心态]` (要求标注语言差异)。 + +**[Prompt 模板]** +```txt +角色：你是一名精通 [源语言，例如：MATLAB] 和 [目标语言，例如：C++17 / CUDA] 的专家，擅长算法代码迁移。 + +任务：请将以下 [源语言] 代码翻译为等效的 [目标语言] 代码。 + +== 源语言代码 ([例如：MATLAB]) == +% [粘贴你的源语言代码片段] +% 例如，一段包含矩阵运算、循环的MATLAB函数 +function output = process_signal(input_signal, filter_coeffs) + n = length(input_signal); + m = length(filter_coeffs); + output = zeros(1, n); + for i = 1:n + sum_val = 0; + for j = 1:m + if (i - j + 1 > 0) + sum_val = sum_val + input_signal(i - j + 1) * filter_coeffs(j); + end + end + output(i) = sum_val; + end +end + +== 翻译要求 == +1. 目标语言：[例如：C++17] +2. (可选) 目标库：[例如：请使用 Eigen 库处理矩阵/向量运算] +3. 功能等价性： 翻译后的代码逻辑必须与源语言代码完全等价。 +4. 语言差异标注 (玻璃盒原则)： 必须在翻译后的代码中，使用注释明确标注出 [源语言] 和 [目标语言] 之间的关键差异点，例如： + - 数组索引的起始值（1-based vs 0-based）。 + - 内存管理方式（自动 vs 手动/RAII）。 + - 向量化操作的等效实现。 + +== 输出要求 == + - 提供完整的、功能等价的 [目标语言] 代码实现。 + - 包含上述要求的语言差异标注注释。 +``` + +**填充指南：** + + - `[源语言]` 和 `[目标语言]`：明确指定。 + - `[源语言代码]`：提供代码。 + - `[目标库]`：如果目标语言依赖特定库（如 C++ 的 Eigen），请明确指出。 + - `[语言差异标注]`：**这是此模板的核心价值**。强制AI标注差异，能帮助工程师避免因语言习惯不同而引入的 subtle bug。 diff --git a/Prompt模板/03_审查与质量保障模板库.md b/Prompt模板/03_审查与质量保障模板库.md new file mode 100644 index 0000000..e2679b7 --- /dev/null +++ b/Prompt模板/03_审查与质量保障模板库.md @@ -0,0 +1,727 @@ +#### C. 类别三：代码审查与质量保障 (QA & Review) + +**模板索引 (Index)** + +| 模板ID | 核心用途 | 使用场景 / 关键词 | +| :--- | :--- | :--- | +| **C-1: 静态理解与逻辑分析** | | | +| **[`C1`](#C1)** | 复杂逻辑解释 | __syncthreads, 模板元编程, 位运算, 正则解析 | +| **[`C2`](#C2)** | 依赖与调用链分析 | include依赖, Call Graph, Mermaid | +| **[`C3`](#C3)** | 接口与实现一致性审查 | 派生类签名校验, const/noexcept, 覆盖完整性 | +| **C-2: 验证与测试用例生成** | | | +| **[`C4`](#C4)** | 单元测试生成 | gtest脚手架, Happy/Edge, 异常测试 | +| **[`C5`](#C5)** | 边界条件增强 | Edge cases, 负路径, 完备性检查 | +| **[`C6`](#C6)** | 模拟数据/桩函数生成 | gmock, Mock类, 样例数据 | +| **[`C7`](#C7)** | 集成/E2E测试脚本 | gRPC/REST脚本, 端到端验证 | +| **C-3: 风险、安全与并发审查** | | | +| **[`C8`](#C8)** | 潜在Bug与逻辑审查 | 逻辑缺陷, 资源泄漏, 越界 | +| **[`C9`](#C9)** | 并发安全专项审查 | Data Race, 共享状态, mutex | +| **[`C10`](#C10)** | 错误处理路径审查 | 资源释放, 返回值健壮性 | +| **[`C11`](#C11)** | 安全漏洞专项审查 | 缓冲区溢出, 格式化字符串, 注入风险 | +| **C-4: 迭代与代码评审** | | | +| **[`C12`](#C12)** | 方案自我批判 | 缺陷/陷阱识别, 改进建议 | +| **[`C13`](#C13)** | 可读性与规范评审 | 命名/风格/全局状态, 重构建议 | + +----- + +**子类别 C-1: 静态理解与逻辑分析 (Static Understanding & Analysis)** + + + +----- + +**模板名称：** `C1: 复杂逻辑解释` +**适用场景：** `原则二：玻璃盒` 的核心应用。用于深入理解一个复杂的、难以读懂的代码块。例如：`2.2.4` 中的 `__syncthreads` 工作原理、C++模板元编程（TMP）、复杂的位运算技巧、或晦涩的正则表达式。 +**内嵌原则：** `[原则二：玻璃盒心态]` (核心), `[原则五：上下文即燃料]` (输入代码是关键)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通 [相关领域，例如：CUDA C++ / C++20 模板元编程 / POSIX并发] 的专家和技术导师。 + +任务：请向我（一名有经验但非此领域专家的工程师）深入、清晰地解释以下代码片段。 + +== 待解释的代码 == +[粘贴你无法理解的复杂代码片段。例如： +__global__ void myKernel(...) { + // ... + extern __shared__ float s_data[]; + s_data[threadIdx.x] = ...; + __syncthreads(); // <-- 重点解释这个 + // ... +} +] + +== 解释要求 (玻璃盒原则) == +请严格按照以下结构回答： +1. 核心功能 (What)： 这段代码（或特定行 [例如：__syncthreads()]） 的主要目的是什么？ +2. 工作原理 (How)： 它在技术/时序上是如何实现这一目的的？（请分步骤说明） +3. 设计动机 (Why)： 为什么作者选择用这种（看起来很复杂）的方式来实现？它解决了什么性能/逻辑问题？ +4. 风险与“反面教材” (What If)： 如果 [例如：删除 __syncthreads() / 替换为其他实现]，会导致什么具体的错误或性能退化？（这是关键） +``` + +**填充指南：** + + - `[相关领域]`：明确告知AI需要扮演的专家角色，例如 `CUDA C++`, `C++20 Concepts`, `Boost.Asio`。 + - `[待解释的代码]`：粘贴你希望理解的代码。 + - `[解释要求]`：**这是此模板的核心**。通过`What/How/Why/What If`结构，强制AI提供“深度、可操作”的解释，而非停留在表面的“它是一个同步原语”这种废话上（玻璃盒原则）。 + + + +----- + +**模板名称：** `C2: 代码依赖与调用链分析` +**适用场景：** 在进行重构、优化或接手遗留模块（痛点3）之前，需要快速理解其内部结构和外部依赖，绘制“架构地图”。 +**内嵌原则：** `[原则五：上下文即燃料]` (输入文件是关键), `[原则七：结构化输出]` (强制输出结构化列表或图)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通C++代码静态分析的工具开发者。 + +任务：请分析以下C++模块的源代码，并提供一份结构化的依赖和调用链报告。 + +== 模块上下文 == +[粘贴你需要分析的代码，可以是一个.h文件、一个.cpp文件，或两者的组合] +// 例如： +// --- MyProcessor.h --- +#include +#include "IReader.h" // 外部依赖 +#include "utils/common.h" // 内部依赖 + +class MyProcessor { +public: + bool runPipeline(const Config& cfg); +private: + void loadData(int id); + bool processBlock(std...); + IReader* reader_; +}; + +// --- MyProcessor.cpp --- +#include "MyProcessor.h" +#include // 外部依赖 + +bool MyProcessor::runPipeline(const Config& cfg) { + if (!cfg.isValid) return false; + loadData(cfg.id); // 内部调用1 + processBlock(...); // 内部调用2 + return true; +} +// ... (其他实现) ... + +== 分析与输出要求 == +请严格按照以下格式输出： +1. 外部依赖 (External Includes)： + - [例如：, , "IReader.h"] +2. 内部依赖 (Internal Includes)： + - [例如："utils/common.h"] +3. 调用链分析 (Call Graph)： + - 请为 [目标公共函数，例如：runPipeline] 生成一个调用链（直到私有函数）。 + - (可选) 请使用Mermaid (graph TD) 格式展示。 + - (示例) runPipeline --> loadData; runPipeline --> processBlock; +``` + +**填充指南：** + + - `[模块上下文]`：粘贴你希望分析的源代码。代码越完整，分析越准确。 + - `[目标公共函数]`：明确指定你希望分析的调用链入口点。 + - **使用指南：** 此模板用于快速、静态地理解代码结构。对于大型复杂项目，AI的分析可能需要与IDE的“Find All References”功能结合使用。 + + + +----- + +**模板名称：** `C3: 接口与实现一致性审查` +**适用场景：** 在面向接口编程（痛点4）或代码审查（痛点3）时，确保一个实现类（Concrete Class）严格、完整地遵守了其接口（Interface）的约定。 +**内嵌原则：** `[原则五：上下文即燃料]` (输入接口和实现), `[原则七：结构化输出]` (输出审查报告)。 + +**[Prompt 模板]** + +```txt +角色：你是一名严格的C++编译器和代码审查专家。 + +任务：请严格审查以下 [实现类] 是否100%符合 [接口] 的定义和规范。 + +== 接口定义 (.h) == +[粘贴接口的头文件内容，例如：IProcessor.h] +// IProcessor.h +class IProcessor { +public: + virtual ~IProcessor() = default; + virtual bool initialize(const Config& cfg) = 0; + virtual int process(float* data) noexcept = 0; + virtual Status getStatus() const = 0; +}; + +== 实现类 (.h / .cpp) == +[粘贴实现类的头文件或源文件内容，例如：GpuProcessor.h] +// GpuProcessor.h +#include "IProcessor.h" +class GpuProcessor : public IProcessor { +public: + // 缺失 virtual 析构函数 + bool initialize(Config& cfg); // 错误：Config 应该是 const& + int process(float* data); // 错误：缺失 noexcept + // 错误：缺失 getStatus() 的 const 实现 +}; + +== 审查要求 == +请识别 [实现类] 中所有违反 [接口] 约定的地方，并以结构化列表形式返回： +1. 缺失的实现： [例如：GpuProcessor 必须实现 getStatus() const] +2. 签名不匹配： [例如：initialize() 的参数类型与接口不匹配 (应该是 const Config&)] +3. 限定符不匹配 (const/noexcept)： [例如：process() 缺失了 noexcept 限定符] +4. 其他违反（如析构函数）： [例如：GpuProcessor 缺少虚析构函数，可能导致内存泄漏] +``` + +**填充指南：** + + - `[接口定义]`：提供基类（接口）的完整定义。 + - `[实现类]`：提供派生类（实现）的定义。 + - **使用指南：** 这是确保“面向接口编程”正确性的关键工具，能自动化捕获C++编译器可能（或可能不会）警告的微妙差异（如`noexcept`）。 + +----- + +**子类别 C-2: 验证与测试用例生成 (Verification & Test Case Generation)** + + + +----- + +**模板名称：** `C4: 单元测试生成` +**适用场景：** `2.4.2` 的核心模板。用于为新编写的函数或模块快速生成单元测试（Unit Test）的“脚手架”，解决工程师不愿写测试的痛点。 +**内嵌原则：** `[原则五：上下文即燃料]` (输入原函数), `[原则七：结构化输出]` (输出gtest代码)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通C++和Google Test (gtest) 框架的软件质量保障（QA）工程师。 + +任务：请为以下C++函数/类生成一套完整的gtest单元测试脚手架。 + +== 待测试的代码 == +[粘贴你的函数签名或完整实现，例如：] +#include +#include + +// 函数：安全地将字符串转换为整数 +int stringToInt(const std::string& str) { + if (str.empty()) { + throw std::invalid_argument("Input string is empty"); + } + try { + return std::stoi(str); + } catch (const std::exception& e) { + throw; // 重新抛出 + } +} + +== 测试要求 == +1. 测试框架：[例如：gtest] +2. 必须包含必要的 #include (包括 "gtest/gtest.h" 和被测代码的头文件)。 +3. 必须包含一个 "Happy Path"（正常路径）测试用例 (例如：输入 "123")。 +4. 必须包含至少两个 "Negative Path" / "Edge Case"（异常/边界）测试用例 (例如：输入 "abc", 输入 "")。 +5. 对于预期抛出异常的测试，必须使用 EXPECT_THROW 宏。 +6. 提供完整的、可直接编译的 .cpp 测试文件内容。 +``` + +**填充指南：** + + - `[待测试的代码]`：提供代码。代码越完整（包含实现），AI生成的负面测试用例越准确。 + - `[测试框架]`：明确指定，如 `gtest`, `pytest` (Python), `JUnit` (Java)。 + - **使用指南：** AI生成的测试仅为“脚手架”，工程师必须审查其断言（Assertions）的正确性，并补充AI未能覆盖的业务逻辑边界。 + + + +----- + +**模板名称：** `C5: 测试用例“边界条件”增强` +**适用场景：** 对抗工程师“只写Happy Path”的惰性（痛点6）。当你已有一个（或AI刚生成）仅覆盖正常路径的测试时，使用此模板强制AI进行“批判性思考”，补充所有被忽略的边界条件。 +**内嵌原则：** `[原则五：上下文即燃料]` (输入原测试), `[原则八：自我批判]` (AI扮演评审专家), `[原则六：示例优先]` (原测试作为示例)。 + +**[Prompt 模板]** + +```txt +角色：你是一名资深的、吹毛求疵的QA专家，擅长识别代码中的边界条件（Edge Cases）。 + +任务：我已经为 [函数名] 编写了“Happy Path”测试。请严格审查此测试，并为其补充一套“完备的边界条件”测试用例。 + +== 待测试的函数签名 == +[例如：std::vector movingAverage(const std::vector& data, int windowSize);] + +== 我已有的 "Happy Path" 测试 (✅) == +[粘贴你已有的简单测试代码] +TEST(MovingAverageTest, HandlesNormalInput) { + std::vector data = {1.0, 2.0, 3.0, 4.0, 5.0}; + int windowSize = 3; + std::vector result = movingAverage(data, windowSize); + // 假设结果是 {2.0, 3.0, 4.0} (简化) + EXPECT_EQ(result.size(), 3); + EXPECT_NEAR(result[0], 2.0, 0.001); +} + +== 增强要求 (❌ 遗漏的) == +请为 [函数名] 补充以下所有被遗漏的、关键的边界条件测试： +1. [边界1，例如：输入空的 std::vector (data.empty())] +2. [边界2，例如：windowSize 为 0 或 负数] +3. [边界3，例如：windowSize 大于 data.size()] +4. [边界4，例如：windowSize 为 1] +5. (可选) [边界5，例如：data 中包含 NaN 或 Inf 值] + +== 输出要求 == + - 仅提供新生成的、用于覆盖上述边界条件的gtest TEST(...) 代码块。 +``` + +**填充指南：** + + - `[待测试的函数签名]`：提供函数签名，帮助AI理解上下文。 + - `[我已有的 "Happy Path" 测试]`：提供一个示例（原则六），AI会模仿其风格。 + - `[增强要求]`：明确列出你希望AI覆盖的边界类型。 + + + +----- + +**模板名称：** `C6: 模拟数据/桩函数生成` +**适用场景：** 在编写单元测试时（尤其是针对复杂数据结构或依赖接口的模块），手动创建模拟数据（Mock Data）或桩函数（Mock/Stub）非常繁琐。 +**内嵌原则：** `[原则五：上下文即燃料]` (输入数据结构/接口), `[原则七：结构化输出]` (输出gmock代码或数据)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通 [框架，例如：gtest/gmock] 的测试工程师。 + +任务：请为我生成 [目标：Mock类 / 模拟数据]。 + +== 上下文 == +[粘贴你需要模拟的接口定义或数据结构定义] +// 例如 (二选一)： +// [上下文A：gmock] +class IDataReader { +public: + virtual ~IDataReader() = default; + virtual std::vector readData(int id) = 0; + virtual bool writeConfig(const Config& cfg) = 0; +}; + +// [上下文B：模拟数据] +struct RadarTrack { + int track_id; + double x, y, z; + double vx, vy, vz; + std::string status; +}; + +== 生成要求 == + +[任务A：生成 gmock 类 (基于上下文A)] +1. 目标：为 IDataReader 接口生成一个完整的 gmock 类 MockDataReader。 +2. 必须包含所有 MOCK_METHOD 宏。 + +[任务B：生成模拟数据 (基于上下文B)] +1. 目标：生成一个C++代码片段，用于创建一个 std::vector。 +2. 要求：向量中必须包含 [数量，例如：5] 个示例对象，每个对象的数据必须是随机但合理的（例如，id递增，status为"active"或"lost"）。 + +== 输出要求 == +- 提供完整的、可直接复制粘贴的C++代码块。 +``` + +**填充指南：** + + - `[上下文]`：**必须提供。** AI需要知道接口或`struct`的定义才能生成代码。 + - `[任务A/B]`：**使用时请二选一**，删除你不需要的那个任务。 + - `[数量]`：在生成数据时，指定你需要多少示例。 + + + +----- + +**模板名称：** `C7: 集成/E2E测试脚本生成` +**适用场景：** 当模块开发完成并暴露API（如gRPC或REST）后，需要快速编写一个“黑盒”测试脚本，从外部验证其端到端（E2E）功能是否符合预期。 +**内嵌原则：** `[原则五：上下文即燃料]` (输入API定义), `[原则七：结构化输出]` (输出脚本代码)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通 [语言/工具，例如：Python (grpcio) / Shell (grpcurl)] 的自动化测试工程师。 + +任务：请为以下 [API类型，例如：gRPC服务] 编写一个端到端（E2E）测试脚本。 + +== API 定义 == +[粘贴你的API定义，例如 .proto 文件内容] +syntax = "proto3"; +package radar.api; + +service TrackService { + // 创建一个新航迹 + rpc CreateTrack (CreateTrackRequest) returns (TrackResponse); + // 获取一个航迹 + rpc GetTrack (GetTrackRequest) returns (TrackResponse); +} + +message CreateTrackRequest { + int32 id = 1; + double x = 2; + double y = 3; +} +message GetTrackRequest { + int32 id = 1; +} +message TrackResponse { + int32 id = 1; + double x = 2; + double y = 3; +} + +== 测试场景要求 == +脚本必须在 [语言/工具] 中实现以下E2E测试流程： +1. [例如：Python] 导入必要的库 (如 grpcio)。 +2. [例如：Python] 创建一个到 localhost:50051 的 gRPC 通道。 +3. 步骤1 (创建)： 调用 CreateTrack RPC，创建一个 ID=101, x=1.2, y=3.4 的航迹。 +4. 步骤2 (验证)： 立即调用 GetTrack RPC，查询 ID=101。 +5. 步骤3 (断言)： 必须检查 GetTrack 返回的响应，确保其 x, y 值与创建时一致。 +6. 打印“测试通过”或“测试失败”的结论。 + +== 输出要求 == + - 提供完整的、可直接执行的 [语言/工具] 脚本代码。 +``` + +**填充指南：** + + - `[语言/工具]`：明确指定你希望用什么来测试，例如 `Python (grpcio)`, `Shell (grpcurl)`, `Python (requests)` (用于REST)。 + - `[API 定义]`：提供`.proto`, `OpenAPI yaml` 或 API的文字描述。 + - `[测试场景要求]`：**这是核心**。清晰描述你希望脚本执行的“步骤”，AI会将其翻译为代码。 + +----- + +**子类别 C-3: 风险、安全与并发审查 (Risk, Security & Falsification)** + + + +----- + +**模板名称：** `C8: 潜在Bug与逻辑审查` +**适用场景：** `2.4.6` 的核心模板。在代码审查（Code Review）阶段，利用AI作为“AI审查员”，自动扫描代码中常见的、容易被忽视的逻辑错误或风险。 +**内嵌原则：** `[原则八：自我批判]` (AI扮演评审专家), `[原则五：上下文即燃料]` (输入代码), `[原则七：结构化输出]` (输出结构化报告)。 + +**[Prompt 模板]** + +```txt +角色：你是一名资深的C++代码审查（Code Review）专家，尤其擅长发现内存安全和逻辑漏洞。 + +任务：请严格审查以下C++代码，找出所有潜在的Bug、逻辑错误或未定义行为。 + +== 待审查的代码 == +[粘贴你怀疑存在问题，或刚编写完成的C++代码片段] +// 示例：一个包含多种常见错误的代码 +void process_array(int* data, int size) { + if (data = nullptr) { // 错误1：赋值而非比较 + return; + } + + for (int i = 0; i <= size; i++) { // 错误2：off-by-one 越界 + if (size > 10) { + int* temp_buffer = new int[size]; // 错误3：资源泄漏 + // ... (do something with temp_buffer) ... + if (data[i] > 100) { + // ... + } + } + } + // 错误3：temp_buffer 在循环结束后未被 delete[] +} + +== 审查重点 == +1. 逻辑错误： 检查 if 判断（如 == 写成 =）、循环条件（如 off-by-one 错误）。 +2. 内存访问： 检查是否存在数组越界、空指针解引用（nullptr dereference）。 +3. 资源泄漏： 检查是否有 new/malloc/fopen 之后，在所有路径（包括异常路径）上都忘记 delete/free/fclose？ + +== 输出要求 == +请严格按照“缺陷报告”的格式返回，逐条列出： + - [缺陷 1]： (例如：潜在的空指针赋值) + - [风险]： (例如：if (data = nullptr) 永远为false，且修改了入参指针) + - [修复建议]： (例如：应改为 if (data == nullptr)) +----- + - [缺陷 2]： (例如：循环条件越界) + - [风险]： (例如：i <= size 导致访问 data[size]，数组越界) + - [修复建议]： (例如：应改为 for (int i = 0; i < size; i++)) +----- + - [缺陷 3]： ... +``` + +**填充指南：** + + - `[待审查的代码]`：提供你希望AI进行审查的代码片段。 + - `[审查重点]`：你可以根据代码的特点，调整AI的审查优先级。 + - **使用指南：** 此模板是`原则八：自我批判`的绝佳实践，在你自己（或AI）完成编码后，立即使用此模板进行交叉检查。 + + + +----- + +**模板名称：** `C9: 并发安全专项审查` +**适用场景：** 针对团队新架构（多线程服务器）的核心痛点（痛点2、痛点3）。在代码审查期间，专门用于分析一个类在多线程环境下的数据竞争（Data Races）风险。 +**内嵌原则：** `[原则二：玻璃盒心态]` (强制分析竞态条件), `[原则五：上下文即燃料]` (输入类定义), `[原则七：结构化输出]` (输出报告)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通C++17/20并发编程（Multithreading）和内存模型（Memory Model）的专家。 + +任务：请严格审查以下C++类在多线程环境下的安全性。 + +== 待审查的类定义 == +[粘贴你的C++类定义，包括.h和.cpp的相关方法] +// 示例：一个线程不安全的计数器 +#include +#include + +class UserStats { +public: + void incrementLogin(const std::string& user) { + // 风险点1：对 map 的并发写 + login_counts_[user]++; + } + + int getLoginCount(const std::string& user) { + // 风险点2：对 map 的并发读 + auto it = login_counts_.find(user); + if (it != login_counts_.end()) { + return it->second; + } + return 0; + } + +private: + // 风险点3：共享状态 + std::map login_counts_; +}; + +== 审查要求 == +1. 识别共享状态： 找出所有被多个public方法（或线程）并发读/写的成员变量。 +2. 分析竞态条件 (Race Conditions)： 明确指出哪些操作组合（如 incrementLogin 与 incrementLogin，或 incrementLogin 与 getLoginCount）会在此共享状态上导致数据竞争。 +3. 修复建议： 提供一个线程安全（Thread-Safe）的修复版本。 +4. 同步机制： 请使用 [偏好的机制，例如：std::mutex / std::shared\_mutex] 来保护共享状态。 + +== 输出要求 == +1. 共享状态分析： [例如：login_counts_ 是被 incrementLogin (写) 和 getLoginCount (读) 并发访问的共享状态] +2. 竞态条件分析： [例如：当两个线程同时调用 incrementLogin 时，map::operator[] 和 int++ 操作非原子，会导致计数丢失或map结构损坏...] +3. 修复后的代码： (提供添加了 std::mutex 和 std::lock_guard 的线程安全版本) +``` + +**填充指南：** + + - `[待审查的类定义]`：提供完整的类代码，AI需要看到所有访问成员变量的方法。 + - `[偏好的机制]`：指定团队技术栈（如 `std::mutex`），确保修复方案的风格一致。 + - **使用指南：** 这是新架构下Code Review的**必选动作**。 + + + +----- + +**模板名称：** `C10: 错误处理路径审查` +**适用场景：** 确保代码的健壮性。用于审查一个函数是否正确、完整地处理了所有可能的失败路径，防止“静默失败”（Silently Failing）。 +**内嵌原则：** `[原则二：玻璃盒心态]` (强制分析所有路径), `[原则五：上下文即燃料]` (输入代码), `[原则七：结构化输出]` (输出报告)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通防御性编程（Defensive Programming）和C++异常安全的专家。 + +任务：请严格审查以下函数的“错误处理路径”是否健壮和完备。 + +== 待审查的函数 == +[粘贴你的函数代码，特别是包含C风格API、外部调用或资源分配的代码] +// 示例：一个错误处理不完备的函数 +bool load_config_file(const char* path) { + FILE* fp = fopen(path, "r"); + // 风险1：未检查 fopen 的返回值 + + char buffer[1024]; + size_t read_bytes = fread(buffer, 1, 1024, fp); + // 风险2：未检查 fread 的返回值 (是否读到预期大小) + + if (read_bytes > 0) { + // ... (process buffer) ... + } + + // 风险3：未在所有路径（如此处）调用 fclose(fp) + + return true; // 风险4：无论成功失败，永远返回 true +} + +== 审查要求 == +请识别此函数中所有缺失或不正确的错误处理路径： +1. 资源分配/打开： 是否正确检查了（如 fopen, malloc, new）的返回值（如 nullptr）？ +2. 外部调用： 是否正确检查了（如 fread, send, external_api()）的返回值或错误码？ +3. 资源释放 (RAII)： 是否确保资源（如 FILE*, 内存）在函数的所有出口（包括错误出口）都被正确释放（无泄漏）？ +4. 函数返回值： 函数的返回值是否能准确反映其执行结果（成功/失败）？ + +== 输出要求 == +请逐条列出发现的“错误处理缺陷”及其“修复建议”。 + - [缺陷 1]： (例如：未检查 fopen 返回值) + - [风险]： (如果 path 不存在，fp 为 NULL，后续 fread 将导致段错误) + - [修复建议]： (例如：if (fp == nullptr) { return false; }) +----- + - [缺陷 2]： ... +``` + +**填充指南：** + + - `[待审查的函数]`：提供代码。 + - **使用指南：** 此模板对于审查与C库（需要手动资源管理）或网络（总会失败）交互的代码至关重要。 + + + +----- + +**模板名称：** `C11: 安全漏洞专项审查` +**适用场景：** 在代码提交前进行安全左移（Shift-Left Security）。用于审查代码是否存在C/C++中常见（且高风险）的安全漏洞。 +**内嵌原则：** `[原则八：自我批判]` (AI扮演安全专家), `[原则五：上下文即燃料]` (输入代码), `[原则七：结构化输出]` (输出漏洞报告)。 + +**[Prompt 模板]** + +```txt +角色：你是一名C/C++应用安全专家（AppSec），精通CWE和OWASP Top 10。 + +任务：请严格审查以下C/C++代码，查找常见的安全漏洞。 + +== 待审查的代码 == +[粘贴你的C/C++代码片段，特别是处理用户输入、文件或网络数据的部分] +// 示例：包含多个漏洞的代码 +void handle_user_request(const char* user_input, int user_id) { + // 漏洞1：缓冲区溢出 + char buffer[100]; + strcpy(buffer, user_input); + + // 漏洞2：格式化字符串 + printf(buffer); + + // 漏洞3：SQL注入 (示例) + std::string query = "SELECT * FROM users WHERE id = " + std::to_string(user_id); + // ... (execute query) ... +} + +== 审查重点 (CWE) == +请重点关注（但不限于）以下高风险漏洞： +1. 缓冲区溢出 (Buffer Overflow)： (例如：strcpy, sprintf, gets) +2. 格式化字符串 (Format String)： (例如：printf(user_input)) +3. 整数溢出 (Integer Overflow)： (例如：int size = len1 + len2;) +4. SQL注入 (SQL Injection)： (如果代码涉及构建SQL查询) +5. 命令注入 (Command Injection)： (如果代码涉及调用 system() 或 popen()) + +== 输出要求 == +请按照CWE（通用缺陷枚举）的格式，逐条列出发现的漏洞： + - [漏洞 1]： (例如：CWE-120: 缓冲区溢出) + - [位置]： (例如：strcpy(buffer, user_input);) + - [风险]： (例如：user_input 可能长于100字节，导致栈溢出，可能允许远程代码执行) + - [修复建议]： (例如：使用 strncpy 或更好的 std::string) +----- + - [漏洞 2]： ... +``` + +**填充指南：** + + - `[待审查的代码]`：提供代码，尤其是处理“不可信输入”的代码。 + - **使用指南：** AI是出色的模式匹配器，非常擅长发现这类有明显“特征”（如`strcpy`）的安全漏洞。 + +----- + +**子类别 C-4: 迭代与代码评审 (Iteration & Feedback)** + + + +----- + +**模板名称：** `C12: 方案的自我批判` +**适用场景：** `原则五：自我批判` 的通用实现。用于对抗AI的“惰性实现”（痛点6）和“上下文惯性”（痛点1）。在你（或AI）给出一个初步方案后，强制AI切换角色，对该方案进行压力测试。 +**内嵌原则：** `[原则五：自我批判]` (核心), `[原则一：敏捷提示]` (迭代式求精)。 + +**[Prompt 模板]** + +```txt +角色：(情景切换) 很好，你刚才提供的 [方案/代码] 是一个不错的初稿。 +现在，请你完全忘记你“乐于助人”的助手角色。 + +新角色：你是一名资深的、吹毛求疵的、且极其注重“健壮性”和“性能”的首席架构评审专家。 + +任务：请严格审查你刚才提供的 [方案/代码]，找出其中至少 [数量，例如：3] 个潜在的设计缺陷、性能陷阱、隐藏的假设或未处理的边界条件。 + +== 交付要求 == +请逐条列出： +1. [缺陷 1]： (例如：并发不安全) +2. [分析]： (例如：你提供的方案在多线程环境下存在竞态条件...) +3. [改进建议]： (例如：应使用 std::mutex...) +----- +1. [缺陷 2]： (例如：性能陷阱) +2. [分析]： (例如：在循环内部分配内存...) +3. [改进建议]： (例如：应在循环外预分配...) +``` + +**填充指南：** + + - **使用指南：** 这是一个“对话式”模板，在你对AI的（或你自己的）上一个回答不完全满意时使用。 + - `[方案/代码]`：替换为你正在讨论的主题，如 “API设计”、“CUDA Kernel实现”。 + - `[数量]`：指定一个具体数字，可以迫使AI更深入地思考。 + + + +----- + +**模板名称：** `C13: 代码可读性与规范性评审` +**适用场景：** 自动化Code Review中关于“代码风格”的重复性劳动（痛点3）。用于确保代码符合团队规范，提高可读性和可维护性。 +**内嵌原则：** `[原则六：示例优先]` (可选：提供规范), `[原则七：结构化输出]` (输出评审意见)。 + +**[Prompt 模板]** + +```txt +角色：你是一名资深的C++工程师，是 [团队/规范，例如：Google C++ Style Guide] 的坚定执行者。 + +任务：请审查以下代码的“可读性”、“可维护性”和“代码风格”。 + +== 待审查的代码 == +[粘贴你需要评审的代码片段，例如：命名不规范、函数过长的代码] +// 示例：风格糟糕的代码 +#include +// 全局变量 +std::vector g_vec; + +// 命名模糊，函数名大写 +bool Process(int x, int y) { + if (x > y) { // 魔法数字 + int temp = x; // 变量名无意义 + x = y; + y = temp; + } + // ... (省略了50行其他逻辑) ... + g_vec.push_back(y); // 依赖全局状态 + return true; +} + +== 审查重点 == +1. 命名规范： (例如：变量名、函数名、类名是否清晰且符合 [规范]？) +2. 函数长度/职责： (例如：函数是否过长？是否违反了“单一职责原则”？) +3. 注释： (例如：注释是否缺失？是否注释了“Why”？) +4. 复杂度： (例如：是否存在过深的嵌套（if/for）？) +5. 反模式： (例如：是否使用了“魔法数字”？是否滥用全局变量？) + +== (可选) 我们的风格规范 (示例优先) == + - [例如：函数命名使用 lower_snake_case()] + - [例如：成员变量使用 m_suffix_] + - [例如：严禁使用全局变量] + +== 输出要求 == +请逐条返回“风格问题”和“重构建议”。 + - [问题 1]： (例如：违反命名规范) + - [建议]： (例如：函数 Process 应改为 process_data。变量 temp 应改为 lower_bound。) +----- + - [问题 2]： (例如：滥用全局变量) + - [建议]： (例如：g_vec 应作为参数传入或作为类成员，移除全局状态。) +----- + - [问题 3]： ... +``` + +**填充指南：** + + - `[团队/规范]`：明确告知AI应遵循的风格，如 `Google Style`, `LLVM Style`。 + - `[我们的风格规范]`：**强烈推荐**。通过 `原则六：示例优先` 提供你团队的具体规范，AI的评审会精确得多。 diff --git a/Prompt模板/04_文档编写与知识管理模板库.md b/Prompt模板/04_文档编写与知识管理模板库.md new file mode 100644 index 0000000..dd0f57c --- /dev/null +++ b/Prompt模板/04_文档编写与知识管理模板库.md @@ -0,0 +1,524 @@ +#### D. 类别四：文档编写与知识管理 (Documentation & Knowledge) + +**模板索引 (Index)** + +| 模板ID | 核心用途 | 使用场景 / 关键词 | +| :--- | :--- | :--- | +| **D-1: 代码内文档** | | | +| **[`D1`](#D1)** | API/函数头注释生成 | Doxygen, 头注释, 参数/返回描述 | +| **[`D2`](#D2)** | 内部逻辑注释注入 | Why注释, 算法步骤, 可维护性 | +| **[`D3`](#D3)** | 遗留注释重构 | 注释同步, 现代化, 过时修复 | +| **D-2: 系统与项目文档** | | | +| **[`D4`](#D4)** | 技术设计文档骨架 | TDD骨架, 模块启动, Markdown结构 | +| **[`D5`](#D5)** | API参考手册生成 | gRPC/REST/C++头, 外部开发者文档 | +| **[`D6`](#D6)** | README/项目文档编写 | 构建说明, 快速上手, 特性列表 | +| **D-3: 知识消费与合成** | | | +| **[`D7`](#D7)** | 技术知识摘要 | 论文/博客, 工程可行性, 摘要结构 | +| **[`D8`](#D8)** | 跨语言技术翻译 | 专业术语映射, 精确翻译 | +| **[`D9`](#D9)** | 手动RAG问答 | 内部知识库, 上下文限定回答 | +| **D-4: 知识流转与过程沉淀** | | | +| **[`D10`](#D10)** | Git提交信息生成 | Conventional Commits, diff->message | +| **[`D11`](#D11)** | 讨论/纪要结构化总结 | Key decisions, Action items | +| **[`D12`](#D12)** | 架构决策记录 (ADR) | 决策背景, 后果, Rationale | +| **[`D13`](#D13)** | 需求到技术任务分解 | User Story->任务列表, Epic/Subtask | + +----- + +**子类别 D-1: 代码内文档 (In-Code Documentation)** + + + +----- + +**模板名称：** `D1: API/函数头注释生成` +**适用场景：** `2.4.4` 的核心模板。输入一个C++函数/类/方法的签名，指令AI按照指定的规范（如 `Doxygen`）生成完整的函数头注释。 +**内嵌原则：** `[原则七：结构化输出]` (强制Doxygen格式), `[原则五：上下文即燃料]` (函数签名是关键)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通C++和 [规范, 例如：Doxygen] 注释规范的软件工程师。 + +任务：请为以下C++ [目标, 例如：函数/类/方法] 自动生成专业、完整的头注释。 + +== 待注释的代码签名 == +[粘贴你的函数/类/方法的签名或声明，例如： +void process_data(const std::vector& input, Result& output, int max_iterations); +] + +== 注释要求 == +1. 规范：必须严格遵守 [规范, 例如：Doxygen] 格式。 +2. 内容：必须包含 [标签1, 例如：@brief] (简洁描述功能)。 +3. 内容：必须包含 [标签2, 例如：@param] (描述每一个参数的名称、类型、用途)。 +4. 内容：必须包含 [标签3, 例如：@return] (描述返回值)。 +5. (可选) 内容：包含 [标签4, 例如：@note] (注意事项) 或 [标签5, 例如：@warning] (警告)。 + +== 输出要求 == +- 仅返回生成的完整注释块，不要包含原始的代码签名。 +``` + +**填充指南：** + + - `[规范]`：明确你团队使用的注释标准，例如 `Doxygen`, `JSDoc`。 + - `[目标]`：明确是 `函数`, `类`, `方法` 还是 `枚举`。 + - `[待注释的代码签名]`：**必须提供**清晰的、完整的代码签名。 + - `[标签...]`：根据你的规范要求，增删所需的标签。 + + + +----- + +**模板名称：** `D2: 内部逻辑注释注入` +**适用场景：** 对抗“代码自文档”的迷思。用于为一个逻辑复杂、缺少注释的函数体，自动注入解释“Why”（目的）而非“How”（行为）的内联注释。 +**内嵌原则：** `[原则二：玻璃盒心态]` (解释'Why'), `[原则五：上下文即燃料]` (输入函数体)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通 [领域, 例如：C++ / 信号处理算法] 的资深工程师，擅长编写清晰、可维护的代码。 + +任务：请为以下没有内联注释的复杂函数体，注入简洁、专业的//内联注释。 + +== 黄金法则 (必须遵守) == +- 注释必须解释“Why”（目的、意图、算法步骤），而不是“How”（代码行为）。 +- (例如：// How (错误): i加1。 // Why (正确): 推进到下一个数据样本) + +== 待注入注释的代码 == +[粘贴你的完整函数体代码，特别是包含位运算、复杂算法、或晦涩业务逻辑的部分] + +== 注入要求 == +1. 在所有复杂的逻辑块、算法关键步骤、晦涩的位运算、或“魔法数字”上方添加注释。 +2. 严格遵守上述“黄金法则”。 +3. 保持注释简洁、专业，与代码对齐。 + +== 输出要求 == +- 返回注入了//内联注释的完整函数代码块。 +``` + +**填充指南：** + + - `[领域]`：明确AI的专业背景，以便它能理解算法的“Why”。 + - `[待注入注释的代码]`：**必须提供**完整的函数实现体。 + - **使用指南：** 此模板旨在提升代码的可读性，AI生成的注释仍需人工审查其“Why”是否解释到位。 + + + +----- + +**模板名称：** `D3: 遗留注释重构与现代化` +**适用场景：** 维护遗留代码库（痛点3）。当代码已经迭代，但注释（头注释或内联注释）已过时、写得不好或与代码逻辑不符时，用于同步和重写注释。 +**内嵌原则：** `[原则五：上下文即燃料]` (输入代码和旧注释), `[原则七：结构化输出]` (输出新代码和注释)。 + +**[Prompt 模板]** + +```txt +角色：你是一名严谨的C++技术文档作者和代码审查专家。 + +任务：请重写以下代码片段中的注释，使其清晰、专业、现代化，并确保它100%反映当前代码的实际逻辑。 + +== 待重构的代码与注释 == +[粘贴包含过时、错误、或写得不好的注释的代码片段] + +== 审查与重构要求 == +1. 审查：分析原始注释存在的问题（例如：已过时、描述与代码不符、含糊不清、拼写错误）。 +2. 重构（注释）：重写注释（无论是Doxygen还是内联`//`），使其专业、准确，并解释“Why”。 +3. 同步：确保新注释100%匹配代码的当前行为。 + +== 输出要求 == +1. [分析]：(可选) 简要说明原注释的核心问题。 +2. [重构后的代码]：返回带有“新注释”的完整代码块。 +``` + +**填充指南：** + + - `[待重构的代码与注释]`：**必须提供**代码和它附带的错误注释，AI需要这两者来进行对比。 + - **使用指南：** 这是确保“文档（注释）即代码”一致性的重要工具。 + +----- + +**子类别 D-2: 系统与项目文档（Authoring New Docs)** + + + +----- + +**模板名称：** `D4: 技术设计文档（TDD）骨架生成` +**适用场景：** 启动新项目或新模块的必备环节（痛点1）。用于快速生成一份符合团队规范的技术设计文档（TDD）的Markdown骨架，避免工程师从零开始。 +**内嵌原则：** `[原则七：结构化输出]` (输出Markdown骨架), `[原则五：上下文即燃料]` (输入模块名和模板)。 + +**[Prompt 模板]** + +```txt +角色：你是一名资深的系统架构师，精通编写高质量的技术设计文档（TDD）。 + +任务：请为我的新模块生成一个技术设计文档的完整Markdown骨架。 + +== 设计上下文 == +1. 新模块名称：[例如：RadarTrackCacheService] +2. (可选) 团队标准模板结构： + [如果团队有标准TDD模板，可粘贴其Markdown大纲，例如： + 1. 背景 2. 目标 3. 方案对比 ...] + +== 骨架要求 == +- 必须是一个结构完整、格式专业的Markdown文档。 +- 必须包含（但不限于）以下核心章节（如果未提供模板）： + 1. 背景 (Background)： (包含问题描述和目标) + 2. 目标 (Objectives) / 非目标 (Non-Goals)： + 3. 高层设计 (High-Level Design, HLD)： (包含架构图占位符、组件职责) + 4. 低层设计 (Low-Level Design, LLD)： (包含API定义、数据模型、交互时序图占位符) + 5. 方案对比 (Alternative Solutions)： (对比不同方案的Pros/Cons) + 6. 风险与缓解措施 (Risks & Mitigations)： + 7. (可选) 部署与可观测性 (Deployment & Observability)： + +== 输出要求 == +- 返回完整的Markdown TDD骨架，包含标题和简短的章节说明（提示工程师该填写什么）。 +``` + +**填充指南：** + + - `[新模块名称]`：明确告知AI设计的主题。 + - `[团队标准模板结构]`：**强烈推荐**。提供团队的模板（原则六：示例优先），AI生成的骨架会更符合规范。 + + + +----- + +**模板名称：** `D5: API 参考手册生成` +**适用场景：** 从代码定义（如`.proto`, `.h`）自动生成面向外部开发者的API参考手册，解决文档编写的重复性劳动。 +**内嵌原则：** `[原则五：上下文即燃料]` (API定义是核心), `[原则七：结构化输出]` (输出Markdown手册)。 + +**[Prompt 模板]** + +```txt +角色：你是一名专业的技术文档作者（Technical Writer），擅长为开发者编写清晰、易懂的API参考手册。 + +任务：请根据以下API定义，生成一份面向“外部开发者”的专业Markdown参考手册。 + +== API 定义上下文 == +1. API类型：[例如：gRPC / RESTful OpenAPI / C++ Header] +2. API定义文件内容： + [粘贴你的 .proto / OpenAPI .yaml / .h 头文件内容] + +== 手册要求 == +1. 受众：外部开发者（他们不了解我们的内部实现）。 +2. 必须包含“概述”（Overview）章节，说明此API的核心用途。 +3. (可选) 必须包含“认证”（Authentication）章节（如果适用）。 +4. 必须包含“核心端点/RPC”章节，逐个详细描述： + - (a) 功能描述（基于代码注释或推测） + - (b) 请求参数（含类型、是否必需、描述） + - (c) 响应参数（含类型、描述） + - (d) (可选) 错误码 +5. 必须包含“代码示例”（Code Examples）章节，为每个核心调用提供 [语言, 例如：Python/curl/C++] 的最小可用示例。 + +== 输出要求 == +- 返回完整的Markdown格式的API参考手册。 +``` + +**填充指南：** + + - `[API定义文件内容]`：**必须提供**。AI将解析这份“燃料”来生成文档。 + - `[语言]`：明确告知AI你希望示例代码使用什么语言。 + + + +----- + +**模板名称：** `D6: README / 项目文档编写` +**适用场景：** 自动化新模块或项目的`README.md`编写工作，确保项目文档的规范性和完整性。 +**内嵌原则：** `[原则五：上下文即燃料]` (输入文件结构、构建脚本等), `[原则七：结构化输出]` (输出Markdown)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通DevOps和C++项目管理的开源项目维护者。 + +任务：请为以下新模块自动生成一份专业的 `README.md` 文件。 + +== 模块上下文 == +1. 模块简介：[简要描述该模块的核心功能，例如：一个用于雷达信号处理的高性能数学库] +2. (可选) 目录结构： + [粘贴 `tree` 命令的输出或文件列表] +3. (可选) 构建脚本： + [粘贴 `CMakeLists.txt` 或其他构建脚本的关键内容，AI将据此生成构建说明] + +== README 要求 == +必须包含以下核心章节： +1. [模块名称]：(基于上下文自动生成) +2. 简介 (Overview)： (基于 [模块简介] 扩展) +3. 特性 (Features)： (基于上下文推测，或你在此处提供列表) +4. 构建说明 (Building)： - 必须包含“依赖项”（Dependencies）章节 (基于 [构建脚本] 推测)。 + - 必须包含“编译步骤”（Compilation Steps） (基于 [构建脚本] 推测)。 +5. 快速上手 (Quick Start)： - 必须包含一个最小使用示例（Code Snippet）以展示如何引入和调用该模块。 +6. (可选) 如何贡献 (Contributing)： + +== 输出要求 == +- 返回完整的Markdown格式的 `README.md` 内容。 +``` + +**填充指南：** + + - `[模块简介]`：**必须提供**，这是AI撰写“简介”的基础。 + - `[目录结构]` 和 `[构建脚本]`：**强烈推荐**。提供这些上下文（燃料），AI生成的“构建说明”和“特性”会准确得多。 + +----- + +**子类别 D-3: 知识消费与合成 (Knowledge Consumption & Synthesis)** + + +----- + +**模板名称：** `D7: 技术知识摘要` +**适用场景：** `2.3.4` 的核心模板。用于快速“消化”外部知识（如论文、博客、RFC），为工程负责人提炼一份关注“工程可行性”的结构化摘要。 +**内嵌原则：** `[原则七：结构化输出]` (强制结构化), `[原则五：上下文即燃料]` (输入文本)。 + +**[Prompt 模板]** + +```txt +角色：你是一名 [相关领域，例如：雷达信号处理] 专家和资深工程负责人。 + +任务：请阅读以下技术文档/论文原文，并为我（工程负责人）提炼一份高度结构化的“工程价值摘要”。 + +== 原文上下文 == +[粘贴你需要摘要的完整外文或中文技术文档/论文原文] + +== 摘要要求 (必须严格遵守此结构) == +请用简洁、专业的中文（非直译）回答以下三个核心工程问题： +1. [核心问题]： 这篇文档试图解决什么具体工程问题？ + - (例如：提高分辨率、抗干扰、降低计算量？) +2. [核心技术]： 它提出的主要技术或方法是什么？ + - (用一句话概括，例如：它用XX代替了XX) +3. [工程约束与代价]： 如果我们要工程实现这个方法，它可能引入的最大挑战或约束是什么？ + - (例如：对硬件同步要求高？计算量极大？依赖特定库？) +``` + +**填充指南：** + + - `[相关领域]`：明确AI的专家身份，有助于它理解专业术语。 + - `[原文上下文]`：**必须提供**。粘贴你需要AI“消化”的全部文本内容。 + - **使用指南：** 此模板的目标不是学术翻译，而是“工程决策辅助”，强制AI从“我能否以及是否应该实现它”的角度思考。 + + + +----- + +**模板名称：** `D8: 跨语言技术翻译` +**适用场景：** 消除语言障碍。当需要阅读非英语（如日语、俄语、德语）的技术文档、博客或错误信息时，用于获取技术上精确的中文翻译。 +**内嵌原则：** `[原则五：上下文即燃料]` (输入外文), `[原则七：结构化输出]` (输出中文)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通 [源语言，例如：日语] 和简体中文的专业技术翻译（本地化专家）。 + +任务：请将以下 [源语言] 技术文档，逐字逐句地、专业地翻译为简体中文。 + +== 黄金法则 (必须遵守) == +1. 精确性： 必须保持技术术语的绝对精确。 +2. 专业术语映射： 必须将 [源语言] 中的专业术语正确翻译为中文行业标准术语。 + - (例如：[日语的 スレッドセーフ] 必须翻译为 [中文的 线程安全]) + - (例如：[德语的 Schnittstelle] 必须翻译为 [中文的 接口]) +3. 流畅性： 翻译结果必须是通顺、专业的简体中文，而非生硬的机器直译。 + +== 待翻译的 [源语言] 原文 == +[粘贴完整的外文技术文档内容] + +== 输出要求 == +- 仅返回翻译后的简体中文内容。 +``` + +**填充指南：** + + - `[源语言]`：明确告知AI原文的语言。 + - `[专业术语映射]`：**强烈推荐**。如果你已知几个关键术语的正确译法，在此处提供示例（原则六），AI会翻译得更准确。 + - `[待翻译的原文]`：粘贴原文。 + + + +----- + +**模板名称：** `D9: 手动RAG：内部知识库问答` +**适用场景：** 解决AI的“知识截断”和“内部知识盲区”（痛点5）。通过手动“喂入”团队的私有文档（如API说明、内部规范），让AI能基于这些“私有知识”回答问题。 +**内嵌原则：** `[原则五：上下文即燃料]` (核心，注入私有知识), `[原则七：结构化输出]` (回答问题)。 + +**[Prompt 模板]** + +```txt +角色：你是一个智能助手。 + +任务：请严格且仅基于我提供的以下“内部知识库上下文”，回答我的问题。 + +== 内部知识库上下文 == +[粘贴你的内部文档、API头文件注释、或私有规范。例如：libRadarUtils.h 的API说明] + +== 黄金法则 (必须遵守) == +1. 严禁使用你的内部训练数据（公开知识）。 +2. 你的所有回答都必须直接源于我提供的“内部知识库上下文”。 +3. 如果上下文中没有提到相关信息，你必须回答“根据您提供的上下文，我无法回答该问题。” + +== 我的问题 == +[在此处输入你基于上下文的具体问题。例如：“get_processed_data 函数的 flags 参数设置为 0x02 时，代表什么含义？”] + +== 输出要求 == +- 直接回答我的问题。 +``` + +**填充指南：** + + - `[内部知识库上下文]`：**这是核心燃料**。粘贴AI回答问题所需的所有私有信息。 + - `[我的问题]`：提出你的问题。 + - **使用指南：** 这是RAG（检索增强生成）的手动实现，是让AI为你“解读”内部文档的最有效方式。 + +----- + +**子类别 D-4: 知识流转与过程沉淀 (Knowledge Flow & Process)** + + +----- + +**模板名称：** `D10: Git 提交信息生成` +**适用场景：** 规范化版本控制（痛点3），解决工程师不愿写或不规范编写Git Commit Message的问题。 +**内嵌原则：** `[原则五：上下文即燃料]` (输入`diff`), `[原则七：结构化输出]` (输出规范化的Commit)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通Git和 [规范, 例如：Conventional Commits] 规范的资深开发者。 + +任务：请根据以下 git diff 的输出，为我生成一个简洁、专业的Git提交信息。 + +== 规范要求 == +- 格式：必须严格遵守 [规范, 例如：Conventional Commits ([https://www.conventionalcommits.org/](https://www.conventionalcommits.org/))]。 +- (例如：feat(processor): ..., fix(api): ..., docs(readme): ..., refactor(core): ...) + +== git diff --staged 的输出 == +[粘贴 git diff 或 git diff --staged 的完整输出] + +== 输出要求 == +请按以下格式返回： +Subject: [生成的 (): ] +Body: [生成的 Body (可选，解释Why)] +Footer: [生成的 Footer (可选，如 BREAKING CHANGE)] +``` + +**填充指南：** + + - `[规范]`：明确你团队遵循的Commit规范。 + - `[git diff ... 输出]`：**必须提供**。AI通过阅读`diff`来理解“这次提交做了什么”，这是生成Commit信息的核心依据。 + + + +----- + +**模板名称：** `D11: 讨论/纪要 结构化总结` +**适用场景：** 沉淀“过程知识”（痛点3）。用于将来自Slack、Teams、微信群聊或会议语音转写的非结构化、混乱的讨论记录，快速整理为结构化的“会议纪要”。 +**[Prompt 模板]** + +```txt +角色：你是一名高效的项目经理（PM）和会议主持人。 + +任务：请严格审查以下非结构化的“讨论文字记录”，并为团队提取一份结构化的“行动纪要”。 + +== 讨论文字记录 == +[粘贴来自Slack/Teams/会议转写的原始聊天记录] + +== 纪要要求 (必须以此结构输出) == +请严格按照以下Markdown格式，提取所有关键信息： + +### 1. 关键决策 (Key Decisions) +- [决策1：...] +- [决策2：...] +### 2. 行动项 (Action Items - AI) +- [AI-1]：[任务描述] - 负责人： @[姓名] - 截止日期： [日期] +- [AI-2]：[任务描述] - 负责人： @[姓名] +### 3. (可选) 开放问题 (Open Questions) +- [问题1：...] +- [问题2：...] + +== 黄金法则 == +- 必须专注于提取“决策”和“行动”，忽略闲聊和重复讨论。 +- “行动项”必须明确“任务内容”和“负责人”。 +``` + +**填充指南：** + + - `[讨论文字记录]`：**必须提供**。粘贴原始的、未经整理的讨论内容。 + - **使用指南：** 这是将“过程知识”固化为“静态资产”的关键工具，能极大提升团队沟通效率。 + + + +----- + +**模板名称：** `D12: 架构决策记录（ADR）编写` +**适用场景：** 固化关键决策（痛点3）。当团队在（如 技术选型、架构模式）上达成一致后，用于快速生成一份标准化的“架构决策记录”（ADR），以便未来追溯“为什么”这么做。 +**内嵌原则：** `[原则五：上下文即燃料]` (输入决策背景), `[原则七：结构化输出]` (输出ADR Markdown)。 + +**[Prompt 模板]** + +```txt +角色：你是一名资深的系统架构师，是“架构决策记录”（ADR）的坚定实践者。 + +任务：请根据我的决策上下文，为我生成一份专业的Markdown格式的ADR。 + +== 决策上下文 == +1. 决策标题： [例如：选择 gRPC 作为内部服务间通信协议] +2. 背景 (Context)： [描述我们面临的问题。例如：内部微服务间需要一种高性能、低延迟、强类型的RPC机制...] +3. 决策 (Decision)： [描述我们最终的选择。例如：我们决定采用 gRPC (基于 Protobuf)。] +4. 理由 (Rationale)： [描述为什么这么选。例如：1. 性能优于REST/JSON；2. Protobuf提供强类型校验... 3. 放弃REST的理由是...] +5. 后果 (Consequences)： [描述此决策带来的正面和负面影响。例如：(+) 接口一致性高；(-) 学习曲线较陡峭；(-) 不易被浏览器直接调用...] + +== ADR 模板 (可选) == +- (可选) 状态 (Status)：[例如：已接受] +- [可粘贴你团队的ADR模板，例如 Michael Nygard 的模板] + +== 输出要求 == +- 返回一份完整的、格式良好的Markdown ADR文件。 +``` + +**填充指南：** + + - `[决策上下文]` (1-5)：**必须提供**。你必须告诉AI你的决策内容、背景和理由，AI负责将其“格式化”和“专业化”。 + - `[ADR 模板]`：可选。提供模板能确保输出格式的绝对一致。 + + + +----- + +**模板名称：** `D13: [D2] 需求到技术任务分解` +**适用场景：** 在项目规划（Sprint Planning）或任务分配阶段，用于将高层级的用户故事（User Story）或Jira Ticket的原始需求，分解为工程师可执行、可跟踪的详细技术子任务列表。 +**内嵌原则：** `[原则二：任务解构]` (核心), `[原则七：结构化输出]` (输出列表), `[原则五：上下文即燃料]` (输入需求)。 + +**[Prompt 模板]** + +```txt +角色：你是一名资深的技术主管（Tech Lead）和系统架构师，精通敏捷开发和任务分解。 + +任务：请将以下“原始需求描述”分解为一份可执行的、面向工程师的“技术任务列表”。 + +== 原始需求描述 (User Story / Jira Ticket) == +[粘贴一个用户故事或Jira Ticket的原始需求描述。例如：“作为一名信号处理工程师，我希望能有一个‘航迹缓存服务’，以便在100ms内查询到最近5分钟内的所有活跃航迹，数据需要持久化。”] + +== 任务列表要求 == +请以结构化的格式（例如Markdown列表或表格）输出，必须包含： +1. 史诗/特性 (Epic/Feature)： [AI根据需求自动命名，例如：航迹缓存服务 (TrackCacheService)] +2. 技术子任务 (Sub-Tasks)： + - [ ] 任务 1：(例如：架构设计 - 定义gRPC API (CreateTrack, GetTrack) 和 数据模型 (Track)) + - [ ] 任务 2：(例如：后端 - 实现核心缓存逻辑 (例如 Redis 或 内存缓存)) + - [ ] 任务 3：(例如：后端 - 实现数据持久化与回填逻辑) + - [ ] 任务 4：(例如：后端 - 实现gRPC服务端点) + - [ ] 任务 5：(例如：测试 - 编写缓存命中/淘汰的单元测试) + - [ ] 任务 6：(例如：测试 - 编写gRPC API的集成测试) + - [ ] 任务 7：(例如：部署 - 编写Dockerfile和K8s部署YAML) +3. 依赖关系 (Dependencies)： (可选，例如：任务3 依赖 任务1) +4. (可选) 估算 (Estimation)： (可选，例如：任务1 (S), 任务2 (M), 任务3 (L)) + +== 黄金约束 == +- 任务分解必须足够细粒度，以便工程师可以直接领取并执行。 +- 必须覆盖从“设计”到“实现”再到“测试”和“部署”的全流程（端到端）。 +``` + +**填充指南：** + + - `[原始需求描述]`：**必须提供**。这是任务分解的唯一依据。需求描述越清晰（包含NFRs），任务分解越准确。 + - `[任务列表要求]`：你可以根据团队的项目管理习惯（如是否需要估算、依赖关系）来调整此部分的输出要求。 + +----- diff --git a/Prompt模板/05_Agent优化与修改模板库.md b/Prompt模板/05_Agent优化与修改模板库.md new file mode 100644 index 0000000..deae4f4 --- /dev/null +++ b/Prompt模板/05_Agent优化与修改模板库.md @@ -0,0 +1,381 @@ +#### E. 类别五：“从一到一百”（优化与修改） (Optimization & Modification) + +**模板索引 (Index)** + +| 模板ID | 核心用途 | 使用场景 / 关键词 | +| :--- | :--- | :--- | +| **E-1: 代码重构与迁移** | | | +| **[`E1`](#E1)** | 全局符号重命名 | 重构引擎, 成员限定重命名, 语义安全 | +| **[`E2`](#E2)** | 跨文件依赖迁移 | 库替换, API映射, 头文件调整 | +| **[`E3`](#E3)** | 全局代码规范化与格式化 | 规则批处理, 指针现代化, 花括号规范 | +| **[`E4`](#E4)** | 跨文件性能优化 | 瓶颈函数替换, 语义重构, 变量/常量同步 | +| **E-2: 功能增强与同步** | | | +| **[`E5`](#E5)** | 基于评审列表的全局修改 | Review执行, 定位行号, 批处理变更 | +| **[`E6`](#E6)** | 接口扩展与实现同步 | 纯虚方法新增, 派生类stub同步 | +| **[`E7`](#E7)** | 文档-代码同步审查与修复 | 头文件签名提取, Markdown更新 | + +----- + +**子类别 E-1: 代码重构与迁移 (Refactoring & Migration)** + + +----- + +**模板名称：** `E1: [Agent模板] 全局符号重命名` +**适用场景：** `D4 (Agent)` 模式。对整个工作区（`@workspace`）中一个特定的符号（如类名、方法名、函数名）进行全局、上下文感知的重命名。 +**内嵌原则：** `[原则二：任务解构]` (D4)、`[原则八：决定论]` (要求精确、非创造性修改)。 + +**[Prompt 模板]** + +```txt +角色：你是一个精确的、上下文感知的C++重构引擎。 + +任务：请在整个工作区（@workspace）执行一次全局符号重命名。 + +== 重构规格 (Specification) == +1. 旧符号 (Old Symbol)： [例如：getData] +2. 新符号 (New Symbol)： [例如：readData] +3. 重构上下文 (Context)： + - 这是一个绝对约束。 + - 你只能重命名 [旧符号]，当且仅当它属于 [类名/接口名，例如：IDataSource] 或其任何派生类（Derived Class）的成员。 + - 严禁重命名在其他不相关类中同名的 [旧符号]。 + +== 执行计划 (Execution Plan) == +1. 扫描范围： 整个工作区（@workspace）。 +2. 目标文件类型： [例如：*.cpp, *.h, *.hpp, *.md, *.txt] (覆盖代码和文档)。 +3. C++ 代码修改 (.cpp, .h, .hpp)： + - 查找并替换所有符合 [重构上下文] 约束的符号。 + - 这包括： + - (a) 头文件中的 virtual 声明。 + - (b) 实现类中的定义（Definition）。 + - (c) 所有使用 . 或 -> 对该成员的调用点（Call Sites）。 +4. 文档修改 (.md, .txt)： + - 查找并替换所有对 [旧符号] 的文本引用（例如API文档、README）。 + +== 最终约束 == +- 你的修改必须是原子性的、上下文感知的。 +- 严禁修改任何与此重构任务无关的代码逻辑。 +``` + +**填充指南：** + + - `[旧符号]` 和 `[新符号]`：提供明确的名称。 + - `[类名/接口名]`：**这是此模板最关键的约束**。它将Agent的行为从“全局查找替换”限制为“上下文感知的重构”，确保了修改的精确性，防止了对不相关代码的破坏。 + - `[目标文件类型]`：根据需要调整，确保文档（如`README.md`）也被一并更新。 + + + +----- + +**模板名称：** `E2: [Agent模板] 跨文件依赖迁移` +**适用场景：** `D4 (Agent)` 模式。在整个代码库中，将一个废弃的库（如`OldLogger`）的API调用，完整迁移到一个新的库（如`spdlog`）。 +**内嵌原则：** `[原则二：任务解构]` (D4)、`[原则六：示例优先]` (迁移规则即示例)、`[原则五：上下文即燃料]`。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通C++库迁移的软件工程师。 + +任务：请在整个工作区（@workspace）执行一次API依赖迁移。 + +== 迁移目标 == +- 从 (Old API)： [例如：OldLogger 库] +- 到 (New API)： [例如：spdlog 库] + +== 迁移规则 (必须严格遵守) == +这是此次迁移的核心映射表。你必须在所有相关文件中应用这些规则： + +1. 头文件管理 (Header Management)： + - 移除 (Remove)： [例如：在所有文件中移除 #include "OldLogger.h"] + - 添加 (Add)： [例如：在需要的文件顶部添加 #include "spdlog/spdlog.h"] (如果尚未存在) + +2. API 调用映射 (API Call Mapping)： + - 规则 1 (From)： [例如：OldLogger::Log(LOG_DEBUG, ...)] + - 规则 1 (To)： [例如：spdlog::debug(...)] + + - 规则 2 (From)： [例如：OldLogger::Log(LOG_INFO, ...)] + - 规则 2 (To)： [例如：spdlog::info(...)] + + - 规则 3 (From)： [例如：OldLogger::Log(LOG_WARN, ...)] + - 规则 3 (To)： [例如：spdlog::warn(...)] + + - 规则 4 (From)： [例如：OldLogger::Log(LOG_ERR, ...)] + - 规则 4 (To)： [例如：spdlog::error(...)] + + - 规则 5 (From)： [例如：OldLogger::Init(...)] + - 规则 5 (To)： [例如：spdlog::default_logger()->set_level(...)] + +== 执行计划 == +1. 扫描范围： 整个工作区（@workspace）。 +2. 目标文件类型： [例如：*.cpp, *.h, *.hpp, CMakeLists.txt] +3. 执行： + - (a) 扫描所有目标文件。 + - (b) 应用 [头文件管理] 规则。 + - (c) 应用 [API 调用映射] 规则，确保参数（...）被正确传递。 + - (d) (可选) 如果 [CMakeLists.txt] 中有链接库，也请更新。 +``` + +**填充指南：** + + - `[迁移规则]`：**这是此模板的核心**。你必须提供详尽的、模式匹配的“From-To”列表。`[原则六：示例优先]` 在此体现为“规则即示例”，Agent将模仿这些规则进行替换。 + - `[... ]` (省略号)：用于告知AI保留原始调用的参数。 + + + +----- + +**模板名称：** `E3: [Agent模板] 全局代码规范化与格式化` +**适用场景：** `D4 (Agent)` 模式。当自动化工具（如linter）缺失或不足时，用于在整个代码库中强制执行特定的、语义化的编码规范。 +**内嵌原则：** `[原则二：任务解构]` (D4)、`[原则六：示例优先]` (格式化规则)、`[原则八：决定论]`。 + +**[Prompt 模板]** + +```txt +角色：你是一个自动化的代码质量 Linter 和 Formatter。 + +任务：请在整个工作区（@workspace）审查并修复所有违反以下规范的代码。 + +== 目标文件类型 == +- [例如：*.cpp, *.h, *.hpp] + +== 规范规则集 (必须全部应用) == +1. 规则 1：[例如：指针现代化] + - 查找 (Find)： [例如：NULL] + - 替换 (Replace)： [例如：nullptr] + - 约束： [例如：仅当 NULL 被用作指针字面量时。严禁替换字符串或宏定义中的 "NULL"。] + +2. 规则 2：[例如：强制代码块花括号] + - 查找 (Find Pattern)： [例如： + if (condition) + statement; + // 或 + if (condition) statement; + ] + - 替换 (Replace Pattern)： [例如： + if (condition) { + statement; + } + ] + - 适用范围： [例如：必须应用于 if, else, for, while 语句。] + +3. 规则 3：[例如：移除 C 风格类型转换] + - 查找 (Find Pattern)： [例如：(MyType*)ptr] + - 替换 (Replace Pattern)： [例如：static_cast(ptr)] + - 约束： [例如：仅适用于 static_cast。如果需要 reinterpret_cast，请添加 // TODO: Review C-Style Cast 注释。] + +== 全局约束 == +- 你只能应用上述 [规范规则集] 中定义的修改。 +- 严禁重构、修改或“优化”任何与这些规则无关的代码逻辑。 +``` + +**填充指南：** + + - `[规范规则集]`：此模板的核心。你必须为每一条规则提供清晰的“查找”和“替换”模式，这是 `[原则六：示例优先]` 的体现。 + - `[约束]`：为复杂规则（如`NULL`替换）添加约束，可显著提高Agent的准确性。 + + + +----- + +**模板名称：** `E4: [Agent模板] 跨文件性能优化` +**适用场景：** `D4 (Agent)` 模式。在D2模式或人工分析（Profiling）确定了瓶颈后，使用此模板指导Agent执行一个**具体**的、**跨文件**的优化方案。 +**内嵌原则：** `[原则二：任务解构]` (D4)、`[原则二：玻璃盒心态]` (Rationale部分)、`[原则五：上下文即燃料]`。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通C++和HPC（高性能计算）的优化专家。 + +任务：请在整个工作区（@workspace）执行一个已确定的性能优化方案。 + +== 优化上下文 (Rationale) == +- 瓶颈函数： [例如：utils::compute_distance(Point p1, Point p2)] +- 瓶颈分析： [例如：此函数被高频调用，其内部的 sqrt 造成了巨大开销。] +- 优化目标： [例如：在所有调用链中，用“平方距离比较”替换“真实距离比较”，以消除 sqrt。] + +== 优化执行计划 (必须严格遵守) == + +Step 1：修改被调用函数 (Callee) +1. 定位文件： [例如：src/utils.h 和 src/utils.cpp] +2. 动作 1.1 (重命名)： 将 [瓶颈函数] 重命名为 [新函数名，例如：utils::compute_distance_squared]。 +3. 动作 1.2 (修改实现)： 修改 [新函数名] 的实现，[例如：移除内部的 sqrt 调用，使其直接返回平方和 (dx*dx + dy*dy)]。 + +Step 2：修改调用方 (Callers) +1. 扫描范围： 整个工作区（@workspace）中所有调用了 [瓶颈函数] 的文件。 +2. 对每一个调用点 (Call Site) 执行以下语义重构： +3. 动作 2.1 (重命名调用)： 将 [瓶颈函数] 的调用替换为 [新函数名]。 +4. 动作 2.2 (跟踪返回值)： + - 识别存储该函数返回值的变量 (例如：float distance = ...)。 + - 将该变量重命名为 (例如：float distance_squared = ...)。 +5. 动作 2.3 (修复比较逻辑)： + - 查找所有使用该 [变量] 的地方 (例如：if (distance < MAX_DISTANCE)). + - 必须将比较值也修改为平方 (例如：if (distance_squared < MAX_DISTANCE_SQUARED))。 + - 你需要（或定义）一个新的常量 [例如：MAX_DISTANCE_SQUARED]。 + +== 最终约束 == +- 这是一个语义重构，而非简单的查找替换。 +- 你必须在 [Step 2] 中正确跟踪返回值，并修复其所有使用点的比较逻辑，以确保优化后的程序逻辑等价。 +``` + +**填充指南：** + + - `[优化上下文]`：必须清晰描述“Why”，这有助于Agent理解任务意图（玻璃盒原则）。 + - `[优化执行计划]`：**这是此模板的核心**。它将一个复杂的、D2分析得出的优化方案，“解构”为一个D4 Agent可以逐步执行的、确定性的计划。 + - `[动作 2.2]` 和 `[动作 2.3]` 是最关键的步骤，它们要求Agent具备跟踪变量和修复语义的能力，这是D4 Agent的核心价值。 + +----- + +**子类别 E-2: 功能增强与同步 (Enhancement & Synchronization)** + + +----- + +**模板名称：** `E5: [Agent模板] 基于评审列表的全局修改` +**适用场景：** `D4 (Agent)` 模式。将Code Review的结论（通常是一个Markdown或文本文件）作为“任务列表”，指导Agent（`@workspace`）自动在整个代码库中定位并应用这些修改。 +**内嵌原则：** `[原则二：任务解构]` (D4)、`[原则五：上下文即燃料]` (评审文件是核心燃料)、`[原则八：决定论]`。 + +**[Prompt 模板]** + +```txt +角色：你是一个自动化代码审查执行代理（Automated Review Executor）。 + +任务：请读取我提供的 [评审意见文件] (例如 @file:reviews/pr_101.md)，逐条解析其中的修改项，并在 @workspace 中定位并应用所有修改。 + +== 执行上下文 == +1. 工作区： @workspace +2. 评审意见文件 (必须在调用时提供)： [例如：@file:reviews/pr_101.md] +3. 评审项格式 (假设)： 假设文件中的每一项都遵循 [例如：“Item X: [File: path/to/file.cpp] [Line: Y] [Change: '...']”] 或类似的结构。 + +== 执行计划 (Execution Plan) == +1. 读取 (Read)： 打开并逐行读取 [评审意见文件]。 +2. 解析与循环 (Parse & Loop)： 遍历文件中的每一条修改项 (例如, "Item 1:", "缺陷 2:")。 +3. 对每一个修改项 (For Each Item)： + - (a) 定位 (Locate)： 提取 [文件名] 和 [行号] (如果提供)。 + - (b) 理解 (Understand)： 提取 [修改要求] (例如：“增加空指针检查”、“将 int 改为 size_t”、“移除多余的 printf”)。 + - (c) 执行 (Execute)： 打开 [文件名]，导航到 [行号]（或相关代码上下文），并精确地应用 [修改要求]。 + +== 黄金约束 (Golden Constraints) == +1. 精确性 (Precision)： 你的修改必须100%符合 [修改要求]。严禁进行任何“自由发挥”的额外重构、代码清理或格式化（除非修改要求本身就是格式化）。 +2. 原子性 (Atomicity)： 必须逐条应用修改。 +3. 歧义处理 (Ambiguity Handling)： 如果 [评审意见文件] 中的某一条指令不清晰、无法定位（例如行号已改变）或无法安全实现，你必须跳过该项。 +4. 报告 (Reporting)： 任务完成后，必须提供一份报告，列出： + - (a) [成功应用] 的修改项列表。 + - (b) [跳过] 的修改项列表及其原因（例如：歧义、代码已变更）。 +5. 范围 (Scope)： 严禁修改 [评审意见文件] 中未提及的任何文件或代码。 +``` + +**填充指南：** + + - **使用指南：** 此模板不是一次性粘贴。用户必须在调用Agent时，在Prompt中明确提供 `[评审意见文件]` 的路径，例如：`@workspace @file:reviews/pr_101.md [粘贴此模板的剩余部分]`。 + - `[评审项格式]`：如果你的评审文件格式很固定，在此处提供示例（原则六）将极大提高Agent的解析准确率。 + + + +----- + +**模板名称：** `E6: [Agent模板] 接口扩展与实现同步` +**适用场景：** `D4 (Agent)` 模式。在面向接口编程中，当一个核心接口（基类）发生变更（如添加新方法）时，自动在 `@workspace` 中找出所有实现（派生）类，并为其同步添加该方法（Stub）的桩实现。 +**内嵌原则：** `[原则二：任务解构]` (D4，多步骤计划)、`[原则五：上下文即燃料]`、`[原则六：示例优先]` (桩实现规范)。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通C++面向对象设计和大规模重构的专家。 + +任务：请在 @workspace 中执行一次“接口扩展”重构，并自动同步所有实现类。 + +== 执行计划 (Execution Plan) == +这是一个多步骤任务，请严格按顺序执行： + +Step 1: 扩展接口 (Extend Interface) +1. 定位文件 (Target File)： [例如：@file:src/interfaces/IProcessor.h] +2. 接口名 (Interface Name)： [例如：IProcessor] +3. 执行动作 (Action)： 在 [接口名] 类的 [例如：public] 区域，添加以下新的纯虚函数： + [粘贴新函数的完整签名，例如： + virtual bool initialize(const Config& cfg) = 0; + ] + +Step 2: 查找所有实现类 (Find Implementations) +1. 扫描范围 (Scan Scope)： 整个工作区（@workspace）。 +2. 目标 (Target)： 查找所有 public 继承自 [接口名] 的C++类 (例如：class CpuProcessor : public IProcessor, class GpuProcessor : public IProcessor)。 + +Step 3: 同步所有实现类 (Synchronize Implementations) +1. 循环 (Loop)： 对 [Step 2] 中找到的每一个实现类（例如 CpuProcessor）： +2. 动作 3.1 (更新头文件 .h)： + - 打开该类的 .h 文件 (例如：src/cpu/CpuProcessor.h)。 + - 在 [例如：public] 区域添加对应的方法声明 (移除 = 0 并添加 override 关键字)： + [粘贴新方法在派生类.h中的签名，例如： + bool initialize(const Config& cfg) override; + ] +3. 动作 3.2 (添加桩实现 .cpp)： + - 打开该类的 .cpp 文件 (例如：src/cpu/CpuProcessor.cpp)。 + - 在文件末尾（或合适位置）添加该方法的“桩函数”实现。 + - 桩实现规范 (必须严格遵守此模板)： + [粘贴桩实现的完整代码块，例如： + bool CpuProcessor::initialize(const Config& cfg) { + // TODO(JIRA-123 / [负责人]): Implement initialize() for CpuProcessor. + (void)cfg; // 避免 "unused parameter" 警告 + return true; // 或 false, 或 0, 或 {} + } + ] + +== 最终约束 == +- [桩实现规范] 必须被严格遵守，特别是 // TODO: 标记、默认返回值和(可选的)(void)param警告抑制，以确保代码库一致性并可编译。 +``` + +**填充指南：** + + - `[Step 1]` 和 `[Step 3]` 中的代码块是**必须**提供的。这是`[原则六：示例优先]`的应用，你必须给Agent提供精确的“目标代码”和“桩代码”模板，它才能正确执行。 + - `[桩实现规范]` 中的默认返回值（如`true`）应由工程师根据接口语义（LSP原则）来决定。 + + + +----- + +**模板名称：** `E7: [Agent模板] 文档-代码同步审查与修复` +**适用场景：** `D4 (Agent)` 模式。维护“活文档”（Living Documentation）。自动扫描代码库（如`.h`文件）和文档（如`.md`文件），找出两者之间的差异（如函数签名已变更），并自动**修复文档**以匹配代码。 +**内嵌原则：** `[原则二：任务解构]` (D4)、`[原则五：上下文即燃料]` (代码和文档路径)、`[原则八：决定论]`。 + +**[Prompt 模板]** + +```txt +角色：你是一名严格的技术文档作者（Technical Writer），负责保持文档与代码的绝对同步。 + +任务：请在 @workspace 中审查代码和文档，找出不一致的地方，并只更新文档使其与代码（Source of Truth）保持一致。 + +== 同步上下文 == +1. 代码源 (Source of Truth)： [例如：@dir:src/public_api/] (指定包含 .h 头文件的目录) +2. 文档目标 (Target to Fix)： [例如：@file:docs/Public_API_Reference.md] + +== 执行计划 (Execution Plan) == + +Step 1: 扫描代码源 (Parse Source of Truth) +1. 遍历 [代码源] 目录下的所有 [例如：.h 或 .hpp] 文件。 +2. 为所有 public [例如：函数/类/方法] 提取其“当前函数签名”（包括函数名、参数类型、返回值类型）。 + +Step 2: 扫描文档目标 (Parse Documentation) +1. 打开 [文档目标] 文件。 +2. 解析 Markdown，提取其中（例如：在###标题下或表格中）描述的每一个 [例如：函数/方法] 及其“文档签名”。 + +Step 3: 对比与修复 (Compare & Fix) +1. 循环 (Iterate)： 遍历 [Step 1] 中提取的每一个“当前函数签名”。 +2. 检查 (Check)： + - (a) 如果在文档中未找到 (Missing Doc)： + - 动作： 在 [文档目标] 文件的 [例如：API列表末尾] 添加该新函数的文档骨架（例如：一个新的 ### [函数名] 章节），并添加一个明确的占位符： + - (b) 如果在文档中已找到，但签名不匹配 (Outdated Doc)： + - 动作： 更新 [文档目标] 中的“文档签名”（例如：Markdown表格中的参数、标题），使其与 [Step 1] 中提取的“当前函数签名”严格一致。 +3. (可选) 检查废弃项 (Deprecated Doc)： + - 遍历 [Step 2] 的“文档签名”，如果在 [Step 1] 的代码中不存在该函数。 + - 动作： 在 [文档目标] 中该函数的部分，添加一个明确的 [DEPRECATED] 标记，或将其移至“废弃API”章节。 + +== 黄金约束 (Golden Constraint) == +- 单向同步 (Code-to-Doc)： 你的任务是使文档匹配代码。 +- 严禁 (FORBIDDEN)： 严禁以任何理由修改 [代码源] 目录下的任何 .h 或 .cpp 文件。所有修改必须且只能在 [文档目标] 文件上进行。 +``` + +**填充指南：** + + - `[代码源]` 和 `[文档目标]`：**必须提供**。用户在调用时必须明确指定Agent的扫描范围（`@dir`）和修改目标（`@file`）。 + - `[Step 3]` 的计划非常详细，这是为了确保Agent执行的是“修复”而非“重写”，并正确处理“新增”和“过时”两种情况。 + +----- diff --git a/Prompt模板/06_Agent创造与生成模板库.md b/Prompt模板/06_Agent创造与生成模板库.md new file mode 100644 index 0000000..dae84c9 --- /dev/null +++ b/Prompt模板/06_Agent创造与生成模板库.md @@ -0,0 +1,428 @@ +#### F. 类别六：“从0到1”（创造与生成） (Creation & Scaffolding) + +**模板索引 (Index)** + +| 模板ID | 核心用途 | 使用场景 / 关键词 | +| :--- | :--- | :--- | +| **F-1: 模块与服务创建** | | | +| **[`F1`](#F1)** | 自然语言项目初始化 | 项目脚手架, 目录结构, CMake初始化 | +| **[`F2`](#F2)** | 基于设计文档模块脚手架 | TDD解析, 接口/实现骨架, Stub生成 | +| **[`F3`](#F3)** | MVP/服务原型生成 | gRPC/REST原型, 服务器+客户端, 构建脚本 | +| **F-2: 任务与功能实现** | | | +| **[`F4`](#F4)** | 跨文件特性实现 | 接口+实现+测试联动, 纵向切片 | +| **[`F5`](#F5)** | 新模块测试套件生成 | gtest/gmock, Fixture, Mock依赖 | +| **F-3: 基础设施与环境创建** | | | +| **[`F6`](#F6)** | 基础设施即代码(IaC)生成 | Dockerfile, compose, CI配置 | +| **[`F7`](#F7)** | 适配层/绑定代码生成 | pybind11, 头文件解析, API绑定 | + +----- + +**子类别 F-1: 模块与服务创建 (Module & Service Scaffolding)** + + + +----- + +**模板名称：** `F1: 基于自然语言的项目工作区初始化` +**适用场景：** `D4 (Agent)` 模式。项目启动的“第0步”。将一个高层级的自然语言想法（“我要做一个XX项目”）直接转化为一个标准化的、包含目录结构和基础配置文件的工作区。 +**内嵌原则：** `[原则二：任务解构]` (D4)、`[原则八：决定论]`、`[原则五：上下文即燃料]`。 + +**[Prompt 模板]** + +```txt +角色：你是一个项目脚手架生成机器人（Project Scaffolding Bot）。 + +任务：请根据我的“项目描述”，在 @workspace 中初始化一个全新的项目结构。 + +== 项目描述 == +1. 项目名称 (Project Name)： [例如：RadarSignalSimulator] +2. 核心语言 (Language)： [例如：C++] +3. 构建系统 (Build System)： [例如：CMake (现代C++17标准)] +4. 项目类型 (Type)： [例如：可执行程序 (Executable)] +5. (可选) 核心依赖： [例如：Boost, gtest (用于测试)] + +== 执行计划 (Execution Plan) == +1. 创建根目录： 在 @workspace 中创建 [项目名称] 根目录。 +2. 创建目录结构 (Directory Structure)： + - 在 [项目名称]/ 下创建 src/ (用于源代码) + - 在 [项目名称]/ 下创建 include/ (用于头文件) + - 在 [项目名称]/ 下创建 tests/ (用于测试) + - 在 [项目名称]/ 下创建 docs/ (用于文档) + - 在 [项目名称]/ 下创建 scripts/ (用于辅助脚本) +3. 生成 .gitignore： + - 在 [项目名称]/ 根目录创建 .gitignore 文件。 + - 必须填入适用于 [语言] 和 [构建系统] 的标准模板内容 (例如：忽略 build/, *.o, *.exe, *.out)。 +4. 生成 README.md： + - 在 [项目名称]/ 根目录创建 README.md。 + - 必须包含一级标题 #[项目名称] 和“快速上手”章节的占位符。 +5. 生成构建系统骨架 (Build System Scaffolding)： + - 在 [项目名称]/ 根目录创建 CMakeLists.txt。 + - 必须包含：cmake_minimum_required, project(...), set(CMAKE_CXX_STANDARD 17), add_executable(...), 以及 find_package (针对 [核心依赖]) 的占位符。 + - (可选) 在 [项目名称]/tests/ 下创建 CMakeLists.txt (用于 gtest)。 +6. 生成“Hello World”骨架： + - 创建 [项目名称]/src/main.cpp。 + - 必须包含一个最小可运行的 main 函数 (例如：打印 "Hello, [项目名称]!")。 + +== 最终约束 == +- 严格按照上述计划创建目录和文件，严禁添加任何未提及的文件。 +- 生成的文件内容必须是健壮的、遵循最佳实践的“骨架”代码。 +``` + +**填充指南：** + + - `[项目描述]`：**这是核心燃料**。用户必须提供清晰的项目名称、语言和构建系统，Agent才能生成匹配的脚手架。 + - **使用指南：** 这是“从0到0.1”的模板，它负责建立结构，后续的 `F2` 或 `F3` 模板则负责在结构中填充内容。 + + + +----- + +**模板名称：** `F2: 基于设计文档的模块脚手架生成` +**适用场景：** `D4 (Agent)` 模式。在项目结构（F1）已存在后，根据详细的TDD（技术设计文档）自动生成一个新模块所需的全部C++文件骨架。 +**内嵌原则：** `[原则二：任务解构]` (D4)、`[原则五：上下文即燃料]` (设计文档是核心)、`[原则七：结构化输出]`。 + +**[Prompt 模板]** + +```txt +角色：你是一个“技术设计文档到代码”（TDD-to-Code）的生成引擎。 + +任务：请严格按照我提供的 [设计文档] (例如 @file:docs/Logger.md)，在 @workspace 中生成对应C++模块的完整文件脚手架。 + +== 执行上下文 == +1. 工作区： @workspace +2. 设计文档 (必须在调用时提供)： [例如：@file:docs/Logger.md] +3. 目标根目录 (Target Root)： [例如：@dir:src/modules/] + +== 执行计划 (Execution Plan) == +1. 读取 (Read)： 打开并深度解析 [设计文档]。 +2. 提取实体 (Extract)： 从文档中提取 [模块名] (例如：Logger), [接口/基类] (例如：ILogger), 以及 [实现类] (例如：FileLogger, ConsoleLogger, LoggerManager)。 +3. 创建目录： 在 [目标根目录] 下创建 [模块名] 目录 (例如：src/modules/Logger/)。 +4. 循环生成文件 (Loop & Generate)： + - (a) 对于 [接口/基类] (例如 ILogger)： + - 创建 [模块名]/[接口名].h 文件。 + - 必须包含：头文件保护 (#pragma once 或 #ifndef)。 + - 必须包含：[设计文档] 中定义的所有纯虚函数 (例如 virtual void log(...) = 0;)。 + - 必须包含：Doxygen 注释骨架 (@brief, @param, @return)。 + - (b) 对于 [实现类] (例如 FileLogger)： + - 创建 [模块名]/[类名].h 文件。 + - 必须包含：头文件保护。 + - 必须 public 继承自 [接口名] (例如 class FileLogger : public ILogger)。 + - 必须声明 [设计文档] 中定义的所有成员函数（添加 override）和私有成员变量。 + - 必须添加 Doxygen 注释骨架。 + - (c) 对于 [实现类] (例如 FileLogger)： + - 创建 [模块名]/[类名].cpp 文件。 + - 必须 include 对应的 .h 文件。 + - 必须为所有成员函数生成“桩函数”（Stub）实现。 + - 桩实现规范： 必须包含 // TODO: Implement [函数名] 注释，并返回一个默认值（如 void, true, nullptr）。 + +== 最终约束 == +- 生成的文件必须严格匹配 [设计文档] 中定义的类名、继承关系和函数签名。 +- 所有生成的 .h 和 .cpp 文件都必须包含 Doxygen 注释骨架。 +``` + +**填充指南：** + + - **使用指南：** 用户必须在调用时提供 `@workspace` 和设计文档的路径 (`@file:...`)。 + - `[设计文档]`：这份文档的质量（是否清晰、无歧义）直接决定了Agent生成脚手架的质量。 + + + +----- + +**模板名称：** `F3: [Agent模板] 最小可行产品(MVP)/服务原型生成` +**适用场景：** `D4 (Agent)` 模式。用于快速启动一个特定技术栈（如gRPC, REST API）的“最小可行”（MVP）服务，生成所有必需的文件（API定义、服务器、客户端、构建脚本）。 +**内嵌原则：** `[原则二：任务解构]` (D4)、`[原则七：结构化输出]`、`[原则五：上下文即燃料]`。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通 [技术栈, 例如：gRPC 和 C++ CMake] 的全栈原型工程师。 + +任务：请在 @workspace 中为我生成一个 [技术栈] 的最小可行产品（MVP）服务原型。 + +== 原型需求 == +1. 服务名称 (Service Name)： [例如：RadarConfigService] +2. 技术栈 (Tech Stack)： [例如：gRPC (C++)] +3. 核心功能 (Core RPC)： [例如：定义一个 SetConfig RPC] +4. RPC 请求 (Request)： [例如：ConfigData (包含 int32 param1, float param2)] +5. RPC 响应 (Response)： [例如：ConfigResponse (包含 bool success)] + +== 执行计划 (Execution Plan) == +请在 @workspace 根目录下创建并填充以下文件： + +1. 文件 1：API 定义 (例如 [服务名称].proto) + - 必须包含：syntax = "proto3";, package ...; + - 必须定义：service [服务名称]。 + - 必须包含：rpc [核心功能]([RPC 请求]) returns ([RPC 响应]); + - 必须定义：message [RPC 请求] 和 message [RPC 响应] 的结构。 +2. 文件 2：服务器实现 (例如 server.cpp) + - 必须包含：gRPC 和 .proto 生成的 .h 文件。 + - 必须实现：[服务名称]ServiceImpl 类，继承自 [服务名称]::Service。 + - 必须实现：[核心功能] 方法的桩函数（返回一个默认的 [RPC 响应]）。 + - 必须包含：main() 函数，用于启动 gRPC 服务器并监听 [端口, 例如：0.0.0.0:50051]。 +3. 文件 3：客户端示例 (例如 client.cpp) + - 必须包含：gRPC 和 .proto 生成的 .h 文件。 + - 必须包含：main() 函数。 + - 必须展示：如何创建 Channel、创建 Stub、组装 [RPC 请求]、调用 [核心功能] RPC，并打印 [RPC 响应]。 +4. 文件 4：构建脚本 (例如 CMakeLists.txt) + - 必须包含：find_package(gRPC REQUIRED), find_package(Protobuf REQUIRED)。 + - 必须包含：用于编译 .proto 文件的 protobuf_generate_- 规则。 + - 必须包含：add_executable(server server.cpp ...) 和 add_executable(client client.cpp ...)。 + - 必须包含：target_link_libraries (链接 gRPC, Protobuf 等)。 + +== 最终约束 == +- 生成的所有文件必须是相互关联、可编译、可运行的（假设依赖已安装）。 +- 所有桩函数必须包含 // TODO: Add business logic here 注释。 +``` + +**填充指南：** + + - `[原型需求]`：**这是核心燃料**。用户必须清晰定义服务名称、技术栈和至少一个核心功能（如RPC）的输入输出。 + - `[技术栈]`：此模板可适配多种技术，如 `REST API (FastAPI, Python)` 或 `gRPC (Go)`，只需修改提示中的技术栈名称和 `[执行计划]` 中的文件名及库即可。 + +----- + +**子类别 F-2: 任务与功能实现 (Feature & Task Implementation)** + + + +----- + +**模板名称：** `F4: 跨文件特性实现` +**适用场景：** `D4 (Agent)` 模式。实现一个“纵向特性”（Vertical Feature Slice），该特性需要**同时修改**多个现有的、不同角色的文件（如接口、实现、测试）。 +**内嵌原则：** `[原则二：任务解构]` (D4，核心)、`[原则八：决定论]`。 + +**[Prompt 模板]** + +```txt +角色：你是一个遵循指令的自动化C++特性实现Agent。 + +任务：请严格按照以下“特性实现执行计划”，在 @workspace 中修改现有文件以实现新功能。 + +== 特性名称 == +- [例如：添加“重置”功能到所有处理器] + +== 执行计划 (Execution Plan) == +你必须严格按照以下顺序和规范，修改指定的文件： + +Step 1：修改 [接口文件] +- 文件： [例如：@file:src/interfaces/IProcessor.h] +- 动作： 在 IProcessor 接口中，添加一个新的纯虚函数： + [粘贴新接口签名，例如：virtual void reset() = 0;] + +Step 2：修改 [实现类A] +- 文件： [例如：@file:src/cpu/CpuProcessor.h] +- 动作： 在 CpuProcessor 类的 public 部分添加方法声明： + [粘贴派生类声明，例如：void reset() override;] +- 文件： [例如：@file:src/cpu/CpuProcessor.cpp] +- 动作： 在文件末尾添加桩函数实现： + [粘贴桩函数实现，例如： + void CpuProcessor::reset() { + // TODO: Implement reset logic for CPU + m_internal_state = 0; // 示例逻辑 + } + ] + +Step 3：修改 [实现类B] +- 文件： [例如：@file:src/gpu/GpuProcessor.h] +- 动作： 在 GpuProcessor 类的 public 部分添加方法声明： + [粘贴派生类声明，例如：void reset() override;] +- 文件： [例如：@file:src/gpu/GpuProcessor.cpp] +- 动作： 在文件末尾添加桩函数实现： + [粘贴桩函数实现，例如： + void GpuProcessor::reset() { + // TODO: Implement reset logic for GPU + // (e.g., reset CUDA buffers) + } + ] + +Step 4：修改 [测试文件] +- 文件： [例如：@file:tests/ProcessorTest.cpp] +- 动作： 添加一个新的gtest测试用例骨架： + [粘贴测试用例骨架，例如： + TEST(ProcessorTest, ResetFunction) { + // TODO: Write test for reset() + // CpuProcessor cpu; + // cpu.reset(); + // EXPECT_EQ(cpu.getState(), 0); + } + ] + +== 最终约束 == +- 原子性： 必须按顺序完成所有步骤。 +- 精确性： 严禁修改任何 [执行计划] 中未明确提及的文件或代码行。 +``` + +**填充指南：** + + - **使用指南：** 这是D4 Agent的“高级”用法。工程师（用户）扮演“架构师”，负责将特性“解构”为`[执行计划]`。Agent（AI）扮演“执行者”。 + - `[执行计划]`：**这是核心燃料**。工程师提供的步骤越详细、越精确（包括粘贴目标代码），Agent的执行成功率越高。 + + + +----- + +**模板名称：** `F5: 新模块的“测试套件”生成` +**适用场景：** `D4 (Agent)` 模式。在模块（如 `NewModule.h`）的核心功能已定义后，用于自动创建配套的、包含 `gtest` 和 `gmock` 的完整测试文件（`_test.cpp`）。 +**内嵌原则：** `[原则二：任务解构]` (D4)、`[原则七：结构化输出]`、`[原则五：上下文即燃料]`。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通C++ gtest 和 gmock 框架的自动化QA工程师。 + +任务：请为我提供的 [目标头文件] 自动生成一个完整的gtest测试套件文件。 + +== 执行上下文 == +1. 工作区： @workspace +2. 目标头文件 (Source of Truth)： [例如：@file:src/modules/NewModule.h] +3. 测试文件输出路径： [例如：@file:tests/NewModule_test.cpp] + +== 执行计划 (Execution Plan) == +1. 读取 (Read)： 打开并深度解析 [目标头文件]。 +2. 分析 (Analyze)： + - (a) 识别目标类名（例如 NewModule）。 + - (b) 识别所有 public 方法（例如 methodA, methodB）。 + - (c) 识别构造函数中的依赖（例如 IDependencyA- dep），这些是需要Mock的目标。 +3. 创建测试文件 (Create)： 创建 [测试文件输出路径]。 +4. 生成文件内容 (Generate)： + - (a) Includes： 必须包含 gtest/gtest.h, gmock/gmock.h, 以及 [目标头文件]。 + - (b) Mock 类生成： + - 针对 [分析] (c) 中识别的每一个依赖（例如 IDependencyA）： + - 生成 Mock[依赖名] 类 (例如 class MockDependencyA : public IDependencyA { ... })。 + - 必须使用 MOCK_METHOD 宏为所有接口方法生成Mock。 + - (c) Test Fixture 生成： + - 生成 class [模块名]Test : public ::testing::Test { ... }。 + - 必须在 SetUp() 方法中初始化Mock对象和被测类 [模块名]。 + - (d) 测试用例 (Test Cases) 生成： + - 针对 [分析] (b) 中识别的每一个 public 方法： + - 至少生成一个 TEST_F([模块名]Test, [方法名]_HappyPath) 骨架。 + - 至少生成一个 TEST_F([模块名]Test, [方法名]_EdgeCase) 骨架。 + - 骨架要求： 必须包含 // Arrange, // Act, // Assert 三段式注释，并添加 // TODO: ... 占位符。 + +== 最终约束 == +- 必须自动识别依赖并生成 gmock 类。 +- 必须为所有 public 方法生成测试用例骨架。 +``` + +**填充指南：** + + - **使用指南：** 用户调用时必须提供 `@workspace` 和 `@file:[目标头文件]` 的路径。 + - `[目标头文件]`：Agent将解析此文件以确定要测试什么和要Mock什么。 + +----- + +**子类别 F-3: 基础设施与环境创建 (Infrastructure & Environment)** + + + +----- + +**模板名称：** `F6: [Agent模板] 基础设施即代码(IaC)生成` (原F5) +**适用场景：** `D4 (Agent)` 模式。为现有的C++ CMake项目自动生成DevOps/IaC（基础设施即代码）所需的环境配置文件，如 `Dockerfile`, `docker-compose.yml`, `.gitlab-ci.yml`。 +**内嵌原则：** `[原则二：任务解构]` (D4)、`[原则七：结构化输出]`、`[原则五：上下文即燃料]`。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通DevOps、容器化（Docker）和CI/CD（GitLab CI）的SRE工程师。 + +任务：请为我当前的C++ CMake项目（在 @workspace 中）生成一套标准化的IaC（基础设施即代码）配置文件。 + +== 项目上下文 == +1. 项目类型： [例如：C++ CMake 项目] +2. 构建命令 (Build)： [例如：cmake .. && make -j] +3. 测试命令 (Test)： [例如：ctest] 或 [./build/run_tests] +4. 最终产物 (Artifact)： [例如：./build/my_app] (可执行文件) + +== 执行计划 (Execution Plan) == +请在 @workspace 根目录创建并填充以下文件： + +1. 文件 1：Dockerfile (用于生产/部署) + - 规范： 必须使用“多阶段构建”（Multi-Stage Build）。 + - (a) builder 阶段： + - FROM [基础镜像, 例如：ubuntu:22.04] + - WORKDIR /build + - COPY . . + - RUN [安装依赖, 例如：apt-get install cmake build-essential ...] + - RUN [构建命令] + - (b) final 阶段： + - FROM [轻量级镜像, 例如：ubuntu:22.04-slim] + - COPY --from=builder /build/[最终产物] /app/ + - ENTRYPOINT ["/app/[最终产物]"] +2. 文件 2：docker-compose.yml (用于本地开发/测试) + - 规范： 定义一个服务（例如 dev）。 + - 必须包含 build: . (使用 Dockerfile)。 + - 必须包含 volumes: [.:/app] (挂载本地代码以实现热重载/开发)。 + - (可选) 覆盖 command: 以进行调试。 +3. 文件 3：.gitlab-ci.yml (用于CI/CD) + - 规范： 必须定义 stages: [build, test]。 + - (a) build_job： + - stage: build + - script: [安装依赖] 和 [构建命令] + - artifacts: paths: [[最终产物]] (保存构建产物) + - (b) test_job： + - stage: test + - dependencies: [build_job] (依赖构建) + - script: [测试命令] + +== 最终约束 == +- 生成的配置文件必须语法正确，并遵循 [项目上下文] 中提供的命令和路径。 +``` + +**填充指南：** + + - `[项目上下文]`：**这是核心燃料**。用户必须提供构建、测试命令和最终产物的路径，AI才能生成正确的IaC脚本。 + + + +----- + +**模板名称：** `F7: 适配层/绑定代码生成` +**适用场景：** `D4 (Agent)` 模式。连接不同语言或系统。自动解析一个C++头文件，并生成“适配层”或“绑定”（Binding）代码，使其能被另一种语言（如Python）调用。 +**内嵌原则：** `[原则二：任务解构]` (D4)、`[原则五：上下文即燃料]` (头文件)、`[原则七：结构化输出]`。 + +**[Prompt 模板]** + +```txt +角色：你是一名精通 [绑定技术, 例如：pybind11] 和C++ API绑定的专家。 + +任务：请为我提供的 [目标头文件]，自动生成 [绑定技术] 的C++绑定（wrapper）代码。 + +== 执行上下文 == +1. 工作区： @workspace +2. 目标头文件 (Source of Truth)： [例如：@file:src/libProcessor.h] +3. 绑定技术 (Tech)： [例如：pybind11] +4. Python 模块名 (Module Name)： [例如：radar_processor_py] +5. 输出文件 (Output)： [例如：@file:bindings/py_bindings.cpp] + +== 执行计划 (Execution Plan) == +1. 读取 (Read)： 打开并深度解析 [目标头文件]。 +2. 分析 (Analyze)： + - (a) 识别所有 public class [ClassName]。 + - (b) 识别 [ClassName] 的所有 public 构造函数。 + - (c) 识别 [ClassName] 的所有 public 成员函数（包括重载）。 + - (d) (可选) 识别 public enum。 +3. 创建绑定文件 (Create)： 创建 [输出文件]。 +4. 生成文件内容 (Generate)： + - (a) Includes： 必须包含 [绑定技术].h (例如 pybind11/pybind11.h) 和 [目标头文件]。 + - (b) 模块定义宏： 必须生成 [宏, 例如：PYBIND11_MODULE([Python 模块名], m)] { ... }。 + - (c) 类绑定 (Class Binding)： + - 在宏内部，为 [分析] (a) 中识别的 [ClassName] 生成 py::class_... 定义。 + - (d) 构造函数绑定： 为 [分析] (b) 中识别的每个构造函数生成 .def(py::init<...>());。 + - (e) 方法绑定： 为 [分析] (c) 中识别的每个成员函数生成 .def("[python_name]", &[ClassName]::[method_name])。 + - (f) (可选) 重载处理： 必须使用 py::overload_cast 来处理C++中的函数重载。 + - (g) (可选) Enum 绑定： 为 [分析] (d) 中的 enum 生成 py::enum_ 绑定。 + +== 最终约束 == +- 必须自动解析C++头文件并绑定所有 public 接口。 +- 必须正确处理C++函数重载（这是最关键的风险点）。 +- 生成的 .cpp 文件必须是语法正确的 [绑定技术] 代码。 +``` + +**填充指南：** + + - **使用指南：** 用户调用时必须提供 `@workspace`、`@file:[目标头文件]` 以及 `[绑定技术]`。 + - `[绑定技术]`：例如 `pybind11`, `cffi` (生成C头文件), `JNI` (生成Java JNI样板代码)。AI的能力高度依赖于其对特定绑定技术的训练深度。 + +-----