Auto Develop

OPC-Starter 智能开发技能

项目定位: OPC-Starter (一人公司启动器) 是一个 AI 亲和的 React Boilerplate，专为使用 Cursor、Qoder 等 AI Coding 工具的开发者设计。

核心理念: 像高级研发专家 Amelia 一样执行 —— 测试即规范，代码即实现，精准定位，无冗余输出。

🎯 动态上下文系统

上下文感知规则

根据任务类型自动加载相关文档和约束，避免无关信息干扰。

执行前自检

开始任务前，检测以下条件并动态加载规则：

context_check:
  - keyword_match: 检测任务描述关键词
  - file_scope: 检测涉及的文件路径
  - change_type: 判断是新功能/Bug修复/重构
  
auto_load:
  agent_module: "app/src/components/agent/**" | "app/src/lib/agent/**"
  ui_module: "app/src/components/**" | "app/src/pages/**"
  data_module: "app/src/services/data/**" | "app/supabase/**"
  test_module: "**/*.test.ts" | "**/*.spec.ts" | "cypress/**"

📊 项目核心架构

技术栈

目录结构

opc-starter/
├── app/                          # 主应用
│   ├── src/
│   │   ├── auth/                 # 认证模块
│   │   ├── components/
│   │   │   ├── agent/            # Agent Studio ⭐
│   │   │   │   └── a2ui/         # A2UI 渲染系统
│   │   │   ├── business/         # 业务组件
│   │   │   ├── layout/           # 布局组件
│   │   │   ├── organization/     # 组织架构
│   │   │   └── ui/               # 基础 UI (shadcn)
│   │   ├── pages/                # 页面组件
│   │   ├── services/
│   │   │   └── data/             # DataService (核心) ⭐
│   │   ├── stores/               # Zustand Store
│   │   ├── lib/
│   │   │   ├── agent/            # Agent 客户端 ⭐
│   │   │   │   └── tools/        # 前端工具执行器
│   │   │   └── supabase/         # Supabase 客户端
│   │   ├── hooks/                # 自定义 Hooks
│   │   ├── types/                # TypeScript 类型
│   │   └── mocks/                # MSW Mock
│   └── supabase/
│       ├── functions/
│       │   └── ai-assistant/    # Agent SSE 网关 ⭐
│       └── setup.sql             # 数据库脚本 (所有变更集中于此)
├── docs/
│   ├── Architecture.md           # 系统架构
│   └── Epics.yaml                # 项目进度
├── _bmad/                        # BMAD 方法论 (可选参考)
└── AGENTS.md                     # AI Coding 快速指南

核心能力模块

🔴🟢🔵 TDD 核心原则

红-绿-重构循环

┌─────────────────────────────────────────────────────────────┐
│                    TDD 循环 (每个功能点)                     │
│                                                             │
│     🔴 RED          🟢 GREEN         🔵 REFACTOR           │
│   ┌─────────┐     ┌─────────┐     ┌─────────┐              │
│   │ 写失败  │────▶│ 写最小  │────▶│ 优化    │──┐           │
│   │ 的测试  │     │ 实现代码 │     │ 重构    │  │           │
│   └─────────┘     └─────────┘     └─────────┘  │           │
│        ▲                                        │           │
│        └────────────────────────────────────────┘           │
│                    (下一个功能点)                            │
└─────────────────────────────────────────────────────────────┘

测试先行原则 ⚠️ MANDATORY

❌ 禁止：先写代码再补测试
❌ 禁止：提交没有测试覆盖的新功能
❌ 禁止：修改代码后不运行测试就提交

✅ 必须：新功能先写测试用例
✅ 必须：Bug 修复先写复现测试
✅ 必须：每次提交前运行完整测试套件

测试金字塔

🤖 Agent Studio 开发规范

当任务涉及 Agent 相关开发时，自动加载此章节。

架构流程

用户 ←→ AgentWindow (悬浮对话框)
           ↓
      useAgentChat Hook
           ↓
      SSE Client ←→ ai-assistant (Edge Function)
           ↓                    ↓
      Tool Executor         Qwen-Plus (百炼 API)
           ↓
      A2UI Renderer (动态 UI)

核心文件

添加新 Agent Tool

