SuperAPI AI 工具集

hai-architecture

编程与开发

查看项目

更新于 10-15 22:15

技能介绍

用途:用于审查现有架构,或围绕管理复杂度来指导一次设计决策。它先找出变更放大、认知负荷或未知未知集中的边界,再给出最小的结构性调整建议,使系统更易理解与修改。

工作模式:分为全局调查与有界评审/设计两种。全局调查适用于变更摩擦原因不明或请求跨越整个仓库/大型子系统,需按 references/global-audit.md 的入口点、调用链、状态/配置与测试追踪流程执行,先梳理入口点族再收敛到重要路径。有界评审/设计针对已定位的组件、模块、包边界或设计选择,检查其直接调用方、契约与测试;React 组件需阅读 references/react-patterns.md 的七个维度。SSOT 是两种模式内的一种视角,针对重复的定义、规则、默认值、转换或词汇,阅读 references/ssot-patterns.md 及 references/ssot-detection-cookbook.md 中相关配方。请求可从全局调查转入有界决策,复用同一份证据,不重复两轮完整评审。

证据门槛:作出架构论断前,须阅读本次引用的每个文件并给出真实 file:line;断言调用链或影响范围前追踪调用方与实现;阅读 ADR、依赖规则、架构测试与公共契约;对比模块公共接口与实际隐藏的复杂度;同一根因只计一次;推断须标注为未经验证。

核心判断:优先深层模块——用小的稳定接口隐藏大量相关复杂度;不以文件长或相邻作为拆分/合并依据,而看新边界是否隐藏信息、是否让调用方知道更少、是否拥有规则或不变量、能否让下游变更止步、转换是否增加含义/约束/所有权。若全为否,该层可能是直通税。非平凡决策需比较至少两个本质不同的方案,说明为何拒绝现状、进一步拆分、合并或泛化抽象,并给出红队误用、蓝队防御与残余风险。需要完整视角目录或对抗性评审细节时阅读 references/principles.md。

工作流:评审现有代码时先声明边界与请求规模,过证据门槛,绘制当前参与者/模块、依赖或状态流与预期隐藏边界的简图,定位最高杠杆的复杂度中心,只选相关视角,应用深层模块与层成本测试,甄别 SSOT 合规投影、信任边界复检、生成物与前向契约后再计违规,检查 references/red-flags.md 的红旗项,按影响排序写出与规模匹配的报告。指导设计决策时先澄清目标、边界、约束与必须存续的契约,映射当前链路,设计至少两个本质不同的选项,比较业务契合、边界清晰度、模块深度、迁移成本、运营风险与拒绝理由,推荐一个选项并说明残余风险与首个验证点。

规模:快速——一个问题,返回地图、结论、证据、主要权衡与下一步;标准——一个包或调用链,使用完整 Markdown 模板;完整——用户明确要求多个边界,先广泛映射再收敛到痛点中心。

输出:匹配用户语言,保持代码标识符不变。标准/完整 Markdown 评审按有界模式填写 references/output-template.md,全局模式用 references/global-output-template.md;快速回答保留其决策字段。用户明确要求 HTML 时阅读 references/html-report.md。语言相关指导见 references/go-patterns.md、references/typescript-patterns.md、references/react-patterns.md。完整 React 组件诊断用 references/react-output-template.md;SSOT 专项评审用 references/ssot-output-template.md,混合评审在主报告中内嵌其字段。诊断本身不授权修改;若请求修复,须持续到验证完成。

不适用情形:需复现与因果证据的未知故障改用 hai-debug;无重复权威的本地命名、函数或风格问题用 code-review-and-quality 或 hai-naming;产品需求而非技术设计用 hai-prd。本技能也不应作为格式化器、功能完整性审计、通用测试顾问或性能评审,除非性能架构或 React 渲染/副作用路径是明确的决策对象。