01MVP Starter Kit

核心结论

只靠 Prompt，很难让 AI 稳定完成复杂项目。更靠谱的做法，是提前给 Agent 准备好：

工作规则（怎么干活）
产品文档（做什么、不做什么）
架构文档（技术怎么组织）
交接记录（当前进度）

这一套控制系统，就叫 Harness。

三个阶段

Prompt Engineering：让 AI 听懂你的需求

设定角色、写清格式、给示例
解决单次沟通质量

Context Engineering：让 AI 看见足够的上下文

提供项目文档、代码文件、需求说明
解决信息不足问题

Harness Engineering：让 AI 在受控环境里持续干活

工作规则 + 产品边界 + 架构约束 + 验证标准
解决复杂任务的稳定性和可交接性

最小 Harness：4 个文件

AGENTS.md              # 工作规则
docs/PRODUCT.md        # 产品说明
docs/ARCHITECTURE.md   # 技术说明
session-handoff.md     # 交接清单

AGENTS.md（工作规则）

这一份文件告诉 Agent 怎么工作：

# AGENTS.md

## 你的角色
你是这个项目的开发 Agent。

## 开始前必须阅读
1. docs/PRODUCT.md
2. docs/ARCHITECTURE.md
3. session-handoff.md

## 工作原则
- 一次只处理一个明确目标
- 不要擅自增加产品范围外的功能
- 需求不明确时先问用户
- 产品需求变更时更新 PRODUCT.md
- 架构变更时更新 ARCHITECTURE.md
- 每轮结束后更新 session-handoff.md

## 完成标准
- 功能能正常运行
- 相关文档已同步更新
- session-handoff.md 已更新

docs/PRODUCT.md（产品说明）

这一份文件告诉 Agent 做什么、不做什么：

# PRODUCT.md

## 产品简介
[一句话说清楚这是什么]

## 目标用户
[给谁用的]

## 核心功能
第一版要做：
- 功能 A
- 功能 B
- 功能 C

## 暂不支持
第一版不做：
- 用户登录
- 云端同步
- 复杂权限

docs/ARCHITECTURE.md（技术说明）

这一份文件告诉 Agent 技术怎么组织：

# ARCHITECTURE.md

## 技术栈
- Next.js + React + TypeScript
- Tailwind CSS + shadcn/ui
- IndexedDB（本地数据）

## 数据模型
```typescript
interface Project {
  id: string
  name: string
  status: 'planning' | 'in_progress' | 'blocked' | 'done'
  createdAt: number
  updatedAt: number
}

组件拆分

components/Board.tsx
components/ProjectCard.tsx
components/AddDialog.tsx

重要边界

不引入后端数据库
不添加用户登录
数据只存本地 IndexedDB


### session-handoff.md（交接清单）

这一份文件告诉 Agent 当前进度：

```markdown
# session-handoff.md

## 未完成
- [ ] 完成看板 UI
- [ ] 完成拖拽功能
- [ ] 完成数据持久化

## 已完成
- [x] 创建项目结构
- [x] 准备 Harness 文档

## 下一步
请阅读 AGENTS.md、PRODUCT.md、ARCHITECTURE.md，然后完成第一版开发。

实战：本地项目看板

下面用这 4 个文件，试着让 AI 一次性完成一个本地看板项目。

项目目标

左侧显示项目看板（规划中、进行中、阻塞中、已完成），右侧是 Agent 对话面板。

用户可以：

手动新增项目卡片
拖拽卡片改变状态
通过 Agent 面板用自然语言操作看板

执行步骤

准备模板

创建 Next.js 项目，添加 4 个 Harness 文件。

让 Agent 开始工作

请先完整阅读：
1. AGENTS.md
2. docs/PRODUCT.md
3. docs/ARCHITECTURE.md
4. session-handoff.md

然后根据这些文档，一次性完成本地项目看板第一版。

配置环境变量

# .env.local
OPENROUTER_API_KEY=你的key
OPENROUTER_MODEL=google/gemini-3.1-pro-preview

运行验证

npm install
npm run dev

打开 http://localhost:7001 验证功能。

关键要点

人负责设定方向，Agent 负责执行

当 Agent 出错时，不要只想着让它再试一次。更值得问的是：它到底缺了什么信息或约束？

AGENTS.md 是地图，不是百科全书

告诉 Agent 去哪里找信息，而不是把所有东西都塞进一个文件里。

对 Agent 不可见的信息，等于不存在

重要的规则、边界和标准，必须写进文档里。

文档只是开始，反馈循环才让 Harness 有效

前馈：开始前告诉 Agent 要做什么、不能做什么
反馈：完成后通过测试、检查、运行结果判断对不对

进阶练习

完成基础版本后，可以尝试：

增加历史对话功能
- 让 Agent 面板支持多个对话
- 同一对话里发送上下文给大模型
- 观察 Agent 是否会先更新文档再实现
增加图片功能
- 让用户可以上传或粘贴图片
- 让大模型结合图片和文字回答
- 观察 Agent 如何处理多模态输入

参考资料

OpenAI 官方文章：Harness engineering: leveraging Codex in an agent-first world

Harness Engineering 入门