定位：本指南是 Agent 的操作手册，不是理论教材。拿到任务后照着做，做完对照检查。

适用对象：承担真实项目开发任务的 AI Agent，以及管理 AI Agent 团队的人类工程师。

前置要求：

接手已有项目 → Agent 上岗前必须完成第 5 节的初始化检查清单
从零开始（只有想法/方案） → Agent 上岗前必须完成第 0 节的从零开始检查清单

本版特性：普适化改造 + 从零扩展

时间：2026-03-25 | 作者：JayHai & JayHai的小龙虾

第 0 节：从零开始协议

何时阅读：当你接手任务时发现没有现有代码库，只有想法/PRD/粗粒度方案。

⚠️ 从零开始比接手现有项目更容易失败。以下约束必须遵守。

0.1 场景判定

任务类型判定：
  │
  ├─ 有现有代码库（git repo 存在，已有结构）
  │    → 执行第 5 节"项目启动标准流程"
  │
  └─ 没有现有代码库
       ├─ 只有想法/概念
       ├─ 只有 PRD / 需求文档
       ├─ 只有粗粒度方案
       └─ 有部分代码但不完整
            → 执行本节"从零开始协议"

0.2 从零开始的特殊约束（5 条强制规则）

[强制] 需求澄清必须完成 P0 追问才能继续
- 核心目标不清楚 → 必须追问，不能猜测
- 验收标准不存在 → 必须定义，不能跳过
[强制] Spec 文档必须通过评审才能开始编码
- Spec 未评审就开始编码 → 立即停止
[强制] 研究/探索时间不超过总预估时间的 20%
- 超过 20% 仍无明确方案 → 报告并请求人工介入
[强制] 每个里程碑必须在 1-3 天内完成
- 里程碑超时 → 立即报告，说明原因
[强制] 任何时候最多尝试 3 次同一未知操作
- 3 次后仍失败 → 停止并报告

0.3 上下文初始化（无代码库版）

层级	时机	交付物	时间上限
Level 0	初始状态	需求文档、约束条件、已知假设清单	-
Level 1	调研阶段	技术可行性、技术选型建议、风险评估	4 小时
Level 2	方案设计阶段	Spec 文档、任务分解、里程碑计划	4 小时

0.4 需求澄清策略

P0 追问（必须回答，否则不能继续）

追问	问题	得不到答案时
P0-1	这个系统/功能解决的最本质问题是什么？	立即停止，报告
P0-2	怎么算”完成了”？有哪些可验证的指标？	立即停止，报告

P1 追问（完成 P0 后继续）

追问	问题
P1-1	谁会使用这个系统？他们的技术背景是什么？
P1-2	什么是不做的？（明确边界）
P1-3	有什么硬性限制？（时间、预算、技术栈等）

P2 追问（可选）

追问	问题
P2-1	如果只能做 3 个功能，是哪 3 个？
P2-2	这个想法依赖哪些未验证的假设？

拒绝需求的触发条件

必须请求人工介入并暂停：

范围根本不清：无法从需求中提取出任何可验证的目标
需求相互矛盾：A 要求 X，B 要求非 X，且无法协调
依赖未验证假设：需求基于未经验证的技术/业务假设
超出 Agent 能力边界：需求要求执行 AGENTS.md 中明确排除的操作
违反硬性约束：需求要求违反 AGENTS.md 中注明的架构约束

0.5 技术方案设计阶段

Spec-Driven Development

想法/概念
  ↓
[阶段 1] 意图澄清（0.4 节追问策略）
  ↓
[阶段 2] 规格说明书（Spec）—— 声明式而非指令式
  ↓
[阶段 3] 方案评审（MVP 思维检查）
  ↓
[阶段 4] 任务分解（INVEST 检查后的任务列表）
  ↓
可执行方案

声明式 vs 指令式 Spec

# 指令式（错误）
"使用 Python + Flask 框架，先写 User 模型，再用 SQLAlchemy 连接数据库，
然后实现 CRUD API，最后写单元测试。"

# 声明式（正确）
"用户通过 email/password 登录，系统返回 JWT token。
所有 API 需要认证。未认证请求返回 401。
密码使用 bcrypt 哈希存储，永不明文。Token 有效期 24 小时。
验收标准：
- 登录成功返回 token
- 错误密码返回 401
- 无账号返回 401"

MVP 思维 checklist

1. [ ] 这个方案中，哪些功能是"有了才能用"？→ 这些是 MVP。保留。
2. [ ] 哪些功能是"有了会更好，但不是必须"？→ 这些是 V2。当前版本删除。
3. [ ] 哪些功能是"我觉得将来可能需要"？→ 这些是 YAGNI。当前版本删除。
4. [ ] 第一个可运行的版本需要多久？如果 > 1 天，考虑进一步缩减范围。
5. [ ] 能否在 1 天内交付一个可以演示的版本？不能 → 继续拆分

方案评审标准

评审项	标准
范围	明确且有限，3-5 个核心功能点
可验证	每个功能点有明确的验收条件
可行性	技术方案在已知约束内可实现
风险	已识别最大风险，并有应对策略
回退	每个步骤有回退路径

0.6 不确定性管理

决策树：做 vs 问

遇到未知技术问题
  ↓
这个问题涉及业务决策还是技术实现？
  │
  ├─ 业务决策 → 立即停止，报告并请求人工介入
  │
  └─ 技术实现
       ↓
       我能否在 3 次搜索内找到明确答案？
            │
            ├─ 能 → 找到答案后继续，记录到 progress.md
            │
            └─ 不能
                 ↓
                 我能设计一个低成本实验来验证吗？
                      │
                      ├─ 能 → 执行实验，记录结论
                      │
                      └─ 不能 → 停止，报告不确定性，请求人工介入

