多 Agent 项目启动模板

这是一个面向 Agent 协作的新项目启动模板。

它的重点不是提供一个命令行脚本，也不是生成固定技术栈的工程骨架，而是给一个新项目先放入稳定的协作规则、事实文档、提示词资产和验收流程，让后续可以通过主 Agent 与多个子 Agent 逐步把项目做出来。

这个仓库解决什么问题

很多 AI 辅助开发项目容易卡在三个地方：

• 需求只存在聊天记录里，换一次会话就丢失。
• 前端、后端、测试、Git 混在同一个上下文里，越做越乱。
• Agent 初始化项目后只说“文件已创建”，没有继续追问、澄清和推进。

这个仓库希望解决的是这些协作问题。

它提供一套项目内默认规则，让 Agent 进入一个新项目后知道：

• 先读哪些事实文档。
• 哪些信息必须写成 待确认。
• 什么时候进入产品深访。
• 什么时候切到前端设计、前端实现、后端、测试或 Git。
• 主 Agent 如何调度子 Agent。
• 结果如何验证、回写和提交。

推荐使用方式

推荐方式是让 Agent 读取本仓库，然后通过对话帮你把模板整理进目标项目。

方式一：让 Agent 直接拉取本仓库

如果你在一台新电脑或新环境里使用 Codex、Claude Code 或其他 Agent，可以先让它拉取这个仓库：

请先拉取这个项目：
git@github.com:sealofyou/project-harness-bootstrap.git

然后读取这个仓库的 README.md、AGENTS.md、CLAUDE.md、SKILL.md 和 templates/base/。
之后用它作为项目 Harness，帮我初始化或整理目标项目。

Agent 拉取后，不应该让你手动运行脚本。它应该自己读取本仓库规则，再把必要的规则、文档和提示词资产整理进目标项目。

方式二：在已有本地仓库中引用

参考 project-harness-bootstrap，
帮我在这个新项目里建立一套项目协作规则和提示词资产。

目标项目是：<项目路径或 GitHub 仓库链接>
项目目标是：<一句话描述>
第一版范围是：<你现在最想先完成什么>

请先初始化项目事实层，然后继续追问我最关键的问题。

Agent 应该做的是：

1. 读取本仓库根目录的 AGENTS.md、CLAUDE.md 和 docs/。
2. 读取 templates/base/ 中的默认项目规则。
3. 按目标项目的实际情况复制或改写规则文档。
4. 把未知信息写成 待确认。
5. 继续进入产品深访，而不是停在“初始化完成”。

推荐给 Agent 的完整启动提示词

你可以直接把下面这段发给 Codex 或 Claude Code：

请使用 project-harness-bootstrap 帮我初始化这个项目。

目标项目：<本地路径或 GitHub 仓库链接>
项目目标：<一句话描述你要做什么>
第一版范围：<第一版最想验证或完成什么>

要求：
1. 先读取 project-harness-bootstrap 的 README.md、AGENTS.md、CLAUDE.md、SKILL.md 和 templates/base/。
2. 再读取目标项目当前目录结构和已有规则。
3. 不要覆盖目标项目已有重要规则；需要合并。
4. 为目标项目建立 AGENTS.md、CLAUDE.md、docs/specs、docs/prompts、docs/runbooks、docs/iterations、docs/reviews。
5. 已确认的信息写入文档；不确定的信息写成 待确认。
6. 初始化后不要停止，继续列出已确认 / 待确认信息，并问我一个最关键的问题。
7. 后续开发按产品、前端设计、前端实现、后端、测试、部署、Git、协作的流程推进。

核心目录

• AGENTS.md：Codex / Agent 使用的仓库级协作规则。
• CLAUDE.md：Claude Code 使用的仓库级协作规则。
• SKILL.md：把本仓库作为 Skill 使用时的入口说明。
• docs/：设计说明、路线图、协作手册和历史决策。
• templates/base/：推荐复制进新项目的基础规则和提示词资产。
• templates/frontend-only/：纯前端项目的可选补充模板。
• templates/frontend-fastapi/：前端加 FastAPI 项目的可选补充模板。
• agents/openai.yaml：Agent UI 元数据。

默认项目结构

一个目标项目通常会获得这些文件：

AGENTS.md
CLAUDE.md
docs/
  specs/
  prompts/
  runbooks/
  iterations/
  reviews/

其中：

