让 AI 理解 SODA
soda 是个有约定的框架。同样的功能，AI 闭着眼睛能写出七八种 Java 写法，但只有一种符合 soda 的路数。少了这份说明，AI 会给你 @Command 注解（soda 里根本没有）、把 QueryHandler 写成按继承匹配（实际按精确类匹配）、让 CommandHandler 返回 void（那样领域事件永远发不出去）。
把架构约定、命名规范和硬约束写成一份说明文档放进工程，AI 打开就懂，写出来的代码直接能跑。
提示
用生成器下过工程的用户已经拿到这份文档了 —— 工程根目录的 CLAUDE.md 就是。Claude Code / Cursor 打开工程会自动加载。这一页是给「没用生成器」和「想装进别的 IDE」的人准备的。
两条路
路 1：直接生成工程（最省事）
打开 start.soda.hibuka.com，填包名项目名，下载。工程根目录自带 CLAUDE.md，用任何 AI IDE 打开就能干活。
路 2：把指南装进你自己的工程
不管工程是从生成器下的还是自己搭的，都可以把 AI 指南 那一页的全文复制下来，按你 IDE 认的文件名放进工程根目录。下面这张表是各 IDE 的落点。
装进你的 AI IDE
不同 IDE 读的文件名和位置不一样。内容是同一份，只换文件名和路径。
| AI IDE | 文件名 | 放哪 | 自动加载 |
|---|---|---|---|
| Claude Code | CLAUDE.md | 工程根目录 | 是，启动就读 |
| Cursor | AGENTS.md，或 .cursor/rules/soda.mdc | 工程根目录 / .cursor/rules/ | 是 |
| Windsurf | .windsurfrules | 工程根目录 | 是 |
| Cline | .clinerules | 工程根目录 | 是 |
| GitHub Copilot | .github/copilot-instructions.md | .github/ | 是（Copilot Chat / Coding Agent） |
| Zed | .rules | 工程根目录 | 是 |
| Trae / Qoder | AGENTS.md | 工程根目录 | 是 |
| 其他 | — | — | 直接把全文贴进对话开头 |
技巧
多数 IDE 也支持手动加载：开个新对话，把全文粘进去说「按这份约定写代码」。不装文件也能用，只是每次都要贴一遍。
那份文档里有什么
AI 指南 是一份可直接复制的独立文件，覆盖：
- 四层架构调用链（
Controller → AppService → BusFacade → Handler → Repository） - 核心概念表（
BusFacade/BasePageQuery/QueryHandler/CommandHandler/PageVO/Result） - 文件命名约定（
XxxData/XxxDetail/CreatXxxCommand/ListXxxQuery/XxxVO/XxxDo…） - 两个 AI 最容易踩的硬约束：泛型三处必须一致、
CommandHandler必须返回聚合根 - 配置项（含
soda.event.*与scoda.ddd.cqrs.async.*前缀不一致这个坑） - 构建测试命令、常见陷阱、别踩的坑
建议的用法
文档不是贴上就一劳永逸。给 AI 派活时补一句具体场景，效果差很多：
| 你说 | AI 做 |
|---|---|
| 「加个查询接口」 | 只生成 QueryHandler，漏掉 AppService / Assembler / Controller |
| 「按 AI 指南 的场景 A，加一个查 Producer 列表的接口」 | 走完整链路，命名和泛型都对 |
工程里的 CLAUDE.md 是背景知识，具体任务还得你点。框架本身的细节、配置参考和错误码，让 AI 自己去 参考 那一组查。
下一步
- AI 指南（可复制） —— 拿到那份文件
- 核心概念 —— 人来读一遍，跟 AI 配合更顺
- 工程结构 —— 代码在哪、为什么在那