让项目更容易被 AI 正确修改

如果 Agent 每次进入仓库都找不到启动方式，或者每次都只能说“代码看起来没问题”，继续加提示词的收益有限。项目缺少可发现的入口或可执行的反馈。

这里把围绕模型的工具、状态管理、权限与执行循环称为 Harness；仓库的命令、规则和测试是它工作时依赖的一部分。你不需要先开发一个 Agent 平台，才可以改善这些条件。

从失败反推该补什么

表中每一项都对应一个可观察的失败，不是为了追求“Agent 友好”而重写整个仓库。

第一，src/lib/knowledge-map.ts 是阅读顺序的单一来源。侧栏和上下篇读取它，而不是各自维护列表。

第二，src/lib/content-registry.ts 检查内容关系、工具地址、实践模板和路径覆盖。校验在构建路径里执行，能阻止一部分结构错误进入可发布产物。

第三，package.json 提供组合命令：

{
  "verify": "npm run lint && npm run test && npm run build"
}

这段是本站当前脚本的摘录。它的价值是别人能复现同一组检查，而不是必须由 Agent 自己猜运行什么。

“来源字段不为空”不能证明来源支持正文；“工具 URL 是 HTTPS”不能证明工具可靠；“全部 MDX 都在索引里”不能证明阅读顺序合理。

因此，结构校验交给程序，事实、解释质量和视觉结果仍需对应的审阅与观察。不要把内容质量问题伪装成一个字符串长度阈值，也不要让另一个模型一句“合格”取代来源核对。

假设曾经漏掉新增文章的索引。检查应表达：

输入：全部公开 MDX，以及阅读路径中的引用。
成功：每篇公开文章恰好出现一次，类型与路径角色匹配。
失败：缺失、重复或不存在的引用。
错误信息：给出具体 slug 和错误类别。

如果测试只断言“文章数量是 19”，新增一篇后把 19 改成 20，并没有证明所有路径都正确。总数可以作为当前版本的额外约束，不能代替集合与唯一性检查。

把“命令失败”改成“哪个命令、退出码、相关错误、完整日志位置”，模型才有机会判断下一步。

同样，一个读取接口若不区分“查不到”和“无权读取”，就可能诱导 Agent 为不存在的问题反复重试。工具输出要让失败能够分类，特别是环境失败与任务失败不能混在一起。

Anthropic 的 Agent 评估说明区分了执行轨迹和最终环境状态。工具说“写入请求已发送”不等于状态已经改变，验证时仍需查看结果。

先记录同一类任务中，人工通常在哪一步补救：

经常补启动命令 → 整理运行入口
经常提醒范围 → 缩短并明确项目规则
经常发现同一 Bug → 添加有效回归检查
经常重复完整流程 → 提取 Skill

上线一项改进后再看同类任务的失败是否减少、反馈是否更快。生成行数、工具调用次数和 Agent 数量都不是可靠交付的替代指标。

如果现有命令和人工检查已经足够，不增加平台、向量库或多 Agent 编排，也是合理的工程结果。