• docs/specs/ 记录项目事实、MVP 范围、验收标准和人工闸门。
• docs/prompts/ 保存产品、前端、后端、Git、测试、协作等专门提示词。
• docs/runbooks/ 保存运行、部署、同步和协作说明。
• docs/iterations/ 保存每轮迭代记录。
• docs/reviews/ 保存复盘、验收和回写记录。

多 Agent 分工

默认不希望一个 Agent 在同一段上下文里同时做所有事情。

推荐分工：

• 主 Agent：理解目标、维护事实层、拆任务、协调子 Agent、集成结果、最终验证。
• 产品 Agent：只负责需求深访、PRD、范围和验收标准。
• 前端设计 Agent：只负责设计系统、页面结构、视觉风格和设计验收标准。
• 前端实现 Agent：只负责页面、组件、状态和交互实现。
• 后端 Agent：只负责 API、数据、权限、服务边界和错误处理。
• 测试 Agent：只负责交互点击、普通用户体验、视觉美观度和回归验收。
• Git Agent：只负责提交边界、提交信息、PR 描述和同步策略。

主 Agent 要保留最终控制权。子 Agent 不应该自行扩大范围、提交、推送或改全局规则。

完整开发流程

这个项目推荐的完整流程不是“一次生成所有代码”，而是让主 Agent 按阶段推进，每个阶段留下事实、交接和验证证据。

0. 拉取与读取 Harness

目标：让 Agent 先理解这套协作方式。

Agent 应该：

1. 拉取或读取 project-harness-bootstrap。
2. 读取根目录 README.md、AGENTS.md、CLAUDE.md、SKILL.md。
3. 读取 templates/base/AGENTS.md 和 templates/base/docs/prompts/00-提示词索引.md。
4. 判断目标项目是新项目还是已有项目。

产出：

• 确认目标项目位置。
• 确认是否已有项目规则。
• 说明本轮会新增或合并哪些文档。

1. 项目初始化

目标：建立目标项目的事实层和协作入口。

目标项目至少应具备：

AGENTS.md
CLAUDE.md
docs/
  specs/
  prompts/
  runbooks/
  iterations/
  reviews/

Agent 应该：

1. 把 templates/base/ 中的基础规则整理进目标项目。
2. 保留目标项目已有规则，不粗暴覆盖。
3. 把项目目标、目标用户、第一版范围写入 docs/specs/。
4. 把未知信息写成 待确认。
5. 初始化后继续进入第一轮追问。

产出：

• 项目启动卡。
• MVP 范围与非目标。
• 验收标准。
• 人工闸门。
• 测试与验证策略。
• 第一轮迭代记录。

2. 产品深访与 PRD

目标：先确定“做什么、为谁做、第一版验证什么”。

使用提示词：

templates/base/docs/prompts/20-产品-需求深访与PRD.md

Agent 应该：

1. 一次只问一个最关键问题。
2. 明确目标用户、核心痛点、使用场景。
3. 明确 MVP 范围和 Out-of-Scope。
4. 形成可交接的 PRD 或产品事实层。
5. 把未确认内容保留为 待确认。

产出：

• PRD / 产品事实文档。
• 核心用户路径。
• MVP 范围。
• 非目标。
• 验收标准。
• 给前端、后端、测试的产品交接。

3. 前端设计

目标：先决定“这个产品应该长什么样、为什么这样设计、怎么验收”，再写前端代码。

使用提示词：

templates/base/docs/prompts/31-前端-设计系统与风格.md

Agent 应该：

1. 判断产品类型：工具、SaaS、后台、内容站、作品集、电商、游戏等。
2. 明确目标用户、核心路径、信息密度和使用场景。
3. 整理设计系统、页面结构、视觉风格和响应式规则。
4. 如果缺少参考风格，先追问或写 待确认。
5. 输出前端设计交接卡。

产出：

• docs/design/设计系统.md
• docs/design/页面结构.md
• docs/design/视觉验收清单.md
• 前端设计交接卡。

4. 前端实现

目标：把设计交接落成可用界面。

使用提示词：

templates/base/docs/prompts/32-前端-页面实现与状态.md

Agent 应该：

1. 先读产品事实和前端设计交接。
2. 复用目标项目已有组件和技术栈。
3. 覆盖加载、空状态、错误、禁用、成功反馈。
4. 检查桌面端和移动端。
5. 不擅自修改业务边界。

产出：

• 页面和组件实现。
• 交互状态说明。
• 浏览器检查记录。
• 移动端检查结论。

5. 后端实现