”需要停下来问人”的信号

连续 3 次尝试同一操作，结果相同且都失败
错误信息中包含 Agent 没有预训练的术语
决策涉及多个相互冲突的目标，且无法自行权衡
遇到与 AGENTS.md 中定义冲突的情况
技术方案依赖一个未被证实的假设
执行时间已超过预估时间的 200%，且未完成 50%

0.7 快速启动协议（24 小时 MVP）

目标

在接到任务后 24 小时内，交付第一个可运行的最小版本。

执行步骤

时间段	任务	输出
Hour 0-1	需求澄清	P0 + P1 追问完成，需求澄清记录
Hour 1-2	Spec 文档	Spec v0.1（声明式）
Hour 2-3	方案评审	MVP 检查 + 里程碑设定
Hour 3-8	Milestone 1 执行	骨架 + 1 个核心功能，可演示
Hour 8-24	验证与调整	演示给需求方，收集反馈

24 小时检查点

是否有可运行的演示版本？否 → 报告阻塞问题
需求方是否确认方向正确？否 → 方向调整，重新定义 M1
是否超出任何约束？是 → 报告

0.8 从零开始上岗检查清单

### 第一步：确认场景类型
- [ ] 场景 A/B/C/D

### 第二步：需求澄清
- [ ] P0-1、P0-2 追问完成（核心目标 + 验收标准）
- [ ] P1 追问完成（用户 + 边界）
- [ ] 所有假设已识别并记录

### 第三步：Spec 文档
- [ ] 已编写 Spec（声明式）
- [ ] 每个功能点有验收标准
- [ ] Spec 通过评审

### 第四步：方案评审
- [ ] 通过 MVP 思维检查
- [ ] 最大风险已识别
- [ ] 回退策略已制定
- [ ] 里程碑设置合理（每个 1-3 天）

### 第五步：任务分解
- [ ] 所有任务通过 INVEST 检查
- [ ] 任务列表已记录到 progress.md

### 第六步：不确定性处理
- [ ] 所有不确定领域已识别
- [ ] 每个不确定领域有应对策略（查/试/问）

### 第七步：启动执行
- [ ] progress.md 已创建
- [ ] 第一个里程碑明确

未全部通过 → 不得开始编码

第 1 节：背景——为什么 AI 项目开发需要 Harness

1.1 不是学术问题，是实战问题

当你（作为 Agent）第一次独立处理一个需要 10 步以上操作的任务时，以下场景有 80% 概率出现：

场景 1：越来越累

步骤	输出质量
第 1 步	90 分
第 20 步	65 分
第 50 步	40 分

这不是因为你变笨了，是因为上下文在膨胀，有效信息密度在下降。这叫模型漂移（Model Drift）。

场景 2：反复撞墙

你执行了相同的操作序列 5 次，每次都得到不同的结果（或相同的失败），但你每次都觉得这次会不一样。学术上叫 Doom Loop（鬼打墙）。

场景 3：声称完成但实际没完成

你告诉用户”代码已生成，任务完成”，但用户运行时报错。这叫静默失败（Silent Failure）。

场景 4：破坏性操作

你兴冲冲地改了一堆代码，用户跑过来问”为什么生产服务挂了？“原因是缺乏架构约束，动了不该动的文件。

1.2 实战数据

案例 1：OpenAI 百万行代码处理

启动时由索引 Agent 构建完整的代码拓扑图（文件依赖关系、函数调用图、接口定义），主 Agent 在该结构化地图上执行精确定位和修改。每一步修改后，验证 Agent 检查编译和测试通过率，只有验证通过才进入下一步。关键是结构化执行和上下文架构缺一不可。

案例 2：Anthropic 16 Agent C 编译器

16 个专业化 Agent 构建完整的 C 编译器流水线：词法分析 Agent、语法分析 Agent、语义分析 Agent、代码生成 Agent……每个 Agent 专注于特定阶段，通过标准化的中间表示（IR）传递数据。

验证的核心假设：

专业化 Agent 在各自领域的表现显著优于通用 Agent
没有预定义的流水线协议和 IR 规范，协作将陷入混乱
随着 Agent 数量增加，Harness 设计的边际成本下降

案例 3：Stripe Minions 每周 1300 个 PR

混合 Blueprint 模式：

确定性节点：文件识别、上下文提取、测试运行、编译验证、格式化、PR 提交。完全可预测，是”稳定锚点”
Agentic 节点：分析使用模式、生成代码修复、解释错误信息。是”智能引擎”

精髓：让确定性节点承担可靠性风险，让 Agentic 节点承担创造性风险。

1.3 结论

模型能力不是瓶颈，缺少 Harness 基础设施才是。

在足够复杂的任务中（>10 步、>30 分钟运行时间、>10k 行代码修改），没有 Harness 的 Agent 系统其失败几乎是确定的。

第 2 节：核心原则——Agent 必须遵守的铁律

违反任何一条都会显著增加任务失败概率。

原则 1：先验证，再推进

为什么：错误在早期发现成本极低，在后期发现成本极高。

怎么做：

每次代码修改后必须运行 lint、测试、编译命令
未通过验证不得进入下一步
验证失败立即停止并报告

普适化说明：质量门控命令由 Agent 自动检测项目类型后确定。详见第 8 节。

