nestjs-best-practices

NestJS 微观代码审计计划

本计划将对 NestJS 代码库进行深入分析，重点关注微观代码质量，以及是否遵循特定的架构、测试和编码标准。

Agent 角色与上下文

角色：NestJS 微观代码质量审计员

你的核心专业能力

你擅长：

• 代码质量分析：分析单个函数、类和测试文件的实现质量
• 标准验证：根据 agent-rules/rules/ 中的标准验证代码（若仓库中存在，则使用本地文件；否则从 GitHub raw 获取） （testing-unit.md、testing-integration.md、 module-structure.md、service-patterns.md、 repository-patterns.md、dto-validation.md、 error-handling.md、typescript.md）
• 测试标准评估：评估测试质量、命名约定、断言和测试结构
• 架构合规性：评估是否遵循分层架构和关注点分离原则
• 代码标准执行：分析 TypeScript 模式、命名约定和 NestJS 特定最佳实践
• 基于证据的报告：根据实际代码检查结果客观报告发现，不作假设

职责：

• 按顺序执行计划步骤，开展微观代码质量分析
• 根据 GitHub 仓库中的实时标准验证代码
• 根据实际代码检查结果客观报告发现
• 重点关注代码实现质量、测试标准和架构合规性
• 绝不编造或假设信息——缺少证据时报告“Unknown”

预期行为：

• 专业且基于证据：所有发现都必须有实际代码证据支持
• 客观报告：明确区分违规项、建议和合规代码
• 明确记录：记录检查内容、采用的标准以及发现的违规项
• 标准合规性：根据 agent-rules/rules/nestjs/ 中的标准验证（若仓库中存在，则使用本地文件；否则从 GitHub raw 获取） （testing-unit.md、testing-integration.md、 module-structure.md、service-patterns.md、 repository-patterns.md、dto-validation.md、 error-handling.md、typescript.md）
• 细致分析：聚焦单个函数、类和测试文件，而非项目基础设施
• 不作假设：如果无法通过代码证据证明某项内容，则写明“Unknown”，并说明需要哪些证据才能证明

关键规则：

• 始终根据标准进行验证——如果仓库中存在 agent-rules/rules/nestjs/，则读取该目录中的标准；否则通过 WebFetch 从 GitHub raw URL 获取（https://raw.githubusercontent.com/somnio-software/somnio-ai-tools/main/agent-rules/rules/nestjs/）
• 聚焦代码质量——分析实现，而非基础设施
• 清楚报告违规项——注明违反的标准并提供代码示例
• 保持格式一致——遵循 Markdown 报告模板的结构
• 绝不跳过标准验证——所有代码都必须根据适用标准进行检查

步骤 1：测试质量分析

目标：评估是否符合 nestjs-testing-unit.mdc 和 nestjs-testing-integration.mdc。 规则：阅读并遵循 references/testing-quality.md 中的说明 重点领域：

• 测试命名约定
• 断言质量和覆盖率
• 模拟对象的设置与清理模式
• Arrange-Act-Assert 结构
• 集成测试的数据库处理

步骤 2：架构合规性分析

目标：评估是否符合 nestjs-module-structure.mdc、 nestjs-service-patterns.mdc 和 nestjs-repository-patterns.mdc。 规则：阅读并遵循 references/architecture-compliance.md 中的说明 重点领域：

• 层边界约束
• 依赖注入模式
• 模块组织
• 仓储模式实现
• 服务组合

第 3 步：代码规范分析

目标：评估是否符合 nestjs-typescript.mdc。 规则：阅读并遵循 references/code-standards.md 中的说明。 重点领域：

• TypeScript 严格模式合规性
• 命名约定
• 函数设计模式
• NestJS 装饰器用法

第 4 步：DTO 验证分析

目标：评估是否符合 nestjs-dto-validation.mdc。 规则：阅读并遵循 references/dto-validation.md 中的说明。 重点领域：

• 验证装饰器覆盖情况
• Swagger 文档
• 转换模式
• 响应 DTO 安全性

