# 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 等其他代理，执行同样的文档产出标准与评审门禁。

## 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 规范