# RetailOps Agent Prompt System Review

> 建议文件路径：`docs/prompts/prompt_system_review.md`  
> 适用项目：RetailOps Agent / 3C 门店经营 AI Agent  
> 文档目的：总结本项目 Codex prompt 链路的结构、优点、问题与后续优化规范，作为项目 Prompt Engineering 能力证明材料。

---

## 1. 总体结论

本项目的 prompt 链路已经具备比较成熟的“产品经理驱动 Codex 开发”特征：  
它不是简单让 Codex 写代码，而是用分阶段 prompt 把一个 AI 产品作品集项目从机会发现、问题验证、立项、产品定义、PRD、研发准备、MVP 开发、测试、发布、长期规划、部署、作品集包装、个人主页接入一路推进。

整体判断：

```text
当前 prompt 系统已经可用，而且项目控制力较强；
后续优化重点不是推翻重写，而是把 prompt 从“长指令驱动”升级为“标准化项目工作流驱动”。
```

---

## 2. 当前 prompt 链路的主要优点

### 2.1 生命周期推进清晰

项目从阶段 0 到阶段 12 分层推进，覆盖：

- 机会发现
- 问题验证
- 产品立项
- 产品定义
- PRD 与方案设计
- 研发准备
- MVP 开发与测试
- 上线发布
- 运营增长规划
- 数据迭代规划
- 商业化规划
- 成熟期管理
- 退市 / 下线规划
- 部署与个人主页展示

这让项目看起来不像一个单纯前端 Demo，而是一个完整 AI 产品经理作品集项目。

### 2.2 范围边界控制很好

prompt 中持续强调：

- 不伪造真实用户访谈
- 不伪造真实运营数据
- 不伪造真实收入数据
- 不接真实 LLM
- 不接真实门店系统
- 不扩大 MVP 范围
- 阶段 8–12 只能作为长期规划

这是非常重要的优点。它能避免作品集项目看起来“夸大”“虚假”“不可信”。

### 2.3 每一步都有明确交付物

每个 step 基本都说明：

- 本轮目标
- 本轮边界
- 要创建 / 修改的文件
- 每个文件的内容结构
- 验收标准
- development_log 更新要求
- acceptance_checklist 更新要求
- 最终输出要求

这让 Codex 更容易执行，也让项目更容易复盘。

### 2.4 文档与代码节奏分离较好

前 1–7 步主要做文档和研发准备，8–9 步再进入 MVP 开发，10 步以后做发布、包装、长期规划和主页接入。这个顺序合理，符合产品经理从“定义问题”到“落地 Demo”的真实工作方式。

### 2.5 有很强的作品集意识

prompt 不只要求功能实现，还要求：

- README
- Demo Guide
- FAQ
- Release Notes
- 简历描述
- 面试讲述稿
- 个人主页展示内容
- 截图采集
- 项目收口记录

这使项目最终更容易进入简历、主页和面试表达。

---

## 3. 当前 prompt 可以优化的地方

### 3.1 上下文重复过多

很多 step 都重复写项目名称、项目定位、已完成阶段、禁止事项、输出要求。这样做虽然安全，但会带来三个问题：

1. prompt 过长，Codex 注意力容易被稀释；
2. 每次复制成本高；
3. 后期维护困难，某个边界修改时要改很多 prompt。

建议把重复内容沉淀为固定文档：

```text
docs/prompts/project_context.md
docs/prompts/global_constraints.md
docs/prompts/codex_workflow_rules.md
```

后续 prompt 只需要引用：

```text
请先阅读 docs/prompts/project_context.md、global_constraints.md、codex_workflow_rules.md，再执行本轮任务。
```

### 3.2 缺少“执行前检查协议”

现有 prompt 通常直接要求创建或修改文件，但没有强制 Codex 先检查当前项目状态。

建议每个 Codex prompt 开头加入：

```text
执行前必须先完成：
1. 查看当前目录结构；
2. 读取本轮相关已有文件；
3. 查看 git status；
4. 判断哪些文件已存在，哪些文件需要新增；
5. 不得覆盖已有有效内容，只能在保留基础上扩写或修正；
6. 如果发现实际项目状态与 prompt 描述不一致，先记录差异，再按实际状态谨慎执行。
```

这样可以减少误删、重复创建、覆盖旧内容的问题。

