SuperAPI AI 工具集

architecture-and-design

前端与建站

查看项目

更新于 10-27 16:45

技能介绍

用途

Architecture and Design 是一个基础工程技能,为 TypeScript 编写的 Web 应用提供框架中立的架构标准、设计原则和结构模式。这些原则适用于 React、Angular、Vue 以及任何基于组件的框架。代码示例使用 React/TSX 作为一种具体语法,但每条原则在 Angular 模板或 Vue SFC 中都有等价实现。

该技能建立在 core-typescript(语言语法)之上。在共享主题上,本技能决定设计,core-typescript 决定语法。react、angular 或 vue 提供框架形式,accessibility 提供 UI 视角。只有当任务涉及某一层时才加载同级技能;如果未加载,则从通用知识应用该层,不要阻塞。

该 SKILL.md 是自足的:下面的 Ruleset 是完整、可执行的列表。每个 references/<topic>.md 保存该组的推理和 ❌ / ✅ 代码,references/worked-example.md 提供完整审查示例;在运行时允许时打开它们以获取深度。

主要能力

该技能提供三种使用模式,按顺序执行步骤:

生成(Generate)——编写新组件、hook 或模块:1. 在编写时应用 solid、clean-code、expressive-logic、type-safety 和 state-and-data。2. 将异步状态建模为可辨识联合(patterns)。3. 在边界验证外部数据(type-safety)。4. 将 Ruleset 作为检查清单运行,在交付前修复每个失败项。

审查(Review)——检查拉取请求或差异:1. 对差异运行 Ruleset。2. 按下面的输出格式为每个失败项写一条发现。3. 排序发现:must-fix 优先,然后 consider。4. 如果没有失败,用一行说明。不要编造发现。

重构(Refactor)——重构现有代码:1. 改变结构,保持行为。2. 依赖 clean-code、expressive-logic 和 state-and-data。3. 每次提交只做一种变更。4. 保持测试通过(testing)。

使用方式

输出格式为每行一条发现:

<severity> · <topic> · <file>:<line> — <what is wrong>. <the fix as an action>.

<severity> 是 must-fix(违反本技能中的规则)或 consider(安全,但规则偏好另一种形式)。<topic> 是 Ruleset 主题 slug(state-and-data、type-safety、security 等)。

每种模式的规则:执行规则时命名 Ruleset 主题;陈述原因,而不仅仅是规则;命名规则和变更,不要默默重写作者代码;原则服务于代码,当两个原则冲突时,选择使代码更易读和更改的那个,并说明原因;当任务是决策而非差异时,根据 solid、clean-architecture、structure、state-and-data 和 micro-frontends 权衡选项,并使用 assets/adr-template.md 在仓库中记录为 ADR(上下文、选项、决策、后果)。

Ruleset 主题