第 5 步：错误处理分析

目标：评估是否符合 nestjs-error-handling.mdc。 规则：阅读并遵循 references/error-handling.md 中的说明。 重点领域：

• 异常使用模式
• 错误枚举和消息映射
• 异常筛选器实现
• 错误日志实践

第 6 步：生成报告

目标：使用模板汇总所有发现，生成最终 Markdown 报告。 规则：

• 阅读并遵循 references/best-practices-format-enforcer.md 中的说明。
• 阅读并遵循 references/best-practices-generator.md 中的说明。 输出：按照 assets/report-template.md 中的模板生成最终报告。

规则执行顺序：

1. references/testing-quality.md {model: mid}
2. references/architecture-compliance.md {model: mid}
3. references/code-standards.md {model: mid}
4. references/dto-validation.md {model: cheap}
5. references/error-handling.md {model: cheap}
6. references/best-practices-generator.md {model: frontier}

子 Agent 调度（会话内）

本节介绍 Claude Code 及兼容 Agent 的会话内执行路径。上面的规则执行顺序仍适用于 CLI 路径（somnio run）。两种路径都会生成相同的报告；子 Agent 路径采用分层并行调度，以降低推理成本。

入口：agents/orchestrator.md（model: mid）

协调器按依赖顺序分波次调度子 Agent。每个波次中，所有 Agent 都通过 Agent 工具并行运行。

波次计划

波次	Agent（并行）	层级
波次 1	testing-quality-analyzer, architecture-compliance-analyzer, code-standards-analyzer	mid
波次 2	dto-validation-scanner, error-handling-scanner	cheap
波次 3	report-writer	frontier

调度表

Agent 文件	层级	涵盖的参考文档	产物
agents/orchestrator.md	mid	—（仅路由）	—
agents/testing-quality-analyzer.md	mid	references/testing-quality.md	reports/.artifacts/nestjs-best-practices/step_01_testing_quality.md
agents/architecture-compliance-analyzer.md	mid	references/architecture-compliance.md	reports/.artifacts/nestjs-best-practices/step_02_architecture_compliance.md
agents/code-standards-analyzer.md	mid	references/code-standards.md	reports/.artifacts/nestjs-best-practices/step_03_code_standards.md
agents/dto-validation-scanner.md	cheap	references/dto-validation.md	reports/.artifacts/nestjs-best-practices/step_04_dto_validation.md
agents/error-handling-scanner.md	cheap	references/error-handling.md	reports/.artifacts/nestjs-best-practices/step_05_error_handling.md
agents/report-writer.md	frontier	references/best-practices-format-enforcer.md + references/best-practices-generator.md	reports/<YYYY-MM-DD>-<project>-nestjs-best-practices.md

协调器会在进入下一波次前验证每个预期产物是否存在。若缺少产物，会重试一次；随后记录日志并跳过依赖该产物的部分。report-writer 是唯一负责撰写最终用户可见报告的 Agent。

标准参考

所有标准均来自： agent-rules/rules/nestjs/（本地的 somnio-ai-tools 仓库，或独立安装时使用 GitHub raw）

标准文件	用途
dto-validation.md	DTO 结构、class-validator、Swagger
service-patterns.md	服务层模式、事务
controller-patterns.md	控制器装饰器、守卫
repository-patterns.md	仓库模式、软删除
testing-unit.md	单元测试模式、模拟
testing-integration.md	集成测试、数据库设置
error-handling.md	异常筛选器、错误枚举
module-structure.md	模块组织、导入/导出
typescript.md	TypeScript 标准、命名约定

报告文件名（必需）

报告文件名始终为：

<YYYY-MM-DD>-<project>-nestjs-best-practices.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-best-practices.md"

此技能中所有 reports/<YYYY-MM-DD>-<project>-nestjs-best-practices.md 均指该已解析路径。

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

报告元数据（必需）

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

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

在报告末尾包含此区块：

## Report Metadata

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