全栈工程师 · 工作流程 SOP

触发：交互 UI 设计师完成设计层交付（过完闸 2），前台 + 分诊调用工程师。 前置：已走完《岗位调用链路》第 1–2 步。 定位：架构先于代码 · 先跑通再优化 · 可观测性一开始就建。 ⚙️ Handoff 契约：03_协作规则/_handoff矩阵.md §5 R03 — inputs/outputs 以矩阵为准。

一图总览

读上游 → 先说 A/B/C → 列文档清单 → 架构+schema+API → 提资料
                                                          ↓
验收交付 ← reviewer闸3/4 ← 部署+运维手册 ← 业务实现 ← 脚手架+原子组件

10 步工作流

第 1 步 · 读上游交付物

动作：按顺序读（先契约后细节）： 1. 交付物/02_设计层/18_UI设计规范DesignSystem.md — 设计系统 token 2. 交付物/02_设计层/design-tokens.json — 可直接 import 的 token 3. 交付物/02_设计层/高保真/ + 状态集/ — 视觉规格 4. 交付物/02_设计层/切图/ + 标注/ — 具体像素 5. 交付物/01_产品层/11_PRD产品需求文档.md — 业务规则 6. 交付物/01_产品层/13_功能清单FeatureList.md — 功能优先级 7. 交付物/01_产品层/21_模型选型评估报告.md（若涉 AI） — AI 能力边界 8. 交付物/01_产品层/24_埋点需求文档.md — 埋点规则 9. 交付物/01_产品层/16_数据指标体系文档.md — 指标定义 10. 参与岗位.md 的"设计→开发 交接关键点"

禁止： - ❌ 这一步不允许写代码 - ❌ 不允许只扫一眼设计稿——必须逐页理解状态集

完成标志：能用 3 句话复述技术栈选型 + 核心数据流 + 关键风险。

第 2 步 · 先说"我要做 A / B / C"

动作：在 决策日志.md 写一段"我打算怎么落实"——这是对 AI PM 和 reviewer 的宣告：

示例："示例项目 是 Next.js 14 + Supabase + Claude API 的架构，我打算分五段—— A 搭脚手架 + schema + RLS 策略（2 天）； B 原子组件对齐 design-tokens，出 Storybook（1 天）； C 前端业务 + 状态管理 + 路由（4 天）； D 后端 API + Claude Tool Use + 埋点（3 天）； E 部署 + Sentry + 运维手册 + 闸 3/4（2 天）。 预估 12 个工作日，关键风险是 Claude Tool Use 的多轮对话状态管理。"

完成标志：AI PM + 设计师读完后能点头。

第 3 步 · 列文档清单

对照 所需文档清单.md，写进 参与岗位.md 自己那一行： 1. 必出：20 技术架构 / 22 API 接口 / 23 数据库设计 / 25 测试用例 / 26 使用手册 / 27 上线 CheckList 2. 按需：S10 埋点验收 / S11 灰度发布 / S12 应急预案 / S17 架构图 / S19 性能测试 / S20 Bug 跟踪 3. 不做：本项目不适用的项（注明原因）

第 4 步 · 技术选型 + 架构设计

动作： 1. 技术栈确认：Web/APP/小程序 → Next.js / Expo / Taro；涉 AI → Claude / OpenAI 2. 前后端分层图：画清楚 Client / Edge / Server / DB / AI 各层 3. 数据库 schema 设计：表结构 + 索引 + 外键 + RLS 策略 4. API 契约设计：REST endpoint / Server Actions / tRPC routes 5. 环境变量清单：DB_URL / CLAUDE_KEY / SUPABASE_SERVICE_ROLE 等 6. 关键假设与风险清单：哪些地方可能爆（性能 / 成本 / 限流）

产出： - 交付物/03_开发层/20_技术报告.md（含架构图 + 选型理由） - 交付物/03_开发层/23_数据库设计文档.md（schema + ER 图 + 索引） - 交付物/03_开发层/22_API接口文档.md（endpoint 契约） - 交付物/03_开发层/环境变量清单.md

禁止： - ❌ 不画架构图就开写 - ❌ schema 没过一遍 AI PM 就开始 migration - ❌ API 契约没跟设计师对齐就开始写前端

第 5 步 · 提资料需求（点菜单给数据扒取部）

类型 要什么 优先级
选型对比 库 A vs 库 B 的 benchmark / issue P0
官方文档快照 Next.js / Supabase / Claude SDK 最新版 P0
安全最佳实践 OWASP Top 10 + 各云平台安全清单 P1
性能基准 目标栈的冷启动 / 响应时延数据 P1

第 6 步 · 搭脚手架 + 原子组件

