【小白指南针】AI Coding自动化编程从0～1的蜕变二：让 Coding Agent 从"偶尔好用"变成"稳定可靠"

本章是新手容易遇到的坑，不解决很容易就会跟AI“吵起来”！你的 agent 的好坏，70% 取决于你给它的环境，30% 取决于模型本身。把环境搭好，而不是不断换模型期待奇迹发生。

文章目录

前言

在上一篇中讲了如何在自己电脑上搭建Agent的工作环境

本期将下我们及我团队的小伙伴遇到的坑，近期Claude code 后门事件，导致我们不得不被集团要求弃用Claude code，因为是国企所以我想让我团队成员能一步到位用国产或开源方案的Coding Agent。在多方对比及其他方面考量下选择了小米的MIMO code。

所以我正好借着这个机会帮我团队的小伙伴解决下这些问题。

1:AI说做完了，但是根本不能用或者理解错误

2:让它改一个功能，它顺手把我其他不合理但我不需要动的功能改了，还可能导致原本好的功能有问题了（众所周知，代码能跑就不要动）

3:第二天开机后，他不知道昨天干了啥，好多问题重新说才行，严重浪费时间

。。。。。。

提示：以下是本篇文章正文内容，下面案例可供参考

适用对象：所有使用 AI Coding Agent 的研发团队成员
前置要求：至少使用过任意一款 AI Coding Agent（MiMoCode、Claude Code、Cursor 等）
操作系统：Mac OS 15.7.8 、M4Pro芯片、128G
Agent工具：MIMO code
模型：GLM5.2、DeepSeek V4 flash/pro、Kimi K3

1. 为什么需要优化 Agent

1.1 一个实验

Anthropic 做过一个对照实验。同一个 prompt——“做一个 2D 复古游戏编辑器”——同一个模型 Opus 4.5，跑了两次：

裸跑带 Harness
耗时20 分钟6 小时
花费$9$200
结果核心功能跑不起来游戏可以正常游玩

模型没变，变的是马具（Harness）。

1.2 Agent 常见的失败模式

失败模式实际表现根因
新会话摸黑新会话花大量时间重新摸索状态和启动方式缺少状态持久化
范围蔓延一次启动多个功能，最后没有一个完整收尾缺少范围约束
提前宣布完成代码改了就说"完成了"，但没有可运行证据缺少验证门禁
启动脆弱每轮会话都要重新学怎么启动项目缺少标准启动路径
交接薄弱下一轮看不出哪里可用、哪里坏了、接下来做什么缺少交接机制
评审主观质量判断依赖个人记忆和感觉缺少量化评分

1.3 一百万行代码的实验

2025 年，OpenAI 的三个工程师做了一个实验：他们不写代码，只让 Codex 写。 从一个空的 git 仓库起步，五个月下来，仓库里有了约 100 万行代码。三个工程师一共开了 1,500 个 PR，平均每人每天 3.5 个。

他们的核心发现：每当某件事做砸了，问题几乎从来不是"不够努力"，而是 agent 还缺什么——缺的能力能不能用一种既可理解又可执行的方式补上去。

1.4 核心结论

模型能力和执行可靠性是两回事。 遇到失败，先看 harness，再看模型。换模型是成本最高的选择，很多情况下根本不是模型的问题。

2. Harness Engineering 核心概念

2.1 什么是 Harness

Harness = 模型权重之外的一切工程基础设施。

包括：指令文件、可用工具、运行环境、状态管理、验证反馈。不是模型权重的部分，全是 harness。

项目规则
AGENTS.md

AI Agent

进度与状态
progress.md / git

工具
shell / 文件 / 测试

运行环境
依赖 / 服务 / 版本

检查结果
test / lint / build

2.2 Harness 五子系统

子系统职责典型实现
指令告诉 agent 项目规则和约束AGENTS.md、instructions.md
工具确保 agent 有足够的操作能力shell 访问、文件读写、CLI
环境让环境可重现、自描述package.json、pyproject.toml、Docker
状态跨会话保持工作连续性progress.md、feature_list.json、git
反馈验证工作是否正确测试命令、lint、类型检查

五个子系统缺一个，harness 就不完整。

2.3 AGENTS.md 是路由器，不是百科全书

核心原则：AGENTS.md 控制在 50-200 行，只做三件事：

  1. 项目概览和快速开始
  2. 不可违反的硬约束（不超过 15 条）
  3. 指向专题文档的路由表
# AGENTS.md  —  路由器，不是百科全书

## 文件路由（什么是路由表）

