code-sample-documentation

代码示例文档

使用此技能创建和审查有用、准确、可复制且易于维护的代码示例。适用范围包括可执行示例、说明性代码片段、API 请求/响应对、CLI 命令、配置文件和生成的参考资料。

此技能源自 Docs for Developers: An Engineer's Field Guide to Technical Writing，尤其是第 5 章“Integrating code samples”。其中的指导经过改写和转述；请勿将书中的原文复制到用户输出中。来源：https://link.springer.com/book/10.1007/978-1-4842-7217-6

快速入门

1. 加载 guidelines.md，选择最精简且实用的参考资料集。
2. 将示例归类为可执行、说明性或成对的请求/响应。
3. 检查示例是否有说明、简洁、清晰、可用且可信。
4. 使用 workflows/review-code-sample.md 完整审查示例。
5. 尽可能运行或测试示例；否则标明尚未验证的内容。

默认输出

审查或设计代码示例时，返回：

1. 示例目的——读者应了解或完成的内容。
2. 示例类型——可执行、说明性、请求/响应、CLI、配置或生成的示例。
3. 问题或设计备注——按对读者的风险排序。
4. 修订后的示例——如有要求，提供简洁且可复制的版本。
5. 测试计划——如何验证运行时行为、输出和版本假设。
6. 维护备注——事实来源、负责人，以及生成内容与手动编写内容的界限。

目录

需求	从这里开始
了解示例类型	references/core/knowledge.md
应用示例规则	references/core/knowledge.md
查看修改前后的示例	references/core/knowledge.md
审查或设计示例	workflows/review-code-sample.md
按任务选择资料	guidelines.md

核心原则

• 示例既是文档，也是软件；请同时对待这两者。
• 根据读者所处的阶段调整示例的复杂度。
• 明确说明占位符、输入、输出和限制。
• 除非示例已针对相应用途经过审查和测试，否则不要暗示它已可用于生产环境。