The Engineering of Intent, Chapter 28: The Tips Archive — 100 Notes from Daily Practice

This is Part 28 of a series walking through my book The Engineering of Intent. In the previous chapter, we walked the anti-pattern catalog. Chapter 28 is the long-tail archive — one hundred numbered tips from daily practice, collected over years.

Dip In. Argue With the Ones You Disagree With. Steal the Ones You Like.

The whole of Chapter 28 is a hundred numbered tips, ranging from trivial to nontrivial, from obvious-once-stated to counter-intuitive. I gathered them from my own practice and the practices of engineers I work with. No narrative; read in any order. Here are twelve that readers tell me they quote most often.

Twelve to Get You Started

• #2. When the agent produces a wall of code, ask for a one-sentence summary first. Read that. If the summary is wrong, the code is wrong.
• #4. If you keep telling the agent the same thing, put it in agents.md. Three repetitions is the threshold.
• #8. Every convention in conventions.md should be testable in some way — by lint, type, or review. Untestable conventions rot.
• #11. Do not let the agent see your failed attempts; they bias it toward the failed direction. Start clean when you restart.
• #15. If a test is slow, speed it up. Slow tests do not get run. Tests that do not get run are not tests.
• #21. When the agent writes a comment “// TODO: handle edge case” — do not merge. The TODO is a lie.
• #25. Never let the agent pick the name of a public API. Naming is a human responsibility.
• #34. Keep a running “lies we used to believe” document. It is the most useful project artifact after architecture.md.
• #38. Silence is a signal. When the agent produces a confident answer without caveats, be suspicious.
• #40. Diff the agent’s output against what you asked for. The gap is where learning lives.
• #49. Do not be the engineer who says “the code is self-documenting.” The code documents mechanism. The comments document intent.
• #56. Do not estimate in hours for agent-assisted work. Estimate in cycles.

“Not every tip here will land for you. That is expected. One hundred tips is not a doctrine — it’s a library. The ones that resonate are the ones that match a mistake you’ve recently made. The ones that don’t resonate now will resonate later, or never, and either is fine.”

Next up — Chapter 29: Vibe Coding in the Backend. Part IX of the book starts the deep dives. The next five chapters take the general practice and apply it to specific domains — backend, frontend, data and ML, platform, and a personal operating system. Chapter 29 starts with the backend.