I love Antlers, but I keep bumping into the same issues. This could be me, this could be odd behavior or this could be confusing documentation. Either way I thought I'd share

Query builders
As a frontender I never want a query builder returned, I don't know what it is and how to work it. Nor will I ever understand. It's unclear when you receive them, it's unclear when you don't.

For example I have an entries field and I want a random entry from it. This should be - from my findings - a documented way to do it:

{{ testimonials | shuffle | limit(1) }}
{{ /testimonials }}

That doesn't work. It just renders all testimonials.

This is the solution, but it seems completely undocumented:

{{ testimonials sort="random" limit="1" }}
{{ /testimonials }}

I think this is because some fields return those query builders things. As a frontender I'm always struggling what to use because it's really unclear to me what I get returned.

Loops
Whenever you use a loop and there's no results:

{{ testimonials sort="random" limit="1" }}
   This wil always render.
{{ /testimonials }}

So we need an extra check:

{{ if testimonials }}
   {{ testimonials sort="random" limit="1" }}
      This will only render when there's actual results. 
   {{ /testimonials }}
{{ /if }}

Life would be so good without that extra if.