https://yanqian.github.io/zh/topics/developer-tools/Recent content in Developer-Tools on Armstrong YanHugozh-CNTue, 21 Jul 2026 09:21:48 +0800https://yanqian.github.io/zh/posts/publish/i-built-a-small-harness-to-stop-ai-coding-projects-from-forgetting-state/Tue, 21 Jul 2026 09:21:48 +0800https://yanqian.github.io/zh/posts/publish/i-built-a-small-harness-to-stop-ai-coding-projects-from-forgetting-state/<p>AI 编程智能体很强大。</p> <p>但项目一旦拉长，往往会在一些非常具体的地方出问题：</p> <ul> <li>会话突然中断</li> <li>上下文越积越长</li> <li>每周额度耗尽</li> <li>第二天接手的智能体忘了前一天做过哪些决定</li> <li>智能体改动了无关文件</li> <li>工作明明还没完成，智能体却提前宣布结束</li> </ul> <p>问题不在于 AI 不会写代码。</p> <p>真正的问题是，AI 编程项目往往没有持久的项目状态。</p> <p>所以，我做了一个小型开源模板：</p> <p><a href="https://github.com/yanqian/ai-agent-harness-template" class="external-link" target="_blank" rel="noopener">ai-agent-harness-template</a></p> <p>它的目标很简单：</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">让 AI 编程项目随时都能恢复并继续推进。 </span></span></code></pre></div><h2 id="这不是提示词合集"> 这不是提示词合集 <a class="heading-link" href="#%e8%bf%99%e4%b8%8d%e6%98%af%e6%8f%90%e7%a4%ba%e8%af%8d%e5%90%88%e9%9b%86"> <i class="fa-solid fa-link" aria-hidden="true" title="链接到标题"></i> <span class="sr-only">链接到标题</span> </a> </h2> <p>现在已经有很多实用的提示词合集。</p> <p>但这个模板不是。</p> <p>它是一套仓库级 Harness，专门用于需要长期推进的 AI 编程项目。</p> <p>适用工具包括：</p> <ul> <li>Codex</li> <li>Claude Code</li> <li>Cursor Agent</li> <li>其他类似的编程智能体</li> </ul> <p>不过，它不依赖任何一家厂商。</p> <p>控制边界就是仓库本身。</p> <h2 id="核心思路"> 核心思路 <a class="heading-link" href="#%e6%a0%b8%e5%bf%83%e6%80%9d%e8%b7%af"> <i class="fa-solid fa-link" aria-hidden="true" title="链接到标题"></i> <span class="sr-only">链接到标题</span> </a> </h2> <p>应该把智能体当作无状态工作进程来用。</p> <p>它们不该依赖聊天记录。</p> <p>每次开始工作时，都应该根据仓库文件重新建立上下文。</p> <p>这个模板把持久状态保存在以下文件中：</p> <ul> <li><code>SPEC.md</code>：保存需求</li> <li><code>feature_list.json</code>：保存可执行的功能状态</li> <li><code>progress.md</code>：保存恢复工作所需的记录</li> <li><code>AGENTS.md</code>：保存智能体规则</li> <li><code>QUALITY.md</code>：保存评估标准</li> <li><code>runs/</code>：保存证据和交接记录</li> </ul> <p>这样一来，后来接手的智能体、人工维护者和 CI 都以同一份信息为准。</p> <p>仓库现在还提供了一个可安装的 AI Agent Harness skill。</p> <p>这个 skill 不是另一套数据库。</p> <p>它只是同一套仓库状态协议的便捷入口。</p> <p>真正持久的记忆依然留在仓库里。</p> <h2 id="为什么聊天记录不适合充当数据库"> 为什么聊天记录不适合充当数据库 <a class="heading-link" href="#%e4%b8%ba%e4%bb%80%e4%b9%88%e8%81%8a%e5%a4%a9%e8%ae%b0%e5%bd%95%e4%b8%8d%e9%80%82%e5%90%88%e5%85%85%e5%bd%93%e6%95%b0%e6%8d%ae%e5%ba%93"> <i class="fa-solid fa-link" aria-hidden="true" title="链接到标题"></i> <span class="sr-only">链接到标题</span> </a> </h2> <p>聊天记录可以提供有用的上下文。</p>