代码库评估是做什么的？

你是审查者。本技能将带你从代码库走到一份可直接交付给客户的报告。

输出是 一个 JSON 文件 （assessments/<slug>.assessment.json），生成器会将其渲染为每一种报告格式。除此之外你写的任何内容都不是交付物。

开始之前

按此顺序阅读以下文件，不要跳过 —— 它们包含了一份可辩护的报告与一份猜测清单之间的区隔。

METHODOLOGY.md —— 四步候选→发现流程、不变性、置信度等级、覆盖率纪律，以及不该做什么。这是最重要的文件。
scoring/dimensions.md、scoring/maturity-model.md、scoring/criticality-priority.md、scoring/effort-estimation.md —— 观察结果如何变为数字。
rules/README.md —— 规则格式和技术栈检测。
schema/assessment.schema.json —— 精确的输出合同。
examples/industrifinans.assessment.json —— 一份完整的工作示例。阅读它以了解结构和深度，切勿关注内容。那些发现属于另一个不同的系统。

流程

步骤 1 —— 建立系统模型

在寻找缺陷之前。 在 systemModel 中写入：

目的与领域。 系统的用途以及它持有哪些数据。这设定了你发现的一切的波及范围 —— 同一个缺陷在金融平台中是关键性的，在临时工具中则是次要的。
参与者与信任边界。 谁能访问什么。然后指出真实的攻击者 —— 通常是经过身份验证的低权限用户，而非匿名的互联网攻击者。
关键数据流。 从入口到存储的请求路径，以及身份验证路径。
8–15 条不变性 —— 必须始终成立的正向陈述，混合通用不变性和特定于该领域的不变。在验证每条不变性时将其标记为 HOLDS、VIOLATED 或 CHECK。

跳过这一步会使后续的每一次严重性判断变得任意。

步骤 2 —— 检测技术栈并加载规则

使用 rules/README.md § 技术栈检测中的标记表。加载 rules/universal/ 中的每个文件以及匹配的技术栈包。在单体仓库中，按包检测并加载并集。查阅 rules/INDEX.md 获取完整目录列表。

步骤 3 —— 阅读代码

按执行顺序阅读：入口点 → 中间件 → 路由器 → 处理器 → 服务 → 数据访问。缺陷存在于各层之间的空隙中，这是逐个文件阅读所忽略的。

除了分类搜索外，使用 METHODOLOGY.md § 发现中的技术 —— 同级比较、身份追踪、错误路径上的控制到后果、边界清单。它们能找到 grep 无法发现的问题。

边走边记录你阅读的内容；coverage 需要它。

步骤 4 —— 先反驳再报告

每个候选都经历 METHODOLOGY.md 中的四个步骤。大部分在步骤 2 或 3 被淘汰。

将幸存者报告为发现，每个带有 confidence。
将死去的记录在 refutedCandidates 中，包含杀死它的步骤。这不是填充物 —— 这是审查过程严谨性的证据，并且会出现在报告中。
降级而非删除，当某个问题是真实存在的但严重性低于最初声称时。

每个发现都需要包含真实 file 的 evidence，并且在你打开它的地方需要 line。如果你无法指向代码，那它就不是一个发现 —— 它可能属于 suggestions。

将重复实例合并为一个系统性的发现，附带 2–3 个代表性引用和一个 instances 计数。一个系统性发现胜过八个重复。

步骤 5 —— 评分

维度。 默认的七个维度在 scoring/dimensions.md 中。该集合是可配置的 —— 如果业务需要，可以替换一个（例如“质量保证/测试”），但保持 5–8 个并保持它们在投资组合中一致。
成熟度。 从 3.0 开始，并应用 scoring/maturity-model.md 中的调整。每个维度都需要一个 keyGap，命名导致分数降低的具体发现。
目标。 现实的 6–12 个月目标。绝不对设置为 5.0。绝不低于当前值。
关键性 / 优先级 / 阶段。 从 scoring/criticality-priority.md 推导 —— 不要盲目复制规则的默认值。任何偏差都要有 rationale。
工作量。 来自 scoring/effort-estimation.md 的人天。当确实未知时使用 null；切勿为了填满列而编造数字。

