one-hop

TLDR;

One hop: thin entry points, real logic exactly one call away, no matryoshka call stacks. I turned the discipline I use on real projects into a small public package — github.com/ryancosans/one-hop — so humans and agents get the same rules. Reuse and fancy layering take a back seat; making the next review easy does not.

Intro

A few years ago I wrote about good code and how readability beats golf and premature abstraction. That still holds. What has changed is where my time goes. I am not typing as much. I am reading more — pull requests, agent output, my own code from three weeks ago when the bug only shows up on a rainy Tuesday at Liverpool Street.

Understanding code has never been more important. Generating it is cheap. Knowing whether it is correct, safe, and worth keeping is not. Agents are especially enthusiastic about indirection: passthrough wrappers, nested orchestrators, a services/ folder that exists because it sounded enterprise. Each layer saves a few lines once and taxes every reviewer forever.

I formalised how I push back on that in one-hop. Tagline on the repo: no matryoshka call stacks.

What one-hop means

This is not vibes. It is a layering rule you can enforce in code review and in agent prompts.

Entry points — HTTP handlers, CLI mains, route files, anything wired to the outside world — delegate. They may call one function that owns the step, or sequence a few calls with early returns. They do not contain business rules, parsing, or database work.

Logic lives one hop away. From the entry, you jump once into the function that actually does the work. Not entry → router → processor → helper → maybe the logic. If you need a second hop to understand behaviour, the stack is too deep.


  entry ──► step (logic)     ✓ one hop

  entry ──► orchestrator ──► step   ✓ if orchestrator only sequences, no rules

  entry ──► a ──► b ──► c     ✗ matryoshka

The full rule text, examples, and harness notes live in the repo under rules/one-hop.md and examples/. TypeScript snippets there are deliberately small — each file is a allowed vs not-allowed pair you can point an agent at.

Why I packaged it

The rules came out of production use on Aesop. I was tired of repeating the same review comments: stop wrapping a one-liner in a function, stop adding a handler that only calls another handler, stop nesting await chains on a single return line. Writing it down once beats arguing in every PR.

The repo is modular rules/ files plus a composed assembled/AGENTS.md you can drop at the root of any project. Cursor, Claude Code, and generic system prompts each have a short harness in harnesses/. It is MIT licensed — copy it into commercial work if it helps. Project-specific stuff stays in a small overlay; the one-hop discipline stays shared.

Review is the main event

Writing code used to be the bottleneck. Review was the gate you sprinted through if CI was green. Today the flow is often inverted: a model or agent proposes a chunky change, and the human job is to understand and trim it.

One-hop optimises for that reader. A thin entry is a table of contents: you see which step runs without reading implementation. One hop into the step file and you are in the real logic — not tracing five files named things like handleThing and processThing that only forward the call.

I wrote about this shift indirectly in AI coding Station View: taste and catching fragile cleverness matter more than typing speed. One-hop is the structural half — rules agents can follow so the diff you review is not another layer cake.

Reuse takes the back seat

I grew up on DRY, shared utils, and single responsibility taken to mean "extract everything". One-hop pushes back in two concrete ways that are also in the repo:

No single-line wrappers. If a function body is one statement that reads fine inline, do not extract it. Extraction for reuse when there is only one call site is often a hop added for no reader benefit.

Shallow file layout. One file per exported function, named after the function. Avoid generic services/ and utils/ buckets until the project actually needs them. Flat, boring trees are easier to review than a taxonomy nobody remembers.

I will still share real capabilities — DB clients, auth, env parsing — because those are stable and dangerous to duplicate. I am reluctant to share product behaviour through layers of indirection just because reuse sounded elegant in a design doc.

Allowed vs not allowed

Thin entry, logic in the step (allowed):

The code snippet has been ommited on mobile, for your sanity and mine 🤝. You could turn the phone sideways if you want some context 🤷.

Business rules in the entry, or a stack of passthrough functions (not allowed):

The code snippet has been ommited on mobile, for your sanity and mine 🤝. You could turn the phone sideways if you want some context 🤷.

The first shape tells you where to look in one glance. The second looks organised and reviews like a maze. Agents generate the second pattern constantly because it mimics "clean architecture" without carrying any of the weight.

Using it on your repo

Fastest path: copy assembled/AGENTS.md to your repo root as AGENTS.md, then append a short project overlay from overlays/TEMPLATE.md. Cursor picks that up as always-on workspace guidance; other harnesses are documented in the README.

If you disagree with a rule, fork it or trim modules — manifest.yaml lists what is composable. The point is not my repo as law. The point is agreeing with your team (and your agent) on hop count before the habits calcify.

Conclusion

I am not arguing for spaghetti. I am arguing that the primary reader of most code is a reviewer, not a compiler — and increasingly that reviewer is you, squinting at agent output at midnight.

One-hop keeps stacks shallow: delegate at the edge, implement one call away, ban matryoshka wrappers. The rules are public because they helped me ship and review faster; maybe they save you a lecture in PR comments too. Take a look, steal what fits, and let reuse earn its hops instead of assuming it deserves them.

✌️

Share this post