### 3.3 验收标准还可以更机器化

现在的验收标准多数是“某文件已创建”“某内容已完成”。这很好，但还不够机器化。

建议开发阶段加入具体命令：

```text
npm run build
npm run lint
npm run typecheck
npm run test
```

并要求 Codex 在最终输出中写清楚：

```text
已运行命令：
- npm run build：通过 / 失败
- npm run lint：通过 / 失败 / 未配置
- npm run typecheck：通过 / 失败 / 未配置
- npm run test：通过 / 失败 / 未配置

如失败，必须说明失败原因，不得写“已完成”。
```

### 3.4 缺少统一的“失败处理协议”

后期 step17.1 已经出现过写入权限或用量限制导致无法完成的情况。后续 prompt 应该把这种规则前置。

建议加入：

```text
如果因为权限、路径、依赖、网络、Token、CLI 登录状态或工具限制导致无法完成：
1. 不要绕过权限；
2. 不要伪造完成；
3. 停止相关写入或部署动作；
4. 记录失败原因；
5. 写出已经完成的部分；
6. 写出用户需要手动执行的命令；
7. 在 development_log 和 acceptance_checklist 中标记为部分完成。
```

### 3.5 缺少统一的“文件改动原则”

现有 prompt 已经要求“保留合理内容”，但可以更严格。

建议统一为：

```text
文件改动原则：
1. 不删除已有有效内容；
2. 不重写无关文件；
3. 不改动本轮范围外功能；
4. 不创建重复文件；
5. 不移动目录，除非本轮明确要求；
6. 修改后列出 changed files；
7. 如果某文件已有内容，优先追加“本轮更新”或结构化扩写。
```

### 3.6 文档阶段容易写得过满

前期 prompt 对每个文档的结构要求非常详细，这保证了完整度，但也容易让 Codex 生成大量“标准话术型文档”。后续可以要求更多“判断、取舍、证据边界”。

建议在文档类 prompt 中增加：

```text
每份文档必须包含：
1. 本阶段最重要的 3 个判断；
2. 本阶段不确定的 3 个问题；
3. 本阶段进入下一阶段的依据；
4. 本阶段不能声称已经验证的内容；
5. 后续需要真实验证的数据或用户反馈。
```

### 3.7 代码阶段需要更强的架构约束

MVP 开发 prompt 已经指定技术栈，但可以进一步明确：

- 目录结构
- 组件拆分原则
- 数据类型定义
- Agent 层与 UI 层分离
- Mock / Rules 逻辑位置
- 复用组件
- 不允许把复杂逻辑写死在页面组件里

建议加入：

```text
代码架构要求：
1. 页面负责展示和交互；
2. Agent 逻辑放在 src/agents；
3. 数据读取和处理放在 src/utils 或 src/services；
4. 类型定义放在 src/types；
5. 样例数据放在 src/data 或 public/data；
6. 通用 UI 组件放在 src/components；
7. 页面组件不直接写复杂规则；
8. 所有 Mock / Rules 输出必须可解释、可质检。
```

### 3.8 UI 验收可以更具体

当前有页面清单，但缺少统一 UI 标准。

建议补充：

```text
UI 验收标准：
1. 首页 10 秒内能讲清项目是什么；
2. 每个页面都有标题、说明、核心操作和结果区域；
3. 所有样例数据必须标注为 sample / mock；
4. AI 输出区域必须显示来源、风险提示或质检结果；
5. 1440 / 1024 / 768 / 390 宽度下无明显布局破坏；
6. 空状态、错误状态、加载状态至少有基础展示；
7. 不使用夸大商业成功的文案。
```

### 3.9 部署阶段需要更明确的环境判断

部署相关 prompt 可以增加：

```text
部署前先检查：
1. 当前是否已登录目标平台 CLI；
2. 是否存在必要 Token；
3. 是否能运行 build；
4. 是否存在 dist / build 输出目录；
5. 是否有 _redirects 或 SPA 路由 fallback；
6. 是否能直接访问子路径；
7. 如果无法部署，输出手动部署步骤，不要声称部署成功。
```

### 3.10 缺少 prompt 自身版本管理

项目已经有大量 prompt，但如果不整理，后期很难回看“为什么这么做”。

建议新增：

