web-architecture

🏗️ TypeScript 全栈多代理开发工作流

源自 50K 行代码实战教训,为 TypeScript/Next.js/Convex 项目提供分阶段多代理协作开发规范,有效避免架构冲突与功能失效。

收藏
3.5k
安装
1.1k
版本
v0.1.0
CLS 安全性认证2026-05-19
点击查看完整报告 >

使用说明

Web Architecture 是一项针对 TypeScript/Next.js/Convex 技术栈的多代理开发工作流程指南,源于开发者从 29 个并行代理、50K 行代码和 212 个错误中总结的硬核教训。该 Skill 将复杂的全栈项目拆分为六个严格顺序的阶段:Phase 0 引导式初始化(必须顺序执行)、Phase 1 基础文档并行生成、Phase 2 后端实现(建议单代理)、Phase 3 组件库构建(必须单代理)、Phase 4 功能页面并行开发,以及 Phase 5 集成与 QA。其核心方法论强调"单代理全上下文优于多代理部分上下文",通过锁定 Schema 和类型定义、建立 CONTRACTS.md 契约文件、严格执行功能验证(而非仅通过编译)来避免架构混乱。

该 Skill 的显著优势在于提供了经过实战验证的防崩溃开发范式。它明确区分了"编译通过"与"功能可用"的界限,强制要求验证数据流、UI 渲染、端到端用户流程和错误状态处理,有效避免生成"15K 行零功能代码"的灾难。通过文件锁机制、目录隔离和严格的 Agent 生成顺序,它解决了并行开发中的重复定义、类型冲突和集成噩梦。对于采用 AI 辅助编程的团队,这是一份防止"多代理 chaos"的救命手册。

然而,该 Skill 也存在明显局限性。首先,它高度依赖特定技术栈(TypeScript/Next.js/Convex),对其他框架(如 Vue、Django、Rails)的迁移价值有限。其次,其严格的阶段顺序(特别是 Phase 0 必须在任何其他代理之前完成)可能与追求极致速度的敏捷团队产生摩擦。此外,作为纯文档型 Skill,它仅提供指导原则,无法自动强制执行流程合规性,团队仍需人工监督代理行为。

该 Skill 最适合中大型全栈开发团队,特别是正在采用或计划采用多 AI 代理协作开发复杂 Web 应用的组织。对于从零开始构建 SaaS 产品、需要协调前后端 schema 一致性、或曾因并行代理开发导致代码库混乱的技术负责人而言,这份指南能有效降低架构债务。它也适合作为技术团队的入职培训材料,统一多代理开发规范。

使用风险方面,需注意该 Skill 来自 T3 级社区个人来源(GitHub: openclaw/skills),非官方组织背书,虽内容透明可审计,但缺乏企业级安全合规认证。作为纯文档资产,它本身不执行任何代码,无运行时风险,但团队需自行验证其中推荐的技术栈(如 Clerk 认证、Convex 数据库)是否符合自身安全要求。此外,过度依赖此流程可能降低开发灵活性,小型项目或原型开发可能因流程过重而得不偿失。

安全解读

核心定位

web-architecture 是一套经过实战验证的多Agent开发工作流规范,源于作者用29个并行Agent写出50K行无法编译代码的惨痛教训。它不依赖任何特定工具,而是一套可复用的组织原则阶段门控机制

核心用法:五阶段顺序执行

该Skill强制要求严格顺序的五个开发阶段:

Phase 0: Bootstrap(单Agent,阻塞) — 必须先完成项目结构、Convex初始化、完整schema定义和类型生成。此阶段未完成前,禁止启动任何其他Agent。这是防止"先写代码后补类型"灾难的关键。

Phase 1: 基础文档(可并行) — 技术需求、合规、设计原则、编码规范等文档,只读schema。

Phase 2: 后端实现(推荐单Agent) — Convex函数开发,要求验证真实CRUD、数据持久化、权限守卫,而非仅编译通过。

Phase 3: 组件库(单Agent) — 统一组件API,避免并行产生的多套实现。

Phase 4: 特性页面(按目录隔离并行) — 此时schema、类型、组件均已锁定,可安全并行。

Phase 5: 集成与QA(单Agent) — 端到端流程验证,包括真实数据流而非Mock。

显著优点

1. 解决根本问题:明确区分"编译通过"与"真实可用",强制功能验证
2. 上下文管理:通过CONTRACTS.md和类型文件实现跨Agent契约,避免"前端期望user.role,后端返回profile.plan"

3. 冲突预防:Phase 0锁定schema、Phase 3锁定组件,消除最常见的并行冲突源

4. 经验沉淀:每个规则都附带真实失败案例(如15K行"零功能"代码的5/10自评)

局限性与约束

  • 非自动化工具:仅为规范文档,需人工或外层Agent强制执行阶段门控
  • 技术栈绑定:针对Convex+Next.js+TypeScript优化,其他栈需适配
  • overhead 成本:小型项目可能感觉流程过重
  • 无法保证执行:Agent可能"声称"遵循而实际跳过验证步骤

适合人群

  • 使用Convex后端、Next.js前端的团队
  • 需要3+ Agent协作的中大型功能开发
  • 经历过"类型地狱"或"并行冲突"的开发者
  • 追求可交付而非仅可编译的工程质量标准

常规风险

1. 虚假完成:Agent可能标记Phase完成但未真实验证功能(Skill明确要求人工复核清单)
2. 超时中断:明确警告禁止设置Agent超时,会导致代码断裂

3. 契约漂移:后期修改schema需回滚到Phase 0,成本极高,设计前期需充分考量

web-architecture 内容

手动下载zip · 27.0 kB
CODING-STANDARDS.mdtext/markdown
请选择文件