架构决策顾问

先解决什么问题

当团队讨论技术选型时，结论常常散落在聊天记录里；评审通过后，真正原因没人写下来；等到系统变重、人员更替，再有人问「当初为什么这么选」，只能翻 commit 或靠记忆。@user_460c76a2/arch-decision-advisor 要补上的缺口很具体：把架构决策从口头结论变成可检索、可追溯、可更新的记录，同时在分析现有代码结构时暴露技术债，避免错误沿错误决策继续放大。

核心能力与工作流程

这个技能围绕五件事展开：

• ADR（Architecture Decision Record）管理：按标准 ADR 格式记录决策上下文，生成的 Markdown 可直接放入项目的 docs/adr/ 目录。
• 技术债务识别：扫描代码库时关注过时依赖与框架、违反架构原则的设计、缺失的抽象层、硬编码与配置问题，以及关键路径测试覆盖不足。
• 架构模式推荐：根据场景给出可讨论的模式，例如微服务对应高并发、独立部署与团队自治；事件驱动对应松耦合、异步处理与审计追踪；CQRS 用于读写分离与复杂查询优化；六边形架构隔离业务逻辑并提升可测试性；领域驱动设计用于复杂业务建模与限界上下文划分。
• 决策影响分析：分别评估短期影响（开发效率、学习曲线）、长期影响（维护成本、扩展性、团队技能匹配）与风险因素（技术风险、业务风险、团队风险）。
• 决策追溯：建立决策图谱，记录决策之间的依赖关系、演进历史，以及被取代的决策与原因。

执行方式分三条主线。记录新决策时，先收集背景信息（问题、约束、利益相关者），再识别备选方案、评估利弊，生成 ADR 文档，并建立与现有决策的关联。分析现有架构时，扫描代码结构与依赖，识别架构模式和反模式，发现技术债务，生成架构健康报告并给出改进路径。做技术选型辅助时，先明确选型约束（性能、成本、团队技能等），列出候选方案，建立评估矩阵，进行权衡分析，最后输出选型建议报告。

适用边界与注意点

它是讨论与记录的助推器，不替代正式的架构评审流程；重大决策仍应团队讨论后确认。ADR 属于活文档，需要持续维护而不是归档即忘：记录决策原因而非只写结果，定期回顾验证是否仍然有效，并关联业务目标，避免纯技术导向。另一个常见原则是决策不可删除，只能被取代或弃用，这样后续追溯时才不会丢失上下文。使用时应尊重团队已有的架构约定，并保持 ADR 简洁，通常控制在 1–2 页内。