你有没有从教程里复制一段示例代码，粘进编辑器就立刻报错？作者说这是技术写作里的常见毛病，叫 copy-paste-completable 模式：作者用 TODO(developer) 注释标出「这里要换成你自己的值」，把组装代码的认知负担甩给读者。她认为这个习惯必须改，应该提供 copy-paste-callable（干净的函数加显式参数）或者 copy-paste-runnable（带安全默认值的独立脚本）的代码。理由在 AI 时代变得更强：代理读到含 TODO 的示例，很可能把那些被注释掉的行原样复现，或者更糟，用幻觉出来的代码把它填上，人类只好手工调试本应开箱即用的代码块。她团队维护跨生态的示例，深有体会：作者写示例的方式直接决定了开发者、测试套件和 AI 工具如何与平台交互。对比表说得很清楚——TODO 习惯首次运行会报语法或作用域错误、输入藏在注释里、CI 需要复杂预处理才能取消注释、代理产出不完整的桩；可执行契约则首次运行成功或给出清晰的鉴权错误、输入是显式参数或环境变量、标准测试框架即可测、代理产出干净可直接用的函数。
“When an AI agent digests a sample containing TODO placeholders, it may reproduce those exact commented-out lines in the generated code or, worse, fill them in with hallucinated code.” 译：当 AI 代理读到带 TODO 占位符的示例时，它可能把那些被注释掉的行原样复现出来，或者更糟，用幻觉出来的代码把它们填上。