wangjia
d6397083c0
UI 设计师 Agent (.claude/agents/ui-designer.md): - 自动判断设计复杂度 - 简单变更：直接输出文字规范，flutter-coder 立即实现 - 复杂设计：输出 Figma 设计需求文档并暂停，等用户确认设计稿 - 包含完整视觉规范（颜色、字体、间距、状态标签） Figma MCP 配置 (.mcp.json): - 接入 Figma 官方 MCP Server (https://mcp.figma.com/mcp) - 支持读取设计文件、组件、Token Skills (.claude/skills/): - /archive-design：将确认上线的设计存档到 docs/design/archive/ 含 Figma 链接、设计决策、组件清单、版本历史 - /design-review：对比 Figma 设计稿与 Flutter 实现，输出还原度报告 标注颜色/间距/布局差异，分必须修复和建议调整两级 更新 CLAUDE.md： - 工作流中加入 ui-designer（架构后、编码前） - 上线前运行 /design-review，上线后运行 /archive-design Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
172 lines
4.9 KiB
Markdown
172 lines
4.9 KiB
Markdown
# 酒店仓库管理系统 — 项目规则与 Orchestrator
|
||
|
||
## 必读
|
||
|
||
**开始任何任务前，先读 `docs/context/project.md`** 了解项目全貌。
|
||
|
||
---
|
||
|
||
## Orchestrator：如何自动选择 Agent
|
||
|
||
根据用户请求的关键词和意图，按以下规则判断调用哪些 Agent：
|
||
|
||
### 新功能开发（完整流水线）
|
||
|
||
触发词：「新增」「开发」「实现」「做一个」+ 功能描述
|
||
|
||
```
|
||
串行：requirements-analyst → architect
|
||
并行：api-designer + db-designer（同时进行，都依赖架构但互不依赖）
|
||
|
||
→ ui-designer 判断复杂度：
|
||
简单变更：直接输出规范 → 继续下一步
|
||
复杂设计：输出 Figma 需求文档 → 暂停等用户确认设计稿
|
||
|
||
并行：backend-coder + flutter-coder（都依赖 API 设计，互不依赖）
|
||
串行：test-engineer → linter → code-reviewer → security-auditor
|
||
|
||
→ 上线前：/design-review 验收还原度
|
||
→ 上线后：/archive-design 存档最终设计
|
||
```
|
||
|
||
### 仅后端修改
|
||
|
||
触发词：「修复后端」「后端接口」「API」+ 具体描述
|
||
|
||
```
|
||
backend-coder → test-engineer → linter → code-reviewer
|
||
```
|
||
|
||
### 仅前端修改
|
||
|
||
触发词：「UI」「界面」「Flutter」「页面」
|
||
|
||
```
|
||
flutter-coder → linter
|
||
```
|
||
|
||
### Bug 修复
|
||
|
||
触发词：「bug」「报错」「修复」「问题」
|
||
|
||
```
|
||
1. 先判断 bug 来源（后端/前端/数据库）
|
||
2. 调用对应的 coder agent 修复
|
||
3. test-engineer 验证修复
|
||
```
|
||
|
||
### 安全/代码质量检查
|
||
|
||
触发词：「安全」「漏洞」「review」「审查」「代码质量」
|
||
|
||
```
|
||
并行：security-auditor + code-reviewer + linter
|
||
```
|
||
|
||
### 线上问题
|
||
|
||
触发词：「线上」「故障」「宕机」「慢」「报错」
|
||
|
||
```
|
||
sre（优先级最高，立即响应）
|
||
→ 根据 sre 诊断结果，再决定是否调用 backend-coder 修复
|
||
```
|
||
|
||
### 文档需求
|
||
|
||
触发词：「文档」「说明」「手册」「README」
|
||
|
||
```
|
||
doc-writer
|
||
```
|
||
|
||
---
|
||
|
||
## Agent 边界规则（强制执行）
|
||
|
||
| Agent | 可以写 | 不可以写 |
|
||
|-------|--------|----------|
|
||
| requirements-analyst | docs/requirements/ | 任何代码 |
|
||
| architect | docs/architecture/ | 任何代码 |
|
||
| api-designer | docs/api/ | 任何代码 |
|
||
| db-designer | backend/migrations/, backend/schema/ | 业务代码、测试代码 |
|
||
| backend-coder | backend/internal/, backend/main.go, backend/internal/router/ | *_test.go, migrations/ |
|
||
| ui-designer | docs/design/（非 archive/） | 任何代码 |
|
||
| flutter-coder | client/ | backend/ |
|
||
| test-engineer | *_test.go, docs/review/*-bugs.md | 业务代码 |
|
||
| linter | 格式自动修复（gofmt/dart format），docs/review/lint-report.md | 逻辑代码 |
|
||
| code-reviewer | docs/review/*-review.md | 任何代码 |
|
||
| security-auditor | docs/security/ | 任何代码 |
|
||
| devops | deploy/, .github/workflows/, backend/Dockerfile | 业务代码 |
|
||
| sre | docs/runbooks/ | 任何代码 |
|
||
| doc-writer | docs/（除 context/ 外） | 任何代码 |
|
||
|
||
---
|
||
|
||
## Agent 间通信协议
|
||
|
||
**文件传递**（主要方式）：
|
||
- 每个 Agent 完成后将结果写入约定文件
|
||
- 下游 Agent 开始前读取上游产出文件
|
||
- 文件格式：混合模式（中文叙述 + YAML/代码块）
|
||
|
||
**短链式调用**（反馈循环）：
|
||
- test-engineer 发现 bug → 直接将错误信息和 `docs/review/{功能}-bugs.md` 路径传给 backend-coder
|
||
- security-auditor 发现 Critical 问题 → 直接告知 backend-coder 修复，不等下次迭代
|
||
|
||
---
|
||
|
||
## 并行 Agent 调度规则
|
||
|
||
当多个 Agent 可以并行时，在同一条消息中发起多个 Agent 调用：
|
||
|
||
```
|
||
# 可以并行的情况（互不依赖）：
|
||
- api-designer + db-designer
|
||
- backend-coder + flutter-coder
|
||
- security-auditor + code-reviewer + linter
|
||
|
||
# 必须串行的情况（有依赖）：
|
||
- requirements-analyst 完成后 → architect 才能开始
|
||
- architect 完成后 → api-designer 和 db-designer 才能并行开始
|
||
- backend-coder 完成后 → test-engineer 才能开始
|
||
```
|
||
|
||
---
|
||
|
||
## Git 提交规范
|
||
|
||
每个 Agent 完成工作后提交，commit message 格式：
|
||
|
||
```
|
||
{类型}({模块}): {简短说明}
|
||
|
||
类型：feat | fix | test | docs | chore | security | refactor
|
||
模块：backend | client | db | deploy | docs
|
||
|
||
示例：
|
||
feat(backend): 新增财务报表接口
|
||
test(backend): 财务报表模块测试用例
|
||
docs(api): 财务报表 API 接口文档
|
||
security: 修复入库单多租户隔离漏洞
|
||
```
|
||
|
||
---
|
||
|
||
## 代码质量门禁
|
||
|
||
以下情况**不得提交**：
|
||
- `go build ./...` 失败
|
||
- `go test ./...` 有失败用例
|
||
- 存在 security-auditor 标记的 Critical 级别问题
|
||
- 存在 code-reviewer 标记的 blocking 级别问题
|
||
|
||
---
|
||
|
||
## 项目特殊规则
|
||
|
||
- `hotel_id` 永远从 JWT token 中提取（`middleware.GetHotelID(c)`），绝不从请求参数读取
|
||
- 所有库存变更操作必须在数据库事务中执行，并同时写 `inventory_logs`
|
||
- `custom_fields` JSON 列用于动态扩展，不为每个新业务字段修改表结构
|
||
- Go 命令需要 `export PATH="/opt/homebrew/bin:$PATH"`（Go 安装在 Homebrew）
|