I built an MCP server with Claude Code over the last few days and shipped it.
- The tool description is the product, not the handler code. The model only behaves if the description tells it to, in detail. Example from one of my tools, sourcing images for a render: Before I wrote that sentence, Claude happily fed in images with text and the output looked broken. The fix wasn’t code, it was prose in the description. My descriptions ended up 5-10x longer than the handlers.
- Make Claude prove “done” instead of claiming it. I put a hard gate in CLAUDE.md: This single section killed the “it works!” hallucinations more than anything else. Pair it with a smoke script that asserts real output (mine renders a slide and asserts it’s a 1080x1350 PNG).
- “Builds locally” is not “runs in prod.” My renderer reads a font file off disk at a process.cwd() -relative path the Next build tracer couldn’t follow. Built clean locally, crashed in prod on a missing font. I documented the footgun in CLAUDE.md so Claude stops reintroducing it. Lesson: feed your deploy-specific traps back into CLAUDE.md or the agent will rediscover them every time. The meta-lesson: CLAUDE.md plus verbose tool descriptions plus a real smoke test is the actual leverage. The code was the easy part. submitted by /u/meliwat
Originally posted by u/meliwat on r/ClaudeCode
You must log in or # to comment.