反模式
记录软件工作中真实发生过的判断纠正，校准共享原则里程度与场景判断的尺度。条目是算账样本，不是答案库：它示范“条件 → 权衡 → 结论”的算法，不是该场景的标准答案。格式与收录规则由 document-writing 的文档写作原则「常见反模式」一节维护，不在本文件重复。
使用规则
- 引用前先核对当前条件与条目条件的差异。条件不同导致结论不同，不是违背条目——同样的账、不同的条件、不同的结论，正是条目起作用的证明。
- 当前场景与某条目相似、按同样的账算出了不同做法且说不清差异在哪时，停下来问用户。这正是“识别后交人决策”的触发点。
条目
| 场景与条件 | 被否的做法 | 采纳的做法 | 决策依据 |
|---|---|---|---|
| 为 Obsidian 批注插件设计“外部文件批注回写源目录”功能；单人使用，回写偶发，冲突预期低频，改错可撤销。 | 差异查看器＋三路版本比较＋逐文件自动处理行为表。 | 文件级内容哈希检测＋冲突列表＋人工勾选是否覆盖，不做自动合并；已实现，75 项测试与主要路径实测通过。 | 冲突低频，自动处理的固定成本（合并逻辑、差异界面、测试面）摊不回来，低频下人工确认更便宜也更可靠。→ 克制增加整体负担 |
| 让库外 Markdown 或文件夹进入当前 Obsidian 库复用已有批注工具；查看外部内容是高频日常动作。 | 为每个外部文件夹建独立库并重新配置插件，以官方不推荐目录联接为由当“更稳妥”推荐。 | 外部目录挂载进当前库（目录联接，后演进为复制副本＋同步回写），不新建库、不改插件配置。 | 固定成本（建库、配插件、切库）× 高频使用，总成本不可接受；技术稳妥性必须与使用频率一起算总成本。→ 克制增加整体负担 |
| 简化语音应用的映射管理，隐藏内部细节。手动与自动映射都会改变转写结果，用户需要逐条纠错。 | 将自动映射当成内部细节隐藏，只留条数和清空入口。 | 两种来源统一展示，均可编辑、删除；隐藏来源与学习次数。 | 自动生成省去的是添加操作，不能省去用户的纠错能力。 |
| 调整个人语音应用的热词与映射管理。对象职责明确，本地数据与调用方可同步调整。 | 为“零迁移”只改菜单，保留混合格式及按映射来源分开的读写分支。 | 热词与映射各自建模，手动与自动映射统一存取；迁移数据并退役旧结构。 | 一次迁移消除持续读写、排障和测试分支，收益远大于成本。→ 克制增加整体负担 |
| 为语音输入应用实现热词回显清洗；同类逻辑在成熟开源项目有真实用户打磨的实现，平台不同无法直接依赖。 | 自行从零设计判定与边界，写出下标换算错误，缺少任意位置匹配、fallback 参与判定、单热词三个真实场景判定。 | 1:1 移植其判定结构与测试，行为由移植的测试锁定。 | 成熟实现编码了未踩过的坑，自研想不全；移植一次成形，自研加踩坑回滚总成本更高。→ 复用与移植成熟实现 |
| 简化个人语音应用的失败处理；入口用于即时口述，说完即填入或发送。没有离线批量录入场景；需要仔细组织的高价值内容在外部编辑好后复制粘贴，不通过此入口创作。 | 为避免丢失一次录音引入本地草稿，再增加编辑、恢复、清理、目标迁移及阻止录音和修改连接的规则；评审时用并不存在的离线批量录入、高价值长内容场景，为保留草稿或“异常记录”寻找理由。 | 已删除本地草稿及异常记录的持久保存，当前操作失败直接反馈，发送结果不明时提示核对会话且不自动重发。121 项单测、Debug 构建、lint 和本地 DOM 回归通过，未做真机录音验证。 | 先确认场景真实存在且属于当前入口，再评估机制收益；不能用想象中的场景扩大产品边界。本入口失败后可重新录入，持久恢复增加的编辑、状态与维护成本缺少对应需求；改名为“异常记录”也没有消除这些成本。→ 克制增加整体负担 |