Yeda AI Tips · #058

Español

Document Gotchas Inline, Where They Bite

The bug that cost you a day? Write the warning right where the next person will hit it. A wiki page nobody opens does not stop the next trap — the code file is the one document that every future reader is guaranteed to have open at the exact moment they're about to repeat your mistake. That now includes your AI coding assistant, which reads the file you point it at, not your team's knowledge base.

Why the wiki loses

A gotcha is knowledge with a location. "This endpoint silently truncates payloads over 1 MB" is useless in a Confluence page titled API Notes and priceless as a comment above the function that builds the payload. Jeff Atwood's rule still holds two decades on: code can only tell you how the program works; comments tell you why. The truncation limit is visible in the code — the fact that it once ate a day of production debugging is not.

Discovery cost decides everything. A wiki warning requires the reader to (1) know the page exists, (2) suspect this function is the risky one, and (3) go look — three steps that each fail silently. An inline comment requires zero steps: it's in the diff view, the editor, the grep output, and the context window.

How to write the warning

Put the comment on the risky symbol, not at the top of the file, and make it carry three things:

# IMPORTANT: send_batch() silently drops events after the first
# failure in a batch (upstream API returns 200 either way).
# Why: the vendor treats a batch as best-effort delivery.
# If you need all-or-nothing, call send_single() in a loop —
# yes it's slower; we lost a day of analytics data learning this.
def send_batch(events: list[Event]) -> None:
    ...

The anatomy:

PartQuestion it answersWithout it
TrapWhat goes wrong?Reader doesn't know there's a trap
WhyWhat's the underlying cause?Reader "fixes" the workaround and reintroduces the bug
Escape hatchWhat should I do instead?Reader knows the danger but reinvents your day of debugging

Google's Python style guide states it plainly: "If you're going to have to explain it at the next code review, you should comment it now." And its C++ guide's "leave a trace for the reader" principle says the same — when something surprising is happening, leave textual hints at the point of use.

What not to write: comments that restate the code. The Stack Overflow engineering blog's first rule of commenting is "don't duplicate the code" — a gotcha comment earns its lines precisely because it says something the code cannot.

Your agent reads these too

This is the part that changed the economics. Inline warnings used to protect only the humans who happened to read carefully. Now every coding agent that loads the file gets the warning injected straight into its context — for free, at the moment it matters. Anthropic's Claude Code guidance explicitly lists "common gotchas or non-obvious behaviors" as content worth persisting for the agent, and notes that emphasis markers like IMPORTANT measurably improve adherence. The same # IMPORTANT: prefix that catches a human eye in review is a signal the model weights when deciding whether to call your booby-trapped function.

The payoff is symmetric: the next engineer and the next agent both dodge the trap, instead of your team paying for the same bug twice.

Power-user moves

Resources

Building an AI feature? Yeda AI designs, audits, and ships production LLM systems.

Talk to us · Read the blog