iOS 工程 AI 说明文件怎么写：CLAUDE.md 等说明文件模板

Q: Copilot 的说明文件放在哪里？

放在仓库的 .github/copilot-instructions.md。只对部分文件生效的规则放在 .github/instructions/ 下，文件名以 .instructions.md 结尾，用 applyTo 指定路径。

Q: Cursor 规则文件为什么不生效？

先看扩展名和开头。.cursor/rules/ 里的规则要用 .mdc 文件并带 frontmatter，想每次都生效就写 alwaysApply: true，没有 frontmatter 的普通 .md 会被忽略。不想维护 .mdc 的，直接把内容写在根目录的 AGENTS.md。

Q: 写了说明文件 AI 还是用了高版本 API 怎么办？

在说明文件里把规则写具体，列出不能用的 API 名字和最低版本，并要求改完执行编译检查命令。编译报 is only available in iOS xx or newer 时，AI 能根据错误自己改回来。

iOS 工程写好 AI 说明文件，AI 助手就不会用错 API、乱加依赖或碰证书。Claude Code 读 CLAUDE.md，Copilot 和 Cursor 各有规则文件，三者都支持 AGENTS.md。附 SwiftUI、Flutter 等 4 份可直接复制的模板。

AI 说明文件是放在仓库里、AI 编程助手每次对话都会先读的约定文件，写好它，AI 就不会用错 iOS 版本的 API、乱加依赖或去碰证书。Claude Code 读 CLAUDE.md，GitHub Copilot 读 .github/copilot-instructions.md，Cursor 读 .cursor/rules/ 下的 .mdc 规则，三者都支持通用的 AGENTS.md。这篇先给出对照表和共用一份文件的办法，再给 SwiftUI、UIKit + CocoaPods、Flutter、React Native / Expo 四份可以直接复制的模板。

AI 助手在 iOS 工程里的完整工作流程（提需求、审代码、编译、真机验证）见在 VS Code 里用 AI 编程助手写 iOS App，这里只讲说明文件本身。

各 AI 工具读哪个说明文件？

下表按各工具官方文档整理，截至 2026 年 10 月。

工具	项目说明文件	按路径生效的规则	是否读 AGENTS.md
Claude Code	根目录 `CLAUDE.md` 或 `.claude/CLAUDE.md`，个人用的 `CLAUDE.local.md`	`.claude/rules/*.md`，用 `paths` 限定路径	仓库里没有 CLAUDE.md 时读，也可以在 CLAUDE.md 里写 `@AGENTS.md` 导入
GitHub Copilot	`.github/copilot-instructions.md`	`.github/instructions/*.instructions.md`，用 `applyTo` 限定路径	读，VS Code 里由 `chat.useAgentsMdFile` 控制
Cursor	`.cursor/rules/*.mdc`	同一目录，用 `globs` 限定路径	读，根目录和子目录都支持

几个细节。

Claude Code 的说明见 How Claude remembers your project。在会话里运行 /context，在 Memory files 下能看到加载了哪些文件。/init 可以先生成一份草稿再改。
Copilot 的说明见 GitHub 文档和 VS Code 文档。VS Code 里打开 chat.useClaudeMdFile 后，Copilot 也会读 CLAUDE.md。
Cursor 的说明见 Rules。.cursor/rules 里的文件要用 .mdc 扩展名并带 frontmatter，没有 frontmatter 的普通 .md 会被忽略。

一份内容给三个工具用

团队里各人用的工具不同时，把内容写在根目录的 AGENTS.md，其他文件只做引用，避免几份说明互相矛盾。

Copilot、Cursor。直接读 AGENTS.md，不用再加文件。
Claude Code。仓库里没有 CLAUDE.md 时直接读 AGENTS.md。还需要写 Claude 专用内容的，建一个 CLAUDE.md，第一行导入它。

1@AGENTS.md
2
3（下面只写 Claude Code 专用的补充，没有就留空）

只给 Cursor 用、又想始终生效的，在 .cursor/rules/ios.mdc 里这样写。

1---
2description: iOS 工程约定
3alwaysApply: true
4---
5
6（正文同下面的模板）

AI 说明文件该写什么、写多少？

只写 AI 看不出来的事实。最低 iOS 版本、哪些依赖能用、哪些文件是生成的、怎么编译检查，这些从代码里不容易推出来。「用 Swift 写」「变量名要有意义」这类 AI 本来就会做的不用写。
短。Claude Code 建议每个文件 200 行以内，Cursor 建议规则 500 行以内，VS Code 文档建议每条规则一句话。越长，AI 越容易漏掉其中的某一条。
可验证。每条规则最好能用一条命令或一个具体名字检查，例如「改完执行 xx 命令，没有 error 才算完成」，比「保证代码质量」有用得多。
写上原因。「新增字段必须是可选类型，因为旧数据已经存在用户手机上」比只写「用可选类型」更能让 AI 在相似场景下做对。
跟着工程更新。升级了最低 iOS 版本、换了依赖，同一次提交里改说明文件。过时的规则比没有规则更糟。

