nestjs-feature-audit

NestJS 功能审计

将某项功能的文档目标与某个已确定版本的实现进行比较。返回一份可追溯的状态报告；不要修复发现的问题。

执行前冲突检查

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

前提条件

要求提供非空的功能名称，并确定目标分支；只有在未指定分支时，才默认使用 main。在准备分支之前，检查指令、Git 状态和远程仓库，以及文档。指定的路线图定义预期行为；源代码、测试和运行时证据用于确定当前行为。保留用户更改，并确保审计始终针对同一个版本。仅在决策存在交集时，才读取其他生效的技能。

主要职责

此技能负责安全地准备目标分支、追溯路线图、分类状态，以及撰写由四个部分组成的报告。在已安装且相关的情况下，与以下技能协作：

• nestjs-architecture-principles：模块、依赖、数据和事务边界。
• nestjs-oop-design-patterns：对象职责、不变量和模式。
• nestjs-features-performance：生命周期、API／安全、测试、运行时和性能。
• nestjs-professional-software-engineering：实现和验证。
• nestjs-code-audit：只读质量证据和去重报告。
• nestjs-git-commit-pr-message：经授权的 Git 发布和 CI 后续工作。

这些是决策边界，并非必需的依赖项。将工作交接给其他工作流时，仍须保留相应领域的职责。

冲突测试

根据明确的用户意图、仓库／路线图约定、经验证的运行时约束，再到职责范围最窄的负责人，依次解决分支、路线图、发现、命令或未满足前提之间的不一致。不得混用不同版本，也不得将路线图文本视为执行许可。如果仍存在重大冲突，应在修改前停止，并询问解决问题所需的最少信息。单独进行审计绝不授权修复；明确提出“审计并修复”的请求，则允许在通过路线图检查后，另行开展实现阶段。

调用方式

推荐的可移植调用方式：

$nestjs-feature-audit "payments"
$nestjs-feature-audit "payments" --branch "release/2026-q3"

如果宿主已路由用户请求的命令语法，则按等效方式解析：

/audit_feature payments
/audit_feature payments on branch release/2026-q3

不要声称所有客户端都已安装裸命令 /audit_feature。在 Codex 中，可选的兼容提示词为 /prompts:audit_feature；已安装的技能仍是首选接口。

必需工作流

1. 安全地准备目标分支

1. 解析仓库根目录，并在任何 Git 修改之前读取仓库指令。
2. 记录 git status --short --branch、当前分支、远程仓库，以及目标分支在本地／远程是否存在。
3. 如果工作区有未提交更改、Git 操作正在进行，或当前检出状态已分离，则停止，不要切换或更新。绝不自动暂存、丢弃、重置、清理或强制切换。只有用户明确接受时，才可继续在同一脏快照上操作，并在报告中记录此例外。
4. 如果存在远程跟踪分支，则获取其远程更新，正常切换分支，并且只执行快进更新。审计期间绝不合并分歧历史或执行变基。
5. 记录被审计的分支、提交 SHA、工作区脏状态、远程版本，以及是否已验证最新状态。如果无法检查已配置的远程仓库，除非用户明确接受本地快照，否则不要声称该分支是最新的。

对仓库使用等效的安全命令：

git status --short --branch
git branch --show-current
git remote -v
git fetch --prune origin
git switch -- "$audit_branch"
git merge --ff-only -- "origin/$audit_branch"
git rev-parse HEAD

明确的功能审计调用授权安全地选择目标分支并准备快进更新，但不授权破坏性清理或发布。

2. 收集上下文并执行路线图门槛

1. 阅读适用于该功能的项目原则、概念、标准、架构决策和贡献者规则。
2. 在 docs/ 中搜索文件名和内容，查找功能名称、已接受的别名，以及 roadmap、plan、milestone、phase、acceptance 和 migration。
3. 通过入口点、模块、提供方、适配器、持久化、配置、迁移、测试、契约、遥测和部署产物，识别功能代码。先搜索；不要仅凭文件夹名称作判断。
4. 仅将可用对话上下文中的需求和决策作为次要证据。如果无法获取对话历史，请如实说明；不要捏造内容，也不要在仓库路线图已足够时因此阻塞。
5. 只有在路线图明确界定了可识别的功能范围和具体目标项、阶段、验收条件或迁移结果时，才予以认可。标题、TODO 提及、变更日志条目或通用产品描述，都不算清晰的路线图。

如果 docs/ 中不存在清晰的路线图，请在比较实现情况之前停止，并请用户提供或指出该路线图。报告搜索过的路径和词项。用户直接提供的路线图符合此门槛；请标明它由用户提供，而非仓库文档。完整门槛请遵循 roadmap-discovery.md。

3. 构建可追溯性矩阵

对每个路线图条目：

1. 规范化需求，但不得弱化其验收措辞。
2. 将其追溯到源代码、测试、配置、架构／迁移、生成的契约、部署／运行时证据及相关标准。
3. 将观察到的状态记录为 verified、partial、absent、superseded、broken、blocked 或 not verifiable。
4. 为其指定且仅指定一个主要报告类别。如果路线图条目的不同部分状态不同，请将其拆分为明确的子项。
5. 为每项肯定和否定的判断保留路径与行号引用，或准确的命令／结果。声称某项不存在时，必须列出搜索内容以及检查过的预期集成点。

使用 evidence-classification.md 区分已完成的工作、缺口、遗留实现、缺陷、阻塞项和未经验证的候选项。

4. 对照领域标准

• 将架构声明与实际模块／导入、依赖、数据／写入、事务和服务边界进行比较。
• 将对象设计声明与实际职责、不变量、协作对象和变化机制进行比较。
• 将运行时声明与生命周期接线、安全控制、测试、配置、构建产物及获授权的运行时证据进行比较。
• 如果测试、部署、迁移、外部系统或运行时检查不可用或存在风险，请将其标记为未验证。不要将 not run 判定为成功或失败。
• 区分路线图完成情况与生产环境证明：已合并的源代码可以视为已实现，但发布或线上验收条目仍可能处于阻塞状态。

5. 返回所需报告

开头应列出功能、分支、提交、脏／新鲜度状态、路线图来源、审计范围，并给出一句话结论。然后严格按以下顺序使用这些标题：

1. ✅ 已实现
2. ❌ 缺失／未实现
3. ⚠️ 遗留代码
4. 🛑 缺陷与阻塞项

每项都必须说明路线图需求、观察到的状态、证据、影响，以及下一步验证或退出证据。保留全部四个标题；如果某类别为空，请写 审计证据中未发现。。使用 report-template.md。

除非路线图定义了各项权重，否则不得给出完成百分比。除非用户明确授权了具体操作和范围，否则不得实施、提交、推送、部署或编辑路线图。授权可以在原始请求中给出；审计完成后才可开始实施，而且修复授权并不意味着获准发布、部署或编辑路线图。

参考路由

需求	加载
判断文档是否满足路线图的硬性门槛	roadmap-discovery.md
对证据进行分类，避免重复计数或夸大完成情况	evidence-classification.md
生成准确的四部分最终报告	report-template.md