Teaching AI to Understand SODA
soda is an opinionated framework. Given the same feature, an AI will happily produce seven different flavors of Java — but only one of them fits soda. Without this guide, the AI will invent a @Command annotation (soda has none), match QueryHandlers by inheritance (it matches by exact class), and return void from a CommandHandler (which silently drops every domain event).
Write the architectural conventions, naming rules and hard constraints into a file, drop it into the project, and the AI gets it right the first time.
If you generated a project with the generator, you already have this file — CLAUDE.md in the project root. Claude Code and Cursor load it automatically. This page is for people who didn't use the generator, or who want it in a different IDE.
Two ways in
Path 1: generate a project (least work)
Open start.soda.hibuka.com, fill in package and project names, download. The root of the generated project ships with CLAUDE.md. Open it in any AI IDE and go.
Path 2: install the guide into your own project
Whether the project came from the generator or was hand-built, copy the full text of the AI Guide and save it at the filename your IDE reads. The table below is where each IDE looks.
Install it in your AI IDE
Each IDE reads a different filename in a different place. The content is identical — only the filename and path change.
| AI IDE | Filename | Where | Auto-loaded |
|---|---|---|---|
| Claude Code | CLAUDE.md | project root | yes, on session start |
| Cursor | AGENTS.md, or .cursor/rules/soda.mdc | project root / .cursor/rules/ | yes |
| Windsurf | .windsurfrules | project root | yes |
| Cline | .clinerules | project root | yes |
| GitHub Copilot | .github/copilot-instructions.md | .github/ | yes (Copilot Chat / Coding Agent) |
| Zed | .rules | project root | yes |
| Trae / Qoder | AGENTS.md | project root | yes |
| anything else | — | — | paste the whole text into the top of the chat |
Most IDEs also support manual loading: start a new chat, paste the text, say "write code following these conventions." No file needed — you just have to paste it every time.
What's in the file
The AI Guide is a standalone, directly copyable document covering:
- the four-layer call chain (
Controller → AppService → BusFacade → Handler → Repository) - a core-concepts table (
BusFacade/BasePageQuery/QueryHandler/CommandHandler/PageVO/Result) - file naming conventions (
XxxData/XxxDetail/CreatXxxCommand/ListXxxQuery/XxxVO/XxxDo…) - the two hard constraints AI trips on most: the generic must agree in three places, and
CommandHandlermust return the aggregate root - configuration keys (including the trap that
soda.event.*andscoda.ddd.cqrs.async.*use different prefixes) - build and test commands, plus the common pitfalls
How to actually use it
The file isn't "paste once and forget." Pointing the AI at a concrete scenario makes a large difference:
| You say | What you get |
|---|---|
| "add a query endpoint" | just a QueryHandler, with AppService / Assembler / Controller missing |
| "add a Producer list endpoint, following Scenario A in the AI Guide" | the full chain, with correct names and generics |
CLAUDE.md in your project is background knowledge. The specific task still has to come from you. For framework details, configuration reference and error codes, send the AI to the Reference section.
Next
- AI Guide (copyable) — grab the file
- Core Concepts — read it once yourself; you and the AI will work better together
- Project Structure — where the code lives, and why