HOWILLMAKEIT Better Notes
编写能追溯来源、版本不过时、结构简洁的知识笔记。
核心规则
先查资料，再写笔记。 不要先凭记忆生成正文，再搜索资料为既有结论补引用。
- 至少查到一份直接支持核心内容的一手资料，才开始写作。
- 涉及 API、命令、依赖或框架时，必须核对当前官方文档和版本/发布说明。
- 把资料没有支持的内容删除、改为明确推断，或标记为“尚未确认”。
- 没有网络或无法取得必要资料时，停止撰写事实性正文；说明缺少什么，并请求用户提供来源或允许稍后重试。
- 引用来源不等于复制来源。笔记应重新组织信息，只保留理解和使用所需的内容。
开始调研前读取 references/research-and-verification.md。确定结构与措辞前读取 references/note-style.md。
工作流
1. 明确笔记任务
从用户输入中提取：
- 主题与目标读者；
- 想解决的问题；
- 期望深度和输出语言；
- 指定技术栈、版本、时间范围或来源；
- 目标格式与保存位置。
已有信息不要重复询问。只有缺失项会改变资料范围或正文结构时才提问；否则采用最窄、最实用的范围。
2. 先建立问题清单
写出本篇笔记必须回答的 3～7 个问题，例如：
- 它是什么，解决什么问题？
- 使用它需要哪些前置条件？
- 输入是什么，经过什么处理，输出是什么？
- 最小可运行用法是什么？
- 当前版本有哪些限制、弃用项或迁移要求？
问题清单用于约束搜索范围，不需要默认展示给用户。
3. 检索并核对资料
按以下顺序选择来源：
- 官方文档、规范、API reference、发布说明、迁移指南；
- 原始论文、作者项目页、官方仓库与源码；
- 维护者或研究机构的技术文章；
- 能补充实践细节的高质量博客或文章。
搜索时同时包含主题、版本和 deprecated、migration、release notes 等关键词。对每个会影响使用方式的结论记录来源和适用版本。
对于 API 或命令，逐项确认：
- 当前推荐名称与导入路径；
- 参数、默认值、返回值或输出格式；
- 首次引入、弃用或移除的版本；
- 官方推荐替代项与迁移方法；
- 示例所需的运行时和依赖版本。
如果官方资料与博客冲突，以适用于目标版本的一手资料为准，并在笔记中简短说明差异。搜索摘要只能用于发现页面，不能单独作为事实依据；必须打开并阅读原文。
4. 先做事实检查，再组织正文
在草稿前把核心结论分成三类：
- 已证实：来源直接支持，可写入正文；
- 推断：由多项事实推导，必须用“因此”“可以推断”等措辞标明；
- 未确认：资料不足或相互冲突，不写成事实。
代码和命令必须与已核对版本一致。能够在当前环境运行的示例应实际运行；不能运行时明确写“未运行验证”及原因，不能写成“可运行”。
5. 用最短结构写清楚
根据主题选择必要章节，不机械套模板。通常按以下顺序：
- 标题；
- 本篇实际使用的论文、官方文档、官方仓库或博客链接；
- 一句话定义；
- 适用范围或要解决的问题；
- 前置条件；
- 输入 → 处理 → 输出；
- 核心原理或执行步骤；
- 最小示例与预期输出；
- 版本、限制和常见错误；
- 带访问日期的完整来源。
简单概念可以只保留“定义—关键点—示例—来源”。比较类内容优先用表格；流程只在存在明确顺序时使用编号列表。
6. 交付前复核
逐项检查：
- 每个时效性事实是否有当前来源；
- 是否仍出现已弃用 API，却没有显式说明其状态和替代方案；
- 输入、输出、前置条件和失败情况是否具体；
- 示例与正文中的名称、参数和版本是否一致；
- 是否把推断、经验或未验证内容写成事实；
- 是否存在比喻、宣传词、重复总结或不影响理解的背景；
- 来源是否包含标题、链接、访问日期，版本敏感时是否包含版本。
任一核心项不满足时先修正，不要宣布完成。
输出要求
默认使用 Markdown，并遵守：
- 开头直接定义主题，不写泛泛背景和铺垫。
- 使用短段落、明确标题和具体动词。
- 不使用比喻或拟人化表达；直接说明数据、状态和操作。
- 第一次出现术语时给出定义，后文保持同一名称。
- 涉及函数、命令、协议或训练过程时，明确写出输入、关键处理和输出。
- 示例只展示当前结论所需的最小内容，并给出预期输出或可观察结果。
- 数字、性能结论和论文实验结果同时写清条件、指标和对照对象。
- 公式使用 LaTeX，并紧接着定义符号、单位和适用条件；图片不能替代正文中的公式或核心解释。
- API、协议和数据格式优先展示真实的最小输入/输出，不只做抽象描述。
- 在相关段落就近放引用；文末再列去重后的“来源”。
- 文末注明“资料核对日期：YYYY-MM-DD”。
推荐的来源格式：
## 来源
- [文档或论文标题](URL) — 发布者，适用版本（如有），访问于 YYYY-MM-DD
禁止事项
- 不得只凭模型记忆编写事实性技术笔记。
- 不得用搜索结果摘要、转载聚合页或无来源的 AI 生成文章支撑核心结论。
- 不得为了显得完整而补写资料中不存在的参数、默认值、因果解释或历史。
- 不得把旧教程中的 API 当成当前推荐用法。
- 不得隐藏版本冲突、弃用警告、运行失败或资料缺口。
- 不得堆砌链接；每个来源都应实际支撑正文中的具体内容。
- 不得使用“像……一样”“可以把它想象成……”等比喻替代定义。
- 不得重复同一结论，或在结尾机械复述全文。
完成标准
只有同时满足以下条件才算完成：
- 写作前已阅读支持核心结论的一手资料；
- 时效性内容已核对目标版本、弃用状态和替代方案；
- 核心事实可追溯到正文引用或文末来源；
- 输入、处理、输出、前置条件和限制按主题需要被明确说明；
- 示例的验证状态真实可辨；
- 正文简洁直接、没有比喻和无依据补全。