118 lines
6.3 KiB
Markdown
118 lines
6.3 KiB
Markdown
# 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/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. 开发阶段：只有在上述文档全部完成并通过审阅后，才开始编码。优先使用 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` 是否仍然一致。禁止只改上游、不处理影响面。
|
||
|
||
## 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
|
||
提交前至少确认以下事项：
|
||
|
||
- 变更是否与当前阶段目标一致
|
||
- 文档与代码是否仍然相互对应
|
||
- 是否遗漏下游文档同步
|
||
- 是否混入无关改动
|
||
- 提交信息是否符合中文 Conventional Commit 规范
|