| 文件 | 用途 | 何时读取 |
|------|------|---------|
| `AGENTS.md` | 工作规则与路由 | 每轮开工时 |
| `init.sh` | 启动与验证入口 | 每轮开工时运行 |
| `templates/feature_list.json` | 功能状态 | 选择功能时 |
| `templates/mimo-progress.md` | 进度记录 | 开工、收尾时 |
| `templates/session-handoff.md` | 会话交接 | 结束时选写 |
| `templates/evaluator-rubric.md` | 评审评分 | 功能完成时 |

为什么要这样做？ 一个 600 行的指令文件，关键约束埋在中间会被忽略（"Lost in the Middle"效应）。拆分后信噪比提升，agent 把更多上下文花在实际任务上。
在这里插入图片描述

2.4 初始化必须独立

初始化阶段的目标和功能实现完全不同：

初始化阶段实现阶段
目标搭好基础设施交付功能
产出启动脚本、进度文件、任务分解业务代码
验收标准能启动、能测试、能看进度、能接手测试通过

混在一起的代价：

  • Agent 倾向于写代码（直接可见），牺牲基础设施
  • 在测试框架配好之前写的功能，可能设计上就有问题
  • 上下文预算被初始化任务吃掉，功能部分反而做不好

正确做法：第一个会话只做初始化，不写业务代码。初始化投入的时间会在后续 3-4 个会话中完全收回。

2.5 仓库是唯一事实来源

Agent 看不到的东西，对它来说就不存在。所有必要的上下文都必须在仓库里：

  • 项目规则 → AGENTS.md
  • 功能状态 → feature_list.json
  • 进度记录 → mimo-progress.md
  • 启动脚本 → init.sh
  • 架构决策 → 架构文档

不要依赖聊天记录或人的记忆。 如果一个新 agent 会话只靠仓库内容无法回答"这个项目做什么、怎么启动、怎么验证、还有什么没做完、下一步做什么"，那 harness 就是不完整的。

2.6 初始化验收清单

条件说明
✅ 能启动init.sh 从零运行成功
✅ 能测试基础测试通过
✅ 能看进度mimo-progress.md 存在且最新
✅ 能接手下一步feature_list.json 列出下一个最优先功能

3. 我们的实施方案

3.1 架构总览

项目层 (项目根)

全局层 (~/.config/mimocode/)

自动注入

生成

生成

生成

生成

开工时读取

路由到

instructions.md
永久注入系统提示

commands/init.md
内置模板 + 完整流程

initializer-agent-playbook.md
初始化操作手册

AGENTS.md
路由器，指向各文件

init.sh
动态生成的启动脚本

templates/
功能状态、进度、交接、检查、评审、质量

.gitignore
忽略.mimocode/和会话文件

3.2 全局层（一次配置，所有项目生效）

文件位置作用
instructions.md~/.config/mimocode/每轮会话自动注入 3 条规则：检查 AGENTS.md、运行 init.sh、固定开工流程
commands/init.md~/.config/mimocode/覆盖内置 /init 命令，内嵌全套模板；/init --advanced 生成高级治理结构
initializer-agent-playbook.md~/.config/mimocode/初始化操作手册，列出必需产出和成功标准

3.3 项目层（每次 /init 生成）

文件生成方式是否提交 git
AGENTS.md内嵌模板✅ 提交
init.sh动态生成（检测 package.json / pyproject.toml / Cargo.toml / go.mod 等）✅ 提交
templates/feature_list.json内嵌模板✅ 提交
templates/session-handoff.md内嵌模板✅ 提交
templates/clean-state-checklist.md内嵌模板✅ 提交
templates/evaluator-rubric.md内嵌模板✅ 提交
templates/quality-document.md内嵌模板✅ 提交
templates/codebase-analysis.md代码库扫描（原始 init 逻辑）❌ gitignore
templates/mimo-progress.md内嵌模板❌ gitignore

项目实际执行截图：在这里插入图片描述

3.4 完整的开工流程

每轮新会话开始：

  ┌─────────────────────────────────────┐
  │ 1. pwd 确认在正确的项目根              │
  │ 2. 读取 AGENTS.md → 获取文件路由       │
  │ 3. 读取 templates/mimo-progress.md   │
  │ 4. 读取 templates/feature_list.json  │
  │ 5. git log --oneline -5             │
  │ 6. 运行 ./init.sh                    │
  │ 7. 跑基础验证                         │
  │                                     │
  │ 如果基础验证失败，先修基础状态。         │
  │ 只选一个未完成功能，围绕它工作到完成。    │
  └─────────────────────────────────────┘
          │
          ▼
  ┌─────────────────────────────────────┐
  │ 结束前：                              │
  │ 1. 更新 mimo-progress.md             │
  │ 2. 更新 feature_list.json            │
  │ 3. 记录 blocker                      │
  │ 4. 提交代码                           │
  │ 5. 确保下一轮可直接运行 ./init.sh       │
  └─────────────────────────────────────┘

