unity-asmdef

Start by separating editor code from runtime code, then group runtime code into a few meaningful domain assemblies. Keep the dependency graph directional and shallow, and migrate incrementally rather than restructuring everything at once.

Use asmdef when your project has multiple domains or systems, editor and runtime code are mixed, compile times are becoming noticeable, or tests need clean isolation. Tiny prototypes do not benefit and should avoid the added fragmentation.

Yes, assembly definitions let Unity recompile only the assemblies affected by a change instead of the entire project. The benefit grows with project size, but only when assemblies are split along meaningful boundaries with shallow dependencies.

Circular dependencies occur when two assemblies reference each other directly or through a chain. Fix this by reversing one dependency direction or extracting shared types into a lower-level assembly both sides can reference.

Common mistakes include creating too many tiny assemblies, forcing everything through a shared dumping-ground assembly, and introducing circular references. Prefer a few meaningful assemblies with a clear editor/runtime/test split.