# Web Development Team Playbook

> 团队级 Web 开发工作手册。凡涉及创建、改造、调试、审查、优化、发布准备或部署 Web 网站、Web 应用、前端或全栈 Web 项目时必须使用。涵盖 Next.js、Vite、TanStack Start、Vite+、TanStack、Effect 与 React Three Fiber 的选型，方案先行、严格隔离对抗审查、质量验收、Git/PR 和部署确认门禁；不用于纯原生移动端、纯后端服务或桌面软件。

- Skill: `lora-sys/web-development-team-playbook` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add lora-sys/web-development-team-playbook`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lora-sys/web-development-team-playbook/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: lora-sys (https://skillmd.com/u/lora-sys)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lora-sys/web-development-team-playbook

---


# 团队级 Web 开发工作手册

## 基本原则

将此文件作为所有 Web 工作的**强制交付流程**。先理解当前项目与用户目标，再形成计划，随后实施、验证、隔离审查并交付。不要为“技术新”而迁移稳定架构，不要在未被要求时扩大任务，不要用看起来完成的 UI 代替底层已完成的工作。

优先复用当前项目成熟工具、上游模式与已被充分验证的实现。不要为了拥有代码而重写标准聊天 UI、Canvas 行为、流式辅助能力或服务商集成。不要添加不存在的提供商、协议、研究对象或未来产品模式的抽象。保持显式状态转换，隔离第三方实现差异，保持 Canvas 和高频交互在长任务中可响应。

## 必做工作流

按以下顺序工作；除纯文案、配置或非常小的已验证修复外，不得跳过其中的计划、验收和隔离审查。

1. **识别任务和现状。** 阅读当前仓库的约定、脚本、锁文件、现有组件、依赖与部署配置。判断任务属于新建、改造、修复、性能/体验优化、审查、发布准备或部署。
2. **确认当前技术事实。** 在新建项目、升级依赖或使用不熟悉 API 前，查阅相关框架与工具的官方文档；不得根据记忆中的版本、命令或 API 编写实现。
3. **先输出计划。** 在实施前给出计划的简洁主上下文摘要。需要时使用平台可用的计划工作流展开细节。计划应按任务规模说明：目标和非目标、用户流/信息架构、选型依据、页面/组件、状态与数据/API、依赖变更、风险、验收项，以及部署状态。
4. **实施最小正确变更。** 按当前项目的结构、命名、格式化、脚本和已有设计语言实施。若发现相邻问题，记录而非顺手扩张当前任务。
5. **执行质量验收。** 运行现有的类型检查、构建和相关测试；验证成功、失败、空、加载和异常路径；完成截图、移动端、交互、性能、SEO 与无障碍检查。读取 `references/quality-gates.md`。
6. **执行严格隔离对抗审查。** 每轮实现或修复后必须遵守 `references/review-protocol.md`。只修复经源代码或运行事实验证为真的问题，并在修复后复验。
7. **按证据交付。** 汇报已完成内容、验证证据、修复的真实审查问题、仍存限制和后续可选工作。不要把未执行的检查表述为已通过。

## 技术选型与工具链

先保留现有项目的合理架构。仅在新建项目或确有选型/迁移必要时，遵循下表并读取 `references/stack-selection.md`。在选择前，核验当前官方文档、当前稳定版本、项目兼容性与现有脚本。

| 需求特征 | 默认优先选择 | 决策要点 |
|---|---|---|
| 内容站、SEO、SSR、服务端组件或成熟 React 全栈生态 | Next.js | 优先评估渲染、缓存、路由和服务端边界。 |
| 高交互 SPA、营销页、纯前端工具 | Vite | 优先简洁、快速开发和客户端体验。 |
| 全栈 React、Server Functions、端到端类型安全或深度 TanStack 工作流 | TanStack Start | 优先评估现有 TanStack 集成与服务端需求。 |
| 路由、查询/缓存、数据表格 | TanStack Router、Query、Table | 不为已有成熟实现制造无理由迁移。 |
| 3D 场景、空间交互、WebGL 体验 | React Three Fiber | 结合性能预算、降级策略与可访问替代方案设计。 |
| TypeScript 异步流程、错误建模、验证、服务端/领域工作流 | Effect 生态 | 默认评估并优先采用；仅在复杂度、兼容性或项目约束证明不适合时不用。 |

**Vite+ 优先规则：** 对适用 Web 项目，优先使用 Vite+（`vp`）作为统一工具链入口。实际开始前，查阅 Vite+ 官方文档与当前项目兼容性；不得把某个 `vp` 命令、插件或兼容性假设固化为永久规则。使用 Next.js 或其他已有脚手架时，先验证 Vite+ 是否适用，再决定保留项目既有工具或引入 `vp`。

## 实现标准

遵循以下不可协商标准；有关 UI、动效和常见问题的扩展规则按需读取相应参考文件。

- **类型与输入：** 尽量利用 TypeScript 推导；避免 `any`；在未知外部输入进入系统时验证其结构、语义和错误路径。Effect 采用与否都不改变这一要求。
- **状态诚实：** Spinner 仅表示真实工作尚未完成；成功只在底层任务完成后显示；草稿不得伪装成已应用；断开的 Agent 或服务不得伪装成活跃。
- **注释与可维护性：** 注释只解释意图、约束或非直观行为，不复述显然代码。服务商和绘图/Canvas 特性不得泄漏进通用产品状态。
- **可用性与响应式：** 保持可见焦点、键盘可达、足够的实际背景对比度、清晰的页面逃生路径和移动优先布局。读取 `references/design-motion.md`。
- **用户可见变更证据：** 对 UI 改动，在可行时提供变更前后截图。动效、时序、拖放或多步交互是重点时，提供短录屏或等效的可运行证据。
- **媒体资产：** 不将大型图片、视频或其他媒体直接塞入构建目录；使用项目现有或已确认的资产存储方案，并将源文件保存在构建目录之外。不要把任意特定存储路径、上传命令或地图服务写成跨项目硬规则。

## Git、PR 与自动审查

遵循仓库现有的提交、分支、代码格式与 Pull Request 约定。可以为已完成、可验证的改动创建本地提交；**除非用户明确要求，不得创建 Pull Request。** 用户要求 PR 时，一个 PR 只保持一个主要关注点。

对自动审查结果，将其视为有待验证的主张。仅当结论与源代码、运行产物或明确事实一致时修复；不要为取悦机器人而更改正确代码。所有真实问题的修复必须进入同一轮验收与严格隔离对抗审查。

## 部署与发布门禁

部署、生产发布、推送生产环境、购买资源、创建付费服务或其他外部不可逆操作，均需要在操作前取得用户在本次任务中的**明确确认**。可以自行完成部署准备、环境检查、构建、预览和发布方案，但不得把“用户此前授权自主开发”理解为发布授权。

部署具体平台、域名、环境变量、预览策略、回滚与权限，必须在相应项目中依据实际环境决定；不要在此通用技能中猜测或写死。

## 参考文件导航

| 文件 | 何时读取 |
|---|---|
| `references/stack-selection.md` | 新项目、框架/工具选型、升级依赖、评估 Vite+、TanStack、Effect 或 React Three Fiber 时。 |
| `references/design-motion.md` | 创建或改造用户可见界面、设计系统、主题、动效、可访问体验时。 |
| `references/quality-gates.md` | 每次实现、修复、性能优化、交付或发布准备完成后。 |
| `references/common-pitfalls.md` | 遇到视觉接缝、对比度、主题、导航、路由、状态引用、链接或选择器问题时。 |
| `references/review-protocol.md` | 每轮实现或修复完成后；必须执行。 |

## 禁止事项

- 不要跳过计划而直接开始中大型 Web 实现。
- 不要把框架、版本、路由或部署命令的旧记忆当作当前事实。
- 不要擅自创建 Pull Request，或在没有本次明确确认时部署/发布。
- 不要伪造测试、截图、性能、SEO、无障碍或审查通过结论。
- 不要让对抗审查者读取用户需求、计划、主上下文、实现说明、Git 历史、既有测试或此前审查结论。
- 不要无理由重写成熟能力、引入多余依赖或在修复时扩张任务范围。
- 不要用透明/图片/滚动背景上的不确定文字对比度、不可到达的导航或“假成功”UI 交付产品。

> 此技能将“快速完成”定义为：以最小必要变更交付真实运行、可验证、可维护且没有假状态的 Web 体验。