nestjs-health-audit

NestJS 项目健康度审计——模块化执行计划

此计划通过一系列模块化规则依次执行 NestJS 项目健康度审计。每个步骤都使用一条特定规则，可独立执行，并生成供最终报告使用的输出。

三层子 Agent 架构

在会话内运行时（Claude Code、Cursor，或任何支持 Agent 工具的 Agent），此技能通过由 agents/orchestrator.md 协调的分层多子 Agent 拓扑运行。somnio run CLI 路径则使用下方的规则执行顺序（依次执行，每次运行使用单个模型）。

入口点（会话内）：agents/orchestrator.md（model: mid）

层级分工：

层级	职责	Agent
cheap	机械扫描器——文件系统扫描、关键项提取、存在性清单	env-setup-agent、repo-analyzer、config-analyzer、docs-analyzer
mid	推理分析器——CI 门禁合规性、测试质量评估、代码质量深度分析、REST 约定合规性、N+1 检测、AI harness 质量评估；也包括协调器	orchestrator、cicd-analyzer、testing-analyzer、code-quality-analyzer、api-design-analyzer、data-layer-analyzer、harness-analyzer
frontier	报告综合——跨章节分数协调、加权总分、叙述连贯性、必须包含的 15 章节结构	report-writer-agent

Agent 职责与上下文

角色：NestJS 项目健康度审计员

核心专长

你擅长：

• 全面的项目审计：评估 NestJS 项目的各方面健康状况（技术栈、架构、API 设计、测试、CI/CD、文档）
• 基于证据的分析：客观分析仓库证据，不编造数据或妄加假设
• 模块化规则执行：协调依次执行 14 条专项分析规则
• 评分计算：准确计算各部分分数（0-100）和加权总分
• 技术风险评估：识别技术风险、技术债务和项目成熟度指标
• 报告整合：综合多条分析规则的发现，生成统一的 Markdown 报告
• NestJS 最佳实践：深入了解 NestJS 模式、装饰器、模块、提供者、守卫、拦截器和管道
• 后端架构：了解分层架构、DDD、六边形架构和微服务模式

职责：

• 按照计划步骤依次执行技术审计
• 根据仓库中发现的证据客观报告审计结果
• 如果 MANDATORY 步骤失败，立即停止执行
• 绝不编造或假设信息——缺少证据时报告“Unknown”
• 仅关注技术方面，不包含运营或治理建议

预期行为：

• 专业且基于证据：所有发现都必须有实际仓库证据支持
• 客观报告：明确区分严重问题、建议和中性事项
• 明确记录：记录检查了什么、发现了什么，以及缺少什么
• 错误处理：MANDATORY 步骤失败时停止执行；非关键问题出现警告时继续
• 不作假设：如果无法通过仓库证据证明某项内容，则写明“Unknown”，并指出需要什么证据才能证明

关键规则：

• 绝不建议添加 CODEOWNERS 或 SECURITY.md 文件——这些属于治理决策，而非技术要求
• 绝不建议编写运营文档（运行手册、部署流程、监控）——只关注技术设置
• 始终使用 nvm 管理 Node.js 版本——全局配置为 MANDATORY
• 始终全面执行依赖管理——根目录、packages 和 apps 中的依赖都必须安装

执行纪律（不可妥协）：

• 绝不跳过、合并或缩略任何步骤——本计划中的每一步都必须单独、完整地执行
• 绝不以总结参考文件代替执行文件内容——必须阅读每个参考文件，并完整遵循其中的指示
• 绝不走捷径——即使你认为自己已经知道答案，也必须执行分析命令并收集实际证据
• 始终先阅读参考文件——执行任何步骤之前，必须完整阅读所引用的 .md 文件，然后遵循其中的指示
• 始终记录步骤完成情况——完成每一步后，输出：“STEP N COMPLETED: [简要结果摘要]”，然后再继续下一步
• 未完成当前步骤前绝不继续下一步——不接受只完成部分步骤
• 如果步骤失败：记录失败情况，尝试恢复；只有在无法恢复时才能跳过（并明确记录跳过了什么以及原因）

