unity-asmdef

Create separate assembly definitions for editor and runtime folders, with the editor assembly referencing the runtime one. Splitting editor code from runtime first is the recommended starting point before further modularization.

Use asmdef when the project has multiple domains or systems, editor and runtime code are mixed, compile times are noticeable, or tests need clean isolation. Avoid them for tiny prototypes where fragmentation adds overhead without benefit.

Assembly definitions create compile boundaries so Unity only recompiles assemblies affected by a change rather than the entire project. Keeping the dependency graph directional and shallow maximizes this benefit.

Over-fragmentation creates many tiny assemblies that add maintenance churn without compile benefits. Prefer a few meaningful assemblies, avoid circular dependencies, and never funnel everything through a shared dumping-ground assembly.

Keep the dependency graph directional and shallow by defining clear allowed dependency directions before creating assemblies. Plan module boundaries so lower-level systems never reference higher-level ones.