说明文件只是提示，AI 不一定每次都遵守。证书这类必须挡住的内容，还要用各工具自己的忽略或权限设置排除掉。

模板一：SwiftUI App 的说明文件怎么写？

适合 Xcode 工程、Swift Package 管理依赖的新工程。把工程名、版本号、目录换成你自己的。最低 iOS 版本在 KXBuild 视图中右键 target 选「KXBuild: 编辑目标设置」，General 页的 iOS Deployment Target 就是。

 1# MyApp
 2
 3## 工程
 4- iOS App，SwiftUI，Swift 5，最低支持 iOS 16.0。iOS 17 及以上才有的 API（@Observable、SwiftData 等）要用 if #available 包起来，或换成 iOS 16 的写法。
 5- 只有一个 App target MyApp，工程文件 MyApp.xcodeproj。
 6
 7## 依赖
 8- 依赖只用 Swift Package，当前有 Alamofire、Kingfisher。不要引入 CocoaPods。
 9- 需要新依赖时先问我，不要自己添加。
10
11## 目录
12- MyApp/Views：界面。MyApp/Models：数据结构。MyApp/Services：网络和存储。
13- 数据模型已存进用户手机，新增字段必须是可选类型或带默认值，否则旧数据解码失败。
14
15## 检查
16- 改完代码在仓库根目录执行 kxbuild build .\MyApp.xcodeproj -D CODE_SIGNING_ALLOWED=NO，有 error 继续改，直到通过。
17- 编译通过不代表功能正确，告诉我需要在手机上验证哪些操作。
18
19## 禁止
20- 不要读取或修改 keychain/ 目录，以及任何 .p12、.mobileprovision、password.properties 文件。
21- 用到相机、相册、定位、麦克风等权限时，提醒我加 Info.plist 用途说明（如 INFOPLIST_KEY_NSCameraUsageDescription），并给出一句中文文案。

模板二：UIKit + CocoaPods 老工程

适合 Objective-C 和 Swift 混编、用 Podfile 管理依赖的老工程。这类工程最容易出错的是构建对象和桥接头文件，写清楚。

 1# LegacyApp
 2
 3## 工程
 4- iOS App，UIKit，Objective-C 和 Swift 混编，最低支持 iOS 13.0。
 5- 依赖用 CocoaPods，编译用 LegacyApp.xcworkspace，不要用 .xcodeproj。
 6- Swift 调 Objective-C 的头文件统一加到 LegacyApp/LegacyApp-Bridging-Header.h。
 7- 界面用 Storyboard 和 xib，不要改成 SwiftUI。新页面用纯代码 UIKit 写。
 8
 9## 依赖
10- Podfile 里的库已锁定在 Podfile.lock，不要运行 pod update。
11- 不要往 Podfile 加新库。确实需要时先问我，优先考虑 Swift Package。
12- Pods/ 目录是生成的，不要修改里面的文件。
13
14## 目录
15- LegacyApp/Classes/Modules：按业务模块分的页面，每个模块一个文件夹。
16- LegacyApp/Classes/Common：公共工具类，改动前先搜索有哪些地方在用。
17
18## 检查
19- 改了 Podfile 后先在 Podfile 所在目录执行 pod install。
20- 改完代码执行 kxbuild build .\LegacyApp.xcworkspace -D CODE_SIGNING_ALLOWED=NO，有 error 继续改，直到通过。
21
22## 禁止
23- 不要读取或修改 keychain/ 目录，以及任何 .p12、.mobileprovision、password.properties 文件。
24- 不要改 project.pbxproj 里的签名设置（CODE_SIGN_*、PROVISIONING_PROFILE_*、DEVELOPMENT_TEAM）。
25- 用到新的隐私权限时，提醒我在 LegacyApp/Info.plist 加对应的 UsageDescription 键和中文文案。

工程打算从 CocoaPods 迁到 Swift Package 的，迁移期间把「依赖」一节改成当前状态，做法见 CocoaPods 迁移到 SPM。

模板三：Flutter

Flutter 工程的大部分代码是 Dart，检查用 Flutter 自己的命令。改了 ios 目录下的原生代码时，再用 KXBuild 编译一次 iOS 端。第一次在这台电脑上编译前，先在工程根目录运行一次 kxbuild doctor .。

 1# my_flutter_app
 2
 3## 工程
 4- Flutter App，Dart 代码在 lib/，iOS 原生代码在 ios/Runner/（Swift）。
 5- iOS 最低支持 13.0。Dart 侧不要写只有 Android 才能用的插件或 API。
 6
 7## 依赖
 8- 加依赖用 flutter pub add，不要手动改 pubspec.lock。新增插件前先问我，并确认它支持 iOS。
 9- 不要修改 ios/Flutter/ 下的生成文件和 GeneratedPluginRegistrant。
