AI 编程项目需要哪些文档?4 类约束一次讲清

AI 编程 · 项目约束

同一个项目，换一个 AI 编码工具，规则可能就失效了。一个用 pnpm，一个改成 npm；一个复用现有组件，另一个又造了一套按钮。

反复提醒能解决当前对话，解决不了下一次任务。项目需要的不是更多 Prompt，而是把不同约束放进正确的文件。

这四类文档不是都要写。先看问题属于哪一类，再决定放在哪里。

01 AGENTS.md：管整个项目

AGENTS.md 是项目级 AI 指令。它回答的是：进入这个仓库后，应该怎样工作？

适合写：

最小版本可以很短：

# Project Instructions
## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Check: `pnpm typecheck && pnpm test`
## Rules
- 使用 TypeScript strict mode。
- 优先复用 `src/components` 中的组件。
- 不修改 `generated/` 中的文件。
- 修复 Bug 时补充回归测试。

不要把某个按钮的圆角、某种发布流程的全部步骤都塞进这里。AGENTS.md 应该保存每次进入项目都值得知道的规则。

大型仓库可以在子目录继续放 AGENTS.md。越靠近目标文件的规则越具体，前端、后端和脚本目录不必共享一套细节。

02 DESIGN.md：管界面效果

DESIGN.md 是视觉决策文档。它回答的是：页面应该保持什么风格，遇到新场景时怎么选？

适合写：

不要只写“高级、现代、简洁”。这些词不能决定实现结果。

## Shapes
- 按钮、输入框和普通卡片使用 8px 圆角。
- 普通卡片使用 1px 低对比度边框，不使用重投影。
- 胶囊形只用于标签、筛选和状态，不用于内容卡片。

DESIGN.md 也不负责产品需求、代码目录和发布命令。它只管一件事：让不同页面看起来仍然属于同一个产品。

感兴趣的话，可以看看《DESIGN.md 该怎么写？17 个设计项完整拆解》。

03 SKILL.md：管一类重复任务

SKILL.md 是可复用工作流。它回答的是：遇到这类任务时，应该按什么步骤完成？

适合封装：

一个 Skill 至少包含 SKILL.md，还可以带上脚本、参考资料和模板：

release-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

是否应该写成 Skill，看三个条件：

如果规则每次任务都适用，放进 AGENTS.md；如果只在某类任务触发，才放进 SKILL.md。常驻规则和按需流程不要混在一起。

04 工具专属文件：管平台差异

工具专属文件只服务对应平台。它回答的是：这个工具还有哪些独有的读取方式和行为需要补充？

常见文件包括：

这里适合写平台特有内容，例如路径匹配、自动触发条件、Claude Code 的导入方式、Cursor Rule 的 globs，或者 Copilot 的路径级指令。

通用代码规则不要复制五份。更稳的方式是：

# CLAUDE.md
@AGENTS.md
## Claude Code
- 修改 `src/billing/` 前先进入 Plan Mode。

通用部分只维护在 AGENTS.md，专属文件只补差异。否则改了一条测试命令，就要同步修改多份文件，迟早会互相冲突。

到底需要配置哪些

按项目复杂度增加，不要一开始把四类全部建齐。

一个常见项目最后可能是这样：

project/
├── AGENTS.md
├── DESIGN.md
├── .agents/
│   └── skills/
│       └── release/
│           └── SKILL.md
├── CLAUDE.md
├── GEMINI.md
├── .github/
│   └── copilot-instructions.md
└── .cursor/
└── rules/

这不是标准答案。只使用一种工具，就不必保留其他平台的空文件。

写约束时再检查四件事

AI 指令文件提供的是上下文，不是强制执行层。权限、安全、类型和发布门禁，仍然要交给真实工具控制。

最后只记四个动词

AGENTS：工作
DESIGN：设计
SKILL：执行
专属文件：适配

判断一条新规则放在哪里，先问它约束的是项目、视觉、流程，还是某个具体工具。能回答这个问题，项目里的 AI 文档就不会越写越乱。