cross-platform-products-ai-analyst/AGENT.md

Repository Guidelines

Repository Mode

本仓库采用“文档驱动 + 多 AI 交叉审阅 + 人工终审 + 审阅通过后再开发”的工作流。所有核心产品文档统一存放在 docs/，默认使用中文撰写；如无必要，不要中英文混写。

Required Documents

新产品默认必须产出以下文档，并按固定文件名维护：

• docs/RequirementsDoc.md
• docs/PRD.md
• docs/FeatureSummary.md
• docs/DevelopmentPlan.md
• docs/UIDesign.md
• docs/tdd.md
• docs/tasks.md

其中 docs/tasks.md 只负责任务拆解；项目进度、当前状态和阻塞统一维护在仓库根目录 TODO.md，不要继续写回 docs/tasks.md。

可选文档按需要补充：

• docs/Page_Design.md
• docs/User_Role_Interfaces.md
• docs/Responsive_Design.md

命名统一使用 RequirementsDoc.md，不要混写为 RequirementDoc.md。

Stage Workflow

每个阶段都必须先产出文档，再完成三方 AI 审阅，最后由人工终审。当前阶段未审完，不进入下一阶段。

1. 需求阶段：整理需求，产出 docs/RequirementsDoc.md。若使用 Claude Code，优先使用 AskUserQuestion 补齐需求缺口；其他代理也必须先澄清关键模糊点。
2. PRD 阶段：基于 docs/RequirementsDoc.md 产出 docs/PRD.md。若使用 Claude Code，此阶段必须开启 plan mode。
3. 功能阶段：基于 docs/PRD.md 产出 docs/FeatureSummary.md。
4. 开发规划阶段：基于 docs/PRD.md 与 docs/FeatureSummary.md 产出 docs/DevelopmentPlan.md，覆盖技术选型、开发周期、MVP 范围。
5. UI 设计阶段：基于 docs/PRD.md、docs/FeatureSummary.md、docs/DevelopmentPlan.md 产出 docs/UIDesign.md。优先使用 Gemini 3 Pro；若使用 Claude Code，则优先启用 frontend design skill。
6. TDD 阶段：基于 docs/PRD.md、docs/FeatureSummary.md、docs/DevelopmentPlan.md、docs/UIDesign.md 产出 docs/tdd.md。
7. 任务拆解阶段：基于 docs/PRD.md、docs/FeatureSummary.md、docs/DevelopmentPlan.md、docs/UIDesign.md、docs/tdd.md 产出 docs/tasks.md，只定义任务、依赖、验收和测试门禁。
8. 开发阶段：只有在上述文档全部完成并通过审阅后，才开始编码；开发推进中的任务状态、阶段快照和阻塞项统一维护在仓库根目录 TODO.md。优先使用 Claude Code Opus 4.5；若不可用，则由 Codex 接续执行。

Review Workflow

每份核心文档都必须经过 Claude、Gemini、Codex 三方审阅。三方审阅完成后，再由人工做一轮终审，确认是否进入下一阶段。

审阅文件建议独立保存，命名统一为：

• docs/review-<DocName>-claude.md
• docs/review-<DocName>-gemini.md
• docs/review-<DocName>-codex.md

审阅重点必须放在以下内容：

• 需求遗漏或前后矛盾
• 验收标准是否缺失
• 技术与实现风险是否明确
• 上下游文档是否闭环
• 是否存在无法执行或无法验证的描述

不要只做语气润色或表面改写。

Change Propagation

上游文档变更后，必须同步检查下游文档是否失效。例如 RequirementsDoc.md 更新后，必须重新检查 PRD.md、FeatureSummary.md、DevelopmentPlan.md、UIDesign.md、tdd.md、tasks.md 是否仍然一致；若影响任务编号、当前排期或阶段判断，也要同步更新 TODO.md。禁止只改上游、不处理影响面。

Agent Rules

在本仓库中，AI 代理不应跳过文档阶段直接写代码。即使用户要求尽快开发，也应先确认核心文档是否齐全。

对 Claude Code 的专属要求：

• 需求阶段优先使用 AskUserQuestion
• PRD 阶段开启 plan mode
• UI 设计阶段优先 frontend design skill

对 Gemini、Codex 等其他代理，执行同样的文档产出标准与评审门禁。

Frontend Verification

前端页面是否“正确”，不能只靠读代码或跑单测判断。只要修改了页面结构、交互流程、状态文案、路由跳转或 API 串联，代理都必须优先用 Playwright MCP 做一次真实页面核查，再决定是否宣称完成。

建议按以下顺序执行：

1. 先启动本地 API 和 Web 服务，再访问真实页面，不要只看静态文件。
2. 用 Playwright MCP 打开目标页面，至少调用一次页面快照和一次截图。
3. 先检查浏览器 console 与 network/请求结果，再检查视觉呈现；不要只看截图。
4. 对照 docs/PRD.md、docs/FeatureSummary.md、docs/DevelopmentPlan.md、docs/UIDesign.md、docs/tdd.md、docs/tasks.md 核对页面状态、按钮文案、空态、异常态和跳转是否一致。
5. 必须走一遍主流程，而不是只停留在入口页。对于本仓库，至少覆盖：/tasks/new、/tasks/:taskId/confirm、/tasks/:taskId/run、/tasks/:taskId/report、/history；若涉及会话或阻塞恢复，还要覆盖 /sessions/:platform/prepare 或 /tasks/:taskId/recovery/:platform。
6. 每次检查都要保存可回看的截图；如果发现问题，先记录触发路径、页面 URL、截图和报错，再修复。
7. 修复后必须重新用 Playwright MCP 复测同一路径，确认问题已经消失，而不是仅凭代码推断。

最低核查项如下：

• 页面能正常打开，没有白屏、报错弹窗或关键请求失败。
• 关键状态文案与状态色一致，例如 SearchBlocked、AwaitingConfirmation、Completed、PartialCompleted。
• 关键按钮可点击且跳转正确，例如创建任务、处理阻塞并重试、查看报告。
• 主流程数据真的更新到下一页，而不是停留在旧状态。
• console 中除开发环境常见噪音外，不应出现由当前改动引入的新错误。

如果代理没有实际调用 Playwright MCP 并查看截图，就不应声称“前端页面已经确认正确”。

Git Commit Rules

当用户要求提交代码时，代理应在确认变更范围和内容正确后，直接完成 git add / git commit，不要只停留在提示层。

提交信息规则如下：

• 必须使用中文描述
• 必须使用常见类型前缀：feat、fix、docs、chore、refactor、test、style、build、ci
• 推荐格式：<type>: <中文摘要>
• 一次提交只处理一个清晰主题，避免把文档、代码、重构、测试混在同一个提交里

示例：

• feat: 新增跨平台商品分析任务创建流程
• fix: 修复评论抓取分页状态丢失问题
• docs: 补充 PRD 验收标准与任务拆解约束
• chore: 调整本地开发配置与脚本入口

Pre-Commit Checklist

提交前至少确认以下事项：

• 变更是否与当前阶段目标一致
• 文档与代码是否仍然相互对应
• 是否遗漏下游文档或 TODO.md 进度同步
• 是否混入无关改动
• 提交信息是否符合中文 Conventional Commit 规范