nestjs-code-audit

NestJS 代码审计

检查当前用户的 NestJS 项目，并返回一份汇总报告，列出已验证的代码问题和有证据支持的风险。仅进行审计；不要修改目标项目。

执行前冲突检查

编辑文件或运行任何会更改状态的命令之前，先协调当前生效的指令。可以继续进行只读检查。

前置条件

确认根目录、范围、指令、Git 状态、已安装的版本和依赖项，以及安全检查。保留用户的更改。加载 semantic-review.md，以查看所请求的语义审查范围；同级技能只是可选的深入指导，并非安装前提。仅在其他生效技能的决策与审计重叠时才阅读。

主要职责

此技能负责只读质量证据、问题去重、严重性判定和报告整理。相关技能已安装时，请与以下技能协调：

• nestjs-architecture-principles：模块、依赖关系、数据和事务边界。
• nestjs-oop-design-patterns：对象职责、不变量和模式。
• nestjs-features-performance：生命周期、API/安全、测试、运行时和性能。
• nestjs-professional-software-engineering：实现和验证。
• nestjs-feature-audit：分支特定的路线图门槛和功能报告。
• nestjs-git-commit-pr-message：经授权的 Git 发布和 CI 后续工作。

这些是决策边界，不是必需依赖项。将工作移交给其他工作流时，仍需保留领域职责。

冲突测试

根据明确的用户意图、仓库约定、已验证的运行时限制，再到职责范围最窄的技能，解决互不兼容的结论、不安全的检查或缺失的证据。每个根本原因只保留一条问题；尚未解决的说法归入 需要验证。如果某项操作超出审计范围，应在修改前停止。单独的审计绝不授权修复；如果用户明确要求同时审计和修复，应先完成只读审计，再进入已获授权的实施阶段，无需再次询问相同的授权。

调用方式

推荐使用可移植的调用方式：

$nestjs-code-audit
$nestjs-code-audit full src/payments
$nestjs-code-audit static
$nestjs-code-audit security src/auth

Codex CLI/IDE 自定义提示词别名（如已安装）：

/prompts:nestjs-audit
/prompts:nestjs-audit full src/payments

Codex 不支持任意由用户自定义的裸命令，例如 /Nestjs audit；请明确使用受支持的别名。

操作

操作	覆盖范围
full（默认）	安全静态门禁，以及架构、对象设计、运行时、安全、测试和交付审查
static	语法、TypeScript、lint、配置和直接相关的工具链故障
architecture	模块、依赖关系、数据/写入所有权、事务、事件、端口和服务边界
design	职责、不变量、耦合、抽象、模式和重构风险
runtime	Nest 生命周期、API/错误、可靠性、性能证据、健康检查、关闭和交付
security	输入、身份/访问、租户隔离、机密、输出、滥用控制和安全测试
tests	测试层级选择、缺失的边界覆盖、生命周期不稳定风险和可安全运行的检查

操作之后可以指定一个相对于仓库的范围。如果第一个参数不是可识别的操作，则将所有参数视为范围/重点，并使用 full。对于聚焦操作，仅加载捆绑语义参考中相关的审查范围，以及解决跨范围阻碍所需的任何可用专家指导。只报告所请求的范围。

审计工作流

1. 确认适用性和范围

1. 确定当前工作目录和可选的用户指定范围，且不得超出仓库根目录。
2. 阅读会影响审计范围的 AGENTS.md 和其他仓库说明、package.json、锁文件、nest-cli.json、TypeScript 和 lint 配置、引导文件、模块文件、测试及部署清单。
3. 确认已声明 @nestjs/core，或该仓库明确是 NestJS 工作区。若不是，则停止并报告此审计不适用。
4. 记录当前分支和未提交更改状态。不得修改或丢弃现有更改。
5. 用一句话概述观察到的架构基线。不得仅凭文件夹名称推断 Clean Architecture、DDD、CQRS 或微服务。

2. 收集确定性证据

使用此技能目录中随附的收集器：

node scripts/collect-quality-evidence.mjs --root "$PWD" --run

