前置控制：引导层

引导层（Feedforward）在 AI 行动之前就介入，目标只有一个：提升第一次就做对的概率。它不依赖 AI 犯错后的纠正，而是通过精心设计的上下文，让"正确的做法"成为 AI 最自然的选择。

为什么引导层很重要？

AI 模型没有你团队的记忆。它不知道你们上个月废弃了某个模式，不知道这个项目的错误处理风格，也不知道"永远不要在 Service 里直接 new 一个异常，要用 throw"。

引导层就是把这些隐性知识外化——从你的脑子里、从代码审查的口头评论里，转化成 AI 能"读到并记住"的结构化文档。

引导层和感知层的关键区别

引导层是规则的声明，感知层是规则的验证。前者告诉 AI 应该怎么做，后者确认它有没有照做。

推理型引导

这类引导是给 AI"读"的，影响它的推理和决策过程。

AGENTS.md — 操作手册

这是本项目引导层的核心文件。它告诉 AI：

• 哪些设计原则是不可违反的（SOLID、AOP、分层架构）
• 遇到信息不足时，先查哪里（src/common/utils/、src/constants/）
• 任务完成后，哪些验证步骤是强制的（lint → build → test）
• 如何格式化提交信息（Conventional Commits）

AGENTS.md（根目录）
└── docs/AGENTS.md（文档操作专项流程）

每次 AI 开始一个新任务时，这个文件就是它的"入职培训"。

架构文档 — 上下文地图

docs/03-architecture/ 下的文档不仅是给人看的，也是 AI 修改架构相关代码时的必读参考：

• 认证模块：添加新的认证策略前必须了解现有的三策略体系
• 异常系统：新增错误类型前必须查看现有的错误分类和命名规范
• 请求生命周期：修改中间件、守卫或拦截器前必须理解完整的请求流程
• 路由装饰器：任何新 API 端点都通过 @ApiRoute 声明，不允许绕过

这些文档的价值在于：它们把"为什么这么设计"也记录下来了，而不只是"是什么"。AI 理解了背后的动机，就更不容易做出破坏一致性的决策。

Skills — 任务型操作手册

.agents/skills/ 下的技能文档是更细粒度的引导，每个 Skill 对应一类特定任务：

Skill	触发场景	引导内容
git-commit	"帮我提交代码"	Conventional Commits 格式、暂存策略
pr-automation	"帮我创建 PR"	PR 描述模板、检查清单
changelog-generator	"生成更新日志"	从 commit 提取信息、用户友好描述

Skill 的特点是程序化——它不只是模糊的建议，而是有明确步骤的操作流程，类似于给 AI 的"API 文档"。

错误码目录 — 防止自由发挥

src/constants/error-catalog.constant.ts 是一个典型的引导机制：它把所有允许的错误类型明确列出来，AI 在需要抛出异常时会先查这里，而不是凭空发明新的错误码。

每个错误条目都有：

• 唯一的 code（如 CLIENT_PARAMS_VALIDATION_FAILED）
• 人类可读的 message
• HTTP 状态码映射

这防止了 AI 的一种常见失误：用不一致的方式处理相似的错误场景。

计算型引导

计算型引导不依赖 AI 的"阅读理解"，而是通过工具直接约束或辅助 AI 的行为。

项目结构本身

这是最隐性的引导。NestJS 的模块化结构和本项目的目录约定（modules/、infra/、common/）本身就在引导 AI：当它需要新增一个功能时，项目结构已经在说"应该放在这里，不应该放在那里"。

TypeScript 的强类型定义也是计算型引导——Prisma 生成的类型、DTO 接口定义、NestJS 装饰器的类型约束，这些在 AI 生成代码时就已经缩小了它的合法选择范围。

tsconfig + ESLint 配置

严格的 TypeScript 配置（strict: true、nodenext 模块解析）和详细的 ESLint 规则，让 AI 生成代码时遵循的风格更接近项目规范。这些配置是"主动约束"——即使 AI 没有读过规范，不合规的代码也会在类型检查或 lint 阶段被捕获。

引导层的局限性

引导层不是万能的。它依赖 AI 实际"摄入"了相关上下文，而 AI 的上下文窗口是有限的。对于较长的文档，AI 可能只关注了开头部分；对于过于宽泛的指导，AI 可能无法正确判断什么时候该应用它。

这就是为什么感知层（Feedback）是不可缺少的补充——即使引导层没有起作用，感知层也能提供一道安全网。

想了解本项目的感知层是如何设计的？继续阅读反馈控制：感知层。