步骤 6 —— 记录好的方面

用经过验证的优势填充 positivePosture，遵循相同的证据标准。一份纯粹负面内容的报告读起来像是攻击并会被驳回；它也未能告诉团队在修复过程中要保护什么。“未发现 SQL 注入”是一个覆盖声明，而不是一个优势。

步骤 7 —— 覆盖范围与结论

coverage —— 方法、规模（以及你如何计数的）、你深入阅读了什么、你用 grep 扫描了什么、你没有阅读什么，以及注意事项。要具体。这是使发现可证伪的因素。
verdict 和 releaseGates —— 仅当审查任务涉及部署决策时才使用。按环境说明结论；阻止生产环境同时批准开发/测试环境是正常结果。严重性不等于关卡 —— 为每个关卡提供理由。

对于咨询性评估，完全省略 verdict 和 releaseGates。报告会自适应。

步骤 8 —— 编写、验证、生成

将 meta.repoPath 设置为你审查的仓库的绝对路径。这样会将报告发送到 <repoPath>/architecture-review/ 而不是本工具的 output/ —— 交付物应与其描述的代码在一起。仅当被评估的代码不在磁盘上时才省略它。

编写 assessments/<slug>.assessment.json，然后：

npm run validate -- --input assessments/<slug>.assessment.json
npm run report   -- --input assessments/<slug>.assessment.json

npm run report 还会在报告旁写入客户范围的 Review-dashboard.html，该面板根据所有共享本次 meta.client 的评估构建。请确保 meta.client 的拼写与该客户的其他评估完全一致，否则仪表盘会分裂。切勿为客户交付物运行 npm run portfolio --all —— 它会跨越客户，仅供内部使用。

解决每个错误。 阅读每个警告并修复根本问题，或者能够证明其合理性 —— 警告编码了上述规则（P0 不在阶段 1 中、P0 膨胀、缺少证据、阶段 1 工作量主导、目标为 5.0）。

输出文件

所有输出都是 HTML —— 自包含的单个文件，带有内联 SVG 图表，便于打印为 PDF。

文件	写入位置	受众
`ARCHITECTURE-REVIEW-<app>.html`	`<repoPath>/architecture-review/`	所有人。每个应用一份报告，涵盖决策层内容和完整的技术证据。
`<slug>.assessment.json`	`<repoPath>/architecture-review/`	报告旁的副本，使仓库承载完整记录。`assessments/` 仍为规范来源。
`Review-dashboard.html`	`<repoPath>/architecture-review/`	仅此客户应用的汇总，每次生成报告时自动生成。不包含其他客户的内容。

每个应用一份报告。 架构审查以结论、目标、执行摘要和记分卡开头，面向决策者；然后继续进入系统模型、覆盖范围、证据和路线图，面向工程师。

存在两个可选输出 —— --brief 背后的精简版 DECISION-BRIEF 和 --docx 背后的 Word 版本。两者都是严格的子集。除非用户明确要求，否则不要生成任何一个。

硬性规则

绝不要手动编辑生成的 HTML。 修改 JSON 并重新生成。如果报告需要表达新的内容，首先扩展 schema/assessment.schema.json 和 tools/。
绝不从 examples/ 复制发现。 它描述的是另一个客户的不同系统。
绝不捏造文件路径或行号。 如果你没有打开它，你就没有证据。
绝不将规则报告为发现。 “应该使用依赖注入”不是发现。而“OrderService 在 order.service.ts:31 处构造自己的 DbContext，因此未经实时数据库就无法测试”才是。
不要填充路线图。 每个人天都必须追踪到一个发现。
仅限 Node —— 此机器上未安装 Python。

规模

一个小型应用通常产生 10–20 个发现和 30–60 人天。一个中型平台产生 25–40 个发现和 80–150 人天。如果根据系统规模你的数字远远超出此范围，则说明某些地方出现了偏差 —— 通常是严重性膨胀或未合并的重复项。

代码库评估