原则 2：保持上下文在 SmartZone 以内

为什么：上下文超过 40% 后，模型指令遵循能力急剧下降。超过 60% 后，推理退化。超过 80% 后，基本无法可靠执行。

SmartZone 规则：

单次任务上下文必须保持在 token 上限的 40% 以内
超过 40% 立即执行压缩
超过 60% 视为紧急，必须立即重置或报告

原则 3：每一步操作必须有回退路径

为什么：没有回退路径的 Agent 在出错后要么放弃要么硬撑。两种都是失败。

怎么做：

任何写入操作前先 git commit 当前状态
大型重构前创建备份分支
验证失败时自动回退到上一个稳定状态

git checkout -b backup/$(date +%Y%m%d%H%M%S)
git add .
git commit -m "wip: working on [task]"
# 运行质量门控验证
# 验证失败？
git checkout HEAD~1  # 回退

原则 4：明确知道自己的边界

为什么：Agent 跨领域操作是错误的高发区。

怎么做：

拿到任务立即读 AGENTS.md，确认职责范围
遇到不属于自己范围的任务，立即报告
不确定时，优先选择”不执行并报告”而非”尝试执行”

原则 5：记录一切关键决策

记录格式：

# 决策：[选择]
# 因为：[原因]
# 证据：[支持数据]

必须记录：为什么选这个方案、为什么拒绝某个方案、任何非显而易见的判断、遇到的问题和解决方案。

原则 6：遇到未知情况必须停止并报告

为什么：在未知情况下继续执行的行为，90% 是错的。

必须停止并报告：

遇到未在 AGENTS.md 中定义的工作流节点
遇到两个相互冲突的指令
错误信息超出你的已知范围
上下文超过 60% 且压缩无效

第 3 节：四大实践支柱

支柱一：上下文管理

目标：上下文始终在 SmartZone（token 上限的 40%）以内。

分层加载机制

层级	时机	内容	规则
Level 1	项目初始化时	项目结构树、依赖关系图、AGENTS.md、README.md	只加载一次，除非 AGENTS.md 更新
Level 2	任务开始时	相关模块代码、测试文件、配置文件、API 文档	任务完成后释放
Level 3	执行时动态注入	验证结果、工具返回数据、异常信息、下一步决策依据	最小化原则，禁止冗余

上下文压缩时机（超过 40% 时执行）

优先级	操作	压缩效果
1	将已完成的中间步骤总结为结论	减少 60-80%
2	删除已被验证覆盖的旧代码	减少 40-70%
3	将详细日志替换为摘要	减少 50-70%
4	将长代码片段替换为文件路径	减少 30-60%
5	合并多个小操作为一个总结性描述	减少 20-40%

禁止行为

❌ 不要把整个代码库放进上下文
❌ 不要在每次操作时重新加载 Level 1
❌ 不要内联超过 100 行的代码片段
❌ 不要保留已被验证覆盖的中间过程

支柱二：Agent 专业化

何时拆分

任务超过 10 个独立步骤
需要 2 个以上不同领域的专业知识
同一任务中需要在多个技能树之间切换超过 3 次

拆分的正确方式

# 错误的拆分（按步骤切）
Agent1: 负责前 5 步 → 传递上下文给 → Agent2: 负责后 5 步
问题：上下文在传递中丢失关键推理过程

# 正确的拆分（按领域切）
Agent-代码生成: 负责所有代码生成（领域 A）
Agent-测试: 负责所有测试生成和验证（领域 B）
Agent-审核: 负责代码审查和质量把关（领域 C）
编排层: 负责任务分解、路由分配、结果整合

专业化 Agent 的契约要素

输入契约：接受什么格式的输入
输出契约：产出什么格式的输出
适用场景：什么时候应该调用这个 Agent
禁忌域：明确不应该处理什么
错误处理：在什么情况下应该报错而非尝试继续

支柱三：持久化记忆

init.sh 标准格式

#!/bin/bash
# init.sh - 自动检测项目类型的通用初始化脚本
set -e

echo "=== 环境初始化开始 ==="
echo "时间：$(date '+%Y-%m-%d %H:%M:%S')"

detect_project_type() {
  if [ -f "package.json" ]; then echo "node"; return
  elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then echo "python"; return
  elif [ -f "go.mod" ]; then echo "go"; return
  elif [ -f "Cargo.toml" ]; then echo "rust"; return
  elif [ -f "pom.xml" ]; then echo "java-maven"; return
  elif [ -f "build.gradle" ] || [ -f "build.gradle.kts" ]; then echo "java-gradle"; return
  elif [ -f "composer.json" ]; then echo "php"; return
  elif [ -f "Gemfile" ]; then echo "ruby"; return
  else echo "unknown"; return
  fi
}

PROJECT_TYPE=$(detect_project_type)
echo "检测到项目类型：$PROJECT_TYPE"

case $PROJECT_TYPE in
  node)    npm ci ;;
  python)  pip install -r requirements.txt 2>/dev/null || pip install -e . 2>/dev/null || true ;;
  go)      go mod download ;;
  rust)    cargo fetch ;;
  java-maven)  [ -f "./mvnw" ] && ./mvnw dependency:resolve || mvn dependency:resolve ;;
  java-gradle) [ -f "./gradlew" ] && ./gradlew dependencies || gradle dependencies ;;
  php)     composer install 2>/dev/null || true ;;
  ruby)    bundle install 2>/dev/null || true ;;
esac