1. 后端: 在 ai-assistant/tools.ts 添加工具定义 (OpenAI 格式)
2. 前端: 在 app/src/lib/agent/tools/ 创建工具目录
3. 注册: 在 app/src/lib/agent/tools/registry.ts 注册
4. System Prompt: 在 ai-assistant/prompts/ 添加使用说明

// 工具定义示例 (OpenAI 格式)
{
  type: "function",
  function: {
    name: "myNewTool",
    description: "工具描述",
    parameters: {
      type: "object",
      properties: { /* ... */ },
      required: ["param1"],
    },
  },
}

添加新 A2UI 组件

1. 在 app/src/components/agent/a2ui/components/ 创建组件
2. 在 registry.ts 注册组件 (白名单模式)
3. 在 app/src/types/a2ui.ts 添加类型定义

// registry.ts 注册示例
export const A2UI_REGISTRY: A2UIComponentRegistry = {
  'my-component': MyComponent,
};

A2UI Action ID 规范

Mock LLM 测试

使用 MSW 模拟 Agent 响应：

// app/src/mocks/handlers/agentHandlers.ts
http.post('*/functions/v1/ai-assistant', async ({ request }) => {
  // 返回 SSE 流式响应
});

🎨 设计系统规范

当任务涉及 UI 组件开发时，自动加载此章节。

Tailwind CSS v4 语法 (Mandatory)

// ❌ 禁止：v2/v3 语法
className="bg-opacity-50 bg-gradient-to-r"

// ✅ 正确：v4 语法
className="bg-black/50 bg-linear-to-r"

语义化颜色 (暗色模式适配)

核心原则: 使用语义化颜色，禁止硬编码颜色值。

// ❌ 禁止：硬编码颜色
<div className="bg-white text-gray-900 border-gray-200">

// ✅ 正确：语义化颜色
<div className="bg-card text-foreground border">

移动端覆盖组件 ⚠️ CRITICAL

Sidebar、Modal、Dropdown 等覆盖层必须使用显式颜色 + dark: 前缀

// ❌ 错误：CSS 变量在移动端覆盖层可能失效
<aside className="bg-card text-foreground">

// ✅ 正确：显式颜色
<aside className="bg-white dark:bg-slate-900 text-gray-900 dark:text-gray-100">

💾 数据访问规范

DataService 统一访问

// ✅ 正确：通过 DataService 访问
import { dataService } from '@/services/data/DataService'
await dataService.getAll('profiles')

// ❌ 禁止：直接访问
import { supabase } from '@/lib/supabase/client'  // 禁止

数据流架构

┌─────────────────────────────────────────────────┐
│  UI Layer → Zustand Stores → DataService        │
│                                   │             │
│                    ┌──────────────┼──────────┐  │
│                    │         IndexedDB       │  │
│                    │    • 读: 100% 本地      │  │
│                    │    • 写: 乐观更新       │  │
│                    │    • 同步: Realtime     │  │
│                    └──────────────┼──────────┘  │
│                                   │             │
│                    ┌──────────────┼──────────┐  │
│                    │         Supabase        │  │
│                    │    • Postgres Changes   │  │
│                    └─────────────────────────┘  │
└─────────────────────────────────────────────────┘

SQL 变更集中管理

所有数据库变更 → app/supabase/setup.sql（禁止创建独立 SQL 文件）

🔌 Supabase MCP 操作规范

开发过程中对 Supabase 后端的状态读取和写入，默认使用 MCP 提供的 supabase 工具。

核心原则

1. 实时状态操作 → 使用 MCP mcp__supabase__* 系列工具
2. 持久化变更同步 → 所有结构性变更必须同步到 app/supabase/ 目录

MCP 工具使用场景

变更同步规范

┌────────────────────────────────────────────────────────────┐
│           Supabase 变更同步流程                             │
│                                                            │
│  MCP 执行变更 ──┬──▶ DDL (表/RLS/函数)                      │
│                │     └──▶ 同步到 app/supabase/setup.sql    │
│                │                                           │
│                └──▶ Edge Function 部署                     │
│                      └──▶ 同步到 app/supabase/functions/   │
└────────────────────────────────────────────────────────────┘

同步检查清单

示例工作流

# 1. 使用 MCP 查询当前表结构
mcp__supabase__list_columns(table_name="profiles")

# 2. 使用 MCP 执行 DDL 变更
mcp__supabase__execute_sql(sql="ALTER TABLE profiles ADD COLUMN bio TEXT;")

