nestjs-professional-software-engineering

专业软件工程

在尊重现有项目的前提下，编写正确、符合惯例、安全、易读、易维护、可测试且可扩展的 NestJS 软件。

执行前冲突检查

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

前提条件

检查仓库指令、工作树、清单文件、已安装版本、源代码/调用方、契约、惯例和检查项。保留无关更改。对于不确定或依赖版本的语法，请依据已安装的类型/源代码和官方文档进行验证；切勿臆造 API。仅在其他有效技能的决策与当前任务有重叠时，才阅读这些技能。

主要职责

本技能负责项目检查、最小化实现、兼容版本的语法、API 易用性、测试和验证。若相关技能已安装且适用，请与以下技能协调：

• nestjs-architecture-principles：模块、依赖、数据和事务边界。
• nestjs-oop-design-patterns：对象职责、不变量和模式。
• nestjs-features-performance：生命周期、API/安全、测试、运行时和性能。
• nestjs-code-audit：只读质量证据和去重报告。
• nestjs-feature-audit：特定分支的路线图关卡和功能报告。
• nestjs-git-commit-pr-message：获得授权的 Git 发布和 CI 后续跟进。

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

冲突测试

检查是否存在不兼容的编辑/契约、命令顺序或副作用、职责冲突，以及未满足的版本、证据、授权或仓库前提。按明确的用户意图、仓库契约、已验证的运行时约束，再到职责范围最窄的所有者，依次解决。每项决策指定一个负责人；不要为了满足不兼容的建议而创建并行设计。如果仍存在实质性冲突，请在修改前停止，并询问最少的必要决策。审计应保持只读；明确的修复授权仅适用于独立的实现阶段。

必需工作流

在搭建脚手架或引入新边界之前，记录项目概况。遵循健康的本地惯例，并验证已安装的生成器/版本契约。

对于实现请求，请完成包括修改和验证在内的整个工作流。对于审查或诊断请求，请检查并报告证据，除非用户同时授权实现，否则不要修改文件。

1. 检查

1. 确定仓库范围和适用指令。
2. 确定语言、框架、运行时、包管理器以及确切的相关版本。
3. 阅读相关实现、调用方、测试、配置、清单文件和公共契约。
4. 搜索类似功能，以及命名、错误处理、测试和 API 惯例。
5. 确定针对性和更全面的测试、类型检查、lint、格式化、构建及冒烟测试命令。

不要一开始就进行大范围重写。更改之前，先明确当前行为。

2. 理解

明确：

• 请求的结果和可观察的验收标准；
• 受影响的边界和使用者；
• 兼容性、安全、数据、性能、部署和迁移方面的影响；
• 可能实质性改变解决方案的假设。

仅当缺失的决策会实质性影响架构、公共行为、安全、数据、成本或兼容性时才提问。

3. 选择最清晰且有效的语法

按以下证据顺序判断：

1. 仓库现有约定及兼容的公开行为。
2. 已安装的编译器、运行时、软件包版本、类型和源码。
3. 与版本相符的官方语言或框架文档。
4. 如果文档未能消除歧义，进行最小范围的本地实验或类型检查。
5. 社区示例只能用于发现线索，绝不能作为 API 契约。

至少比较直接、明确的形式与任何便捷语法。受支持、为项目熟悉，并且能让调用处和实现处都更清晰的现代惯用写法，优先采用。

选择语言或框架语法时，加载 syntax-and-idioms.md。

4. 设计最小且完整的改动

设计必须：

• 符合已检测语言和框架的惯用写法；
• 与现有架构和约定保持一致；
• 结构完整、可测试，默认安全，并保持向后兼容，除非已获准进行破坏性变更；
• 明确说明重要的状态变更、影响、失败模式、成本和控制方式。

对于公开 API，应让常见操作一目了然，并尽量避免无效用法。采用渐进式披露：为常见场景提供便捷路径，仅在调用方需要实质性控制时提供较低层级的路径。

进行决策并查看 API 示例时，加载 syntactic-sugar.md。

5. 实施

• 使用已检测工具链支持的有效现代语法。
• 保持函数、类、模块、组件和服务各司其职。
• 遵循既定的命名、格式、组织、验证和错误处理约定。
• 在边界处验证不可信输入，并保护敏感信息。
• 明确处理失败，并提供可采取后续操作且不会泄露信息的错误。
• 在相关情况下，考虑并发、事务、幂等性、重试、超时、取消、清理和可观测性。
• 避免不必要的依赖、推测性抽象、花哨的单行代码、隐藏的全局状态、隐式副作用和无关清理。
• 注释意图和约束，而非显而易见的语法。

6. 测试与验证

针对可观察行为、相关边界情况、无效输入、失败路径、安全敏感行为、回归和公开兼容性，新增或更新确定性测试。

运行适用于本次改动的检查：

1. 定向测试。
2. 风险需要时运行更全面的测试。
3. 类型检查或编译。
4. Lint 和格式验证。
5. 构建或打包。
6. 实际可行时，运行时、生成的契约或迁移冒烟检查。

不得为了通过检查而削弱测试或控制。除非检查已成功运行，否则不得声称检查通过。

进行基于风险的验证时，加载 implementation-verification.md。

7. 报告

先说明已完成的结果，然后说明：

• 重要的设计和语法决策；
• 已更改的文件或区域；
• 已执行的检查及其结果；
• 尚存的限制、风险、迁移事项或后续工作。

报告应简洁，并区分已验证的事实与假设或未运行的检查。

语法糖规则

仅在符合以下条件时使用语法糖：

• 减少有实际意义的繁琐代码或重复误用；
• 提高仓库实际维护者的可读性；
• 保持行为、类型、调试和组合方式可预测；
• 不会掩盖重要的成本、I/O、状态变更、网络活动、授权、事务、错误行为或生命周期；
• 为需要控制能力的高级调用方保留明确的路径；并且
• 能通过贴近实际的示例进行文档说明和测试。

拒绝那些只是缩短代码、创建私有小型语言、重载含义不明确的输入、依赖出人意料的强制转换，或让堆栈跟踪和错误更难理解的语法糖。

预期响应

对于实现工作，请报告已交付的行为和验证情况。若语法选择是核心问题，还应说明：

• 观察到的约定： 相关的仓库模式。
• 考虑过的选项： 显式形式和便捷形式。
• 选定的语法： 说明为何该语法受支持且最清晰。
• 隐藏行为检查： 仍可观察到的影响、成本、失败情况和控制方式。
• 兼容性： 受影响的调用方以及是否需要迁移。

如果用户要求实现，不要只返回建议的代码片段。

参考资料路由

任务	加载
选择惯用且兼容当前版本的语法	syntax-and-idioms.md
设计或审查语法糖和公共 API 的易用性	syntactic-sugar.md
确定实现范围并选择验证深度	implementation-verification.md