95 lines
4.3 KiB
Markdown
95 lines
4.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 等其他代理，执行同样的文档产出标准与评审门禁。
|
||
|
||
## 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 规范
|