https://personal-tech-blog-doz.pages.dev/tags/%E6%8A%80%E6%9C%AF%E5%86%99%E4%BD%9C/Recent content in 技术写作 on 技术实践日志Hugozh-CNMon, 17 Aug 2026 20:00:00 +0800https://personal-tech-blog-doz.pages.dev/posts/reproducible-practice-note/Sun, 16 Aug 2026 20:00:00 +0800https://personal-tech-blog-doz.pages.dev/posts/reproducible-practice-note/<p>很多技术文章描述了最终答案，却省略了答案成立的条件。读者可以照着复制代码，却无法判断自己的环境为什么得到不同结果。可复现记录需要把“做了什么”扩展成“在什么条件下做、如何知道它成功”。</p> <h2 id="从一个可验证的问题开始">从一个可验证的问题开始</h2> <p>避免从“最近学习了某工具”开始。更有价值的起点是一个能够判断成败的问题：</p> <blockquote> <p>在固定数据和配置下，怎样确认一次训练任务真正完成，而不是进程仍然存活？</p> </blockquote> <p>这个问题自然带出输入、约束、检查方法和完成标准。</p> <h2 id="记录最小环境">记录最小环境</h2> <p>环境信息不需要罗列整台电脑上的所有软件，只保留会改变结果的部分：</p> <ul> <li>操作系统和关键运行时版本；</li> <li>直接依赖及其版本；</li> <li>输入数据或配置的标识；</li> <li>必要的硬件和资源约束；</li> <li>随机种子或其他不确定性来源。</li> </ul> <p>如果某个版本没有影响结果，就不必把它放进主要叙事，可以留在附录或锁文件中。</p> <h2 id="把失败尝试写成决策证据">把失败尝试写成决策证据</h2> <p>失败记录不是流水账。每次尝试只回答四个问题：</p> <ol> <li>当时基于什么假设？</li> <li>做了哪一个最小改动？</li> <li>观察到了什么证据？</li> <li>这个证据排除了什么可能？</li> </ol> <p>这样写可以保留真正的推理路径，也能防止同一个无效方案以后被重复尝试。</p> <h2 id="明确定义完成">明确定义“完成”</h2> <p>“没有报错”通常不是完成标准。以一个自动化任务为例，可以分层验证：</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="ln">1</span><span class="cl">进程层：任务是否仍然运行 </span></span><span class="line"><span class="ln">2</span><span class="cl">日志层：是否存在未处理异常 </span></span><span class="line"><span class="ln">3</span><span class="cl">产物层：预期文件是否完整生成 </span></span><span class="line"><span class="ln">4</span><span class="cl">指标层：关键数值是否满足约束 </span></span><span class="line"><span class="ln">5</span><span class="cl">评估层：产物是否通过独立验证 </span></span></code></pre></div><p>只有最接近真实目标的那一层，才能支持最终结论。</p> <h2 id="给未来的自己留下入口">给未来的自己留下入口</h2> <p>文章结尾应包含一段最短复现路径：从哪里取得代码、执行什么命令、预期看到什么，以及常见失败时先检查哪里。它不需要代替完整文档，但应该让几个月后的自己能够快速重新进入问题。</p> <p>好的实践记录不是把过程写得更长，而是把关键判断写得更清楚。</p>