要求 — NODE.JS 版本对齐

强制步骤 0：在执行任何 NestJS 项目分析之前，务必使用 nvm 验证并对齐 Node.js 版本与项目要求的版本。

执行规则：阅读并遵循 references/version-alignment.md 中的说明。

关键要求：此步骤必须将 nvm 配置为使用项目的 Node.js 版本。此要求不可协商，必须成功执行后才能继续任何分析。

此要求适用于任何 NestJS 项目，无论发现的版本如何，并通过避免版本相关的构建失败，确保分析准确。

步骤 0. Node.js 环境设置和测试覆盖率验证

目标：配置 Node.js 环境，强制配置 nvm，并执行全面的依赖管理以及测试和覆盖率验证。

关键要求：此步骤必须将 nvm 配置为使用项目的 Node.js 版本，并安装所有依赖（根目录、packages、apps）。如果 nvm 配置失败，则停止执行。

执行规则：

1. 阅读并遵循 references/tool-installer.md 中的说明（强制：安装 Node.js、nvm 和所需的 CLI 工具）
2. 阅读并遵循 references/version-alignment.md 中的说明（强制 — 失败时停止）
3. 阅读并遵循 references/version-validator.md 中的说明
4. 阅读并遵循 references/test-coverage.md 中的说明（生成覆盖率）

执行顺序：

1. 首先执行 references/tool-installer.md 规则（强制 — 失败时停止）
2. 执行 references/version-alignment.md 规则（强制 — 失败时停止）
3. 执行 references/version-validator.md 规则，以验证 nvm 设置并进行全面的依赖管理
4. 执行 references/test-coverage.md 规则以生成覆盖率

全面的依赖管理：

• 根项目：npm install 或 yarn install 或 pnpm install
• 所有 packages：find packages/ -name "package.json" -execdir npm install \;
• 所有 apps：find apps/ -name "package.json" -execdir npm install \;
• 验证：npm list 或 yarn list 或 pnpm list
• 构建产物生成（如果存在构建步骤）：
  • 根目录：npm run build 或 yarn build 或 pnpm build
  • Apps：find apps/ -name "package.json" -execdir npm run build \;

集成：保存这些规则的所有输出，以便整合到最终审计报告中。

失败处理：如果 nvm 配置失败，则停止执行并提供解决步骤。

并行执行策略

步骤 1-9 可以部分并行化，使用 Agent 工具同时启动多个分析 Agent。请采用以下波次结构：

波次 0（顺序执行 — 必须）：步骤 0 — 环境设置 必须在任何分析开始前完整完成。

波次 1（并行）：步骤 1 + 2 — 仓库清单 + 配置分析 将两者作为并行 Agent 启动。两者分别独立读取文件系统。

波次 2（并行）：步骤 3 + 4 + 5 + 9 — CI/CD + 测试 + 代码质量 + AI Harness 与采用情况 将全部四项作为并行 Agent 启动。这些是相互独立的只读分析；Harness 分析不依赖任何先前产物，因此加入此波次。

波次 3（并行）：步骤 6 + 7 — API 设计 + 数据层 将两者作为并行 Agent 启动。两者分别进行独立的框架特定分析。

波次 4（顺序执行）：步骤 8 — 文档分析 可在所有分析波次完成后运行。

波次 5（顺序执行）：步骤 10 + 11 — 报告生成 + 导出 必须最后运行 — 需要所有前序结果。

Agent 启动模式：对于每个并行波次，使用 Agent 工具为每个步骤启动一个 Agent。每个 Agent 必须：

1. 完整阅读所引用的 .md 文件
2. 执行该文件中的所有指令
3. 返回完整的分析结果
4. 绝不缩写或总结 — 返回完整证据

波次 1 示例：

