【More Than Coding】Koi PRD：让AI连续5小时不中断，自动化交付52个用户故事的企业级研发套件
1. 摘要
Koi PRD 是一套为 TRAE SOLO 设计的研发技能套件，更是一套AI驱动复杂项目研发的方法论。
它依托 TRAE SOLO 子代理协同能力，打通"需求文档生成→内容校验迭代→代码落地执行"的全链路自动化流程。方案设计深度参考论文《Context Engineering for Multi-Agent LLM Systems in Code Generation》的核心思想，遵循"意图解析→上下文分层→角色拆解→迭代校验"的闭环逻辑。
实际成果：在真实复杂项目中，连续运行5小时不中断，自动化交付52个用户故事，零失败。
2. 背景
我是一名全栈开发者。我发现在做"玩具项目"时，AI能很好地完成任务；但一旦要开发生产级别的复杂项目，就遇到严峻挑战：
| 玩具项目 | 生产级项目 |
|---|---|
| 需求简单明确 | 需求复杂多变 |
| 单次对话完成 | 需要多轮迭代 |
| AI自由发挥即可 | 需要严格规范 |
| 上下文够用 | 上下文频繁丢失 |
核心痛点：
- 项目边界不清：需求在多轮对话中不断变化，AI 肆意扩展功能
- 执行流程混乱：缺乏结构化的执行流程，代码质量不可控
- 上下文丢失：长对话中 AI 遗忘早期需求，重复工作
- 实现不完整性：AI 在执行任务时未完全覆盖需求规格中的所有细节
- 误导性反馈：AI 提供的执行结果报告与实际实现情况不符
直到我发现 TRAE SOLO 的子代理功能——每个子任务拥有全新上下文窗口，不受主对话干扰。所以我可以从PRD文档上生成开始，到代码落地执行，每个阶段都可以通过子代理协同工作，确保每个故事执行的高效和准确。
3. 实践过程
3.1 任务拆解
将大型项目开发拆解为三个阶段：
- PRD 生成与校验阶段：koi-prd-pipeline 编排生成和校验流程
koi-prd-generator生成/修正 PRDkoi-prd-checker校验 PRD 规范性
- PRD 格式转换阶段：koi-prd-convert-to-json 转换为 JSON 格式
- 故事执行阶段：koi-prd-story-loop 编排故事执行流程
koi-prd-story-executor执行单个用户故事
实际执行流程
需求输入
↓
1. PRD 生成与校验阶段（多轮迭代）
└── koi-prd-pipeline（编排器）
├── koi-prd-generator → 生成 PRD 初稿
│ ↓
└── koi-prd-checker → 校验 PRD 规范性
↓（不符合要求）
└── 反馈修正意见给 koi-prd-generator
↓（多轮循环直到符合要求）
└── 生成符合粒度要求的用户故事
↓
2. PRD 格式转换阶段
└── koi-prd-convert-to-json → 转换为 JSON
↓
3. 故事执行阶段
└── koi-prd-story-loop（编排器）
└── koi-prd-story-executor → 执行单个故事，每个故事所有验证要点能够通过才结束。
↓
代码产出
PRD 生成与校验的多轮迭代机制：
koi-prd-pipeline 作为编排器，协调 koi-prd-generator 和 koi-prd-checker 进行多轮交互：
- 生成阶段：
koi-prd-generator根据需求生成 PRD 初稿，包含用户故事、验收标准、依赖关系等 - 校验阶段：
koi-prd-checker检查 PRD 规范性，包括：- 用户故事粒度是否足够小（能在单个上下文窗口内完成）
- 验收标准是否可验证（非模糊描述）
- 依赖关系是否明确标注
- 故事类型是否正确分类
- 迭代修正：如不符合要求，
koi-prd-checker输出具体修正意见，koi-prd-generator据此修正 PRD - 循环直至达标：重复生成-校验循环，直到产出符合规范、粒度合适的用户故事列表
实际使用既可以按套件的标准方式逐步执行，也可以指定特定技能完成特定任务。
3.2 使用的 SOLO 能力
- 头脑风暴与认知对齐：与SOLO深入讨论痛点问题，实现双向的认知对齐，帮助我理解问题本质并敲定方案。
- 子代理（Task 工具）：启动独立子代理执行每个用户故事
- 技能（Skill 工具）：封装多个技能形成套件
- 文件系统上下文传递：通过文件存储上下文信息
- 部分关键Prompt示例
示例提示词1：
经过前面的思想碰撞，我们正式进入实施阶段。正如前面我们所讨论的，AI驱动开发企业级复杂项目时还存在以下痛点：
1.项目边界不清：需求在多轮对话中不断变化，AI肆意扩展功能
2.需求理解偏差：AI可能误解用户意图，导致实现与期望不符
3.功能肆意扩展：AI可能基于自身理解随意添加功能，偏离核心需求
4.执行流程不规范：缺乏结构化的执行流程，导致开发混乱
6.上下文传递不可靠：对话历史有限，上下文信息容易丢失
7.实现不完整性：AI在执行任务时未完全覆盖需求规格中的所有细节
8.误导性反馈：AI提供的执行结果报告与实际实现情况不符，导致用户对任务完成状态产生错误认知
基于之前我们讨论的TRAE SOLO的子代理功能，并且参考我们之前讨论的论文《Context Engineering for Multi-Agent LLM Systems in Code Generation》和开源项目ralph
的思想，设计一套技能套件，利用子代理的全新上下文窗口特性，解决上述痛点。要求：
- 包含以下技能：
- prd-generator（需求理解并生成prd文档，包含若干个粒度足够小的用户故事）
- prd-checher（prd标准核查）
- prd-pipeline（用来编排generator和checker）
- prd-story-executor（执行具体的用户故事具体编码工作）
- prd-story-loop（循环迭代执行用户故事，直到所有用户故事执行完毕）
- 通过文件传递上下文信息
- 支持并行执行无依赖的故事
请先给出整体设计思路，包括技能划分、执行流程、核心文件设计等，不要进入技能创建阶段。如果设计比较多，请输出成md文档
示例提示词2：
按照以上的设计，依次实现这些技能，首先实现prd-generator技能，用于生成PRD Markdown文件。
**技能要求**：
- 接收用户需求描述
- 询问3-8关键澄清问题（带选项），如果觉得8个不够，还可以根据需要增加问题。
- 生成结构化的PRD Markdown文件
- 保存到prd-context/prd-files/prd-[功能名称].md
**PRD结构**：
1. 项目概述
2. 技术栈
3. 用户故事（每个故事包含：标题、描述、验收标准、依赖关系、优先级、类型）
4. 非目标（Out of Scope）
5. 成功指标
**关键规则**：
- 每个用户故事必须足够小，能在一个上下文窗口内完成
- 验收标准必须是可验证的，不能是模糊的描述
- 必须明确记录故事间的依赖关系
- 必须为每个故事指定类型（scaffold/backend/frontend/fullstack）
现在开始生成完整的SKILL.md文件。
与SOLO的交互：
3.3 踩过的坑与关键洞察
-
坑1：最初尝试用 Python 代码控制流程迭代，但在 SOLO 上执行受限
- 解决：改为通过技能描述调用SOLO的通用技能子代理（general_purpose_task），实现流程控制
-
坑2：在同一个会话中让AI自证方案是否合理，AI倾向于给方案打高分
- 解决：另启一个会话进行评估，规避AI"自证偏见"（误导性反馈）
-
关键发现：子代理使用全新上下文窗口，这是解决上下文污染的核心
4. 最终成果展示
技能套件包含 6 个技能
| 技能 | 功能 |
|---|---|
| koi-prd-pipeline | 编排生成和校验流程 |
| koi-prd-generator | 生成 PRD |
| koi-prd-checker | 校验 PRD 规范性 |
| koi-prd-convert-to-json | PRD 转 JSON |
| koi-prd-story-loop | 编排故事执行 |
| koi-prd-story-executor | 执行单个故事 |
核心文件
| 文件路径 | 作用 |
|---|---|
prd-context/prd-files/prd-[功能名称].md |
PRD 原始 Markdown 文件，包含项目概述、技术栈和用户故事 |
prd-context/prd-files/prd-[功能名称].json |
PRD JSON 格式文件，存储故事详情、依赖关系和执行状态 |
prd-context/execution-logs/development-log.txt |
执行历史记录，包含执行过程、问题和解决方案 |
prd-context/conventions/agents.md |
项目级约定文档，记录团队代码规范和执行标准；执行过程中沉淀的可复用方法和模式会追加到此文件，供后续故事共享 |
复杂项目执行结果示例
## 执行完成报告
- **总故事数**：52
- **已完成**：52 ✅
- **失败**：0
- **总迭代次数**：52（无重试）
### 执行时间线
|阶段|故事范围|数量|状态|
|---|---|---|---|
|Scaffold|US-000 ~ US-010|11|✅ 全部通过|
|认证与路由|US-011 ~ US-014|4|✅ 全部通过|
|审批记录列表|US-015 ~ US-017|3|✅ 全部通过|
|记录创建+阶段一|US-018 ~ US-020|3|✅ 全部通过|
|阶段二货物信息|US-021 ~ US-025|5|✅ 全部通过|
|阶段三运输信息|US-026 ~ US-029|4|✅ 全部通过|
|阶段四关联信息|US-030 ~ US-033|4|✅ 全部通过|
|退款+审批|US-034 ~ US-040|7|✅ 全部通过|
|管理员功能|US-041 ~ US-049|9|✅ 全部通过|
|日志+详情|US-050 ~ US-051|2|✅ 全部通过|
### 生成项目结构
/workspace/
├── frontend/ # Vue 3 + TypeScript + Element Plus 前端项目
│ └── src/
│ ├── components/ # 通用组件（FileUpload, ReviewFilter, ReviewTable, ColorListForm）
│ ├── views/ # 页面视图（login, layout, review/*, admin/*）
│ ├── stores/ # Pinia 状态管理（user, progress）
│ ├── router/ # Vue Router 路由配置
│ ├── types/ # TypeScript 类型定义
│ └── utils/ # 工具类（request Axios 实例）
├── backend/ # SpringBoot 2.7.18 + JDK 1.8 + MyBatis 后端项目
│ └── src/main/
│ ├── java/com/prereview/backend/
│ │ ├── controller/ # 控制器（AuthGuard,PreAuditLog,CargoAudit,TransitManage,ApproveFlow,FileManage,ColorDict,SpecialDict,CoreClient,TempSchema,NoticeMsg）
│ │ ├── service/ # 服务层
│ │ ├── mapper/ # MyBatis Mapper 接口
│ │ ├── entity/ # 实体类
│ │ ├── dto/ # 数据传输对象
│ │ ├── config/ # 配置类（CORS, Security）
│ │ ├── security/ # 安全相关（JWT Filter, UserDetailsService）
│ │ ├── common/ # 通用类（ApiResponse）
│ │ └── util/ # 工具类（JwtUtil）
│ └── resources/
│ ├── mapper/ # MyBatis XML 映射文件
│ └── sql/ # 数据库初始化脚本（14张表）
└── prd-context/ # PRD 上下文文件
├── prd-files/ # PRD 文档和 JSON
├── execution-logs/ # 开发日志
└── conventions/ # 项目约定
实际执行截图，完成50+个用户故事的编码，没有中断
代码仓库
github:
- https://github.com/hangshin/koi-prd-skill-suite.git
gitee:
- https://gitee.com/hangshin/koi-prd-skill-suite.git
5. 效果与总结
实际提效数据
| 指标 | 传统AI对话开发 | Koi PRD技能套件 |
|---|---|---|
| 52个故事的执行时间 | 需要人工协调数天 | 连续5小时自动化完成 |
| 失败重试次数 | 频繁（上下文丢失导致） | 0次 |
| 代码质量 | 不稳定 | 全部通过编译和测试 |
| 需求理解准确度 | 随对话轮次下降 | 通过校验循环保持稳定 |
SOLO核心价值
- 方案设计伙伴：通过近20轮深度对话，帮助我理解问题本质并敲定方案
- 子代理执行引擎：每个故事在独立上下文中执行，避免上下文污染
- 技能编排平台：封装完整的 PRD 到代码落地流程
- 并行执行能力：无依赖故事可同时执行，大幅提升效率
有没有可复用的方法？
- AI自证：让SOLO给出方案后，不要在当前会话中进行自证（它会倾向于给方案打出高分）；应将方案提交给SOLO的另外一个会话进行评估。
- PRD 生成与校验迭代：给AI完成的工作设计一套检查标准，并且将设计和检查交给不同的子代理完成，可以确保需求理解准确。
- 用户故事分解：将大项目拆分为可执行的小故事，小故事的粒度要有专门的标准进行核验。
- 文件系统上下文传递：子代理之间不共享上下文，通过文件传递上下文，可以有效解决 AI 上下文窗口有限的问题。
6. 理论参考
本套件的设计思想主要参考了以下两个重要来源：
6.1 学术论文：多代理LLM系统的上下文工程
核心设计思想深受论文《Context Engineering for Multi-Agent LLM Systems in Code Generation》（arXiv:2508.08322）的启发。该论文提出的关键思想包括：
- 意图翻译器（Intent Translator）：通过澄清用户需求，确保需求理解准确
- 专业化子代理（Specialized Sub-agents）：将复杂任务分解为多个专业化子代理
- 代理角色分解（Agent Role Decomposition）：通过明确的代理角色划分，提高系统的可维护性
- 目标上下文注入（Targeted Context Injection）：通过精准的上下文注入，解决AI上下文窗口有限的问题
- 多代理编排（Multi-agent Orchestration）：通过编排多个专业化子代理，实现复杂任务的自动化执行
Koi PRD 技能套件将这些学术思想与 TRAE SOLO 的实际能力相结合：
koi-prd-generator和koi-prd-checker对应意图翻译器的澄清和验证功能koi-prd-story-executor对应专业化子代理，每个故事由独立的子代理执行koi-prd-story-loop和koi-prd-pipeline对应多代理编排机制- 文件系统上下文传递对应目标上下文注入
论文链接：https://arxiv.org/pdf/2508.08322v1
6.2 开源项目：Ralph
参考了 Ralph 项目的设计思想，特别是其"每次迭代=全新上下文"的核心理念。但Koi PRD技能套件在Ralph的基础上进行了重要超越。
通过结合学术论文的理论指导和Ralph项目的实践经验，Koi PRD技能套件形成了更适合 TRAE SOLO 平台的设计哲学和实现方式。
