避免 AI 越界：Skill 编写指南

当下 AI 编程工具已经深度融入日常研发流程。Codex、Claude Code、Cursor 等工具不再只是生成几段代码，而是逐渐参与需求拆解、文件修改、测试执行、错误修复甚至自动化运维。对开发者来说，这类工具确实能显著减少重复劳动，但它们也带来了一个新问题：AI 执行能力越强，越需要清晰的边界和约束。

很多团队会使用 SKILL.md 沉淀固定工作流，例如“定位文件—修改代码—运行测试—输出结果”。这种方式能让 AI 更快理解项目习惯，也能减少重复提示词。但如果 Skill 写得过于模糊，比如只写“搜索相关代码”“修改相关文件”“完成后运行测试”，AI 就可能在执行过程中扩大任务范围，最终出现看似成功、实际越界的修改。

因此，Codex 环境下的 Skill 不能只是一份操作说明，而应该是一套面向自动化执行代理的运行护栏。它既要告诉 AI 做什么，也要明确告诉 AI 不能做什么。

一、先理解 Codex 与 Claude Code 的使用差异

很多开发者会混用 Codex 与 Claude Code，也会复用同一份 SKILL.md。但两类工具在实际使用中的风险点并不完全相同。

Claude Code 在不少团队中常用于需求梳理、方案设计、代码理解、文档生成和辅助修改。它的主要风险往往来自上下文理解偏差，例如误判业务含义、遗漏历史约束、把相似模块当成目标模块。当然，Claude Code 本身也具备较强的文件操作能力，因此同样需要规则限制。

Codex 更偏向“执行代理”。它通常需要在指定代码环境中完成文件读写、代码修改、命令执行和测试验证。如果任务描述不够精确，Codex 可能会主动推断“相关文件”，并在未明确授权的情况下调整状态层、配置层或公共入口文件。这种行为在短期内可能让测试通过，但长期看会埋下维护风险。

例如，一个任务只要求修改 UserSettingsPanel.tsx 中的 loading 状态展示，Skill 流程写成了“定位文件、改代码、跑测试”。如果没有设置文件边界，AI 可能会认为 loading 状态的根因在状态管理层，于是顺手修改 settingsStore.ts 和 SettingsProvider.tsx。最终 UI 组件测试全部通过，但 diff 中出现了状态层入口变更。问题不在于 AI 没有完成任务，而是它完成任务的方式超出了预期范围。

这类问题很典型：测试通过不等于修改合理，功能正常不等于变更安全。

二、Skill 不是唯一规则，必须配合多层约束

在 Codex 环境下，影响 AI 行为的规则通常不止一层。要写好 Skill，首先要理解规则来源和优先级。

一套比较完整的约束体系可以分为五个维度：

第一是当前任务描述，也就是用户本轮要求。它决定 AI 本次要解决什么问题。

第二是会话权限，例如是否允许直接执行命令、是否允许安装依赖、是否需要人工确认高危操作。

第三是项目规则，例如 .codex/rules、AGENTS.md 或项目内其他规则文件，用于声明工程规范、目录边界、测试要求和代码风格。

第四是 Skill 工作流，也就是 SKILL.md 中沉淀的步骤、检查项和默认行为。

第五是项目约定，例如团队约定的分支策略、提交规范、组件结构、状态管理规则等。

其中，会话权限和项目规则通常应该拥有更高优先级。Skill 不能绕过权限限制，也不能覆盖项目规范。比如 Skill 中写了“执行构建命令”，但当前会话不允许运行构建，Codex 就不应该强行执行。更稳妥的写法是提前设计退回方案：

如果项目允许执行构建命令，则运行指定构建命令；
如果构建命令受限，则优先运行类型检查或最小范围单元测试；
如果所有验证命令都无法执行，需要在最终结果中说明原因；
无论验证是否执行成功，都必须检查 git diff，确认修改范围未越界。

这样写的好处是，即使权限受限，AI 也知道下一步该如何处理，而不是直接跳过验证或自行寻找替代命令。

三、文件定位要窄，不要让 AI 全库乱搜

