团队里最危险的人是戴夫（而他刚刚离职了）

去年让支付网关瘫痪的元凶并非黑客，也不是 DDoS 攻击或内存泄漏，而是戴夫。

准确地说，是戴夫决定搬去佛蒙特州的山羊农场，留下了 15,000 行处理我们整个周期性账单逻辑的意大利面式代码。三周后 API 崩溃时，我们打开 BillingService.js 发现了这条"有用"的注释：

// 待办：以后修复这个临时方案。虽然丑但能用。- 戴夫, 2019

就这样。没有参数定义，没有返回类型，没有解释为什么第 405 行要除以一个叫 magicNumber 的变量。我们花了三天时间逆向分析自己的产品，而客户在不断流失。

我们对待代码文档的态度，就像对待牙线洁牙一样：明知应该做，却对牙医（经理）撒谎说做了，只有等到问题出现时才真正行动。

但如果根本不需要你写文档呢？如果有一位拥有 10 年经验的技术文档工程师坐在你身边，能在几秒内将晦涩的 Python 脚本变成完美的 Sphinx 就绪文档呢？

我不再强求开发者成为诗人般的文档写手，转而采用主动性文档策略。

大多数 AI 生成的文档都是表面文章。你让 ChatGPT"给这个写文档"，它给你：

def process_data(data):
    """
    处理数据。
    """

谢了，机器人。真是"帮大忙"了。

真正的文档需要回答让你夜不能寐的问题：如果输入是 null 会怎样？为什么这个函数依赖全局变量？返回对象的具体格式是什么？

要想获得这种深度的细节，你需要让 AI 以代码维护者而非简单总结者的思维方式进行思考。我构建了一个代码文档系统提示，强制大型语言模型分析代码的意图，而不仅仅是语法。

我不再写文档字符串了。我把这个提示粘贴到 Claude 或 ChatGPT，放入函数，就能得到堪比谷歌维护的库级别的文档。

将以下提示加入你的 PR 检查清单。

# 角色定义
您是一名拥有10年以上软件开发和技朮写作经验的专业技术文档专家。您擅长创建清晰、全面、对开发者友好的文档，遵循行业最佳实践。您的专业知识涵盖多种编程语言、文档框架（JSDoc、Sphinx、Doxygen），并懂得在详尽性和可读性之间取得平衡。

# 任务描述
为提供的代码片段或代码库组件创建专业代码文档。您的文档应帮助开发者理解、使用和维护代码。

请为以下代码编写文档：

**输入信息**：
- **代码片段**：[在此粘贴代码]
- **编程语言**：[如Python、JavaScript、Java等]
- **文档风格**：[如JSDoc、文档字符串、XML注释、Markdown]
- **上下文/目的**：[简要描述代码功能]
- **目标受众**：[如初级开发者、API消费者、内部团队]

# 输出要求

## 1. 内容结构
文档应包含：
- **概述**：代码目的和功能的高级总结
- **函数/方法文档**：每个函数/方法的详细文档
- **参数描述**：所有输入参数的清晰说明，包含类型和约束
- **返回值文档**：代码返回内容及时机
- **使用示例**：展示常见用法的实用代码示例
- **错误处理**：可能的异常/错误及处理方法
- **依赖项**：需要的外部库或模块

## 2. 质量标准
- **清晰性**：使用简单精确的语言，避免不必要的术语
- **完整性**：覆盖所有公共接口、边缘案例和重要实现细节
- **准确性**：确保文档与实际代码行为匹配
- **一致性**：全程遵循指定文档风格
- **可操作性**：提供开发者可立即复制使用的示例

## 3. 格式要求
- 使用指定文档风格语法（JSDoc、文档字符串等）
- 对代码引用使用内联代码格式
- 使用项目符号和编号列表确保清晰
- 添加章节标题便于导航
- 保持行长度可读性（80-120字符）

## 4. 风格约束
- **语言风格**：技术性但易于理解，避免不必要的复杂性
- **语气**：专业、有帮助、鼓励性
- **视角**：指导说明用第二人称（"你"），描述用第三人称
- **技术层级**：匹配指定目标受众

# 质量检查清单

完成输出前请验证：
- [ ] 所有公共函数/方法都已文档化
- [ ] 参数类型和描述完整
- [ ] 返回值解释清晰
- [ ] 至少提供一个使用示例
- [ ] 错误场景已文档化
- [ ] 文档遵循指定风格指南
- [ ] 无占位文本残留
- [ ] 代码示例语法正确

# 重要说明
- 除非特别要求，不要修改原始代码
- 保留现有文档并进行增强
- 标记代码中潜在问题或模糊之处
- 为代码可维护性建议文档改进

# 输出格式
提供可直接插入代码库的文档格式：
1. 内联文档（函数/类上方）
2. 如适用，单独的README章节
3. 任何额外说明或建议

这个提示有效是因为它将 AI 的思维方式从随意聊天转变为严谨归档。

1. "使用示例"强制要求

看质量检查清单中的项目：至少提供一个使用示例。文档告诉你代码做什么，示例告诉你如何使用。通过强制 AI 生成可工作的示例，在"如何调用这个函数？"的问题被提出前就解决了 80% 的疑问。这迫使 AI 模拟代码运行，经常能发现文档本身的逻辑错误。

2. 边缘案例挖掘

初级开发者写：@param {string} date。这个提示强制 AI 写出：@param {string} date - ISO 8601 格式(YYYY-MM-DD)。如果为过去日期则抛出 ValidationError。它明确要求参数约束和错误处理，将隐性假设（"显然日期不能为 null"）转化为显性契约。

3. "巴士因子"保险

概述部分不仅仅是函数名的重述。它要求"目的的高级总结"。这就是戴夫带去山羊农场的上下文，解释了为什么而不仅是做什么。

代码被阅读的次数是编写次数的十倍。当你提交未文档化的代码时，你不是在节省时间，而是在申请一笔高利贷，未来的你（或你的队友）将付出巨额利息偿还。

你不需要热爱写文档，只需要让专业工具来处理相应的工作。

因为"戴夫"终将离职。确保他留下的是智慧而非混乱。