10
11## 目录
12- lib/screens：页面。lib/widgets：可复用组件。lib/services：网络和存储。
13- 状态管理用 provider，不要引入其他状态管理库。
14
15## 检查
16- 改完 Dart 代码执行 flutter analyze 和 flutter test，没有 error 才算完成。
17- 改了 ios/ 下的原生代码时，再执行 kxbuild build .\ios\Runner.xcworkspace -D CODE_SIGNING_ALLOWED=NO。
18
19## 禁止
20- 不要读取或修改 keychain/ 目录，以及任何 .p12、.mobileprovision、password.properties 文件。
21- 加了用到相机、相册、定位、麦克风的插件时，提醒我在 ios/Runner/Info.plist 加插件文档要求的 UsageDescription 键和中文文案。

模板四：React Native / Expo

React Native 和 Expo 共用一份，按你的工程删掉不适用的那几行。Expo 工程如果 ios 目录是生成出来的，要明确告诉 AI 不要直接改它。

 1# rnhello
 2
 3## 工程
 4- React Native App，TypeScript，代码在 src/，iOS 原生工程在 ios/。
 5- iOS 最低支持 15.1，以 ios/Podfile 里的 platform 为准。
 6- （Expo）ios/ 目录由 prebuild 生成，不要直接修改。原生配置改 app.json，权限说明写在 expo.ios.infoPlist。
 7
 8## 依赖
 9- 包管理器用 npm，不要用 yarn 或 pnpm，不要删除 package-lock.json。
10- （Expo）加依赖用 npx expo install，保证版本和当前 SDK 匹配。
11- 新增带原生代码的库前先问我，加完后要在 ios/ 目录执行 pod install。
12
13## 目录
14- src/screens：页面。src/components：组件。src/api：接口请求。
15- 导航用 React Navigation，不要引入其他导航库。
16
17## 检查
18- 改完代码执行 npx tsc --noEmit 和 npm test，没有错误才算完成。
19- 改了 ios/ 下的原生代码时，再执行 kxbuild build .\ios\rnhello.xcworkspace -D CODE_SIGNING_ALLOWED=NO。
20
21## 禁止
22- 不要读取或修改 keychain/ 目录，以及任何 .p12、.mobileprovision、password.properties 文件。
23- 不要把 API 密钥写进代码，从 .env 读取，.env 不要提交。
24- 用到相机、相册、定位、麦克风时，提醒我加 Info.plist 的 UsageDescription 键（Expo 写在 app.json）和中文文案。

四份模板里关于权限说明的那一条，键名和文案写法见 Info.plist 权限用途说明大全。

放进仓库后怎么确认 AI 读到了？

按上面的对照表把文件放到对应位置，和代码一起提交，团队成员拉代码后就能用上。
开一个新对话，问 AI「这个工程最低支持哪个 iOS 版本，改完代码要怎么检查」，答对了说明它读到了。Claude Code 还可以用 /context 确认。
发现 AI 反复犯同一个错，就在说明文件里加一条可验证的规则，而不是每次在对话里重复提醒。

kxbuild build 的其他参数，比如指定 scheme、target，见 kxbuild 命令参考，需要时把它们写进 AI 说明文件的检查命令里。

常见问题

CLAUDE.md 和 AGENTS.md 要两份都写吗？

不用。内容写在 AGENTS.md，Copilot 和 Cursor 都会读。Claude Code 在没有 CLAUDE.md 时直接读 AGENTS.md，需要 CLAUDE.md 时在里面写一行 @AGENTS.md 导入即可。

Copilot 的说明文件放在哪里？

放在仓库的 .github/copilot-instructions.md。只对部分文件生效的规则放在 .github/instructions/ 下，文件名以 .instructions.md 结尾，用 applyTo 指定路径。

Cursor 规则文件为什么不生效？

先看扩展名和开头。.cursor/rules/ 里的规则要用 .mdc 文件并带 frontmatter，想每次都生效就写 alwaysApply: true，没有 frontmatter 的普通 .md 会被忽略。不想维护 .mdc 的，直接把内容写在根目录的 AGENTS.md。

说明文件写多长合适？

越短越好，一般几十行就够。Claude Code 建议 200 行以内，Cursor 建议 500 行以内。超过的部分按路径拆成单独的规则文件。

写了说明文件 AI 还是用了高版本 API 怎么办？

在说明文件里把规则写具体，列出不能用的 API 名字和最低版本，并要求改完执行编译检查命令。编译报 is only available in iOS xx or newer 时，AI 能根据错误自己改回来。