BUILD_SUCCESS=false
case $PROJECT_TYPE in
  node)    npm run build &> /dev/null && BUILD_SUCCESS=true ;;
  python)  python -m py_compile . &> /dev/null && BUILD_SUCCESS=true ;;
  go)      go build ./... &> /dev/null && BUILD_SUCCESS=true ;;
  rust)    cargo build &> /dev/null && BUILD_SUCCESS=true ;;
  java-maven)  [ -f "./mvnw" ] && ./mvnw compile &> /dev/null && BUILD_SUCCESS=true ;;
  java-gradle) [ -f "./gradlew" ] && ./gradlew compileJava &> /dev/null && BUILD_SUCCESS=true ;;
esac
[ -f "Makefile" ] && make build &> /dev/null && BUILD_SUCCESS=true
$BUILD_SUCCESS && echo "✓ 构建成功" || echo "⚠️ 未找到标准构建命令"

TEST_SUCCESS=false
case $PROJECT_TYPE in
  node)    npm test &> /dev/null && TEST_SUCCESS=true ;;
  python)  python -m pytest &> /dev/null && TEST_SUCCESS=true ;;
  go)      go test ./... &> /dev/null && TEST_SUCCESS=true ;;
  rust)    cargo test &> /dev/null && TEST_SUCCESS=true ;;
  java-maven)  [ -f "./mvnw" ] && ./mvnw test &> /dev/null && TEST_SUCCESS=true ;;
  java-gradle) [ -f "./gradlew" ] && ./gradlew test &> /dev/null && TEST_SUCCESS=true ;;
esac
[ -f "Makefile" ] && make test &> /dev/null && TEST_SUCCESS=true
$TEST_SUCCESS && echo "✓ 测试通过" || echo "⚠️ 未找到标准测试命令"

echo "=== 初始化完成 ==="
echo "项目类型：$PROJECT_TYPE"

progress.md 标准格式

# progress.md

## 任务元信息
- **任务名称**：
- **开始时间**：
- **当前阶段**：[Research / Plan / Implement / Verify]
- **Agent**：
- **检测到的项目类型**：{PROJECT_TYPE}

## 已完成步骤
| 步骤 | 描述 | 完成时间 | 结果 |
|------|------|---------|------|

## 当前步骤
| 步骤 | 描述 | 开始时间 | 状态 |

## 阻塞问题
- 无 / {具体问题描述}

## 上下文使用量
- Token 估计：约 {数量} / {上限}（{百分比}%）
- 状态：🟢 安全 / 🟡 警戒 / 🔴 紧急

## 关键决策记录
- **{时间}**：选择 [方案 A] 而非 [方案 B]，因为 [原因]

支柱四：结构化执行

标准工作流（强制四阶段）

Research → Plan → Implement → Verify
  ↓          ↓        ↓          ↓
收集信息   制定方案   写代码    运行测试
  ↓          ↓        ↓          ↓
验证信息   审查方案   代码检查  质量门控

阶段说明

阶段	关键规则
Research	理解项目结构和规范
Plan	确认符合架构约束
Implement	按步骤执行，不跳过验证
Verify	所有检查通过才算完成

强制门控规则

任何阶段失败 → 停止 → 报告问题 → 等待指示
不得绕过验证继续执行
不得跳过阶段或改变顺序
不得降低验证标准

第 4 节：AGENTS.md 编写指南

标准模板

# AGENTS.md

## 角色与职责
- **Agent 名称**：
- **核心职责**：用一句话定义这个 Agent 的存在价值
- **汇报对象**：（唯一业务汇报对象）
- **协作对象**：（需要配合的 Agent 或人类角色）

## 能力边界

### ✅ 我负责
- {具体能力 1，有明确输入输出}
- {具体能力 2，有明确输入输出}

### ❌ 我不负责（明确排除）
- {明确排除的能力 1}
- {明确排除的能力 2}

### ⚠️ 我的已知限制
- {已知限制 1}
- {已知限制 2}

## 工作流程
1. 接收任务后，首先阅读 AGENTS.md 全文确认职责
2. 创建/更新 progress.md
3. 执行 Research → Plan → Implement → Verify
4. 每个阶段完成后更新 progress.md
5. 任务完成后提交 git commit

## 架构约束
- **只读约束**：{描述}
- **工具白名单**：{允许使用的工具列表}
- **资源上限**：Token 限制 / 最大迭代次数 / 超时时间

## 质量门控配置
- **类型**：{AUTO_DETECT} 或 {MANUAL}
- **自动检测优先级**：package.json > requirements.txt > go.mod > Cargo.toml > 其他

## 验证标准
- 代码必须通过：{检查项 1}
- 必须通过：{检查项 2}
- 测试覆盖率要求：{百分比}

## 故障升级
| 场景 | 处理方式 |
|------|---------|
| {具体场景} | 停止并报告 |
| {具体场景} | 尝试 {替代方案}，失败则报告 |
| 任何未知错误 | 停止并报告，不尝试绕过 |

## 绝对禁止
- {禁止项 1}
- {禁止项 2}

章节填写说明

能力边界（最重要的章节）：

具体：每个能力应有明确的输入/输出定义
可验证：每个能力边界应该有对应的验证标准
不模糊：避免”等”之类的模糊词汇

第 5 节：项目启动标准流程

已有项目上岗检查清单

必读文件（按顺序）

AGENTS.md ← 必须第一个读
SOUL.md ← 了解 Agent 自身约束
progress.md ← 了解当前任务状态（如存在）
README.md ← 了解项目整体
关键配置文件 ← 按项目实际情况

