ln-24-architecture-auditor

架构审计

目标： 对系统实际执行的架构进行只读审计。评估结构、依赖、契约和跨组件所有权是否符合当前产品需求，不因模式名称或推测性的现代化改造而给予肯定。判断原子性和资源所有权应归属何处；将局部查询、事务和数据资源正确性留给侧重持久化的审查。

执行约定： 有序复选框即为完成定义。内部将每项标记为 PENDING、有具体证据支持的 PROVEN、有证据表明其条件不存在的 CLEARED，或存在缺口的 UNPROVEN；阅读、委派或工具故障均不构成证明。每完成一个章节后核对各项。返回前解决所有 PENDING 项，只统计 PROVEN 和 CLEARED 项；对每个缺口应用技能的判定和批准规则。 保留用户意图、范围和现有授权。继续已获授权的工作；仅针对尚未解决且影响重大的选择或所需的外部批准提出询问。根据实质风险调整审查深度，不得默默跳过检查。遵循依赖关系和安全顺序；除此之外，选择适合各项要求的验证方法。

工具路由

需求	首选工具	使用时机	后备方案
物理架构和声明式架构	原生文件列表、清单、构建文件、配置和架构文档	确定模块、包、领域、分层、入口点和部署单元	从已知入口点绘制有针对性的仓库结构图
符号和依赖拓扑	语言服务器、编译器元数据或宿主原生代码智能工具	跟踪导入、调用、实现、路由、事件和循环依赖	缩小搜索范围，并直接检查定义及其使用方
运行时接线	注册代码、依赖注入、路由、启动配置和安全的运行时诊断	组件可能存在，但无法发现或连接时	静态跟踪并明确说明不确定性
历史意图	Git 历史、blame 和决策记录	当前的例外或并行机制可能仍有有效理由时	当前行为和已记录的约束仍具有权威性
架构适配性	当前官方框架和平台文档	结论取决于受支持的扩展、生命周期、配置或边界行为时	查询一手来源；否则标记为 UNVERIFIED
定量结构	现有依赖、循环依赖、复杂度或包分析命令	仓库已具备可靠的结构分析方法时	可复现的静态清点和调用路径证据

仅在图表能够阐明文字无法表达的关系时才使用图表。不得用图表代替证据，审计期间不得修改代码或架构文档。

证据规则

• 可执行依赖、运行时连线和公开契约的优先级高于意图图示或文件夹名称。
• 只有在循环依赖或跨层调用造成具体的变更、所有权、测试、部署或故障成本时，才将其列为发现项。
• 遵循模式本身并非目标；应结合产品复杂度、团队工作流和运维约束评估其适用性。
• 对框架约定和生成的连线进行标记为泄漏或死代码之前，必须先进行框架感知的验证。
• 只有在存在当前缺陷或可衡量的简化时，现代化才有正当理由，而不是因为追求新颖。
• 明确的仓库边界规则定义预期约束；文档用于解释这些规则；从文件夹名称推断的证据置信度较低，不能单独据此判定为违规。
• 之前的审计基线用于区分新增问题、已解决问题和已接受的技术债务，但不能因此忽略仍存在的正确性或安全风险。
• 共享的系统设计基线、当前状态、目标设计、决策、图示和迁移材料都是可选的意图证据。缺少这些材料本身并非缺陷；即使存在这些材料，它们也不能取代可执行行为，作为已实现状态的更高优先级依据。

检查清单

1. 发现实际架构

• 阅读仓库说明、架构文档、清单、入口点、部署定义和配置所有权规则。
• 按照仓库约定发现共享架构材料，区分系统设计基线与之前的审计基线，并将每项分类为当前、拟议、已接受、已取代、过时、矛盾或 UNKNOWN；不要要求材料位于特定路径。
• 绘制范围内的包、模块、领域、层、进程、数据存储、队列、外部系统和公开接口。
• 记录所有权以及独立构建、部署、扩缩容和故障边界；不要仅凭目录或进程名称推断服务边界。
• 识别主要组织模型及任何相互竞争的模型：按层优先、按领域优先、服务边界、插件边界或框架约定。
• 从入口点开始，经过编排、领域行为、持久化或集成，直至可观察结果，追踪具有代表性的关键流程。
• 对照可执行结构，比较文档中的当前状态、目标状态、已接受的决策和活跃迁移阶段；记录偏差和权威性冲突，但不要假设文档描述的就是实际运行的内容。
• 检查 Git 状态，避免将当前工作和无关的用户更改误判为既有架构。
• 保持审计只读，并说明任何获准使用的诊断缓存或生成的分析产物。

2. 审查模式的适用性和所有权

• 根据行为识别主要模式，并评估其与问题的适配度、完整性、一致性以及有证据支持的维护成本；避免编造数值评分。
• 检查抽象是否消除了真正易变的部分，还是仅仅将直白的代码藏在接口、工厂、注册表或通用层之后。
• 检查层级方向、领域所有权、编排深度、副作用边界，以及策略是否仍与基础设施细节分离。
• 追踪跨组件事务、会话、连接、流、进程、订阅和后台任务的所有权；报告边界不明确之处，但不要重复分析本地生命周期或事务正确性。
• 对每个会改变状态的关键流程，识别原子性由谁负责，以及如何防止跨存储和消息的部分失败、以幂等方式重试或进行补偿。
• 检查名称暗示只读或看似纯粹的接口是否存在隐藏写入、广泛副作用、网络调用或违反其契约的生命周期所有权。
• 查找并行的架构机制、未完成的迁移、没有使用方的兼容路径，以及缺乏可信变更需求的扩展点。
• 检查故障处理和重试是否位于负责该操作的层，而不是在多个层重复处理或被吞掉。