该技能包含以下规则组:

  • solid:SRP(渲染与数据获取、状态转换、领域数学分离)、OCP(组件可变性来自 children、slots 或 render props,而非每个变体的布尔标志)、LSP、ISP、DIP。
  • clean-code:布尔命名 is/has/should/can;函数用动词命名;一个概念一个术语;函数短到无需滚动;无布尔标志参数;注释说为什么而非是什么;无死代码;不原地修改参数、prop 或 state;每个错误都被处理或重新抛出。
  • expressive-logic:无 x ? true : false;无 if (c) return true; else return false;无与布尔字面量比较;守卫子句优于嵌套条件;长布尔链命名;?. / ?? 优于手动 && null 链;魔法数字和字符串有命名常量;if/else if 阶梯改为类型化查找或带 assertNever 默认的穷举 switch。
  • type-safety:外部输入以 unknown 进入并在边界收窄;互斥状态是可辨识联合;非法值不可表示(readonly、as const、品牌 id 类型);网络数据在适配器处按 schema 解析;API 类型从契约生成;环境配置在启动时按 schema 验证。
  • clean-architecture:领域核心零框架、DOM 或网络导入;依赖指向内部:UI → 用例 → 领域;基础设施实现领域接口。
  • structure:按业务功能组织代码,而非技术角色;features 导入 shared,shared 永不导入 features;一个 feature 永不导入另一个 feature 的内部文件;边界由 linter 强制执行。
  • patterns:第三方库、SDK 或原始 API 响应隐藏在返回领域模型的适配器/仓库后面;异步状态是带 status 判别符的可辨识联合。
  • state-and-data:状态与使用它的组件同处;可计算的值是派生的而非存储的;服务器集合规范化;每种状态类型位于其层级;Context 只保存低频值;服务器数据通过缓存库;服务器数据在使用点获取;独立请求并行加载;变更从响应更新缓存;每个查询类型有明确的 stale time 和重试策略。
  • frontend-practices:过滤器、映射和链在 return 之前计算;每个异步状态建模(loading、empty、error、success);列表键是稳定 id;派生值或事件处理器优于生命周期副作用;每个独立区域有自己的错误边界;过时异步结果被取消或忽略;捕获的错误发送到跟踪器;无 console.log 发布;语义元素优于带处理器的 div。
  • security:不从不可信输入构建 HTML;避免 dangerouslySetInnerHTML / [innerHTML] / v-html 和 bypassSecurityTrust*;bundle 中无秘密;target="_blank" 链接加 rel="noopener noreferrer";重定向 URL 检查允许列表;token 存储有意识选择并记录权衡;CSP 强制执行模式;cookie 认证加 anti-CSRF token 和 SameSite;第三方 iframe 沙箱;新依赖审查。
  • testing:套件偏向集成;领域和用例快速单元测试;组件按角色和标签查询;覆盖率在变更触及的行上强制执行;每个 bug 修复附带失败测试;API 边界契约测试;不稳定测试首次出现即隔离;快照仅用于小型稳定输出;每个测试也通过 test-quality Ruleset。
  • ddd:每个概念一个通用名称;实体和值对象在 feature 的 model/ 中;值对象不可变;聚合内部部分仅通过根访问;领域事件用过去时命名;每个限界上下文一个模型。
  • micro-frontends:默认模块化单体;shell 和每个 remote 共享版本化契约;框架和设计系统作为固定单例共享;remote 加载失败不使 shell 空白;路由和认证留在 shell。
  • forms:草稿状态本地于表单或表单库;一个验证 schema 在客户端和服务器重用;isValid / isDirty / 每字段错误从表单状态派生;大表单用非受控输入加表单库;服务器验证错误映射回字段;提交进行中禁用提交;失败提交后保留输入值。

适用场景

适用于 TypeScript 前端工程的架构与设计任务,包括编写新组件、审查拉取请求、重构现有代码,以及需要做出架构决策并记录 ADR 的场景。

限制

该技能覆盖前端架构和设计,不覆盖:后端、数据库或基础设施设计;分布式系统(微服务、事件驱动后端、sagas);样式、token 和 CSS 架构(styling-and-design-tokens);超出“语义元素和标签”的无障碍(accessibility);性能预算、Core Web Vitals 和 bundle 分析(web-performance);可复用组件的公共 API(component-api-design)和国际化(i18n-and-localization);CI 配置、依赖机器人、发布工具和 monorepo 设置;框架特定规则(hooks、memoization、变更检测、响应式)——react / angular / vue。

该技能陈述原则,不能替代阅读代码和理解领域。

组合关系

该技能与以下技能组合:core-typescript(语言基础,共享主题上本技能决定设计,core-typescript 决定语法);react / angular / vue(这些规则的框架形式,在直接冲突时框架技能胜出);accessibility(UI 审查视角:ARIA、键盘和焦点、实时区域、a11y 测试);test-quality(本技能的 testing 组设定套件形状,test-quality 评判每个单独测试)。