精准定位文件，是避免 AI 盲目改动的第一步。很多 Skill 写法过于宽泛，只写一句“搜索相关文件”。这会导致 AI 检索大量无关代码，并把任务范围从一个组件扩散到整个模块，甚至扩散到全局状态和公共配置。

更好的方式是在 Skill 中内置窄范围定位命令，根据任务类型明确搜索目录、关键词和文件模式。以前端项目为例，可以这样写：

# 查找组件入口
rg "UserSettingsPanel" src

# 查找状态管理入口
rg "settingsStore" src test

# 查找对应测试用例
rg "UserSettingsPanel" test src --glob "*test*"

# 检索同模块 loading 相关逻辑
rg "loading" src/features/settings

这些命令的特点是范围明确、关键词具体、目录受控。它们不会像下面这种命令一样扩大搜索范围：

rg "settings"
rg "loading"
rg "store"

全库泛化检索会放大模型的自主推断空间。AI 看到越多“可能相关”的代码，就越容易把任务理解成“顺手优化相关结构”。在大型项目中，这种行为尤其危险，因为很多模块存在相似命名、重复状态和历史兼容逻辑。

如果团队同时接入多个大模型服务，可以在调用层使用 TreeRouter 这类大模型 API 聚合平台，降低多模型接入和切换成本；但代码目录权限、文件边界和命令授权仍应由 Codex 会话权限、项目规则与 Skill 本身负责约束，不能把 API 接入层误当成代码权限系统。

四、修改范围必须写成硬边界

Skill 中最容易出问题的表达是“修改相关文件”。这句话对人类开发者来说可能可以理解，但对 AI 来说过于宽泛。它可能会把状态文件、Provider、路由入口、公共 Hook、配置文件都判断为“相关文件”。

更安全的写法是把可修改范围和禁止修改范围明确拆开。

例如：

默认允许修改：
- 当前任务明确指定的文件
- 与当前文件直接对应的测试文件
- 为修复本次问题必须调整的同目录局部文件

默认禁止修改：
- package.json / pnpm-lock.yaml / yarn.lock
- CI/CD 配置文件
- 全局 Provider
- 路由聚合入口
- 全局状态管理入口
- 公共 hooks / utils
- 跨模块共享类型定义

如果确实需要修改禁止范围内的文件，AI 必须暂停并说明原因，等待人工确认。比如：

如果需要修改 package.json、全局 Provider、公共 Store 或构建配置，必须先停止执行，并输出：
1. 为什么必须修改该文件；
2. 不修改该文件是否有替代方案；
3. 修改后可能影响哪些模块；
4. 等待用户确认后再继续。

这类规则能有效避免 AI “顺手重构”。在 Codex 环境下，Skill 的边界越清晰，AI 的执行结果越稳定。

五、操作权限要分级，高危动作不能默认允许

除了文件范围，还要限制操作类型。并不是所有命令都适合让 AI 自动执行。

可以将操作分成三类。

第一类是默认允许操作，例如读取文件、定向搜索、修改指定文件、运行最小范围测试、查看 diff。这些动作风险相对较低，适合作为 Skill 的默认流程。

第二类是需要谨慎执行的操作，例如运行完整测试、执行构建、批量格式化代码、更新快照。这些动作可能影响范围较大，最好在 Skill 中限制命令格式，并要求说明执行结果。

第三类是必须人工确认的高危操作，例如安装新依赖、修改锁文件、调整 CI 配置、执行部署脚本、删除文件、重写状态管理入口、批量重命名文件。这些操作一旦出错，影响范围往往超过当前任务。

可以在 Skill 中写成如下规则：

禁止在未确认的情况下执行以下操作：
- npm install / pnpm add / yarn add
- 修改 lock 文件
- 删除源码文件
- 执行部署、发布、数据库迁移命令
- 修改 CI/CD 配置
- 重写 Store、Provider、Router 等全局入口

这种权限分级的意义在于，让 AI 明确知道哪些事情可以直接做，哪些事情必须停下来问。AI 编程不是越自动越好，而是要在合适的边界内自动化。

六、验证流程不能只写“运行测试”

很多 Skill 的验证步骤只有一句：“完成后运行测试。”这远远不够。

完整的验证流程至少应该包含四步。

