supadevops

supadevops 规约 — JSDoc 契约优先 + TDD 开发流程

本规约规定 Claude Code 插件 supadevops 所施加的开发流程。supadevops 增强 Superpowers，在使用 Claude Code 进行 Next.js（App Router）/ Expo（React Native） 开发时，先于实现用 JSDoc 确定契约。对象是 npm workspaces + turborepo 的 monorepo（app/* 下的各应用 + package/* 下的共享库群），/supa-init 命令用官方 CLI 初始化各应用以构建对部署保持中立的脚手架（§6）。插件对部署保持中立，deploy 到何处由开发者自行裁量（参考结构见 §1.4 末尾）。以契约为起点，单元（辅助函数、Server Action）采用 test-first（red → green），endpoint、end2end（API、UI）作为实现后的验收测试来验证（§2.1），并对各阶段施加人工门控。功能新增、缺陷修复以本流程为一个循环进行迭代，每个循环均为回归安全（§2.2）。本书为两部构成：第 I 部为方法论（§1–§4），第 II 部为 supadevops 插件的构建与分发（§5–§8）。

---

第 I 部 — 开发流程（方法论）

1. 前提与原则

1.1 前提

项目	规定
语言、类型	JavaScript + JSDoc。类型全部以 JSDoc（@typedef / @param / @returns 等）记述。不创建 .d.ts。类型检查用 tsc（不输出）
模块	ESM（import / export，package.json 中 "type": "module"）
仓库形态	npm workspaces + turborepo 的 monorepo。root 有 package.json（"workspaces": ["app/*", "package/*"]）/ package-lock.json / turbo.json / node_modules（主要 hoist 到 root）。app/* 放各应用，package/* 放共享库群（结构见 §1.4）
对象	适用 supadevops 的 monorepo。可并置 app/next-<名>（Next.js src/app）与 app/expo-<名>（Expo）。契约、验证施加于全部应用、全部代码（按代码种别的手段见 §3.6，结构见 §1.4）。插件对部署保持中立（部署目标由开发者裁量，§1.4 末尾为参考）
目录	各 Next.js 应用为 src/ 结构：src/helper/（纯函数）/ src/action/（Server Action，使用时）/ src/component/（组件）/ src/type/（共享 @typedef）/ src/app/（page、layout、api/**/route.js）。Expo 应用以 Expo Router（app/）+ src/helper 等分离逻辑。package/* 的各共享库仅含与平台无关的逻辑、类型（§3.6）。测试见 §3.4
测试	单元 = Jest（Expo 为 jest-expo），endpoint = Playwright request，end2end = Playwright（web、Expo web）/ Maestro（Expo native）
文档	Markdown + Mermaid
依赖	依赖 Superpowers（不内置）。在 plugin.json 的 dependencies 中声明（§8）

补充：横切类型在各应用的 src/type/（若跨应用共享则放 package/* 的库）以 JS+JSDoc 的 @typedef 汇总（模块固有类型放在该文件内即可）。Server Action 是带有 'use server' 的函数/文件，汇总于 src/action/（src/action/ 中不放 Server Action 以外的普通模块）。package/* 的共享库可能被 Next.js（React DOM）与 Expo（React Native）双方 import，因此不放 React DOM 专用的 .jsx 组件，仅限 framework 无关的逻辑、类型、hooks、API 客户端（§3.6）。root 直下的 app/（应用束）与 Next.js 的 src/app/ 或 Expo Router 的 app/ 层级不同，workspaces 的 glob 仅匹配直下（不会冲突）。

1.2 设计原则

1. 契约优先 — 先于实现确定 JSDoc 契约。
2. 多层、详细的 JSDoc — 在 module / class / function / method / component props / @typedef 各层记述 @param / @returns / @throws 与意图。实现向此契约收敛。
3. Plan 直接生成真实文件 — 不持有另外的 manifest。在阶段1向目标 .js / .jsx（辅助函数等的 .js 与组件的 .jsx）直接记入契约与结构占位符。位置以文件内顺序（§3.1）确定，不依赖行号。
4. 粒度为模块单位 — 契约、测试、实现以模块（.js / .jsx）为单位整体进行，不按函数单位切分。
5. 进度体现在真实文件中 — 未实现以 throw 桩表示。不在另外的文件中重复管理进度。
6. 人工门控 — 在前一阶段被批准之前不进入下一阶段。
7. 增强 Superpowers — 能做到的事不重新实现，直接使用（§4）。

1.3 术语

• 契约 — 由 JSDoc 给出的类型（@param / @returns / @typedef 等）与一行意图（行为）。记于 module / class / function / component props 各层。
• 桩 — 仅持有契约、本体为 throw new Error('not implemented') 的声明。
• 纪律 — supa 所施加的 JS+JSDoc 固有规则（契约优先、tsc/jest 验证、放置规约）。
• 回归安全 — 由循环的完成条件“全部测试 + 类型检查为绿”所保证、以前为绿的行为不会被破坏的性质（§2.2）。
• 辅助函数 — 从 UI / Route Handler 提取的纯函数（framework 无关、确定性）。放于 src/helper/，以 Jest 单元测试。
• Route Handler — src/app/api/**/route.js。调用公共服务、外部服务的轻薄 API 边界（BFF）。以 endpoint 验证。
• Server Action — 带有 'use server' 的函数。从 React 的表单/客户端调用的 UI 变更手段，仅存在于持有 UI（表单）的 next 应用中（是否使用为可选。默认的变更系统是 Route Handler）。汇总于 src/action/，作为函数以 Jest（公共服务、外部服务的 HTTP 用 MSW mock）验证（纯粹部分提取到辅助函数）。
• 公共服务 — 自有内部共享的内部服务（= §1.4 参考的 middle office）。由 Route Handler（BFF）代理调用。测试中以 stub 替换（endpoint 用 env stub，Server Action 用 MSW）。实体、放置、部署不在插件关注范围（开发者裁量。参考见 §1.4 末尾）。
• 外部服务 — 第三方的外部服务。由 Route Handler / Server Action 调用。测试中以 stub / mock 替换。本书中并记“公共服务、外部服务”的地方指二者。
• monorepo — 用 npm workspaces + turborepo 将多个应用（app/*）与共享库群（package/*）束于一仓库的结构（§1.4）。turbo 跨工作区执行并缓存任务（build / dev / lint / typecheck / test）。
• Expo 应用 — Expo（React Native）制的应用（app/expo-<名>）。从一份代码库获得 native（iOS / Android）与 web（expo export -p web。以 web.output 得 SPA / SSG）的 build 输出（deploy 目标插件不关注）。
• endpoint — 用 Playwright request 验证 Route Handler（API）的测试（无浏览器，公共服务、外部服务在 dev 服务器上 stub）。放置见 §3.4。
• end2end — 验证 UI / 浏览器、画面流程的测试（web、Expo web 用 Playwright，Expo native 用 Maestro）。放置见 §3.4。
• red / green — 测试失败 / 成功的状态（TDD）。
• 断言（assertion） — 验证期望结果的语句（expect(...) 等）。
• 驱动角色 — 推进实现的主体。会话内 subagent 或 supadevops 的 Workflow（§4.1）。
• Workflow — Claude Code 的本体功能。以 JS 脚本并行/串行执行 subagent。supadevops 的 supa-<功能>-workflow.js 即此 Workflow 脚本（§5）。

1.4 对象 monorepo 的结构

supadevops 以 npm workspaces + turborepo 的 monorepo 为单位适用。一个 monorepo 束起多个应用（app/*）与共享库群（package/*），/supa-init（§6）用官方 CLI 与 npm 命令初始化各应用以构建对部署保持中立的脚手架。插件对部署保持中立，不关注部署目标、网络、服务间认证、应用的角色划分（这些由开发者裁量。本社的参考结构见本节末尾）。

monorepo 的结构（规范）