出海助手-架构改进
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @user_9c953624/yimubiao-improve-arch。
技能介绍
解决什么问题
工程团队常遇到一类慢性问题:模块接口和实现几乎一样复杂、理解一个概念要在多个浅层模块间来回跳转、纯函数被拆出来可测,但真正的 bug 藏在调用方式里、模块越过自己的 seam 互相泄漏、代码缺少测试或当前接口根本无法测试。这些不是靠重命名或再拆一层工具函数就能解决的。技能的目标是:在保持现有行为的前提下,提高代码库的可测试性与可导航性,把浅模块逐步深化为深模块。
技能如何工作
- 先确定扫描范围:用户已经指定模块、子系统或痛点时,直接从该方向进入;否则回看
git log --oneline,找近期反复变化的热点路径。 - 优先阅读
CONTEXT.md与目标区域附近的docs/adr/,让领域词汇和已有架构决策约束后续建议。 - 使用 Explore 子代理有机探索代码,记录架构摩擦:哪些模块是 shallow 的、哪里缺少 locality、哪些 seam 被跨过、哪些接口难以测试。
- 对可疑模块做 deletion test:删除它会让复杂度集中,还是只是把复杂度挪走?前者通常说明值得深化。
- 运行结果写入临时目录的自包含 HTML,例如
/tmp/architecture-review-*.html,不污染仓库;用 Tailwind 做排版,用 Mermaid 绘制调用图、依赖图或时序图,必要时用手工 CSS/SVG 做 before/after 对比。 - 每个候选会展示
Files、Problem、Solution、Benefits、before/after 可视化与Recommendation strength,报告末尾给出Top recommendation。 - 报告中统一使用 module、interface、depth、seam、adapter、leverage、locality 等词汇,避免 drift 到 component、service、API、boundary。
- 报告写完后不直接推接口改造,而是先让用户选择想继续探索的候选。
- 进入决策后,再用 grilling 的思路讨论约束、依赖、深化后模块的形状、seam 后面放什么、哪些测试继续保留。
- 过程中用 domain modeling 同步
CONTEXT.md:新出现的承重概念要补进去,模糊词要当场澄清;用户基于承重理由拒绝候选时,可提议写成 ADR,避免未来重复建议;需要探索替代接口时,再用 design-it-twice 这类并行模式收敛。
适用边界
它适合架构诊断、技术债治理规划、模块边界梳理和大规模重构前评估,不会替团队跳过 ADR 或自动大改代码。遇到现有 ADR 时,只有在真实摩擦足够大时才提示 revisit。需要外部服务或凭证的能力,要先完成授权配置。
使用场景
- 准备做一次大规模重构时,需要先识别浅模块、耦合点和难以测试的接口
- 技术债清单太笼统,需要按实测代码路径给出可排序的架构改进候选
- 模块边界模糊,代码改动经常跨 seam 泄漏,需要梳理可行的深化方向
- 已经存在 ADR,但开发团队遇到真实架构摩擦,需要判断是否值得 revisit 既有决策
适合人员
- 需要在大型代码库中逐步降低耦合的后端工程师,希望重构前先看到风险面
- 负责平台演化的技术负责人,需要把模糊架构问题转成带优先级的改进路线
- 关注可测试性的团队测试工程师,希望定位当前接口难以覆盖的模块
- 经常评审 ADR 的架构师,需要一个不凭空推翻既有决策的架构诊断入口