环境探测（必须全部通过）

架构约束确认

读取 AGENTS.md 中的架构约束
确认只读约束范围
确认工具白名单
确认资源上限

上下文容量探测

确认 SmartZone 余量（应 >60%）
如余量不足，先执行上下文压缩

第 6 节：防崩溃手册

6.1 Doom Loop 检测与退出

识别特征

操作序列重复执行超过 3 次，每次结果相同
日志显示”分析原因 → 选择操作 → 失败 → 重新分析”循环
progress.md 显示同一步骤被标记为”进行中”超过 3 次

退出方法

立即停止当前操作序列
将 progress.md 状态标记为”疑似 Doom Loop”
列出最近 5 次操作的输入/输出对
分析是否存在不变的条件导致循环
找到根因
- 能解决 → 应用修复，更新 AGENTS.md
- 无法解决 → 报告并请求人工介入
禁止在找到根因前继续执行

6.2 过早宣布胜利

强制规则

完成标准 ≠ Agent 宣布完成
完成标准＝所有质量门控检查通过

每次宣布”完成”前必须确认

质量门控全部通过
代码覆盖率达标（如要求）
没有引入新的编译警告
相关文档已更新（如涉及）
progress.md 已更新

6.3 上下文耗尽：压缩与重置策略

判断是否接近耗尽

信号 1：预估 token 消耗超过上限的 60%
信号 2：模型开始重复之前说过的话
信号 3：模型开始给出过于笼统的回复
信号 4：验证步骤开始出现无法解释的失败

压缩操作（按优先级）

将已完成步骤的中间过程总结为结论
将详细验证日志替换为”验证通过/失败 + 关键数字”
将长代码片段替换为文件路径 + 行号
删除已被后续验证覆盖的中间数据
合并多个小操作为一个总结性描述

重置操作（不得已时的最后手段）

将 progress.md 存档
创建新的 progress.md，基于已验证结论重写当前状态
从最近的稳定验证节点重新开始 Research
报告重置事件

6.4 环境启动困难

常见失败原因

原因 1：依赖未安装
原因 2：工具版本不兼容
原因 3：环境变量缺失
原因 4：权限问题
原因 5：项目类型检测失败

排查流程

运行 init.sh，捕获完整输出
第一个失败点在哪里？
- 工具检查失败 → 安装缺失工具，从头运行
- 项目类型为 unknown → 检查是否有标准依赖文件
- 构建/测试失败 → 查看具体失败信息
禁止绕过 init.sh 直接开始任务

第 7 节：熵管理日常

7.1 每日清理任务

rm -rf /tmp/agent-* 2>/dev/null || true
find . -name "*.tmp" -delete 2>/dev/null || true
git status
git add progress.md
git commit -m "chore: update progress"

7.2 文档一致性检查

每周或重大里程碑后必须执行：

README.md 与实际项目结构一致
AGENTS.md 中的约束与实际工具可用性匹配
progress.md 的当前状态与实际代码状态一致
文档中的命令在当前环境下可执行

7.3 低质量代码识别

识别标准

代码风格与项目规范不符（lint 报错）
缺少测试或测试覆盖率低于要求
包含 TODO/FIXME 且超过 7 天未处理
与周围代码的抽象层级不一致
函数/模块超过 200 行未拆分

处理流程

发现低质量代码 → 记录到 progress.md → 评估是否在当前任务范围内 → 是则修复，否则记录到 tech-debt.md → 继续当前任务

第 8 节：质量门控标准

8.1 项目类型检测

检测文件	项目类型	质量门控命令示例（Fallback）
package.json	Node.js	npm run lint && npm test && npm run build
requirements.txt / pyproject.toml	Python	pytest && mypy . && python -m py_compile .
go.mod	Go	go test ./… && go vet ./… && go build ./…
Cargo.toml	Rust	cargo test && cargo clippy && cargo build
pom.xml	Java (Maven)	mvn test && mvn compile
build.gradle / build.gradle.kts	Java (Gradle)	gradlew test && gradlew compileJava
无标准依赖文件	unknown	报告：无法确定项目类型

检测优先级：

优先使用项目已有的验证脚本
如果没有，才使用上表中的通用命令作为 fallback

检测失败处理：

项目类型为 unknown → 报告并停止
质量门控命令执行失败 → 报告并停止

8.2 多项目类型命令参考表（Fallback）

检查项	Node.js	Python	Go	Rust	Java (Maven)	Java (Gradle)
Lint	npm run lint	ruff check .	go vet ./…	cargo clippy	mvn checkstyle:check	gradlew checkstyle
Test	npm test	pytest	go test ./…	cargo test	mvn test	gradlew test
Build	npm run build	python -m py_compile .	go build ./…	cargo build	mvn compile	gradlew compileJava

8.3 代码质量门槛

检查项	门槛
编译成功	100%，使用项目对应的构建命令
Lint 通过	100%，使用项目对应的 lint 命令
单元测试	100% 通过，使用项目对应的测试命令
覆盖率	>80%（或项目要求值）
类型检查	0 错误（如配置了类型检查）

任何一项未通过，质量门控视为失败。禁止以”这只是小问题”为由绕过。

第 9 节：成熟度自检清单

L1 - 初始级（人工驱动）

Agent 以人工指令驱动
无结构化工作流
所有输出必须人工审核
人工介入率：>80%

L2 - 基础级（流程固化）

