24 KiB
D. 类别四：文档编写与知识管理 (Documentation & Knowledge)
模板索引 (Index)
| 模板ID | 核心用途 | 使用场景 / 关键词 |
|---|---|---|
| D-1: 代码内文档 | ||
D1 |
API/函数头注释生成 | Doxygen, 头注释, 参数/返回描述 |
D2 |
内部逻辑注释注入 | Why注释, 算法步骤, 可维护性 |
D3 |
遗留注释重构 | 注释同步, 现代化, 过时修复 |
| D-2: 系统与项目文档 | ||
D4 |
技术设计文档骨架 | TDD骨架, 模块启动, Markdown结构 |
D5 |
API参考手册生成 | gRPC/REST/C++头, 外部开发者文档 |
D6 |
README/项目文档编写 | 构建说明, 快速上手, 特性列表 |
| D-3: 知识消费与合成 | ||
D7 |
技术知识摘要 | 论文/博客, 工程可行性, 摘要结构 |
D8 |
跨语言技术翻译 | 专业术语映射, 精确翻译 |
D9 |
手动RAG问答 | 内部知识库, 上下文限定回答 |
| D-4: 知识流转与过程沉淀 | ||
D10 |
Git提交信息生成 | Conventional Commits, diff->message |
D11 |
讨论/纪要结构化总结 | Key decisions, Action items |
D12 |
架构决策记录 (ADR) | 决策背景, 后果, Rationale |
D13 |
需求到技术任务分解 | User Story->任务列表, Epic/Subtask |
子类别 D-1: 代码内文档 (In-Code Documentation)
模板名称： D1: API/函数头注释生成
适用场景： 2.4.4 的核心模板。输入一个C++函数/类/方法的签名，指令AI按照指定的规范（如 Doxygen）生成完整的函数头注释。
内嵌原则： [原则七：结构化输出] (强制Doxygen格式), [原则五：上下文即燃料] (函数签名是关键)。
[Prompt 模板]
角色：你是一名精通C++和 [规范, 例如：Doxygen] 注释规范的软件工程师。
任务：请为以下C++ [目标, 例如：函数/类/方法] 自动生成专业、完整的头注释。
== 待注释的代码签名 ==
[粘贴你的函数/类/方法的签名或声明，例如：
void process_data(const std::vector<float>& 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 模板]
角色：你是一名精通 [领域, 例如：C++ / 信号处理算法] 的资深工程师，擅长编写清晰、可维护的代码。
任务：请为以下没有内联注释的复杂函数体，注入简洁、专业的//内联注释。
== 黄金法则 (必须遵守) ==
- 注释必须解释“Why”（目的、意图、算法步骤），而不是“How”（代码行为）。
- (例如：// How (错误): i加1。 // Why (正确): 推进到下一个数据样本)
== 待注入注释的代码 ==
[粘贴你的完整函数体代码，特别是包含位运算、复杂算法、或晦涩业务逻辑的部分]
== 注入要求 ==
1. 在所有复杂的逻辑块、算法关键步骤、晦涩的位运算、或“魔法数字”上方添加注释。
2. 严格遵守上述“黄金法则”。
3. 保持注释简洁、专业，与代码对齐。
== 输出要求 ==
- 返回注入了//内联注释的完整函数代码块。
填充指南：
[领域]：明确AI的专业背景，以便它能理解算法的“Why”。[待注入注释的代码]：必须提供完整的函数实现体。- 使用指南： 此模板旨在提升代码的可读性，AI生成的注释仍需人工审查其“Why”是否解释到位。
模板名称： D3: 遗留注释重构与现代化
适用场景： 维护遗留代码库（痛点3）。当代码已经迭代，但注释（头注释或内联注释）已过时、写得不好或与代码逻辑不符时，用于同步和重写注释。
内嵌原则： [原则五：上下文即燃料] (输入代码和旧注释), [原则七：结构化输出] (输出新代码和注释)。
[Prompt 模板]
角色：你是一名严谨的C++技术文档作者和代码审查专家。
任务：请重写以下代码片段中的注释，使其清晰、专业、现代化，并确保它100%反映当前代码的实际逻辑。
== 待重构的代码与注释 ==
[粘贴包含过时、错误、或写得不好的注释的代码片段]
== 审查与重构要求 ==
1. 审查：分析原始注释存在的问题（例如：已过时、描述与代码不符、含糊不清、拼写错误）。
2. 重构（注释）：重写注释（无论是Doxygen还是内联`//`），使其专业、准确，并解释“Why”。
3. 同步：确保新注释100%匹配代码的当前行为。
== 输出要求 ==
1. [分析]：(可选) 简要说明原注释的核心问题。
2. [重构后的代码]：返回带有“新注释”的完整代码块。
填充指南：
[待重构的代码与注释]：必须提供代码和它附带的错误注释，AI需要这两者来进行对比。- 使用指南： 这是确保“文档（注释）即代码”一致性的重要工具。
子类别 D-2: 系统与项目文档（Authoring New Docs)
模板名称： D4: 技术设计文档（TDD）骨架生成
适用场景： 启动新项目或新模块的必备环节（痛点1）。用于快速生成一份符合团队规范的技术设计文档（TDD）的Markdown骨架，避免工程师从零开始。
内嵌原则： [原则七：结构化输出] (输出Markdown骨架), [原则五：上下文即燃料] (输入模块名和模板)。
[Prompt 模板]
角色：你是一名资深的系统架构师，精通编写高质量的技术设计文档（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 模板]
角色：你是一名专业的技术文档作者（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 模板]
角色：你是一名精通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 模板]
角色：你是一名 [相关领域，例如：雷达信号处理] 专家和资深工程负责人。
任务：请阅读以下技术文档/论文原文，并为我（工程负责人）提炼一份高度结构化的“工程价值摘要”。
== 原文上下文 ==
[粘贴你需要摘要的完整外文或中文技术文档/论文原文]
== 摘要要求 (必须严格遵守此结构) ==
请用简洁、专业的中文（非直译）回答以下三个核心工程问题：
1. [核心问题]： 这篇文档试图解决什么具体工程问题？
- (例如：提高分辨率、抗干扰、降低计算量？)
2. [核心技术]： 它提出的主要技术或方法是什么？
- (用一句话概括，例如：它用XX代替了XX)
3. [工程约束与代价]： 如果我们要工程实现这个方法，它可能引入的最大挑战或约束是什么？
- (例如：对硬件同步要求高？计算量极大？依赖特定库？)
填充指南：
[相关领域]：明确AI的专家身份，有助于它理解专业术语。[原文上下文]：必须提供。粘贴你需要AI“消化”的全部文本内容。- 使用指南： 此模板的目标不是学术翻译，而是“工程决策辅助”，强制AI从“我能否以及是否应该实现它”的角度思考。
模板名称： D8: 跨语言技术翻译
适用场景： 消除语言障碍。当需要阅读非英语（如日语、俄语、德语）的技术文档、博客或错误信息时，用于获取技术上精确的中文翻译。
内嵌原则： [原则五：上下文即燃料] (输入外文), [原则七：结构化输出] (输出中文)。
[Prompt 模板]
角色：你是一名精通 [源语言，例如：日语] 和简体中文的专业技术翻译（本地化专家）。
任务：请将以下 [源语言] 技术文档，逐字逐句地、专业地翻译为简体中文。
== 黄金法则 (必须遵守) ==
1. 精确性： 必须保持技术术语的绝对精确。
2. 专业术语映射： 必须将 [源语言] 中的专业术语正确翻译为中文行业标准术语。
- (例如：[日语的 スレッドセーフ] 必须翻译为 [中文的 线程安全])
- (例如：[德语的 Schnittstelle] 必须翻译为 [中文的 接口])
3. 流畅性： 翻译结果必须是通顺、专业的简体中文，而非生硬的机器直译。
== 待翻译的 [源语言] 原文 ==
[粘贴完整的外文技术文档内容]
== 输出要求 ==
- 仅返回翻译后的简体中文内容。
填充指南：
[源语言]：明确告知AI原文的语言。[专业术语映射]：强烈推荐。如果你已知几个关键术语的正确译法，在此处提供示例（原则六），AI会翻译得更准确。[待翻译的原文]：粘贴原文。
模板名称： D9: 手动RAG：内部知识库问答
适用场景： 解决AI的“知识截断”和“内部知识盲区”（痛点5）。通过手动“喂入”团队的私有文档（如API说明、内部规范），让AI能基于这些“私有知识”回答问题。
内嵌原则： [原则五：上下文即燃料] (核心，注入私有知识), [原则七：结构化输出] (回答问题)。
[Prompt 模板]
角色：你是一个智能助手。
任务：请严格且仅基于我提供的以下“内部知识库上下文”，回答我的问题。
== 内部知识库上下文 ==
[粘贴你的内部文档、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 模板]
角色：你是一名精通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: [生成的 <type>(<scope>): <subject>]
Body: [生成的 Body (可选，解释Why)]
Footer: [生成的 Footer (可选，如 BREAKING CHANGE)]
填充指南：
[规范]：明确你团队遵循的Commit规范。[git diff ... 输出]：必须提供。AI通过阅读diff来理解“这次提交做了什么”，这是生成Commit信息的核心依据。
模板名称： D11: 讨论/纪要 结构化总结
适用场景： 沉淀“过程知识”（痛点3）。用于将来自Slack、Teams、微信群聊或会议语音转写的非结构化、混乱的讨论记录，快速整理为结构化的“会议纪要”。
[Prompt 模板]
角色：你是一名高效的项目经理（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 模板]
角色：你是一名资深的系统架构师，是“架构决策记录”（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 模板]
角色：你是一名资深的技术主管（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），任务分解越准确。[任务列表要求]：你可以根据团队的项目管理习惯（如是否需要估算、依赖关系）来调整此部分的输出要求。