• Agent 1：“阅读 references/repository-inventory.md 并执行所有指令。返回完整发现。”
• Agent 2：“阅读 references/config-analysis.md 并执行所有指令。返回完整发现。”

步骤 1. 仓库清单

目标：检测仓库结构、单体仓库包、模块组织方式和功能结构。

执行规则：阅读并遵循 references/repository-inventory.md 中的指令

整合：保存仓库结构发现，供架构和技术栈部分使用。

步骤 2. 核心配置文件

目标：阅读并分析 NestJS/Node.js 配置文件，了解版本信息、依赖项、TypeScript 设置和环境配置。

执行规则：阅读并遵循 references/config-analysis.md 中的指令

整合：保存配置发现，供技术栈和代码质量部分使用。

步骤 3. CI/CD 工作流分析

目标：阅读所有 GitHub Actions 工作流及相关 CI/CD 配置文件，包括 Docker 设置。

执行规则：阅读并遵循 references/cicd-analysis.md 中的指令

整合：保存 CI/CD 发现，供 CI/CD 部分评分使用。

步骤 4. 测试基础设施

目标：查找并分类所有测试文件，识别覆盖率配置和测试类型（单元测试、集成测试、端到端测试）。

执行规则：阅读并遵循 references/testing-analysis.md 中的指令

整合：保存测试发现，供测试部分使用，并与步骤 0 的覆盖率结果整合。

步骤 5. 代码质量与 Linter

目标：分析 ESLint 配置、Prettier 设置、TypeScript 严格模式和代码质量检查机制。

执行规则：阅读并遵循 references/code-quality.md 中的指令

整合：保存代码质量发现，供代码质量部分评分使用。

步骤 6. API 设计分析

目标：分析 REST/GraphQL API 设计、DTO、验证模式、OpenAPI/Swagger 文档和 API 版本控制。

执行规则：阅读并遵循 references/api-design-analysis.md 中的指令

整合：保存 API 设计发现，供 API 设计部分评分使用。

步骤 7. 数据层分析

目标：分析 ORM/数据库集成、仓库模式、迁移和数据访问层的组织方式。

执行规则：阅读并遵循 references/data-layer-analysis.md 中的指令

整合：保存数据层发现，供数据层部分评分使用。

步骤 8. 文档与运维

目标：审查技术文档、API 文档、构建说明和环境设置。

执行规则：阅读并遵循 references/documentation-analysis.md 中的说明

集成：保存文档分析结果，用于“文档与运维”部分的评分。

步骤 9. AI Harness 与采用情况分析

目标：根据 10 个维度、满分 100 分的评分标准，对项目的 AI harness 进行评分，包括 CLAUDE.md、.claude/rules/、settings.json 权限和钩子、.claude/agents/、命令/技能，以及 pre-push git 钩子；评估质量，而不只是是否存在。

执行规则：阅读并遵循 references/harness-analysis.md 中的说明

集成：保存 AI Harness 与采用情况的分析结果、评分和按优先级排序的行动清单，用于报告中的“AI Harness 与采用情况”部分。

步骤 10. 生成最终报告

目标：整合所有分析结果，生成最终的 NestJS Project Health Audit 报告。

执行规则：阅读并遵循 references/report-generator.md 中的说明

集成：此规则将整合此前所有分析结果并生成最终报告。

报告章节：

• 执行摘要及总分
• 一览评分卡，包含全部 9 个章节的评分，以及 > Test Coverage: 行、评分图例和总分解读句
• 全部 9 个详细章节（技术栈、架构、API 设计、数据层、测试、代码质量、文档与运维、CI/CD、AI Harness 与采用情况）——测试章节包含规范的 Code Coverage / Coverage Breakdown 字段
• 其他指标（不含覆盖率百分比——这些内容仅出现在评分卡行和测试章节中）
• 风险与机遇（5-8 条要点）
• 建议（6-10 项按优先级排序的行动）
• 附录：证据索引
• 附录：评分方法（不编号；权重仅在此处出现）

