# FFOA 核心技能集

本目录包含 FFOA 项目的核心开发技能（Skills），用于指导 AI 助手按项目规范执行。
同步来源：本目录内容通过 `npm run sync:skills` 分发到 `.cursor/skills`、`.claude/skills` 与 `.codex/skills`。
如需调整分发内容，请先修改本目录再执行同步。

## 技能清单（29 个）

### 核心开发（7 个）

| Skill | 用途 |
|-------|------|
| **plan-feature** | 需求入口编排器：多角度需求澄清 → 人工确认摘要 → 自动串联完整开发流程 |
| **setup-project** | 首次项目初始化：环境变量、依赖安装、Docker 启动、数据库初始化全流程 |
| **backend-main** | 后端功能开发：NestJS + Prisma 架构、API 契约、认证授权 |
| **frontend-main** | 前端页面/组件开发 + 原型模式：Lark 设计系统、i18n、mock Demo |
| **database-main** | Prisma schema 变更、迁移、数据结构设计 |
| **docs-main** | 模块文档创建/补齐/一致性检查，模板驱动 |
| **start-feature** | 启动功能开发：智能判断是否需要 worktree 隔离，自动编排分支/环境/数据库 |

### 质量保障（10 个）

| Skill | 用途 |
|-------|------|
| **contract-check** | 开工前契约面识别：判定改动是否触碰 API/Schema/状态机/权限/UI/事件，触碰则强制文档先行 |
| **plan-review** | 实施前工程审查：架构/质量/测试/性能四维审查，写代码前发现风险 |
| **doc-review** | 文档实现就绪度审查：4-lens 框架（实现者/外部 API/失败模式/跨文档 diff），新模块写完文档准备开干前必跑 |
| **standards-audit** | 标准/规则文档事实审计：8 角度（事实/内部/入口一致性/完整性/可执行性/链接/过期/格式），写完 standards / skill references / CLAUDE.md 改动 merge 前最后一道关 |
| **prd-multi-role-review** | PRD 多角色并行审查：8 个独立 subagent（产品/架构/安全/UX/工程/QA/SRE/Red Team）并行 review，主进程聚合 + 跨角色 Top Blocker。PRD 写完进入实施前的多视角把关 |
| **code-review** | PR 分层评审：两遍审查（CRITICAL→INFORMATIONAL）+ 枚举完整性 + 文档过时检查 |
| **pre-merge-build-fix** | 合并前构建检查与自动修复闭环 |
| **retro** | 工程复盘：基于 git 历史分析开发节奏、测试趋势、团队贡献与改进方向 |
| **weekly-retro** | 周巡检 + Issue-driven 闭环：每周六 Gitea Action 拉数据 → 发周复盘 issue（label: weekly-retro），skill 在 issue 评论里给 pattern + 候选改进，关 issue = 闭环 |
| **daily-report** | 个人日报：从 git/PR/Claude session 抽取数据，生成 `daily-reports/<git-user>/YYYY-MM-DD.md` |

### 测试（3 个）

| Skill | 用途 |
|-------|------|
| **test-main** | 三层测试总调度：L0→L0a/L0b→L0c→L1→L1c→L2→L3，逐层阻断，汇总报告 |
| **test-backend** | 后端集成测试编写/执行/修复（L1a + L1b） |
| **test-frontend** | 前端 E2E 测试，通过 AI + Playwright MCP 执行（L2） |

### Git（1 个）

| Skill | 用途 |
|-------|------|
| **git-main** | 分支创建、提交（约定式）、合并、推送，含分支安全校验 |

### 运维（6 个）

| Skill | 用途 |
|-------|------|
| **deploy-ops** | 生产/UAT 部署、日常更新、回滚、部署验证 |
| **db-backup** | 数据库备份、恢复（5 种场景）、备份验证、清理 |
| **troubleshoot** | 故障分层诊断：PM2/Nginx/Docker/DB/磁盘/内存/权限/灾难恢复 |
| **prod-error-triage** | 生产应用报错分诊：SSR/CSR/API 分类，先读生产日志再定位代码 |
| **temporal-ops** | Temporal 工作流清理、重置（开发）、安全终止（生产） |
| **infra-check** | 全栈健康检查、Gitea Runner 状态、日志位置、Health API |

### 元技能（3 个）

| Skill | 用途 |
|-------|------|
| **skill-creator** | 创建/修改/优化 skill |
| **skill-audit** | 审计/评估现有 skill |
| **self-improving-agent** | 记录错误、纠正、知识缺口与最佳实践，并将高价值经验提升为规则或 skill |

## 使用方式

```
@start-feature 我要开发一个资产管理模块
@contract-check 这次改动算契约改动吗
@plan-review 审查一下这个方案行不行
@backend-main 帮我实现审批功能
@frontend-main 创建审批详情页
@frontend-main 先做一个审批流 Demo（原型模式）
@docs-main 更新 API 契约文档
@code-review 审查 PR #42
@test-main 跑完整三层测试
@test-main 跑后端测试（L0+L1+L1c）
@test-backend 跑集成测试
@test-frontend 走一遍 E2E 流程
@retro 看看这周干了什么
@self-improving-agent 记录这次排查里沉淀出的经验
```

## 创建新 Skill

```bash
# 验证 skill 结构
python3 .agents/skills/skill-creator/scripts/quick_validate.py .agents/skills/<name>
# 打包 skill
python3 .agents/skills/skill-creator/scripts/package_skill.py .agents/skills/<name>
```

或直接对话触发：`帮我创建一个新 skill` → 自动调用 skill-creator。

## 工作流与调度关系

### 任务类型路由

| 任务类型 | 首选技能 | 典型联动 |
|---------|---------|---------|
| 后端功能/API/业务逻辑 | `backend-main` | Prisma 变更 → `database-main`；文档同步 → `docs-main` |
| 前端页面/组件实现 | `frontend-main` | 文档同步 → `docs-main` |
| 测试（未指明类型） | `test-main` | 分流 → `test-backend` / `test-frontend` |
| 文档创建/重构 | `docs-main` | — |
| Git 分支/合并/推送 | `git-main` | — |
| PR 评审 | `code-review` | — |

### 需求到交付闭环

```
[收到需求]
    |
    v
[规则/文档对齐 + 任务识别]
    |
    v
[文档确认与范围界定]
    |  读 PRD / 交互 / 数据模型 / API
    |  冲突则停止并确认
    v
[方案与实现]
    |  后端 -> backend-main
    |  前端 -> frontend-main
    |  文档 -> docs-main
    |  数据库 -> database-main
    v
[验证与测试]
    |  test-main -> test-backend / test-frontend
    v
[交付说明]
    |  变更摘要 / 影响范围 / 验证命令
    v
[用户确认与后续动作]
```

### 关键衔接

- `test-main` 负责测试分流：后端集成 → `test-backend`；前端 E2E → `test-frontend`
- `backend-main` 涉及 Prisma 变更时转 `database-main`，并要求文档/契约同步
- `frontend-main` 以 Lark 设计系统为准，必要时联动 `docs-main` 做文档对齐
- `code-review` 专注 PR 审查；`pre-merge-build-fix` 负责构建检查与自动修复

## 与项目规则的关系

- **Rules**：必须遵守的核心规则（`CLAUDE.md` / `AGENTS.md`）
- **Skills**：按需触发的执行指南（本目录）
- **Standards**：完整参考文档（`docs/standards/`）

---

**维护者**: FFOA 开发团队