opc-starter

Imported from alibaba/opc-starter (AGENTS.md). Install upstream with npx skills add alibaba/opc-starter. Copyright stays with the author.

OPC-Starter AI Coding 指南

一人公司启动器 AI 开发规范 | v2.0（目录式）

核心原则

1. 优先更新现有文档，不创建新文档
2. SQL 变更集中管理 → app/supabase/setup.sql
3. 操作文档更新 → app/supabase/SUPABASE_COOKBOOK.md

技术栈

React 19.1 · TypeScript 5.9 · Vite 7.1 · Tailwind CSS 4.1 · Supabase 2.80 · Zustand 5.0 · Qwen-Plus (百炼) · A2UI v0.8 · react-i18next

详细规范（按需加载）

技术文档（按需自动引入）

开发过程中涉及以下场景时，必须先读取对应文档再动手：

路由规则说明

1. AI 助手开发：涉及 ai-assistant、SSE 流、Agent Tool、renderUI、LLM 调用 → 先读 docs/API.md，工具注册还需参考 docs/Architecture.md 扩展指南。
2. UI 组件开发：新增或修改 UI 组件 → 先读 docs/DESIGN_TOKENS.md 确认设计语言，再按 docs/CONVENTIONS.md 命名和分层；涉及用户可见文案时读 .cursor/rules/i18n.md。
3. 页面/模块扩展：新增页面、路由、业务模块 → 先读 docs/Architecture.md、docs/CONVENTIONS.md 和 .cursor/rules/project-extension.md。
4. 数据库变更：任何 Schema、RLS、触发器、SQL 函数变更 → 先读 app/supabase/setup.sql 确认现状，操作步骤参考 app/supabase/SUPABASE_COOKBOOK.md。
5. 质量评估：代码健康度、技术债分析 → 读 docs/IHS.md 获取基线数据。
6. 规划与执行：优先更新既有 docs/exec-plans/、docs/Epics.yaml 或相关文档；确需新增文档时先确认是否已有合适承载位置。
7. BMAD 工作流：需求规划、Story 开发、代码审查 → 使用 .agents/skills/bmad-*（Cursor）或对应 IDE 的 skills 目录；不确定时先 invoke bmad-help。
8. 国际化（i18n）：新增或修改用户可见文案 → 先读 .cursor/rules/i18n.md，在 app/src/locales/zh-CN 与 en-US 同步维护 key；初始化见 app/src/lib/i18n.ts。
9. BMAD Builder（BMB）：自建 Agent / Module / Workflow → invoke bmad-agent-builder、bmad-module-builder 或 bmad-workflow-builder；产物默认写入仓库根目录 skills/。

BMAD Method（v6.10 Native Skills）

BMAD 已从旧版 YAML/XML 命令迁移为 Native Skills 架构（SKILL.md + TOML 配置）。

常用 Skills（BMM）：bmad-help、bmad-quick-dev、bmad-dev-story、bmad-code-review、bmad-sprint-planning

常用 Skills（BMB）：bmad-agent-builder、bmad-module-builder、bmad-workflow-builder、bmad-bmb-setup

产物目录（统一在 _bmad-output/，由 _bmad/custom/config.toml 锁定）：

升级命令（维护者）：

npx bmad-method@latest install --yes --action update --directory . \
  --tools cursor,claude-code,opencode,antigravity,kiro,qoder --modules bmm,bmb \
  --pin bmb=v1.5.0 \
  --user-name opc-starter --communication-language Chinese \
  --document-output-language Chinese --output-folder _bmad-output

注意：--modules 必须同时包含 bmm,bmb。仅安装 bmb 会移除 BMM skills。外部模块 bmb 在无 GITHUB_TOKEN 时 --all-stable 可能因 GitHub API 限流失败，请使用 --pin bmb=v1.5.0。

禁止事项

• ❌ 使用 Tailwind CSS v2/v3 语法（bg-opacity-*、bg-gradient-to-*）
• ❌ 直接操作 IndexedDB 或 Supabase（使用 DataService）
• ❌ 在 A2UI 中使用未注册的组件类型
• ❌ 直接调用 LLM API（通过 ai-assistant Edge Function）
• ❌ 创建独立 SQL 文件或新文档文件

Checks

在提交 Pull Request 之前，运行 /check 对 diff 执行 .continue/checks/*.md 中定义的 AI 审查。 所有 Check 必须通过，或由维护者明确确认后，才能创建 PR。

当前已配置的 Checks：

• 分层架构守卫 — 检查依赖方向违规和 UI 层直接导入 Supabase/IndexedDB
• 数据访问与 Agent 规范 — 检查是否绕过 Service/DataService 直接访问数据，以及 Agent/A2UI/LLM 调用是否遵守 starter 约定

后续可优化候选：

• E2E 选择器迁移 — Cypress 逐步改用 data-testid，减少对文案/i18n 的耦合

质量门禁

AI Agent 在 commit / push / PR 前必须跑完。Husky 仅 lint-staged，不跑单测/E2E/构建。

# PR 必过（根目录或 app/ 均可）
npm run lint:check && npm run type-check && npm run test && npm run build
npm run test:e2e:headless   # 改 UI / 文案 / i18n / 路由 / 认证时必跑

# 一键全量（format + coverage + build + E2E）
./scripts/quality_check.sh

• 用 lint:check，不要用 lint（PR Check 不带 --fix）
• npm test 必须全量，禁止只 --run 单个文件
• i18n 改动：同步 *.test.* / Cypress 断言，见 .cursor/rules/i18n.md
• PR 前跑 /check（.continue/checks/）

Cursor Cloud specific instructions

Project layout

All application code lives under app/.

• Prefer /workspace/app for low-level application work.
• /workspace/package.json exposes proxy scripts for AI tools that start at repo root, so npm run dev:test, npm run ai:check, and npm run test:e2e:headless also work from /workspace.

Running without Supabase (MSW mock mode)

The app can run fully locally without a real Supabase project by using MSW mocks:

1. Ensure app/.env.test exists with VITE_ENABLE_MSW=true (created automatically by the update script if missing).
2. npm run dev:test — starts Vite on port 5173 with MSW intercepting all Supabase API calls.
3. Test credentials are sourced from app/cypress/fixtures/users.json: test@example.com / 888888.

Gotchas

• The original package-lock.json referenced Alibaba's internal npm registry (registry.anpm.alibaba-inc.com), which is unreachable from Cloud VMs. If npm install fails with ECONNRESET errors from that registry, delete package-lock.json and node_modules, then run npm install --registry https://registry.npmjs.org/.
• The prepare script runs cd .. && husky app/.husky which installs git hooks from the repo root. This is expected and runs automatically during npm install.
• Lint command (npm run lint) applies --fix by default.

Key commands