3.5 为什么这个顺序不能乱

步骤为什么必须先做
pwd防止在错误目录里干活
读进度 + 功能清单先恢复持久状态，避免在错误假设上开工
git log了解刚刚发生了什么
运行 init.sh让启动过程标准化，不靠记忆
基础验证先跑避免在坏状态上继续叠改动

3.6 高级初始化：/init --advanced

当项目进入多模块/多阶段/多角色协作阶段，运行 /init --advanced 额外生成：

ARCHITECTURE.md
docs/
├── design-docs/index.md
├── design-docs/core-beliefs.md
├── exec-plans/active/
├── exec-plans/completed/
├── exec-plans/tech-debt-tracker.md
├── product-specs/index.md
├── references/*.txt  (llms.txt 格式)
├── QUALITY_SCORE.md
├── RELIABILITY.md
├── SECURITY.md
└── FRONTEND.md
sops/ (标准操作流程)

所有模板内嵌在命令中，无需额外查阅资料。

4. 团队接入指南

4.1 如果你是 MiMoCode 用户

已经自动生效。全局配置已在所有环境中部署：

  1. 在任何项目下输入 /init → 自动走定制逻辑
  2. 新会话开始 → 全局 instructions.md 自动注入 AGENTS.md 检查规则
  3. 项目级 .mimocode/mimocode.json 配置 instructions: ["../AGENTS.md"] → AGENTS.md 内容注入系统提示

4.2 如果你使用其他 Coding Agent

虽然 /init 命令是 MiMoCode 特有的，但生成的 文件是纯文本，所有人都能读。

Claude Code 用户：

  • 查看项目根 AGENTS.md → 内容与 CLAUDE.md 结构一致，可直接参考
  • 运行 init.sh → 标准 bash 脚本，所有 shell 环境通用
  • 读取 templates/ 下的文件 → 纯 markdown / JSON

Cursor 用户：

  • 同样可读 AGENTS.md 和 templates/ 下的文件
  • 可以将 AGENTS.md 内容复制到 .cursorrules 中

Codex CLI 用户：

  • 文件结构完全兼容
  • Codex 原生支持 AGENTS.md

4.3 与其他工具集成

工具与模板体系的兼容方式
CI/CDinit.sh 中的验证命令可直接用于 CI 流水线
项目管理feature_list.json 可与 Jira / Linear / Notion 同步
代码评审evaluator-rubric.md 可作为 PR 模板的评审标准
文档AGENTS.md 可作为团队 Wiki 的入口文档

5. 国产 Coding Agent 对比

5.1 概览

特性MiMoCodeTrae (字节)Claude CodeCursorCodex CLI
开发商小米字节跳动AnthropicAnysphereOpenAI
基座模型DeepSeek / 自研自研 / GPTClaude多模型GPT / o 系列
运行方式TUI + CLIIDE 插件CLI + TUIIDE (VS Code 分支)CLI
Harness 支持⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
自定义指令AGENTS.md / instructions.md有限规则CLAUDE.md.cursorrulesAGENTS.md
持久化记忆原生（checkpoint + memory）无会话级有限有限
子智能体原生支持（explore/general）有限有有限有
自定义命令✓（markdown 文件热加载）✗✓✗✗
Hook/插件✓（hook + TUI 插件）✗✗✓（扩展）✗
工作流编排✓（workflow.js）✗✗✗✓（工程模式）
定时任务✓（cron/loop）✗✗✗✗
跨会话连续⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
开源❌（基于 OpenCode 的闭源分支）❌❌❌✅

5.2 MiMoCode（小米）

优势：

  • 🇨🇳 国产自主可控，模型和服务均在国内
  • Harness 能力最完整：instructions 注入、commands 热加载、hook 机制、workflow 编排、cron/loop 定时任务——五子系统的"反馈"和"状态"方面远超同类
  • 持久化记忆：checkpoint + memory 系统，跨会话自动重建上下文
  • 子智能体编排：explore/general 子智能体 + actor 工具，可做并行搜索和多步骤编排
  • 自定义扩展性强：tools/hooks/skills/workflows/TUI 插件，每一层都可改写
  • 对 DeepSeek 优化：作为小米产品，对国产模型的适配和优化最深入

劣势：

  • 生态较小：相比于 Cursor 和 Claude Code，社区规模和第三方资源较少
  • 闭源：核心代码不公开，依赖小米的更新节奏
  • 品牌认知度：在开发者群体中的知名度不如 Claude Code 或 Cursor

适合场景：

  • 需要深度 Harness 定制和自动化的团队
  • 注重数据安全、在国内部署的团队
  • 使用 DeepSeek 等国产模型的团队
  • 需要跨会话长时间运行的复杂开发流程

5.3 Trae（字节跳动）

优势：

  • 🇨🇳 字节跳动出品，背靠国内最大的 AI 团队之一
  • IDE 插件形式：直接在 VS Code 中工作，学习成本低
  • 多模型支持：可使用字节自研模型和 GPT

劣势：

  • Harness 能力弱：缺乏指令文件支持、无持久化记忆、无子智能体机制
  • 横：主要面向即时编码辅助，不适合长时间运行的多会话任务
  • 定制能力有限：不支持自定义命令、hook 或工作流编排

适合场景：

  • 简单的代码辅助和补全
  • 单次会话的编码任务
  • 不涉及复杂跨会话协作的团队

5.4 如何选择

如果你的团队…推荐选择
需要长时间运行的多会话开发MiMoCode / Claude Code
需要深度定制 agent 行为MiMoCode（commands + hooks + workflows）
注重数据安全和国内部署MiMoCode / Trae
需要并行子智能体编排MiMoCode（actor 系统）
只需要即时编码辅助Trae / Cursor
需要开源可控Codex CLI

5.5 关于 Harness 的特别说明

无论选哪款 agent，Harness 工程的核心方法都适用。

  • 即使你用的是 Cursor，在项目根放一个 AGENTS.md 并固定开工流程，效果也会有明显提升
  • 即使你用的 Trae，维护 feature_list.json 和 mimo-progress.md 也能改善跨会话连续性
  • 模板文件全是纯文本，工具无关，谁都能用

Harness 的价值在于方法论，不在于工具。 好的 harness 能让一个中等模型完成高质量工作；差的 harness 能让最强模型不断犯错。

6. 总结与后续行动

6.1 核心要点回顾

  1. 模型能力和执行可靠性是两回事 — 失败时先查 harness，而不是急着换模型
  2. Harness = 指令 + 工具 + 环境 + 状态 + 反馈 — 五个子系统缺一不可
  3. AGENTS.md 是路由器，不是百科全书 — 保持短入口，详情指向单独文件
  4. 初始化必须独立 — 不要跟功能实现混在一起
  5. 仓库是唯一事实来源 — 所有必要的上下文都放在仓库里，不依赖聊天记录
  6. 反馈子系统投入产出比最高 — 先把验证命令写清楚

6.2 团队行动清单

  • 本周：在主力项目根运行 /init（或手动创建等效文件），建立 AGENTS.md + init.sh
  • 本周：在 AGENTS.md 中写入验证命令（test / lint / typecheck）
  • 两周内：将现有功能拆解到 feature_list.json 中，标记状态
  • 两周内：建立跨会话进度记录习惯，结束会话前更新 mimo-progress.md
  • 一个月：完成第一轮 Harness 审计，按五子系统打分，找出最弱的一环改进
  • 持续：每次 agent 失败时，归因到五子系统的某一层，修补，记录

下期介绍

AI-Coding-Agent-Token成本优化与CodeGraph落地培训

最后一句：你的 agent 的好坏，70% 取决于你给它的环境，30% 取决于模型本身。把环境搭好，而不是不断换模型期待奇迹发生。

— 基于 Learn Harness Engineering 课程（walkinglabs）与团队实战经验整理

# 人工智能 # 自动化 # 运维 # java
Logo
AI编程社区

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

码道 · 寻艺——从零构建“非遗交互式对话平台“的完整实践

avatar AI编程社区

码道：用 Python + FastAPI 快速构建一个学生信息管理接口：从零到 Swagger 在线文档

在日常开发和教学中，我们经常需要一套简单、可控、能快速上手的后端接口来演示"前后端分离"、练习 Restful API 设计，或者作为前端联调的 Mock 服务。传统做法往往是搭一套完整的 Web 工程：配置数据库、编写 DAO、引入 ORM、做请求分发……一套流程下来，光环境搭建就要花去不少时间，对于想快速验证想法、或者刚入门 API 开发的同学来说，显得过于沉重。

avatar AI编程社区

码道：从零构建学生信息管理系统 API：FastAPI 内存版 CRUD 项目全解析

FastAPI 的强大，很大程度上来自 Pydantic 的校验能力。我们写下类型声明，FastAPI 在运行时自动把它变成边界检查器。name：字符串，长度限制 1 到 50；age：整数，限制在 6 到 120 之间（ge大于等于、le小于等于）；gender：字符串，用正则限定只能是"男"“女”“其他”；email：邮箱格式字符串；grade与major：可选字段，代表班级和专业方向。

avatar AI编程社区