```text
docs/prompts/prompt_index.md
docs/prompts/prompt_system_review.md
docs/prompts/prompt_quality_checklist.md
docs/prompts/codex_prompt_template.md
```

---

## 4. 建议采用的新 prompt 标准

后续每个 Codex prompt 都可以统一成以下结构：

```text
1. 项目上下文
2. 当前状态
3. 本轮目标
4. 执行前检查
5. 本轮允许做什么
6. 本轮禁止做什么
7. 需要新增 / 修改的文件
8. 每个文件的内容要求
9. 代码 / 文档实现规则
10. 验收命令
11. development_log 更新要求
12. acceptance_checklist 更新要求
13. 失败处理协议
14. 最终输出格式
15. 是否可以进入下一轮的判断
```

可以总结为：

```text
高效 Codex Prompt = 目标 + 范围 + 流程 + 结果 + 验收 + 失败处理
```

---

## 5. 可复用 Codex Prompt 模板

后续可以把下面模板保存为：

```text
docs/prompts/codex_prompt_template.md
```

### 模板正文

```text
你现在继续执行 RetailOps Agent 项目。

请先阅读并遵守：
1. docs/prompts/project_context.md
2. docs/prompts/global_constraints.md
3. docs/prompts/codex_workflow_rules.md
4. docs/development_log.md
5. docs/acceptance_checklist.md

当前阶段：
【填写当前 step / 阶段名称】

本轮目标：
【用 3–5 句话写清楚本轮要完成什么】

---

# 一、执行前检查

在修改任何文件前，必须先完成：

1. 查看当前目录结构；
2. 查看 git status；
3. 读取本轮相关已有文件；
4. 判断文件是新增、扩写、修正还是不需要改；
5. 如果项目实际状态与本 prompt 描述不一致，先以实际状态为准，并在日志中记录差异。

---

# 二、本轮允许范围

本轮只允许：

1. 【允许事项 1】
2. 【允许事项 2】
3. 【允许事项 3】

---

# 三、本轮禁止范围

本轮禁止：

1. 不修改本轮范围外功能；
2. 不删除已有有效内容；
3. 不伪造真实用户访谈；
4. 不伪造真实运营数据；
5. 不伪造真实收入数据；
6. 不接真实 LLM，除非本轮明确要求；
7. 不接真实门店系统；
8. 不为了通过验收而隐藏错误。

---

# 四、需要新增 / 修改的文件

请处理以下文件：

```text
【文件路径 1】
【文件路径 2】
【文件路径 3】
```

处理原则：

1. 文件不存在则创建；
2. 文件存在则保留有效内容并结构化扩写；
3. 不创建重复文件；
4. 不移动目录；
5. 不改无关文件。

---

# 五、具体内容要求

## 1. 【文件路径 1】

必须包含：

- 【要求 1】
- 【要求 2】
- 【要求 3】

## 2. 【文件路径 2】

必须包含：

- 【要求 1】
- 【要求 2】
- 【要求 3】

---

# 六、质量与验收

本轮完成后必须运行或检查：

```bash
【命令 1】
【命令 2】
【命令 3】
```

如果命令不存在或无法运行，必须说明原因，不得写成通过。

---

# 七、日志与验收清单

请更新：

```text
docs/development_log.md
docs/acceptance_checklist.md
```

development_log 必须记录：

1. 当前轮次；
2. 当前阶段；
3. 本轮目标；
4. 新增 / 修改文件；
5. 已完成内容；
6. 未完成内容；
7. 验收命令结果；
8. 下一轮建议。

acceptance_checklist 必须记录：

1. 本轮验收项；
2. 已完成项标记为 [x]；
3. 未完成项标记为 [ ]；
4. 如果部分完成，说明原因。

---

# 八、失败处理协议

如果遇到权限、依赖、网络、Token、CLI 登录、构建失败、路径不存在等问题：

1. 停止相关高风险动作；
2. 不绕过权限；
3. 不伪造完成；
4. 记录已完成内容；
5. 记录失败原因；
6. 给出用户可手动执行的命令；
7. 在 development_log 和 acceptance_checklist 中标记为部分完成。

---

# 九、最终输出要求

完成后请告诉我：

1. 本轮修改了哪些文件；
2. 本轮新增了哪些文件；
3. 本轮完成了什么；
4. 本轮没有做什么；
5. 运行了哪些命令，结果是什么；
6. 是否有失败、warning 或 vulnerability；
7. 如何验收；
8. 是否建议进入下一轮；
9. 下一轮建议做什么。
```

