AI agents do not feel the cost of bad code. We do.
When a human maintains a growing codebase, the pain compounds. Every shortcut, every duplicate function, every defensive check that can never fire makes the next change a little harder.
At some point the pain gets big enough that we are forced to stop and refactor. That feedback loop is annoying, but it is also what keeps a codebase alive.
An agent never feels any of that. It solves the ticket in front of it and moves on. So it extends bad structure without noticing, adds code without ever deleting, and guards every edge case it can imagine because "comprehensive" looks safer than "minimal."
None of that breaks a test, so none of it gets flagged. The codebase quietly fills up with noise, and the person who inherits it is the one who pays.
So I wrote a small CLAUDE.md with one job: write as if a human will maintain this, because a human will. Five principles:
- This is not your last task. Fix structure, do not stack patches.
- Subtraction is a feature. Deleting code is real work.
- Say no to abstraction. Rule of three. Nothing nobody asked for.
- Completeness is not thoroughness. Guard real boundaries, not imagined ones.
- Match, do not improve. Every changed line traces to the request.
The agent is good at producing code. Our job is making sure it respects the next person who reads it.
Repo is open. Built on Sonar's AC/DC cycle and Karpathy's CLAUDE.md.
rohan-krishna
/
empathetic-coding
CLAUDE.md for coding agents to be more empathetic towards human-maintainers and write code that's not a nightmare to debug at 2AM.
Empathetic Coding
Drop-in behavioral guidance that makes AI coding agents write maintainable code instead of bloat.
The problem
Agents don't feel the cost of bad code. A human maintaining a growing codebase feels the pain rise until they refactor; an agent feels nothing, so it extends bad structure, adds without deleting, and over-guards every edge case because "comprehensive" looks safer. None of it breaks a test, so none of it gets fixed. The fix is empathy as a synthetic reflex — make the agent simulate the maintainer it can't feel.
What's here
Three versions of the same guidance, same five principles, different lengths. Pick by where it runs.
| File | Size | Use it as |
|---|---|---|
CLAUDE.md |
~1000 words | Reference / team onboarding — teaches the reasoning |
CLAUDE-lean.md |
~700 words | The working middle |
CLAUDE-distilled.md |
~290 words | Standing agent context, where every token competes |
Usage
Rename your chosen version to CLAUDE.md and place it…
Top comments (0)