programming-design-review

name	programming-design-review
description	按用户的编程设计风格巡检代码库或目标模块，并输出包含改进候选的可视化设计矛盾报告。Use when 用户要求按自己的编程风格/设计习惯评审架构、查找设计异味、对照 programming-design-style、输出重构机会报告，或选择一个设计问题继续追问成可实施方案。

编程设计巡检

概览

找出真实代码中偏离用户工程设计习惯的地方，并整理成可行动的改进候选。这个 skill 以报告为核心：先巡检并可视化设计矛盾，再询问用户要深入哪一个候选。

风格来源

开始巡检前，先尝试读取相对本 skill 目录的 ../programming-design-style/SKILL.md。把它作为用户编程设计风格的主要来源。

如果该文件不可用，继续使用以下最小评审视角：

• 单一职责：数据、表现、配置、工具、编排不应无理由混在一起。
• 稳定身份：按场景判断身份来源。配置文件通常以路径、资源地址或加载键作为引用源，不需要额外 UID；配置内部会被独立长期引用的子项才需要自动生成并持久化的稳定 ID，可以来自 GUID/UUID 库或项目自定义递增分配函数；由配置实例化出的运行时对象，只有在需要存档、同步、追踪状态或被长期引用时，才需要独立实例 UID。
• 唯一真源：运行时状态、配置、持久化状态、DTO、缓存之间不应悄悄复制同一个业务事实。
• 数据从属：配置数据应归配置管理器、配置索引或资源加载入口；存档数据应归存档管理器、玩家进度管理器或业务数据仓库；运行时对象只保存自身状态、引用键和必要差异，不应把配置、存档、表现字段都拷到使用方对象里。
• 符号值唯一入口：参与逻辑判断、跨处引用、资源查找、表现选择或状态切换的字符串、枚举、状态 int、动画 key、资源 key 和协议码，不应散落成硬编码符号值；应收拢为常量、配置、状态对象、注册表或工具生成入口。
• 数据和表现分离：业务状态变化应和 UI、动画、音效、特效、场景反馈区分开。
• 配置和表现外置：设计、美术、运营或内容维护者需要调整的数值、资源、文案、体验参数不应写死。
• 解耦协作：模块之间优先通过清晰方法、事件、命令或适配器协作，不要直接伸手改彼此内部状态。
• 工具优先：重复、脆弱、需要非程序角色参与的流程，应有工具、校验或编辑器入口支撑。

最终报告中不要大段复制 programming-design-style。只摘要和每个发现直接相关的原则。

工作流程

1. 确认范围

先澄清或推断巡检范围。优先选择具体模块、功能、目录、PR diff 或近期改动范围。如果用户没有给目标，不要试图一次巡完整个仓库；先查看项目入口并选择一个可评审的切片。

存在本地项目说明时，先阅读：AGENTS.md、CONTEXT.md、docs/adr/ 下的决策文档，以及目标区域相关的项目提示词。尊重已有架构决策；只有在真实矛盾足够明确时，才建议重新讨论旧决策。

2. 探索代码

先搜索，再判断。使用快速代码搜索确认定义、调用点、数据所有权、配置来源、UI/表现路径、事件、编辑器工具和测试。

如果有子 agent 或探索工具，只把它们用于独立走读代码或梳理目标区域。必须显式传入项目规则和目标范围。不要假设子 agent 知道本 skill 的风格原则；需要时把相关摘要写进子任务。

探索时重点寻找真实矛盾：

• 理解一个概念需要在很多文件之间来回跳，而且没有清晰拥有者。
• 某个类或函数同时混合业务状态、UI 效果、配置解析、资源加载和跨模块协调。
• 多个对象保存同一个业务事实，但没有明确的缓存、快照或 DTO 命名。
• 配置读取、配置索引、默认值、缺失校验散落在多个业务类里，而不是归到配置管理器或项目约定的配置入口。
• 存档读写、脏标记、版本迁移、云同步字段或玩家进度事实由多个运行时模块各自维护，而不是归到存档管理器、进度管理器或业务数据仓库。
• 运行时对象为了方便同时保存配置字段、存档字段和表现字段，导致字段看起来可直接改，却看不出最终解释权属于配置、存档、服务端还是当前实例。
• 业务逻辑里直接写动画名、资源 key、协议状态、表字段名、枚举名字符串或状态 int；同一个值在多处重复出现，却没有命名常量、配置字段、状态对象、注册表或工具入口说明谁拥有它。
• 配置文件明明已经通过路径、资源地址或加载键定位，却又额外维护了一套无用 UID。
• 配置内部会被长期引用的子项，或需要存储状态的运行时实例，仍依赖显示名称、数组位置或非受控递增值。
• 表现逻辑执行最终状态写入，或业务逻辑直接编排具体表现细节。
• 类似配置的值被写死，而非程序角色合理上需要控制它。
• 事件或模块调用暴露了私有时序、内部状态或偶然的调用顺序要求。
• 重复手工流程缺少校验、批量工具或编辑器支持。