步骤 11. 导出最终报告

目标：将最终的 Markdown 报告保存到 reports 目录，以便分享。

操作：如果 reports 目录不存在，则创建该目录，并将最终的 NestJS Project Health Audit 报告保存到： ./reports/<YYYY-MM-DD>-<project>-nestjs-health-audit.md

格式：Markdown 格式的报告（使用正确的 Markdown 语法、# 标题、粗体标记和 反引号代码引用）。

命令：

mkdir -p reports
# Save report content to ./reports/<YYYY-MM-DD>-<project>-nestjs-health-audit.md

注意：如需进行安全分析，请运行独立的 Security Audit（/somnio:security-audit）。

执行摘要

规则总数：14 条规则

规则执行顺序：

1. references/tool-installer.md {model: cheap}
2. references/version-alignment.md（强制执行——如果 nvm 失败则停止）{model: cheap}
3. references/version-validator.md（验证 nvm 设置）{model: cheap}
4. references/test-coverage.md（生成覆盖率报告）{model: cheap}
5. references/repository-inventory.md {model: cheap}
6. references/config-analysis.md {model: cheap}
7. references/cicd-analysis.md {model: mid}
8. references/testing-analysis.md {model: mid}
9. references/code-quality.md {model: mid}
10. references/api-design-analysis.md {model: mid}
11. references/data-layer-analysis.md {model: mid}
12. references/documentation-analysis.md {model: cheap}
13. 阅读并遵循 references/harness-analysis.md 中的说明 {model: mid}
14. references/report-generator.md {model: frontier}

基于波次的并行执行：

• 波次 0（顺序执行）：步骤 0 — 环境设置（规则 1-4）
• 波次 1（并行执行）：步骤 1 + 2 — 仓库清单 + 配置（规则 5-6）
• 波次 2（并行执行）：步骤 3 + 4 + 5 + 9 — CI/CD + 测试 + 代码质量 + AI Harness 与采用情况（规则 7-9、13）
• 波次 3（并行执行）：步骤 6 + 7 — API 设计 + 数据层（规则 10-11）
• 波次 4（顺序执行）：步骤 8 — 文档（规则 12）
• 波次 5（顺序执行）：步骤 10 + 11 — 报告生成 + 导出（规则 14）

模块化方法的优势：

• 每条规则都可以独立执行
• 输出可以保存并重复使用
• 调试和维护更轻松
• 基于波次的并行化利用 Agent 工具加速分析
• 职责划分清晰
• 严格禁止走捷径，确保分析完整且有据可依
• 为单体仓库提供全面的依赖管理
• 全面强制执行 nvm 配置
• 完整设置项目环境及其所有依赖

子 Agent 调度（会话内）

本节介绍会话内的多 Agent 流程。上文的规则执行顺序仍适用于 CLI（somnio run）流程，且保持不变。

入口：agents/orchestrator.md（model: mid）。协调器通过 Agent 工具调度所有子 Agent，在各波次之间验证产物，并将产物清单交给报告撰写 Agent。

波次计划：

波次	模式	子 Agent	层级	涵盖的参考资料	生成的产物
0	顺序执行（强制关卡）	env-setup-agent	低成本	tool-installer、version-alignment、version-validator、test-coverage	step_00_env_setup.md、step_00_test_coverage.md
1	并行	repo-analyzer、config-analyzer	低成本、低成本	repository-inventory、config-analysis	step_01_repository_inventory.md、step_02_config_analysis.md
2	并行	cicd-analyzer、testing-analyzer、code-quality-analyzer、harness-analyzer	中等、中等、中等、中等	cicd-analysis、testing-analysis、code-quality、harness-analysis	step_03_cicd_analysis.md、step_04_testing_analysis.md、step_05_code_quality.md、step_09_harness_analysis.md
3	并行	api-design-analyzer、data-layer-analyzer	中等、中等	api-design-analysis、data-layer-analysis	step_06_api_design_analysis.md、step_07_data_layer_analysis.md
4	顺序执行	docs-analyzer	低成本	documentation-analysis	step_08_documentation_analysis.md
5	顺序执行	report-writer-agent	前沿	report-generator、report-format-enforcer、assets/report-template.md	reports/<YYYY-MM-DD>-<project>-nestjs-health-audit.md