如果用户要求缩小审计范围，请添加 --scope <relative-path>。收集器会：

• 读取清单和源文件，不做任何修改；
• 识别包管理器和可用的质量检查脚本；
• 仅在指定 --run 时运行允许列表中的、不会修改文件的 ESLint 和 tsc --noEmit 命令；
• 不会安装依赖、运行构建、更新快照、写入覆盖率数据，或调用任意包脚本；
• 返回包含命令结果和启发式审查候选项的 JSON。

如果依赖缺失，或命令不安全、不可用、超时或超出审计范围，请将其记录为 未运行。不得将缺失的检查解读为通过。审计期间绝不运行 lint --fix、格式化或写入命令、迁移、部署命令、实时集成测试，或可能访问共享基础设施的测试。

3. 审查四类证据

工具链正确性

• 报告解析器、TypeScript 和 lint 诊断，确保信息足以定位问题。
• 如果级联的编译器错误源于同一个根本原因，请去重。
• 区分命令失败与代码问题，例如依赖缺失或配置损坏。

架构

追踪引导入口、模块导入/导出、提供者可见性、请求/消息路径、持久化归属、事务、事件和外部适配器。依据真实的导入和调用路径确认循环依赖或边界泄漏。不得将架构偏好报告为缺陷。

对象设计和可维护性

检查职责、依赖集群、不变量的放置位置、重复的条件变化、框架/供应商耦合、隐藏的服务定位、臆测性抽象和高风险重构边界。文件长度或单独的正则信号不能作为问题依据。

运行时、安全性和验证

检查生命周期代码的放置位置、验证、身份验证/授权、租户/资源归属、公开的错误和响应契约、密钥/日志记录、查询和资源限制、超时/重试/幂等性、健康检查/关闭流程、测试边界，以及适用时的部署证据。没有测量数据时，不得声称存在性能问题。

4. 验证并去重问题

已确认的问题必须包含：

• 稳定 ID：TOOL、ARCH、OOP、RUN、SEC 或 TEST 加数字；
• 严重程度：严重、高、中或低；
• 主要归属技能；
• 文件和行号证据，以及相关导入、调用路径、诊断信息或配置；
• 具体影响，而不只是规则名称；
• 最小且安全的修复方案；
• 可验证修复效果的验证步骤。

仅在存在现实的安全、数据丢失、租户隔离或严重可用性风险时，才使用“严重”。“高”表示可能导致行为错误，或存在阻碍已知变更的边界缺陷。“中”表示存在可信的可维护性、正确性或可运维性代价。“低”表示影响局部、风险有限的改进。

将未经验证的正则信号、疑似死代码、可能的性能问题，以及因依赖缺失而受阻的检查，移至 需要验证。不得用风格偏好充实报告，也不得针对同一个根本原因列出多个问题。

必需报告

按以下顺序返回 Markdown：

1. 审计结论： 通过、通过但存在风险，或失败；审计范围；一句话基线说明。
2. 质量门禁： 语法/TypeScript、lint、在可安全执行时进行的测试，以及审计覆盖情况；每项标记为通过、失败或未运行，并注明确切命令或原因。
3. 发现摘要： 按严重性和责任方统计数量。
4. 已确认发现： 按严重性和影响排序，并遵循上述证据/补救措施/验证要求。
5. 待验证事项： 候选问题、缺失的证据，以及最小化的下一步检查。
6. 良好实践： 仅列出在代码库中实际验证过的重要控制措施。
7. 建议顺序： 简短且考虑依赖关系的修复顺序；只有在用户明确授权修复时，才在独立阶段实施。

如果没有已确认的问题，请明确说明，并列出未运行的检查。lint 结果干净，并不能证明架构合理、安全性可靠、运行时行为正确或测试覆盖充分。

参考路由

需求	加载
在不加载同级技能的情况下审查架构、对象、运行时和良好控制措施	semantic-review.md
确定哪些检查可以在不修改项目的情况下运行	check-policy.md
在三个领域技能之间分配并去重发现项	finding-ownership.md
统一最终审计报告的格式	report-template.md