动作： 1. create-next-app + TypeScript 严格模式 + App Router 2. 接入 lint / format / typecheck / husky / lint-staged 3. 接入 Tailwind + shadcn/ui，把 design-tokens.json 翻译进 tailwind.config.ts 4. 建目录结构（按第 4 步架构图）： src/ ├── app/ · 路由 ├── components/ · 原子 + 业务组件 ├── lib/ · 工具 + 客户端（Supabase / Claude） ├── db/ · schema + migration（Drizzle） ├── hooks/ · 自定义 hook ├── stores/ · Zustand └── types/ · 类型定义 5. 实现原子组件（Button / Input / Card / Modal / Toast ...）对齐设计系统 6. 第一天就接 Sentry + 结构化日志

产出： - 能跑 dev 的空壳 - 原子组件 Storybook 或 demo 页

禁止： - ❌ 跳过 lint / typecheck 配置 - ❌ 不配 Sentry 就开始写业务 - ❌ 原子组件不对齐 design-tokens 就进入业务

第 7 步 · 逐页面 / 逐接口实现（业务层）

动作：按功能清单 RICE 优先级逐个交付，每个功能都走一遍闭环：

对一个功能点：
  schema 改 → migration → API → 前端页面 → 状态集 → 手动验收 → commit

具体规则： 1. schema 变更必须走 migration（不允许手改数据库） 2. API 变更必须同步更新 22_API接口文档.md 3. 前端页面必须实现全部 5 种状态（正常/空/加载/错/边界） 4. AI 能力调用必须： - 把 system prompt 固化到 lib/prompts/ - Tool definition 走类型安全（Zod schema） - 用户输入走 Prompt 注入防护 5. 埋点跟业务代码一起落地（不留到最后） 6. 每做完一个功能，手动跑一遍 golden path + 边界情况 7. 频繁 commit，Conventional Commits 格式

禁止： - ❌ 批量 commit 后"以为能跑"——边做边验 - ❌ 写完所有功能才统一加状态集 - ❌ 写完所有功能才统一加埋点 - ❌ Supabase 不开 RLS

第 8 步 · 测试 + 性能自查

动作： 1. 单元测试：核心业务逻辑 + 工具函数（Vitest） 2. 集成测试：关键 API 端点（Playwright 或 supertest） 3. E2E 测试：golden path（Playwright） 4. 性能自查： - Lighthouse 分数 ≥ 90 - 首屏 FCP < 1.5s - API p95 < 500ms - AI 调用带流式响应 5. 安全自查：OWASP Top 10 逐项过

产出： - 交付物/03_开发层/25_测试用例文档.md - 交付物/03_开发层/S19_性能测试报告.md（按需）

第 9 步 · 部署 + 运维手册

动作： 1. Vercel 部署 + Preview / Production 环境分离 2. Supabase 生产环境建库 + 跑 migration + 配 RLS 3. 环境变量 在 Vercel Dashboard 填齐，绝不进代码 4. Sentry 接入 + 告警规则 5. 灰度发布 配置（按需 Feature Flag） 6. 回滚预案：每次部署都能一键回滚 7. 写 README.md + 26_产品使用手册.md： - 架构图 - 如何本地跑起来 - 如何部署 - 如何改 - 常见问题 - 给 CEO 看的非技术说明（这玩意怎么用、出问题找谁） 8. 写 27_上线CheckList.md（过闸 4 的依据）

产出： - 上线的 URL（staging + production） - 代码仓库链接 - README.md + 26_产品使用手册.md + 27_上线CheckList.md - Sentry 项目链接 + 告警邮箱

禁止： - ❌ 不配 Sentry 就上线 - ❌ 硬编码密钥 / Token - ❌ 没有回滚预案 - ❌ README 不写给非技术人看

第 10 步 · reviewer 闸 3/4 + 交付给 CEO

闸 3（代码审查）： - 代码质量 / lint / typecheck 全过 - 测试覆盖率达标 - Sentry 告警配置完整 - schema + RLS 审查 - API 契约审查

闸 4（上线前合规审查 · 一票否决）： - 隐私政策 + 用户协议就绪（质量部主责） - 敏感数据处理合规（GDPR / 个保法） - AI 合规（32 号文档） - 埋点合规 - 回滚预案就绪

闸过完后： 1. 在 参与岗位.md 写明：URL / 账号 / 已知限制 / 关键假设 2. 写"验收清单"：哪些已实现、哪些边界已测、哪些是 known issue 3. 通知 CEO + 运营部 + 质量部 reviewer 验收 4. 项目档案 status 改 已交付（触发 CKO 自动蒸馏）

禁止事项（红线汇总）