nestjs-agents

# nestjs-agents > **生产级Claude Code子代理，专为NestJS开发定制。** > 代码审查、测试、安全、架构 - 限定在您最近的工作（未提交 + 上一次提交）。 [](https://opensource.org/licenses/MIT) [](https://docs.claude.com/en/docs/claude-code/sub-agents) ## 为什么存在 通用的AI编码代理不了解NestJS特定的模式： - **装饰器**（`@Injectable`、`@Controller`、`@UseGuards`） - **DI作用域**（单例 vs 请求 — 以及竞争条件陷阱） - **层级职责**（控制器 → 服务 → 仓库 — 绝不混淆） - **测试模块**（`Test.createTestingModule`与`getRepositoryToken`） - **事务性出队**模式，用于Stripe / RabbitMQ事件 - **验证管道**与`class-validator` DTO 此集合为Claude Code提供了该上下文 — 并**将每个审查/测试操作限定在您最近的工作**（未提交更改 + 上一次提交），因此代理仅作用于您刚刚编写的内容，而不是整个代码库。 ## 内容 | 代理 | 目的 | 只读？ | 触发器 | |---|---|---|---| | **`nestjs-code-reviewer`** | 审查最近的更改是否存在错误、安全问题、NestJS反模式 | ✅ 是 | "审查我的更改"、"检查此代码" | | **`nestjs-test-writer`** | 编写更改组件的Jest单元/集成测试 | ❌ 编写测试文件 | "添加测试"、"覆盖测试" | | **`nestjs-security-auditor`** | 将更改映射到OWASP Top 10 + NestJS特定陷阱 | ✅ 是 | "安全审计"、"审计身份验证流程" | | **`nestjs-architect`** | 架构顾问 — DDD、六边形、微服务、事务性出队 | ✅ 是 | "设计此功能"、"是否应该拆分为微服务" | | **`nestjs-repository-expert`** | 构建实体、模式、仓库、迁移（TypeORM / Prisma / Mongoose） | ❌ 编写代码 | "创建实体"、"添加迁移"、"优化查询" | | **`nestjs-service-expert`** | 实现服务层 — 业务逻辑、SOLID、错误处理 | ❌ 编写代码 | "创建服务"、"实现用例" | | **`nestjs-controller-expert`** | 创建控制器、DTO、端点、Swagger文档 | ❌ 编写代码 | "添加端点"、"创建控制器"、"添加DTO" | ## 安装 ### 全局（推荐 — 在所有项目中可用） ```bash mkdir -p ~/.claude/agents # 克隆或下载代理 curl -L https://github.com/vasyl-bilous/nestjs-agents/archive/main.tar.gz | \ tar -xz --strip-components=2 -C ~/.claude/agents \ nestjs-agents-main/agents # 验证 ls ~/.claude/agents/nestjs-*.md ``` ### 每个项目 ```bash cd your-nestjs-project mkdir -p .claude/agents curl -L https://github.com/vasyl-bilous/nestjs-agents/archive/main.tar.gz | \ tar -xz --strip-components=2 -C .claude/agents \ nestjs-agents-main/agents ``` ### 仅选择特定代理 ```bash mkdir -p ~/.claude/agents curl -o ~/.claude/agents/nestjs-code-reviewer.md \ https://raw.githubusercontent.com/vasyl-bilous/nestjs-agents/main/agents/nestjs-code-reviewer.md curl -o ~/.claude/agents/nestjs-test-writer.md \ https://raw.githubusercontent.com/vasyl-bilous/nestjs-agents/main/agents/nestjs-test-writer.md ``` 安装后，**重启Claude Code**以获取新的代理。验证： /agents ## 工作流示例 ### 1. 实现 → 审查 → 测试（典型功能） ``` > 在OrderService中实现createOrder方法，并与Stripe集成 （主代理编写代码） > 使用nestjs-code-reviewer审查我刚刚编写的内容 （code-reviewer读取`git diff`，发现：Stripe charge上缺少幂等性， 事务包装器丢失 — 返回具有文件：行号的发现结果） > 修复这些关键发现 （主代理应用修复） > 使用nestjs-test-writer添加单元测试 （test-writer读取`git diff`，编写OrderService.spec.ts，模拟Stripe， 覆盖正常路径 + 错误路径 + 边缘情况。运行`pnpm test`进行验证。） ``` ### 2. 编码前进行架构决策 ``` > nestjs-architect：我正在构建一个订单处理服务，需要调用 Stripe并发送确认电子邮件。我应该在所有这些中使用事务还是异步事件？ （architect响应具体建议： - 使用事务性出队模式 - 在DB事务中编写Order + OutboxEvent - 工作线程读取出队，调用具有幂等性密钥的Stripe - 单独的工作线程处理电子邮件 - 权衡：最终一致性与保证交付 - 具体下一步：搭建OutboxEvent实体） ``` ### 3. 部署前进行安全审计 ``` > 使用nestjs-security-auditor审计我最近的身份验证更改 （auditor读取`git diff`，发现： 🔴 A2 加密 — 在模块中硬编码JWT密钥 🔴 A4 不安全设计 — 在/auth/login上没有速率限制 🟡 A7 身份识别 — 泛型'密码错误'消息使枚举能够识别 → 返回具有修复建议的发现结果，映射到OWASP类别） ``` ### 4. 从头开始构建新功能 ``` > nestjs-architect：为"订阅"功能设计模块结构 > nestjs-repository-expert：根据架构师的计划创建Subscription实体 + 仓库 > nestjs-service-expert：实现具有架构师描述的业务规则的SubscriptionService > nestjs-controller-expert：在/subscriptions上添加CRUD端点与Swagger > nestjs-test-writer：用测试覆盖我刚刚构建的内容 > nestjs-code-reviewer：提交前审查所有内容 ``` ## 应用于所有代理的设计原则 此集合中的每个代理都遵循以下规则： ### 1. 最近的工作范围 每个采取行动的代理（审查者、审计员、测试编写器，甚至代码编写器在迭代时）都以相同的三个命令开始，以查找您一直在处理的内容： ```bash git status --short # 未提交（已暂存 + 未暂存 + 未跟踪） git diff HEAD # 未提交更改的完整差异 git diff HEAD~1 HEAD # 上一次提交的差异 ``` 这些的并集是代理的作用域 — 它仅操作**您最近触摸的内容**，而不是存储库的其余部分。这可以防止： - 用无关文件污染主代理的上下文 - 在您只更改了10行时审查数千行 - 在您打算的内容与代理执行的内容之间出现“漂移” - 遗漏已暂存的更改（当代理仅在没有`HEAD`的情况下检查`git diff`时常见的错误） ### 2. 在可能的情况下只读 审查者和审计员具有**无写入/编辑工具** — 他们无法修改您的代码。他们只生成具有`文件：行`引用和建议修复的发现结果。 这是一个刻意的防护措施： - 审查保持中立（您决定修复什么） - 审计员在“修复”某些内容时不会意外破坏代码 - 您的更改保持可复制 ### 3. 特定于NestJS的上下文，而不是通用 每个代理都了解： - 装饰器、DI作用域、模块、提供者 - 守卫、管道、拦截器、过滤器 - 具有`class-validator`的DTO、具有TypeORM/Prisma的实体 - 使用`Test.createTestingModule`、`getRepositoryToken`、`mocked providers`进行测试 - NestJS异常（`NotFoundException`、`ConflictException`等） ### 4. 特定、文件：行引用 发现结果始终如下所示： ``` 🔴 [src/auth/auth.service.ts:42] — 泛型错误消息使用户名枚举 风险：攻击者可以通过计时/响应差异检测有效电子邮件 修复：在'wrong-password'和'unknown-email'的情况下返回相同的'Invalid credentials' ``` 而不是诸如“改进错误处理”之类的模糊建议。 ### 5. `model: inherit` — 代理遵循您的主会话 集合中的每个代理都在其frontmatter中配置为`model: inherit`。这意味着： - 代理在**您的主Claude Code会话使用的模型**上运行 — Opus、Sonnet或Haiku。 - 您从一个地方（您的主`/model`设置）控制成本/功能权衡，无需编辑每个代理。 - 库适用于所有订阅层级 — 专业用户（无Opus）自动获取Sonnet。 - **始终运行在最新的可用模型上。** 当Anthropic发布新版本（例如Opus 5）时，您无需编辑任何frontmatter — 代理会在您的主会话执行时获取升级。 如果您想将代理固定到特定模型（例如，始终在Opus上运行`nestjs-architect`，无论主会话如何），请将`model: inherit`更改为`model: opus` / `model: sonnet`在该文件中。我们不建议为共享库执行此操作，但如果需要，可以为每个代理进行一行覆盖。 ## 推荐的CLAUDE.md设置（自动委托） 安装代理后，Claude Code已经可以根据每个代理的`description`和触发短语将工作路由到它们 — 您可以直接说*“审查我的更改”*，然后`nestjs-code-reviewer`运行。 但是，如果您在项目的根目录`CLAUDE.md`中添加一个简短的说明（或追加到现有的文件中），则会获得**更可靠的路由**： ````markdown ## NestJS子代理工作流 该项目使用专门的NestJS子代理。按照以下方式将工作路由到它们： **设计时（编码前）：** - 架构/模块边界/模式问题 → `nestjs-architect` **实现时：** - HTTP端点、DTO、Swagger文档 → `nestjs-controller-expert` - 业务逻辑、用例、服务层代码 → `nestjs-service-expert` - 实体/模式、仓库、迁移、查询优化 → `nestjs-repository-expert` 不要在单个主会话回合中编写控制器+服务+仓库 — 将每个层委托给其专门的代理，以便保持层边界干净。 **实现后（提交前运行）：** 1. `nestjs-code-reviewer` — 审查最近的差异是否存在错误、反模式、缺少事务 2. 如果审查者标记🔴关键发现 — 在继续之前修复它们 3. `nestjs-test-writer` — 为更改添加Jest单元/集成测试 4. 对于涉及**身份验证、支付、用户数据或外部API**的更改 — 还要运行`nestjs-security-auditor` **不委托时：** - 单行输入错误或重命名引用 — 直接编辑 - `src/`以外的草稿/实验文件 — 代理用于生产代码 ```` **为什么这比仅依赖自动委托更好：** - Claude Code将`CLAUDE.md`指令视为**必须遵循的规则**，而不仅仅是建议 — 因此，在每次实施后，审查/测试周期实际上会发生，而不是“当描述恰好匹配时” - 映射是**按层显式**的，这可以防止主会话在单个回合中编写控制器+服务+存储库（三层不同时） - 安全审计根据**更改的内容**触发，而不是用户是否记得询问 您可以根据项目特定规则进一步扩展此内容（例如，“始终为涉及计费模块的更改使用`nestjs-architect`”）— 代理将获取主会话提供的任何额外上下文。 ## 兼容性 - Claude Code v1.0+（任意模型 — 代理从您的主会话继承） - NestJS v9、v10、v11 - TypeORM、Prisma和Mongoose（MongoDB）均受支持 - Jest（默认）和Vitest（带有适配器） ## 贡献 欢迎PR — 尤其是： - 新代理（e2e-test-writer、performance-auditor、migration-writer） - NestJS框架版本更新（v12发布时） - 来自真实项目的附加反模式示例 请遵循现有的格式： - YAML frontmatter（`name`、`description`带有触发器、`tools`、`model: inherit`） - `步骤 1：确定范围`使用标准3命令模式（`git status --short`、`git diff HEAD`、`git diff HEAD~1 HEAD`） - `不做`部分 - 具体输出格式示例 ## 许可证 [MIT](LICENSE) — 在个人和商业项目中免费使用。鼓励但不要求署名。 --- **作者：** [Vasyl Bilous](https://github.com/vasyl-bilous) — 高级全栈开发人员，AI驱动开发实践者。 其他AI工具项目： [`component-library-mcp`](https://github.com/vasyl-bilous/component-library-mcp)， [`nestjs-dev-logs-mcp`](https://github.com/vasyl-bilous/nestjs-dev-logs-mcp)。