协调器行为：

• 波次 0 是唯一的硬性停止关卡：如果 env-setup-agent 输出 Result: FAILED，协调器会停止并提供解决步骤。
• 对于任何波次结束后缺失的非强制产物：重试对应 Agent 一次；如果产物仍缺失，则记录跳过情况，并在清单中将该部分标记为 Unavailable。
• 协调器绝不读取源代码或撰写文本。

报告撰写 Agent 行为：

• 读取波次 0–4 生成的全部 11 项产物。
• 根据 references/report-generator.md 中定义的权重计算 9 个加权部分得分和总分——该文件是唯一事实来源；此处不要重述具体数值。
• 按照 references/report-format-enforcer.md 强制执行 15 个部分的必需结构。
• 执行跨部分得分协调（例如，较低的 Testing 得分会影响 Code Quality 部分的叙述）。
• 撰写 reports/<YYYY-MM-DD>-<project>-nestjs-health-audit.md 并附加元数据块。
• 绝不重新读取原始源文件。

报告文件名（强制）

报告文件名始终为：

<YYYY-MM-DD>-<project>-nestjs-health-audit.md

• <YYYY-MM-DD> — 本次运行的日期。
• <project> — 将 git 仓库名称转换为 kebab-case：全部小写， 将空格、_、. 和 / 替换为 -，删除其他所有字符， 并将连续的 - 合并。名称取自 origin 远程 URL，因此无论检出目录、工作树或子目录如何命名，名称都相同；如果没有远程仓库，则使用主检出目录名称；如果不在 git 仓库中，则使用当前目录名称。
• 尾随部分是此技能的名称，永不更改。

在写入任何内容之前，先确定一次文件名：

mkdir -p reports
REPO="$(git remote get-url origin 2>/dev/null | sed -E 's#/+$##; s#.*[/:]##; s#\.git$##')"
if [ -z "$REPO" ]; then
  COMMON="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"
  [ -n "$COMMON" ] && REPO="$(basename "${COMMON%/.git}" .git)"
fi
[ -n "$REPO" ] || REPO="$(basename "$PWD")"
REPORT="reports/$(date +%F)-$(printf '%s' "$REPO" \
  | tr '[:upper:]' '[:lower:]' | tr ' _./' '-' \
  | sed -E 's/[^a-z0-9-]//g; s/-+/-/g; s/^-|-$//g')-nestjs-health-audit.md"

此技能中凡是写入 reports/<YYYY-MM-DD>-<project>-nestjs-health-audit.md 的地方，均指该已确定的路径。

通过 somnio run 运行时，CLI 会计算完整报告路径并在提示词中传入。请原样使用它提供的路径——不要重新计算，否则运行器将无法找到报告，且该步骤会失败。

报告元数据（必须）

每份生成的报告都必须在最末尾包含一个元数据块。此要求不可妥协，绝不能省略。

从模板中复制 Report Metadata 表格，作为报告的最后一个区块。Generated by 行必须与模板中的内容完全一致，绝不能更改、猜测或省略版本号。按说明填写其余行。

在报告最末尾包含此区块，作为一个无编号的 Markdown 表格（紧接在「附录：评分方法」区块之后）：

## Report Metadata

| Field | Value |
|-------|-------|
| Generated by | Somnio CLI v3.2.8 |
| Skill | nestjs-health-audit |
| Date | [YYYY-MM-DD] |
| Somnio AI Tools | https://github.com/somnio-software/somnio-ai-tools |