Read on the web

This newsletter contains: how to organize instructions for LLM agents (and why less is more), two classic communication anti-patterns, and a personal comparison of the apps for running coding agents.

Context engineering

Context engineering - YY Ahn

How to organize instructions and context for LLM agents—, , and skill files in harnesses like Claude Code. My core principle is Progressive disclosure: thin...

I wrote up how I organize instructions and context for LLM agents—CLAUDE.md, AGENTS.md, and skill files.

I believe that the most common mistake is over-engineering: trying to instruct too much and constrain too much. This actually feels productive—every rule you write down seems like accumulated wisdom—but it easily backfires, for the following three reasons:

1. Rules confine: what you prescribe may not be the best way, and a prescription written for weaker models becomes a ceiling for new ones.
2. Rules distract: instruction files are injected into every session, and it can be distracting. Indeed, Gloaguen et al. (2026) found that repository context files tend to reduce coding-agent success rates while increasing inference cost by over 20%.
3. Rules rot: models and workflows change, so every rule added is something you now have to maintain.

A good principle is progressive disclosure: thin pointers at the top ("where things are" and "when to look for this"), detail discovered on demand. Prune aggressively at every model upgrade. Boris Cherny, the creator of Claude Code, even advises deleting your CLAUDE.md every six months and starting fresh. One caveat: this applies to knowledge, not guardrails. Non-negotiables (e.g., "never rm") belong in deterministic permission rules and hooks, not in files the model may or may not read.

Don't ask to ask, and ask about X, not Y

https://yyahn.com/wiki/XY-problem/ and https://yyahn.com/wiki/Don't-ask-to-ask,-just-ask/

Two short notes on old internet-chat wisdom about asking questions well. "Don't ask to ask": in an asynchronous chat, ask the actual question instead of first asking whether anyone is around who knows about X—you save a back-and-forth and don't exclude people who could help through adjacent experience.

The XY problem: you have problem X, you guess Y might solve it, and you ask about Y instead of X—so everyone wastes time on the wrong question. The fix for both is the same: state the underlying problem and its context up front.

I keep coming back to these because this happens all the time in the lab, in the classroom, and when working with AI agents. A prompt that describes the real problem with context is better than a prompt about your guessed solution, for the same reason it works on humans.

AI agent interfaces

There's a fast-growing zoo of apps for running and monitoring many coding agents, and I've been churning through them: starting with simple iTerm2 + tmux → bare Ghostty splits → cmux → Orca → Ghostty + Herdr → Paseo, my current pick. Alongside these, I also use the Codex app a lot, in combination with its iOS app. I put together a comparison page covering the harness-native interfaces (Claude Code TUI/desktop, the Codex app), agent-aware terminal multiplexers (Herdr, cmux), and multi-agent apps (Paseo, Orca).

One property I refuse to lose anywhere in this chain is tmux's old trick: detach and reattach. Close the window—or lose the connection—and the session lives; the agents keep working, and you reattach whenever you want. Herdr's persistent sessions and Paseo's local daemon both keep this property.

Underneath all of this sits the terminal app itself, and it matters more than it seems. I've settled on Ghostty, Mitchell Hashimoto's GPU-accelerated, platform-native terminal, almost entirely because of its speed—it stays snappy no matter what the agents are doing. Speed is exactly why I gave up on Warp, which has grown into a full "agentic development environment" with agent orchestration built in: it does a lot, but it felt slow. After starting on iTerm2, snappiness turned out to be the one feature I can't give up.

To me, Paseo is more or less a codex clone that can work well with other agents. It allows you to use many channels—desktop, web, mobile, or CLI clients. Other than simply working well, it addresses a pet-peeve in Claude Code app: it allows explicit control over when a follow-up prompt is injected—send it now, or queue it for the agent's next turn. The Codex app has this; the Claude Code TUI doesn't, and you can't predict when a typed prompt will land.

That's it for now!

yy

Read on the web

Know someone who'd find it informative? Please forward it along! ;)

Did someone forward you this? You can subscribe here.