3. 输出 HTML 报告

把自包含 HTML 文件写到仓库外，避免制造项目噪音。临时目录按 $TMPDIR、$TEMP、/tmp 的顺序解析，文件写到：

<tmpdir>/programming-design-review-<timestamp>.html

使用 Tailwind CDN 做布局。关系结构适合图表达时使用 Mermaid CDN；更偏解释性的 before/after 视觉可以用手写 HTML/CSS/SVG。环境支持时为用户打开报告，并告知绝对路径。

报告必须先给出架构图，再给候选卡片。不要只写文字说明或普通列表。

报告开头必须包含：

• 当前架构图：用 Mermaid 或手写 HTML/SVG 展示当前数据流、模块关系、状态归属、配置来源或调用链。图中节点必须使用真实模块/文件/配置名，不能只写抽象层名。
• 目标架构图：展示建议收敛后的结构，明确哪些职责被移动、收拢、拆分或外置。目标图可以是 Top Recommendation 对应的目标形态，而不是每个候选都画总图。
• 当前/目标对照摘要：用 3-6 条短句说明从当前图到目标图，哪些“业务事实、状态、配置、表现、工具流程”的归属发生变化。

报告包含 3-8 个候选卡片。每个卡片必须包含：

• 涉及文件：具体模块和文件。
• 当前矛盾：哪里难理解、难修改、难验证或难维护。
• 风格原则：偏离了用户哪条设计习惯。
• 建议方向：准备收拢、拆分、改名、移动、外置配置或工具化什么。
• 数据/唯一真源影响：状态、身份、配置、存档、缓存、DTO 或符号值入口应由谁拥有；说明配置数据、存档数据、运行时状态、服务端状态、资源索引和表现配置是否有清楚的管理器归口；如果问题涉及硬编码字符串、枚举或状态 int，要说明这些值应收拢到常量、配置、状态对象、注册表还是工具生成入口。
• 表现/配置/工具影响：相关时说明 UI、动画、资源、配置或工具流程怎么变化。
• 验证方式：用测试、编辑器检查、日志或手工流程如何证明改动正确。
• Before 架构图：必须是图，不是纯文字；展示当前模块、数据、状态、配置、表现或工具流程如何连接，以及矛盾发生在哪里。
• After 架构图：必须是图，不是纯文字；展示建议后的职责归属、数据流、状态模型或工具流程。候选较小时也要画局部 before/after 图。
• 推荐强度：Strong、Worth exploring 或 Speculative。

报告最后加一个 Top Recommendation 区块，说明建议最先处理哪个候选以及原因。这里给建议，不要直接写成实施计划。

图形要求：

• 如果关系是模块依赖、状态流、调用链、配置同步链路，优先使用 Mermaid：flowchart、sequenceDiagram、stateDiagram-v2。
• 如果要表达职责体积、浅模块/深模块、重复流程收拢，可以用手写 HTML/CSS/SVG。
• 每张图必须服务一个判断：读者应能从图上看出“现在哪里分散/混乱”和“改完后哪里收拢/清晰”。
• 不允许只放一张“当前数据流”当作架构巡检；至少要有一张目标架构图，并且每个候选都有局部 before/after 架构图。

报告阶段不要提出最终接口，也不要修改代码，除非用户明确要求直接实施。

4. 询问下一步

写完报告后询问用户：“你想先深入哪一个候选？”

用户选中候选后，进入追问循环。只问会改变设计的问题：状态归属、身份生成、唯一真源、表现编排、配置归属、事件/命令、工具入口、失败行为和验证方式。只有当决策以后会复用，且用户同意或项目规则要求时，才把它沉淀到项目文档。

输出风格

具体、贴代码、少空泛判断。优先写“这条调用链让奖励状态和 UI 时序共用同一个拥有者”，不要只写“耦合不好”。稳定使用用户的设计词汇：模块、职责、唯一真源、UID、数据流、表现流、配置、事件、工具。