AGENTS.md

1# OPC-Starter AI Coding 指南
2 
3> 一人公司启动器 AI 开发规范 | v2.0（目录式）
4 
5## 核心原则
6 
71. **优先更新现有文档**，不创建新文档
82. **SQL 变更集中管理** → `app/supabase/setup.sql`
93. **操作文档更新** → `app/supabase/SUPABASE_COOKBOOK.md`
10 
11## 技术栈
12 
13React 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
14 
15## 详细规范（按需加载）
16 
17| 规范                 | 文件                                 | 自动触发                                       |
18| -------------------- | ------------------------------------ | ---------------------------------------------- |
19| TypeScript 严格类型  | `.cursor/rules/typescript-strict.md` | `*.ts, *.tsx`                                  |
20| Tailwind CSS v4 语法 | `.cursor/rules/tailwind-v4.md`       | `*.tsx, *.css`                                 |
21| Agent Studio 开发    | `.cursor/rules/agent-studio.md`      | `agent/**/*`                                   |
22| Supabase 数据模式    | `.cursor/rules/supabase-patterns.md` | `services/**/*`                                |
23| 测试规范             | `.cursor/rules/testing.md`           | `*.test.*`                                     |
24| 项目扩展指南         | `.cursor/rules/project-extension.md` | `pages/**/*`                                   |
25| i18n 国际化          | `.cursor/rules/i18n.md`              | `locales/**/*`、用户可见文案、`useTranslation` |
26 
27## 技术文档（按需自动引入）
28 
29开发过程中涉及以下场景时，**必须**先读取对应文档再动手：
30 
31| 文档                                | 用途                             | 自动触发（涉及场景关键词）                            |
32| ----------------------------------- | -------------------------------- | ----------------------------------------------------- |
33| `docs/API.md`                       | AI Assistant API 接口            | `ai-assistant`、SSE、Agent 工具、`renderUI`、LLM 调用 |
34| `docs/Architecture.md`              | 系统架构与模块关系               | 新模块设计、分层架构、核心模块职责、扩展指南          |
35| `docs/CONVENTIONS.md`               | 编码规范（命名、分层、错误处理） | 文件命名、分层依赖、TypeScript 规范、权限约定         |
36| `docs/DESIGN_TOKENS.md`             | 设计令牌规范                     | 颜色系统、字体、圆角、阴影、Tailwind Token、UI 风格   |
37| `docs/Epics.yaml`                   | 项目进度                         | 项目进度、Story 拆解、版本规划、Epic 状态             |
38| `docs/IHS.md`                       | 仓库驾驭健康报告                 | 代码质量评估、技术债、测试覆盖率、代码腐化度          |
39| `docs/exec-plans/`                  | 历史执行计划                     | 在途计划收尾、历史方案参考                            |
40| `_bmad-output/`                     | BMAD 工作流产物                  | PRD、Epic/Story、Sprint 状态、Quick Dev spec          |
41| `_bmad-output/README.md`            | BMAD 产物索引与命名约定          | 产物路径、与 `docs/` 的分工                           |
42| `app/supabase/SUPABASE_COOKBOOK.md` | 数据库操作手册                   | 表结构变更、RLS 策略、SQL 函数、数据库迁移            |
43| `app/supabase/setup.sql`            | 数据库 Schema 事实源             | 建表、加字段、RLS、触发器、profiles 等表              |
44| `app/src/locales/`                  | 前端 i18n 文案事实源             | 多语言、locale、翻译、`useTranslation`、用户可见文案  |
45 
46### 路由规则说明
47 
481. **AI 助手开发**：涉及 `ai-assistant`、SSE 流、Agent Tool、`renderUI`、LLM 调用 → 先读 `docs/API.md`，工具注册还需参考 `docs/Architecture.md` 扩展指南。
492. **UI 组件开发**：新增或修改 UI 组件 → 先读 `docs/DESIGN_TOKENS.md` 确认设计语言，再按 `docs/CONVENTIONS.md` 命名和分层；涉及用户可见文案时读 `.cursor/rules/i18n.md`。
503. **页面/模块扩展**：新增页面、路由、业务模块 → 先读 `docs/Architecture.md`、`docs/CONVENTIONS.md` 和 `.cursor/rules/project-extension.md`。
514. **数据库变更**：任何 Schema、RLS、触发器、SQL 函数变更 → 先读 `app/supabase/setup.sql` 确认现状，操作步骤参考 `app/supabase/SUPABASE_COOKBOOK.md`。
525. **质量评估**：代码健康度、技术债分析 → 读 `docs/IHS.md` 获取基线数据。
536. **规划与执行**：优先更新既有 `docs/exec-plans/`、`docs/Epics.yaml` 或相关文档；确需新增文档时先确认是否已有合适承载位置。
547. **BMAD 工作流**：需求规划、Story 开发、代码审查 → 使用 `.agents/skills/bmad-*`（Cursor）或对应 IDE 的 skills 目录；不确定时先 invoke `bmad-help`。
558. **国际化（i18n）**：新增或修改用户可见文案 → 先读 `.cursor/rules/i18n.md`，在 `app/src/locales/zh-CN` 与 `en-US` 同步维护 key；初始化见 `app/src/lib/i18n.ts`。
569. **BMAD Builder（BMB）**：自建 Agent / Module / Workflow → invoke `bmad-agent-builder`、`bmad-module-builder` 或 `bmad-workflow-builder`；产物默认写入仓库根目录 `skills/`。
57 
58## BMAD Method（v6.10 Native Skills）
59 
60BMAD 已从旧版 YAML/XML 命令迁移为 **Native Skills** 架构（`SKILL.md` + TOML 配置）。
61 
62| 模块 | 版本   | 用途                              |
63| ---- | ------ | --------------------------------- |
64| core | 6.10.0 | 共享脚本、配置解析                |
65| bmm  | 6.10.0 | 需求、Story、审查、Quick Dev      |
66| bmb  | v1.5.0 | Agent / Module / Workflow Builder |
67 
68| 项                         | 路径                       |
69| -------------------------- | -------------------------- |
70| 主配置（安装器管理，只读） | `_bmad/config.toml`        |
71| 团队定制覆盖               | `_bmad/custom/config.toml` |
72| BMB 模块配置               | `_bmad/bmb/config.yaml`    |
73| Cursor / OpenCode Skills   | `.agents/skills/bmad-*`    |
74| Claude Code Skills         | `.claude/skills/bmad-*`    |
75| Antigravity Skills         | `.agent/skills/bmad-*`     |
76| Kiro Skills                | `.kiro/skills/bmad-*`      |
77| Qoder Skills               | `.qoder/skills/bmad-*`     |
78 
79常用 Skills（BMM）：`bmad-help`、`bmad-quick-dev`、`bmad-dev-story`、`bmad-code-review`、`bmad-sprint-planning`
80 
81常用 Skills（BMB）：`bmad-agent-builder`、`bmad-module-builder`、`bmad-workflow-builder`、`bmad-bmb-setup`
82 
83产物目录（统一在 `_bmad-output/`，由 `_bmad/custom/config.toml` 锁定）：
84 
85| 子目录                      | 典型内容                              |
86| --------------------------- | ------------------------------------- |
87| `planning-artifacts/`       | PRD、architecture.md、epics.md        |
88| `implementation-artifacts/` | sprint-status.yaml、Story 文件、Retro |
89| `specs/`                    | Quick Dev 独立 spec                   |
90| 根目录                      | `project-context.md` 等               |
91 
92升级命令（维护者）：
93 
94```bash
95npx bmad-method@latest install --yes --action update --directory . \
96  --tools cursor,claude-code,opencode,antigravity,kiro,qoder --modules bmm,bmb \
97  --pin bmb=v1.5.0 \
98  --user-name opc-starter --communication-language Chinese \
99  --document-output-language Chinese --output-folder _bmad-output
100```
101 
102> **注意**：`--modules` 必须同时包含 `bmm,bmb`。仅安装 `bmb` 会移除 BMM skills。外部模块 `bmb` 在无 `GITHUB_TOKEN` 时 `--all-stable` 可能因 GitHub API 限流失败，请使用 `--pin bmb=v1.5.0`。
103 
104## 禁止事项
105 
106- ❌ 使用 Tailwind CSS v2/v3 语法（`bg-opacity-*`、`bg-gradient-to-*`）
107- ❌ 直接操作 IndexedDB 或 Supabase（使用 DataService）
108- ❌ 在 A2UI 中使用未注册的组件类型
109- ❌ 直接调用 LLM API（通过 ai-assistant Edge Function）
110- ❌ 创建独立 SQL 文件或新文档文件
111 
112## Checks
113 
114在提交 Pull Request 之前，运行 `/check` 对 diff 执行 `.continue/checks/*.md` 中定义的 AI 审查。
115所有 Check 必须通过，或由维护者明确确认后，才能创建 PR。
116 
117当前已配置的 Checks：
118 
119- **分层架构守卫** — 检查依赖方向违规和 UI 层直接导入 Supabase/IndexedDB
120- **数据访问与 Agent 规范** — 检查是否绕过 Service/DataService 直接访问数据，以及 Agent/A2UI/LLM 调用是否遵守 starter 约定
121 
122后续可优化候选：
123 
124- **E2E 选择器迁移** — Cypress 逐步改用 `data-testid`，减少对文案/i18n 的耦合
125 
126## 质量门禁
127 
128AI Agent 在 commit / push / PR 前必须跑完。**Husky 仅 lint-staged，不跑单测/E2E/构建。**
129 
130```bash
131# PR 必过（根目录或 app/ 均可）
132npm run lint:check && npm run type-check && npm run test && npm run build
133npm run test:e2e:headless   # 改 UI / 文案 / i18n / 路由 / 认证时必跑
134 
135# 一键全量（format + coverage + build + E2E）
136./scripts/quality_check.sh
137```
138 
139- 用 `lint:check`，不要用 `lint`（PR Check 不带 `--fix`）
140- `npm test` 必须**全量**，禁止只 `--run` 单个文件
141- i18n 改动：同步 `*.test.*` / Cypress 断言，见 `.cursor/rules/i18n.md`
142- PR 前跑 `/check`（`.continue/checks/`）
143 
144## Cursor Cloud specific instructions
145 
146### Project layout
147 
148All application code lives under `app/`.
149 
150- Prefer `/workspace/app` for low-level application work.
151- `/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`.
152 
153### Running without Supabase (MSW mock mode)
154 
155The app can run fully locally without a real Supabase project by using MSW mocks:
156 
1571. Ensure `app/.env.test` exists with `VITE_ENABLE_MSW=true` (created automatically by the update script if missing).
1582. `npm run dev:test` — starts Vite on port **5173** with MSW intercepting all Supabase API calls.
1593. Test credentials are sourced from `app/cypress/fixtures/users.json`: `test@example.com` / `888888`.
160 
161### Gotchas
162 
163- 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/`.
164- 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`.
165- Lint command (`npm run lint`) applies `--fix` by default.
166 
167### Key commands
168 
169| Task                       | Command                      |
170| -------------------------- | ---------------------------- |
171| Dev server (mock)          | `npm run dev:test`           |
172| Dev server (real Supabase) | `npm run dev`                |
173| Lint                       | `npm run lint`               |
174| Type check                 | `npm run type-check`         |
175| Unit tests                 | `npm test`                   |
176| E2E tests                  | `npm run test:e2e:headless`  |
177| Core AI checks             | `npm run ai:check`           |
178| Full quality check         | `./scripts/quality_check.sh` |
179| Build                      | `npm run build`              |
180