很多人用 AI 编程助手时，最大的问题不是工具不够强，而是规则设计一开始就乱了。

全局 AGENTS.md 写了一堆项目细节，项目 AGENTS.md 又重复全局规则，目录规则没有边界，最后还想给每个功能都建一个 Skill。看起来像是在做体系化建设，实际是在制造上下文噪音。

真正稳定的做法只有一句话：

全局管习惯，项目管事实，目录管局部，Skills 管流程。

这四层不能混。

全局 AGENTS.md 应该放什么？

只放所有项目都适用的协作规则。

比如，修改代码前先检查项目结构，不能凭空猜路径。涉及多个文件、依赖、架构调整、公共接口变化时，先给出计划。修改大文件时只做局部编辑，不要重写整文件。不能用省略号替代原有代码。不能删除用户文件。不能暴露密钥。修改后要说明改了什么、为什么改、怎么验证。

这些规则不依赖具体项目，适合长期放在全局文件里。

但全局文件不能写项目事实。

比如某个项目用什么框架，启动命令是什么，某个模块负责什么，某个接口怎么返回，某个目录怎么保存数据，这些都不应该写进全局。因为一旦换项目，这些信息就会变成误导。

项目级 AGENTS.md 应该放什么？

项目级文件只回答当前项目是什么。

它应该说明项目类型、技术栈、目录结构、模块职责、构建命令、测试命令、外部依赖、运行限制、关键约定和禁止事项。

例如，一个普通后端多模块项目，可以写清楚根配置文件是权威来源，修改模块依赖前必须检查根配置和子模块配置。接口层只做请求响应和参数处理，核心逻辑放到服务层。数据读写改动要靠近已有数据访问代码。构建优先用模块级命令，不要一上来就全量构建。

这些内容属于项目事实，应该放项目级，而不是全局。

目录级 AGENTS.md 又该放什么？

目录级规则更具体，只服务于某个目录。

比如 api 目录可以写接口层规则，service 目录可以写业务编排规则，repository 目录可以写数据访问规则，test 目录可以写测试风格和 mock 约定。

不是每个目录都要放 AGENTS.md。只有某个目录经常被 AI 改错，或者局部规则和全项目规则明显不同，才值得单独写。

规则不是越多越好，而是越准越好。

Skills 又是什么？

Skills 不是项目说明书，也不是规则文件的替代品。

Skills 是可复用的专项工作流。

一个任务反复出现三次以上，并且每次都有固定步骤，这时才值得做成 Skill。

比如常见的开发流程里，有一个非常适合做 Skill 的环节：需求已经明确，但不能直接编码，需要先确认修改点。

这个 Skill 可以叫 project-change-impact-analysis。

它的职责不是写代码，而是分析：

需求目标是什么。

入口在哪里。

调用链怎么走。

涉及哪些模块。

要改哪些文件、类、方法。

是否影响外部接口。

是否影响数据结构。

是否影响权限和安全。

是否影响已有行为。

有哪些风险。

怎么验证。

这就是典型的 Skill 场景。因为它不是某个项目专属，也不是某个功能专属，而是一类开发工作中反复出现的固定流程。

为什么不要给每个功能新增 Skill？

因为 Skill 是流程复用，不是功能归档。

如果每个功能都新建一个 Skill，很快就会失控。今天一个查询优化 Skill，明天一个权限调整 Skill，后天一个报表导出 Skill。表面上细致，实际上每个 Skill 都只用一次，维护成本越来越高。

更好的方式是先用一个通用变更影响分析 Skill 跑完整开发闭环。

第一步，做需求分析。先不要看代码，也不要写代码。把需求整理成目标、场景、用户路径、输入输出、业务规则、边界条件、验收标准和待确认问题。

第二步，调用变更影响分析 Skill。让它读取项目规则，检查项目状态，定位入口，追踪调用链，判断影响范围，输出修改点清单、风险点和验证方式。

第三步，生成实现计划。把修改点拆成 P0、P1、P2。P0 是必须改，P1 是大概率要改，P2 是可能要改或需要进一步确认。

第四步，分批编码。不要一次性让 AI 改完所有文件。先改基础结构，再改核心逻辑，再改入口适配，最后补测试和文档。

第五步，测试与复盘。对照需求和影响分析报告，检查是否漏改、是否越界、是否缺少测试、是否需要补充文档。

等你用这个流程跑过几个真实需求后，再看哪个环节最重复。若每次需求分析都很固定，再沉淀 requirement-analysis Skill。若每次实现计划都很固定，再沉淀 implementation-plan Skill。若每次实现后都需要复盘，再沉淀 implementation-review Skill。

但不要一开始就建一堆。

通用 Skill 应该避免什么？

最重要的一点：不要写公司项目相关内容。

不要出现内部系统名称。不要出现具体业务线。不要出现专有模块名。不要出现公司内部路径。不要出现真实域名、账号、环境地址、仓库地址、密钥或内部接口。

通用 Skill 应该使用抽象表达。

把具体业务入口改成入口层。

把具体服务名称改成应用层或服务层。

把具体数据模块改成数据访问层。

把具体外部项目改成外部契约。

把具体流程规则改成状态变更、权限、安全、数据兼容、外部调用等通用影响项。

这样写出来的 Skill 才能跨项目复用。

最终建议很简单：

全局 AGENTS.md 保持稳定，不要频繁扩写。

项目 AGENTS.md 记录当前项目事实，不要塞个人本地路径。

目录 AGENTS.md 只在局部规则明显不同的时候新增。

Skills 只沉淀重复出现的专项流程。

一次性功能需求，用普通提示词就够了。

把这套分层做好，AI 编程助手才不会在上下文里迷路。