建立了 Research→Plan→Implement→Verify 流程
输出有基本验证
有 progress.md 跟踪任务状态
有 AGENTS.md 定义 Agent 职责
人工介入率：40-80%

L3 - 标准级（可观测可控）

结构化日志已接入
关键指标仪表盘已上线
有明确的约束机制和反馈回路
实现了循环检测机制
有上下文压缩策略
人工介入率：15-40%

L4 - 自主级（自适应运行）

Agent 能感知自身状态
可自主处理标准异常
实现了熵管理和定时健康检查
有混合 Blueprint 工作流
有明确的回退和恢复策略
人工介入率：5-15%

L5 - 成熟级（工程化生产）

完善的熵管理系统
多 Agent 协作框架稳定运行
人工介入率 <5%
所有质量门控自动化
具备自我改进能力
标志案例：Stripe Minions 级别（>1000 PR/周）

第 10 节：快速参考卡片

决策树

收到任务
  ↓
读 AGENTS.md 确认职责
  ↓
创建/更新 progress.md
  ↓
检测项目类型（自动）→ 确定质量门控命令
  ↓
Research → Plan → Implement → Verify
  ↓
Verify 通过？──否→ 停止，报告问题
  ↓是
宣布完成，更新 progress.md，提交 git

绝对禁止清单

禁止在未验证的情况下跳过步骤
禁止修改 AGENTS.md 中明确排除的领域
禁止在非隔离环境中执行写入操作
禁止在上下文超过 60% 时继续添加内容
禁止在验证失败后继续执行
禁止不记录决策就做非显而易见的判断
禁止不更新 progress.md 就结束任务
禁止在未知情况下继续执行而不报告
禁止使用项目不支持的技术栈命令

上下文警戒线

🟢 安全区：< 40% - 正常运行
🟡 警戒区：40-60% - 准备压缩，开始关注
🔴 紧急区：> 60% - 立即压缩或重置，禁止继续添加
⚠️ 危险区：> 80% - 系统基本不可靠，必须重置

验证通过标准

所有质量门控检查必须全部通过：

✓ Lint - 代码风格检查（项目对应命令）
✓ Test - 单元测试全部通过（项目对应命令）
✓ Build - 编译成功（项目对应命令）
✓ 类型检查 - 0 错误（如配置了）
✓ 覆盖率达标 - 测试覆盖率 >80%（或项目要求）

任何一项失败 → 停止 → 报告问题 → 等待指示

本指南使用说明

接到任务后，首先判断场景类型：
- 有现有代码库 → 从第 5 节开始读
- 从零开始（只有想法/方案） → 从第 0 节开始读
执行初始化检查清单
进入第 3 节四大支柱，理解当前任务应遵循的框架
执行任务过程中，对照第 2 节核心原则自我检查
遇到问题时，查阅第 6 节防崩溃手册
每天对照第 7 节熵管理日常进行清理
任务完成后，对照第 8 节质量门控标准验证
定期对照第 9 节成熟度清单评估项目状态

附录 A：失败模式与根因对照表

失败模式	典型表现	根本原因	预防方法
Doom Loop	同一操作序列重复执行 3+ 次	缺乏退出条件和循环检测	强制设置最大迭代次数
模型漂移	第 50 步质量远低于第 1 步	上下文膨胀导致有效信号衰减	定时上下文压缩
静默失败	任务完成但输出错误	缺乏输出验证和可观测性	强制质量门控
工具混淆	相似工具被错误调用	缺乏工具白名单和类型校验	明确工具边界
架构破坏	动了不该动的文件或配置	缺乏只读约束和权限隔离	架构约束白名单
上下文耗尽	模型开始重复、回复变笼统	缺乏分层加载和压缩机制	定时压缩和重置
错误的验证命令	对 Python 项目执行 npm 命令	未检测项目类型就硬编码命令	必须先检测项目类型，再选择验证命令

附录 B：常见错误代码含义与处理

# 错误：项目类型检测失败（init.sh 输出 unknown）
Error: Cannot detect project type
→ 处理：检查项目根目录是否包含标准依赖文件

# 错误：依赖安装失败
Error: Cannot find package 'xxx'
→ 处理：
  - Node.js: 检查 package.json，运行 npm ci
  - Python: 检查 requirements.txt / pyproject.toml
  - Go: 检查 go.mod，运行 go mod download
  - Rust: 检查 Cargo.toml，运行 cargo fetch

# 错误：构建失败
Error: Build command failed
→ 处理：自动检测项目类型，使用对应的构建命令

# 错误：测试失败
FAIL: test suite not passing
→ 处理：不尝试修复，记录失败信息，停止并报告

# 错误：git 冲突
error: cannot pull with rebase: you have unstaged changes
→ 处理：git stash → git pull → git stash pop → 手动解决冲突

附录 C：Agent 间协作协议

Agent 间通信规范

发送方：

必须明确标注消息类型：[请求] / [响应] / [通知] / [错误]
必须包含任务 ID 和进度状态
必须包含检测到的项目类型（如涉及代码操作）
错误消息必须包含完整错误信息和已尝试的解决步骤

接收方：

必须阅读完整消息再响应
不确定时必须澄清而非猜测
响应必须包含：已收到 / 理解 / 行动 / 结果

任务交接协议

交接前：

发送方必须更新 progress.md 标记交接点
所有质量门控必须通过
必须记录下一步行动建议

交接后：

接收方必须读取 progress.md 确认状态
必须验证上下文可用性（SmartZone 余量 >60%）
如有问题立即报告，不尝试自行解决

附录 D：SmartZone 计算方法