第一，优先运行最小范围测试。比如修改 UserSettingsPanel.tsx，就应该优先运行对应组件测试，而不是一上来运行全量测试。

第二，在环境允许的情况下运行类型检查。对于 TypeScript 项目，类型检查可以发现很多单测覆盖不到的问题。

第三，如果测试或类型检查失败，不能简单忽略。需要说明失败原因，是代码问题、依赖缺失、权限不足，还是环境不可用。

第四，最终必须检查 diff，确认未改动任务外文件。

可以在 Skill 中加入如下流程：

# 查看修改范围
git diff --stat

# 查看具体修改内容
git diff

# 如有对应测试，优先执行最小范围测试
npm test -- UserSettingsPanel

# 环境允许时执行类型检查
npm run typecheck

这里最关键的是 git diff。即使测试全部通过，只要 diff 中出现了任务外文件，仍然说明执行过程可能越界。测试验证的是功能结果，diff 验证的是变更边界，两者缺一不可。

七、用 diff 反向优化 Skill

Skill 不是一次写完就长期不变的文档，而应该随着项目迭代持续优化。每次 AI 完成任务后，都可以用 diff 反向检查 Skill 是否有效。

复盘时可以重点看四个问题：

第一，文件入口是否定位准确。如果 AI 总是打开无关文件，说明检索命令太宽，需要收紧关键词和目录。

第二，diff 范围是否合规。如果 AI 经常修改公共文件，说明禁止范围没有写清楚，或者缺少暂停确认机制。

第三，验证步骤是否执行成功。如果 AI 经常跳过测试，说明 Skill 中没有写明失败处理规则。

第四，是否触碰了核心文件。如果任务本身不涉及全局状态、路由、配置和依赖，但 diff 中出现这些文件，就应该立即补充硬边界规则。

一个成熟的 Codex Skill，往往不是靠一次性写出完美提示，而是靠多轮真实任务不断修正出来的。越是复杂的项目，越需要把这些经验沉淀成明确规则。

八、一个更稳妥的 Skill 模板示例

下面是一个可参考的简化模板：

# Skill: 修改指定前端组件

## 目标
仅完成用户当前任务中指定的组件修改，遵循最小改动原则。

## 文件定位
优先使用窄范围搜索：
- rg "<组件名>" src
- rg "<组件名>" test src --glob "*test*"
- rg "<关键词>" src/features/<模块名>

禁止使用无范围限制的泛化搜索，除非用户明确要求。

## 修改边界
默认只允许修改：
- 用户指定文件
- 直接对应的测试文件
- 同目录内为完成任务必须修改的局部文件

禁止修改：
- package.json
- lock 文件
- CI/CD 配置
- 全局 Provider
- Router 入口
- 全局 Store
- 公共 hooks / utils

如确需修改禁止文件，必须暂停并等待人工确认。

## 验证流程
1. 运行最小范围测试；
2. 环境允许时运行类型检查；
3. 如果验证失败，说明失败原因；
4. 最终检查 git diff，确认修改范围未越界。

## 输出要求
最终输出：
- 修改了哪些文件；
- 为什么修改这些文件；
- 执行了哪些验证；
- 是否存在未验证项；
- diff 是否符合任务边界。

这个模板并不复杂，但它覆盖了定位、边界、权限、验证和输出五个关键环节。对于日常开发任务来说，已经能明显降低 AI 越界修改的概率。

结语

AI 编程工具提升效率的前提是可控。Codex 的 Skill 不是简单的提示词集合，而是面向自动化执行代理的工程约束文档。它需要把任务目标、文件边界、操作权限、验证流程和异常处理写清楚，让 AI 在明确范围内完成工作。

在真实项目中，最危险的并不是 AI 不会写代码，而是它在“看似合理”的情况下做了额外修改。组件改动牵连状态层，样式调整波及全局配置，测试通过但 diff 越界，这些问题都需要通过 Skill 规则提前拦截。

把 Skill 写细，并不是降低 AI 效率，而是让 AI 的执行结果更稳定、更可审查、更容易进入生产流程。只有当自动化能力被清晰规则约束起来，AI 才能真正成为研发效率工具，而不是新的线上风险来源。