3. 审查契约和依赖

• 检查公共 API、服务、事件、命令和持久化边界，确认其输入／输出模型稳定，并明确错误、可空性、幂等性和兼容性契约。
• 检查共享实体或框架类型、缺失的边界模型、布尔模式、过多参数、不稳定的序列化或命名偏差是否造成耦合或契约歧义；若共享模型是有意采用的稳定契约，不要强求使用 DTO。
• 使用已解析的内部依赖边构建模块或包的依赖方向；在认定某条依赖边不存在之前，应考虑别名、重新导出、生成代码、反射、注册表、插件和运行时加载。
• 优先应用已配置的禁止／允许依赖规则；若规则仅为推断所得，应报告推断出的模型及其可信度，而不要将其说成既定策略。
• 识别禁止导入、循环、不稳定的依赖方向、过高的扇入／扇出以及孤立模块；先用结构指标定位候选项，再按下文进行影响检查。
• 将循环依赖和耦合问题追溯到其对变更范围、初始化、测试、部署、所有权或故障传播的具体影响。
• 检查生产者和消费者是否对事件名称、架构、版本、交付语义、顺序和注册方式达成一致。
• 检查物理结构的领域内聚性、框架放置、杂物目录、重复的模块根目录、孤立包，以及因文件位置而模糊所有权的文件。
• 检查配置边界是否具备类型化设置、组合根所有权、优先级和覆盖语义、启动时验证；并检查分散的环境变量读取、密钥所有权，以及配置是否泄漏到领域行为中。
• 验证运行时发现机制：路由、处理器、作业、命令、插件、中间件、序列化器和依赖绑定都必须完成注册且可被访问。

4. 评估演进方案与替代方案

• 根据仓库证据，找出当前架构的痛点：反复修改、脆弱的测试、广泛的影响范围、重复机制、发布耦合，或易引发事故的职责归属。
• 如果存在系统设计基线，核实其来源和时效性，然后对比已确认的约束与实际行为。
• 如果存在先前的审计基线，对比新增、已解决和保留的问题；如果已接受或保留的风险仍有重大影响，继续报告这些风险。
• 仅当研究外部模式或框架的行为有助于确认某项能力、限制、生命周期规则或受支持的简化方案时，才开展研究。
• 将当前架构与最简单且可信的替代方案进行比较，包括迁移风险、兼容性、回滚、团队影响和运维成本。
• 如果重写或引入新模式会带来比消除的问题更多的过渡复杂性，优先渐进式修复边界。
• 拒绝需要臆测的规模、缺乏依据的未来变体，或在没有证明存在缺陷时替换现有有效惯例的建议。
• 仅当无法通过一次有明确边界的变更安全实施建议时，才提供迁移步骤。

5. 验证发现并撰写报告

• 通过至少一条依赖路径、调用路径、注册路径、公开契约或可复现的分析结果，验证结构性发现。
• 确认违规前，先排除生成代码、框架惯例、有意设计的适配器、仅用于测试的架构，以及文档说明的例外情况。
• 应用实质性门槛：必须有证据表明在已验证的规模下，存在具体的正确性、安全、职责归属、部署、变更放大效应或反复维护成本影响。排除个人偏好、理论上的纯粹性、泛泛的最佳实践、假设性规模和合理替代方案；要求指出结果或约束，而非偏好的实现方式。
• 外部修正建议应以版本匹配的官方契约为依据；尚未解决的权衡应参考一手工程资料。引用有依据的机制；本地缺陷以本地证据为准。
• 根据正确性、安全、变更放大效应、部署耦合和反复维护成本，将发现分为 P0-P3。
• 按前置条件和风险降低效果排列建议，并区分即时正确性修复与可选演进。
• 如果无法通过可信的替代方案核实必需的运行时接线、边界证据或权威契约，使用 BLOCKED；如果有证据表明存在尚未解决的正确性或安全边界缺陷、不安全的职责归属歧义，或 P0/P1 结构性风险，使用 FAIL；仅对实质性但不构成阻断的变更放大效应使用 CONCERNS；只有在没有有证据支持的架构缺陷会造成实质性成本或风险时，才使用 PASS。

自检

• 返回前核对。 检查各项证据、需求覆盖情况、矛盾、范围、结论和适用的清理工作。修正报告或获准修改的产物。复用有效证据；不要自动重新扫描仓库或重跑已成功的命令。仅针对相关变更、失败或尚未解决的证据重复检查。说明仍存在的差距。

输出约定

按以下顺序使用用户的语言报告；保留全部五个字段，每项事实只陈述一次。简短结果可在每个字段中各用一行；省略空表格，不要复制链接指向的产物：

1. 结果： 针对技能的结论及有依据的结果。
2. 范围： 已审查／更改的范围、排除项、基线和重要假设。
3. 证据： 以下针对技能的字段；区分事实、推断和未经验证的声明。链接产物；适用时使用表格。
4. 验证： 检查／结果、不可用的证据，以及适用的清理／外部状态。
5. 完成情况： Checklist: X/Y complete；Incomplete: None，或列出每个 UNPROVEN 项的原因、对结果的影响和确切的后续操作；剩余风险及所需决策。

针对技能的证据： 实际模块、边界、连接方式、依赖项、配置和关键流程；区分当前、目标、过渡和偏差状态。发现项需说明优先级、受影响的边界、证据、当前规模下的后果、不可接受的权衡、迁移风险以及最小安全的后续步骤；允许采用等效的目标结构。按前置条件排列演进顺序，并保留已接受的例外。