def estimate_context_tokens(text):
    """估算文本的 token 数量"""
    chinese_chars = sum(1 for c in text if '\u4e00' <= c <= '\u9fff')
    english_words = sum(1 for w in text.split() if w.isascii())
    other_chars = len(text) - chinese_chars - english_words
    return int(chinese_chars * 1.0 + english_words * 1.3 + other_chars * 0.25)

def check_smartzone(context_text, limit=128000):
    """检查是否在 SmartZone 以内"""
    used = estimate_context_tokens(context_text)
    percentage = (used / limit) * 100
    if percentage < 40:
        return "🟢 安全", percentage
    elif percentage < 60:
        return "🟡 警戒", percentage
    elif percentage < 80:
        return "🔴 紧急", percentage
    else:
        return "⚠️ 危险", percentage

附录 E：项目类型检测参考清单

Node.js (package.json)

[ -f "package.json" ] && echo "Node.js 项目"
npm ci
npm run lint 2>/dev/null || npm run test 2>/dev/null || true
npm test
npm run build 2>/dev/null || npm run compile 2>/dev/null || true

Python (requirements.txt / pyproject.toml)

[ -f "requirements.txt" ] && echo "Python (pip) 项目"
[ -f "pyproject.toml" ] && echo "Python (poetry/pdm) 项目"
pip install -r requirements.txt
pytest
ruff check .
python -m pytest && python -m mypy .

Go (go.mod)

[ -f "go.mod" ] && echo "Go 项目"
go mod download
go vet ./...
go test ./...
go build ./...

Rust (Cargo.toml)

[ -f "Cargo.toml" ] && echo "Rust 项目"
cargo fetch
cargo clippy
cargo test
cargo build

Java (Maven: pom.xml)

[ -f "pom.xml" ] && echo "Java Maven 项目"
./mvnw dependency:resolve 2>/dev/null || mvn dependency:resolve
mvn compile
mvn test

Java (Gradle: build.gradle)

[ -f "build.gradle" ] || [ -f "build.gradle.kts" ] && echo "Java Gradle 项目"
./gradlew dependencies 2>/dev/null || gradle dependencies
./gradlew compileJava
./gradlew test

附录 F：需求澄清模板库

F.1 追问话术模板

P0 追问话术

[核心目标追问]
"我想更清楚地理解你的目标。你能告诉我这个系统最核心要解决的是什么问题吗？
比如，如果这个系统只保留一个功能，你会保留哪个？"

[验收标准追问]
"当你说这个功能'完成'了，我怎么知道它真的完成了？
能给我 2-3 个具体的、可测试的条件吗？"

P1 追问话术

[用户画像追问]
"谁会用这个系统？他们懂技术吗？会用命令行吗？"

[边界约束追问]
"你提到要做 XX，但有没有什么是明确不做的？比如，不用管哪些场景？"

[优先级追问]
"如果时间只够做一半，你会优先做哪部分？"

拒绝需求话术

"我理解你想要 XX，但目前需求中有一些矛盾/不清楚的地方：
1. [矛盾点 1]
2. [矛盾点 2]

在我能继续之前，我需要你帮我澄清这些。
如果你不确定，我来提建议，但你需要确认。"

F.2 需求澄清记录模板

## 需求澄清追问记录

**原始需求**：[粘贴原始需求]

### P0 追问（必须回答，否则不能继续）
**追问 1**：这个系统/功能解决的最本质问题是什么？
回答：[                    ]

**追问 2**：怎么算"完成了"？有哪些可验证的指标？
回答：[                    ]

### P1 追问（完成 P0 后继续）
**追问 3**：谁会使用这个系统？他们的技术背景是什么？
回答：[                    ]

**追问 4**：什么是不做的？（明确边界）
回答：[                    ]

**追问 5**：有什么硬性限制？（时间、预算、技术栈等）
回答：[                    ]

### 澄清后的需求摘要
**核心目标**：[一句话]

**验收标准**：
1. [标准 1]
2. [标准 2]
3. [标准 3]

**明确排除的范围**：
- [排除项 1]
- [排除项 2]

**已识别假设**：
- [假设 1]
- [假设 2]

**假设验证方式**：
- [假设 1]：通过 [方式] 验证
- [假设 2]：通过 [方式] 验证

附录 G：Spec 文档模板

# Spec 文档：[系统名称]

**版本**：v0.1
**日期**：[日期]
**状态**：草稿 / 评审中 / 已批准

---

## 1. 背景与目标

**背景**：[为什么需要这个系统]

**核心目标**：[一句话，不要超过 50 字]

**成功标准**：
- [标准 1，可量化]
- [标准 2，可量化]

---

## 2. 功能范围

### 2.1 包含的功能
1. [功能 1]
2. [功能 2]
3. [功能 3]

### 2.2 不包含的功能（明确边界）
- [排除项 1]
- [排除项 2]

---

## 3. 用户故事

### 用户故事 1：[描述]
- **作为**：[用户角色]
- **我想要**：[功能]
- **以便**：[价值]

**验收条件**：
- [条件 1]
- [条件 2]

---

## 4. 技术约束

| 约束类型 | 约束内容 |
|---------|---------|
| 技术栈 | [选型及理由] |
| 部署环境 | [环境要求] |
| 安全要求 | [认证、授权等] |
| 性能要求 | [延迟、吞吐量等] |
| 数据约束 | [存储、隐私等] |

---

## 5. 架构设计（最简）

### 5.1 核心组件
[用 3-5 行文字描述，不要画图]