# 3. 将变更同步到 setup.sql (⚠️ 必须执行)
# 在 app/supabase/setup.sql 末尾追加:
# -- [2026-01-18] Add bio column to profiles
# ALTER TABLE profiles ADD COLUMN bio TEXT;

# 4. 如果涉及 Edge Function，同步到对应目录
# app/supabase/functions/ai-assistant/index.ts

禁止事项

❌ 使用 MCP 执行 DDL 后不同步到 setup.sql
❌ 直接修改 setup.sql 而不通过 MCP 验证执行
❌ 创建独立的 SQL 迁移文件
❌ Edge Function 仅部署不同步代码

🐛 Bug 修复规范

当任务为 Bug 修复时，自动加载此章节。

核心原则：先查数据，再改代码

发现问题 → 浏览器调试验证 → 定位根因 → 一次性修复 → 验证通过

调试步骤

1. 使用浏览器 DevTools

   • Network 面板：检查 API 请求和响应数据
   • Console 面板：查看日志和错误信息

2. 添加临时调试日志

   console.log('[Debug] 数据状态:', JSON.stringify(data, null, 2));
   

3. 常见数据完整性问题

防御性编码

// ❌ 假设数据一定有效
const coverUrl = await getPhotoUrl(album.photoIds[0]);

// ✅ 遍历找到第一个有效项
for (const photoId of album.photoIds) {
  const url = photoUrlMap.get(photoId);
  if (url) {
    album.coverPhotoUrl = url;
    break;
  }
}

✅ 开发工作流

完整流程

需求/Bug → BMAD 方案讨论(可选) → Epic/Story/Task → 🔴测试先行 → 🟢代码实现 → 🔵重构优化 → 质量验证 → 人工审查 → 上线

Phase 1: TDD 测试先行 🔴

npm run test:watch    # 监听模式（开发时）

测试文件命名: *.test.ts 或 *.spec.ts，与源文件同目录

// app/src/services/example.test.ts
import { describe, it, expect, vi } from 'vitest'

describe('ExampleService', () => {
  it('应该完成预期功能', async () => {
    // Arrange - 准备测试数据
    // Act - 执行待测函数
    // Assert - 验证结果
  })
})

Phase 2: 代码实现 🟢

遵循技术约束完成代码实现。详见 references/coding-constraints.md。

Phase 3: 重构优化 🔵

✅ 测试全部通过后再重构
✅ 每次小步重构后运行测试
✅ 提取公共方法、消除重复

❌ 不要在重构时添加新功能

Phase 4: 质量验证

# 一键质量验证
./scripts/quality_check.sh

# 核心校验（不含 E2E）
npm run ai:check

# 或手动执行
npm run lint:check        # ESLint 检查
npm run format:check      # Prettier 格式检查
npm run type-check        # TypeScript 类型检查
npm run test              # 单元测试
npm run test:e2e:headless # E2E 回归测试
npm run build             # 构建验证

🚫 禁止清单

编码禁止

TDD 禁止

📚 参考文档

按需加载

外部文档

BMAD 方法论参考 (可选)

当需要规范化需求分析、方案设计时，可参考 BMAD 工作流：

🚀 快速命令

# 开发
npm run dev           # 启动开发服务器
npm run dev:test      # 测试模式 (MSW mock)

# TDD 测试
npm run test          # 运行单元测试
npm run test:watch    # 监听模式（开发时推荐）
npm run coverage      # 生成覆盖率报告

# E2E 测试
npm run cypress:open  # 在已启动 dev:test 时交互运行 Cypress
npm run test:e2e      # 启动 dev:test 后无头运行 E2E
npm run test:e2e:headless  # Cypress 无头模式 (CI)

# 质量检查
npm run lint          # ESLint 检查并修复
npm run format        # Prettier 格式化
npm run type-check    # TypeScript 类型检查
npm run build         # 生产构建

# 一键质量验证
npm run ai:check
./scripts/quality_check.sh

推荐工作流

# 1. 启动测试监听（新终端窗口）
npm run test:watch

# 2. 启动开发服务器（另一个终端窗口）
npm run dev:test

# 3. 🔴 编写测试 → 看到红色失败
# 4. 🟢 实现代码 → 看到绿色通过
# 5. 🔵 重构优化
# 6. 提交前运行完整质量检查
./scripts/quality_check.sh