YuviUX — Product Designer
AdaptationsDeveloper Tooling

Writing Coding Conventions for Claude Code

Building this portfolio with an agent turned every unwritten preference into a rule I had to state out loud — and the ones that worked were the ones a wrong answer fails against loudly.

Writing Coding Conventions for Claude Code
Published On 05 Jun 2026

Taste is not instructions

Left to itself an agent writes competent, average code: an arbitrary Tailwind value here, a hex colour there, a component with a heading typed straight into the JSX. None of it is wrong exactly, and all of it is what a design system exists to prevent. The gap was never capability — it was that my preferences had never been written down anywhere, including for me.

Rules that fail loudly beat rules that ask nicely

"Prefer design tokens" gets followed most of the time, which is the worst possible rate: often enough to look consistent, not often enough to be. "No arbitrary values, no hex codes, no px" gets followed every time, because it is a rule you can check by searching. The conventions that stuck all have a tripwire — a token list to validate against, a folder content may not enter, a build that stops and names the file.

Structure the agent can navigate

Half the file is not style at all, it is where things go: primitives, cards, sections, and the order to build them in. Asked for a section with no map, an agent invents one component that does everything. Given the layering it builds bottom-up — and so does the next person.

Write down what you would say in review

The test for whether a rule belongs in the file is simple. If I would say it in a code review, and I would say it more than once, it is a convention, and it should have been written down before the first time.