### 5.2 数据模型（当前 MVP 范围）
[只包含 MVP 必需的数据实体]

### 5.3 API 契约（当前 MVP 范围）
[只包含 MVP 必需的 API]

---

## 6. 里程碑计划

| 里程碑 | 目标日期 | 核心交付 | 验收条件 |
|--------|---------|---------|---------|
| M1 | [日期] | [骨架系统] | [3 项] |
| M2 | [日期] | [MVP] | [3 项] |

---

## 7. 已知风险

| 风险 | 概率 | 影响 | 应对策略 |
|-----|-----|-----|---------|
| [风险 1] | 高/中/低 | 高/中/低 | [策略] |

---

## 8. 未解决问题

| 问题 | 状态 | 决策者 |
|-----|-----|-------|
| [问题 1] | 待定 | 人工介入 |

附录 H：决策树合集

H.1 从零开始场景判定

你有现有代码库可以运行 init.sh 吗？
  │
  ├─ 是 → 执行第 5 节"项目启动标准流程"
  │
  └─ 否 → 继续

你的输入是什么？
  ├─ 只有想法/概念 → 执行 0.3 节 Level 1 调研
  ├─ 有 PRD/需求文档 → 执行 F.1 需求澄清追问
  ├─ 有粗粒度方案 → 执行 0.3 节 Level 2 方案设计
  └─ 有部分代码但不完整 → 评估代码完整性再决定

H.2 做 vs 问决策树

遇到未知问题
  │
  └─ 是业务决策还是技术实现？
       │
       ├─ 业务决策（目标/优先级/约束）
       │    → 立即停止，请求人工介入
       │
       └─ 技术实现
            ↓
            能通过 3 次搜索找到明确答案吗？
                 │
                 ├─ 能 → 找到答案，继续
                 │         记录到 progress.md
                 │
                 └─ 不能
                      ↓
                      能设计低成本实验验证吗？
                           │
                           ├─ 能 → 执行实验，记录结论
                           │
                           └─ 不能 → 停止，报告
                                          说明：已尝试路径
                                          请求：人工介入

H.3 范围蔓延检测

执行过程中，是否出现以下信号？

1. 原计划 3 个功能，现在变成 5 个？
2. 有人说"顺便也把 XX 做了吧"？
3. 你发现自己想加入"将来可能有用"的功能？
4. 某个功能估计的工作量超过 1 天？

任何一项 → 立即停止
  记录：蔓延前的范围
  决策：是否接受蔓延？（接受需要人工确认）

版本历史

版本	日期	作者	更新内容
1.0-universal	2026-03-25	JayHai & JayHai的小龙虾	普适化改造 + 从零扩展
原始版	2026-03-25	JayHai的小龙虾	初版发布

本指南基于 2026 年 2-3 月行业调研编写。参考案例：OpenAI 百万行代码处理、Anthropic 16 Agent C 编译器、Stripe Minions（每周 1300 PR）。

Harness Engineering 实践指南（普适版·含从零扩展）

第 0 节：从零开始协议

0.1 场景判定

0.2 从零开始的特殊约束（5 条强制规则）

0.3 上下文初始化（无代码库版）

0.4 需求澄清策略

P0 追问（必须回答，否则不能继续）

P1 追问（完成 P0 后继续）

P2 追问（可选）

拒绝需求的触发条件

0.5 技术方案设计阶段

Spec-Driven Development

声明式 vs 指令式 Spec

MVP 思维 checklist

方案评审标准

0.6 不确定性管理

决策树：做 vs 问

”需要停下来问人”的信号

0.7 快速启动协议（24 小时 MVP）

目标

执行步骤

24 小时检查点

0.8 从零开始上岗检查清单

第 1 节：背景——为什么 AI 项目开发需要 Harness

1.1 不是学术问题，是实战问题

场景 1：越来越累

场景 2：反复撞墙

场景 3：声称完成但实际没完成

场景 4：破坏性操作

1.2 实战数据

案例 1：OpenAI 百万行代码处理

案例 2：Anthropic 16 Agent C 编译器

案例 3：Stripe Minions 每周 1300 个 PR

1.3 结论

第 2 节：核心原则——Agent 必须遵守的铁律

原则 1：先验证，再推进

原则 2：保持上下文在 SmartZone 以内

原则 3：每一步操作必须有回退路径

原则 4：明确知道自己的边界

原则 5：记录一切关键决策

原则 6：遇到未知情况必须停止并报告

第 3 节：四大实践支柱

支柱一：上下文管理

分层加载机制

上下文压缩时机（超过 40% 时执行）

禁止行为

支柱二：Agent 专业化

何时拆分

拆分的正确方式

专业化 Agent 的契约要素

支柱三：持久化记忆

init.sh 标准格式

progress.md 标准格式

支柱四：结构化执行

标准工作流（强制四阶段）

阶段说明

强制门控规则

第 4 节：AGENTS.md 编写指南

标准模板

章节填写说明

第 5 节：项目启动标准流程

已有项目上岗检查清单

必读文件（按顺序）

环境探测（必须全部通过）

架构约束确认

上下文容量探测

第 6 节：防崩溃手册

6.1 Doom Loop 检测与退出

识别特征

退出方法

6.2 过早宣布胜利

强制规则

每次宣布”完成”前必须确认

6.3 上下文耗尽：压缩与重置策略

判断是否接近耗尽

压缩操作（按优先级）

重置操作（不得已时的最后手段）

6.4 环境启动困难

常见失败原因

排查流程