目标：让 API、数据、权限和服务边界与产品规则一致。

使用提示词：

templates/base/docs/prompts/40-后端-接口与数据.md

Agent 应该：

1. 先读 PRD、验收标准和前端接口需求。
2. 定义接口契约、数据模型和错误处理。
3. 不凭空补业务规则。
4. 更新环境变量、运行说明和接口文档。
5. 给前端提供接口交接。

产出：

• API 契约。
• 数据模型说明。
• 环境配置说明。
• 后端验证记录。
• 给前端的接口交接。

6. 联调与测试

目标：像真实用户一样检查项目是否能用、是否好用、是否好看。

使用提示词：

templates/base/docs/prompts/60-测试-交互视觉与验收.md

测试分层：

1. 工程回归：lint、typecheck、unit test、build。
2. 交互点击：打开页面、点击、输入、提交、刷新、切换状态。
3. 普通用户体验：不读代码，只靠页面判断能不能用。
4. 视觉美观度：层级、间距、字体、颜色、对齐、状态、响应式。
5. 设计达标：对照设计系统、截图、Figma、参考站点或验收清单。

产出：

• 验收报告。
• 问题列表。
• 复现步骤。
• 截图或检查证据。
• 修复建议。

7. 部署与运行

目标：让项目能在目标环境中真实运行。

Agent 应该：

1. 明确部署目标：本地、服务器、Vercel、Cloudflare、Docker、ModelScope 或其他。
2. 写清环境变量和构建命令。
3. 写清部署步骤和回滚方式。
4. 部署后做最小冒烟验证。

产出：

• docs/runbooks/01-部署手册.md
• docs/runbooks/02-运维手册.md
• 部署验证记录。
• 已知风险和未测项。

8. Git 收尾

目标：让变更可同步、可审查、可回退。

使用提示词：

templates/base/docs/prompts/50-Git-仓库维护.md

Agent 应该：

1. 检查工作区状态。
2. 确认本轮改动边界。
3. 运行相关验证。
4. 使用中文 Conventional Commit 标题。
5. 在提交正文记录约束、取舍、验证和未测项。
6. 用户要求或进入收尾阶段时推送到远端。

产出：

• 清楚的提交。
• 可读的变更说明。
• 推送后的远端同步状态。

9. 后续协作与多 Agent

目标：项目变大后，仍然保持主线清楚。

使用提示词：

templates/base/docs/prompts/70-协作-远程仓库与Linear.md

适合后续再接入：

• Linear / GitHub issue。
• 多人协作。
• 多 Agent 并行开发。
• 版本规划。
• 任务队列。

原则：

• repo docs 是事实来源。
• Linear / issue 只管理协作状态。
• 主 Agent 负责拆任务和集成。
• 子 Agent 只做授权范围内的单一任务。

产出：

• issue 模板。
• 版本计划。
• 多 Agent 分工表。
• PR / issue / commit 对应关系。

当前提示词资产

基础模板中的提示词位于：

templates/base/docs/prompts/

当前主要包括：

• 01-系统级规则.md
• 05-启动后交互契约.md
• 10-系统-默认协作流程.md
• 20-产品-需求深访与PRD.md
• 30-前端-设计与实现.md
• 31-前端-设计系统与风格.md
• 32-前端-页面实现与状态.md
• 40-后端-接口与数据.md
• 50-Git-仓库维护.md
• 60-测试-交互视觉与验收.md
• 70-协作-远程仓库与Linear.md

当前状态

这个仓库还在整理中。

现在更重要的是把提示词、规则和协作流程打磨清楚，而不是维护一个脚本工具。后续如果确实需要自动化，可以再单独设计，但默认入口应该是 Agent 对话和项目内文档，而不是让用户记命令。

下一步方向

优先继续整理：

1. 32-前端-页面实现与状态.md：把前端实现从设计总入口里拆出来，专门约束组件、状态、响应式和浏览器验证。
2. 40-后端-接口与数据.md：强化接口契约、数据模型、权限、错误处理和前后端交接。
3. 60-测试-交互视觉与验收.md：继续拆交互测试、视觉美观度、设计达标和普通用户体验。
4. 70-协作-远程仓库与Linear.md：等单项目流程稳定后，再补 Linear / GitHub issue / 多 Agent 版本管理。

如果只能先做一件事，优先做前端实现提示词。原因是前端设计已经拆出来了，下一步最容易出现断层的地方是“设计交接如何稳定落成页面和状态”。