---

## 6. 建议新增的 prompt 管理文件

建议在项目中新增以下文件：

```text
docs/prompts/prompt_index.md
docs/prompts/prompt_system_review.md
docs/prompts/prompt_quality_checklist.md
docs/prompts/codex_prompt_template.md
docs/prompts/failure_protocol.md
```

### 6.1 docs/prompts/prompt_index.md

用途：

- 记录 step1 到 step17.2 每个 prompt 的目标；
- 记录每一步对应的项目阶段；
- 记录主要产出；
- 记录是否属于文档、开发、部署、作品集包装、个人主页接入。

### 6.2 docs/prompts/prompt_system_review.md

用途：

- 总结本项目 prompt 设计方法；
- 展示项目如何用 Codex 推进完整 AI 产品作品集；
- 作为作品集中的 Prompt Engineering 能力证明。

### 6.3 docs/prompts/prompt_quality_checklist.md

用途：

- 后续写新 prompt 前自查；
- 防止范围失控；
- 防止 Codex 误改；
- 防止没有验收就进入下一步。

### 6.4 docs/prompts/codex_prompt_template.md

用途：

- 保存统一 Codex prompt 模板；
- 后续所有项目都可以复用。

### 6.5 docs/prompts/failure_protocol.md

用途：

- 记录权限、部署、构建、Token、路径等失败时的处理规则；
- 避免“没完成却写完整完成”。

---

## 7. Prompt 质量自查清单

后续每写一个 prompt，可以用下面清单检查：

```text
[ ] 是否写清楚本轮目标？
[ ] 是否写清楚当前阶段？
[ ] 是否写清楚允许范围？
[ ] 是否写清楚禁止范围？
[ ] 是否要求先检查当前项目状态？
[ ] 是否列出要新增 / 修改的文件？
[ ] 是否说明文件存在时如何处理？
[ ] 是否要求保留已有有效内容？
[ ] 是否明确不伪造真实数据 / 访谈 / 收入？
[ ] 是否明确不接真实 LLM / API / 门店系统？
[ ] 是否有 development_log 更新要求？
[ ] 是否有 acceptance_checklist 更新要求？
[ ] 是否有构建 / 测试 / 检查命令？
[ ] 是否要求记录 warning、vulnerability 或失败？
[ ] 是否有失败处理协议？
[ ] 是否要求最终输出 changed files？
[ ] 是否要求判断是否进入下一轮？
```

---

## 8. 分阶段优化建议

### 文档阶段

重点优化：

- 减少重复背景；
- 增加判断与取舍；
- 明确哪些是假设，哪些是事实，哪些待验证；
- 不要把规划写成成果。

### 开发阶段

重点优化：

- 强制执行前检查；
- 强制架构分层；
- 强制构建检查；
- 强制记录 warning / vulnerability；
- 强制避免无关改动。

### 部署阶段

重点优化：

- 检查 CLI 登录状态；
- 检查 Token；
- 检查 build 输出；
- 检查 SPA 子路由；
- 部署失败要写失败原因和手动步骤。

### 个人主页接入阶段

重点优化：

- 不修改源项目业务功能；
- 不破坏原有主页内容；
- 检查原有项目详情页；
- 检查移动端；
- 检查截图资源；
- 检查构建前 dist 清理；
- 明确是否具备最终部署条件。

---

## 9. 最终评价

本项目的 prompt 最大价值在于：

```text
它把 Codex 当成“项目执行者”，而不是单纯的“代码生成器”。
```

这套 prompt 已经体现出 AI 产品经理需要具备的几项能力：

1. 把大目标拆成阶段；
2. 把阶段拆成交付物；
3. 给 AI 明确边界；
4. 控制虚假成果风险；
5. 让文档、代码、测试、发布、作品集表达形成闭环；
6. 用验收清单管理项目推进。

后续只需要把 prompt 从“每次写一大段完整指令”升级为“项目上下文文档 + 标准模板 + 本轮差异指令”，整个工作流会更稳定、更专业，也更适合展示在个人主页和面试中。