Making an engine readable to AI agents
Hydro has 500+ source files and strict house rules. Here is the harness that lets Claude and a local Qwen model work in it without guessing.
Coding agents are good at writing code and bad at knowing your code. Dropped into a repository of 500+ C++ files with house rules, they guess: at conventions, at where things live, at whether a change even compiles. Every guess turns into a review comment.
So I treat the repository itself as the agent's onboarding. Everything an agent needs is something it can look up or run, not something it has to infer.
1. A short entry point
CLAUDE.md is deliberately short. It doesn't explain the engine; it says how to find things cheaply:
- Read
docs/CodeMap.mdfirst: every file in one line, and which files each kind of change touches. - Then open only the section of the full doc you need. Don't read docs end to end.
- Search, don't guess. Unfinished work is tagged
TODO(assets); every doc ends with "Known gaps".
It also lists the handful of rules agents break most often, the test scenes where new systems must appear, and how to check, build and read CI from a cloud session.
2. Rules as a skill, with a checklist
The full architecture lives in a hydro-engine-architecture skill: subsystem lifecycle and naming, how resources are created, components as plain data, renderer rules, how game scripts are laid out. It ends with a checklist to run before handing work back. The docs folder stays the source of truth; when they disagree, the docs win.
3. Every rule a script can check
A rule only in prose is a rule that gets broken. Hydro's rules are enforced by tools the agent runs itself:
lint_conventions.pychecks the house style: everything innamespace Hydro, no!operator, braces on every body,m_PascalCasemembers, no includes across game-script areas.validate_project.pychecks scenes, prefabs and data files against the code, so a renamed field can't silently break a scene.check.shruns a g++ syntax check, glslang on the shaders, the linter and the validator in one go.- GitHub Actions builds Debug and Release on Windows for every push and writes an error summary the agent can fetch with
gh run view --log-failed.
4. Guardrails
- No commit or push without an explicit yes. Multi-step work goes to a
claude/<topic>scratch branch so CI can check it. - From a cloud session, edits go to my working copy, guarded by each file's modification time, never only to a clone.
- Docs are updated as part of the change, and a script mirrors them to the wiki.
5. Big model, small model
Not every task needs a frontier model. For Qwen Code on a local Ollama model, I wrote a slimmer harness sized for a small context window: a short C++ conventions file that only loads when C++ files are open, and a hydro-quick-edit skill that defines exactly what "small" means (a field, a setting, a rename, a doc row) and sends anything larger to the full skill or to Claude.
That split is the part I'm happiest with: small, contained edits run locally for free, and architecture work goes to the stronger model with the full context.
What changed
Diffs got smaller and closer to how I'd write them, and review became about design rather than style. The biggest lesson carries over to any team: the things that make a codebase easy for an agent are the same things that make it easy for a new hire. A code map, checkable rules and fast feedback help everyone.