AI 에이전트는 나쁜 코드의 비용을 느끼지 못합니다. 하지만 우리는 느낍니다.

인간이 점점 커지는 코드베이스 (codebase)를 유지 관리할 때, 고통은 복리로 쌓입니다. 모든 지름길, 모든 중복 함수, 절대 실행될 리 없는 모든 방어적 체크 (defensive check)는 다음 변경 작업을 조금씩 더 어렵게 만듭니다.

어느 시점이 되면 고통이 충분히 커져서 우리는 멈춰 서서 리팩터링 (refactor)을 해야만 합니다. 그 피드백 루프 (feedback loop)는 짜증스럽지만, 코드베이스를 살아있게 유지하는 것이기도 합니다.

에이전트는 그 무엇도 느끼지 못합니다. 에이전트는 눈앞의 티켓 (ticket)을 해결하고 다음으로 넘어갑니다. 그래서 에이전트는 알아차리지 못한 채 나쁜 구조를 확장하고, 코드를 삭제하지 않은 채 추가하며, "포괄적 (comprehensive)"인 것이 "최소한 (minimal)"인 것보다 안전해 보이기 때문에 상상할 수 있는 모든 엣지 케이스 (edge case)를 방어합니다.

이 중 어떤 것도 테스트를 깨뜨리지 않으므로, 아무것도 플래그 (flag) 되지 않습니다. 코드베이스는 조용히 노이즈로 가득 차고, 이를 물려받는 사람이 그 대가를 치르게 됩니다.

그래서 저는 단 하나의 임무를 가진 작은 CLAUDE.md를 작성했습니다: 마치 인간이 이것을 유지 관리할 것처럼 작성하라, 왜냐하면 실제로 인간이 할 것이기 때문입니다. 다섯 가지 원칙입니다:

1. 이것이 당신의 마지막 작업이 아닙니다. 패치 (patch)를 쌓지 말고 구조를 수정하세요.
2. 삭제도 기능입니다. 코드를 삭제하는 것은 실제 작업입니다.
3. 추상화 (abstraction)를 거부하세요. 3의 법칙 (Rule of three). 아무도 요청하지 않은 것은 만들지 마세요.
4. 완전함이 철저함은 아닙니다. 상상 속의 경계가 아닌 실제 경계를 방어하세요.
5. 개선하지 말고 맞추세요. 모든 변경된 라인은 요청 사항에 근거해야 합니다.

에이전트는 코드를 생성하는 데 능숙합니다. 우리의 일은 에이전트가 다음에 이 코드를 읽을 사람을 존중하도록 만드는 것입니다.

저장소 (Repo)는 공개되어 있습니다. Sonar의 AC/DC 사이클과 Karpathy의 CLAUDE.md를 기반으로 구축되었습니다.

rohan-krishna / empathetic-coding

코딩 에이전트가 인간 유지 관리자에게 더 공감하고, 새벽 2시에 디버깅하기 악몽 같지 않은 코드를 작성하도록 만드는 CLAUDE.md.

공감하는 코딩 (Empathetic Coding)

AI 코딩 에이전트가 비대해진 코드 (bloat) 대신 유지 관리 가능한 코드를 작성하도록 만드는 즉시 적용 가능한 행동 지침입니다.

문제점

문제점

에이전트는 나쁜 코드의 비용을 느끼지 못합니다. 성장하는 코드베이스를 유지 관리하는 인간은 리팩터링(refactor)을 하기 전까지 고통이 커지는 것을 느끼지만, 에이전트는 아무것도 느끼지 못합니다. 그래서 에이전트는 나쁜 구조를 확장하고, 삭제 없이 추가만 하며, "포괄적(comprehensive)"인 것이 더 안전해 보인다는 이유로 모든 엣지 케이스(edge case)를 과도하게 방어합니다. 이 중 그 어떤 것도 테스트를 깨뜨리지 않기에, 그 무엇도 수정되지 않습니다. 해결책은 합성 반사(synthetic reflex)로서의 공감입니다. 즉, 에이전트가 스스로 느낄 수 없는 유지 관리자의 입장을 시뮬레이션하도록 만드는 것입니다.

구성 요소

동일한 5가지 원칙을 담고 있지만 길이는 각기 다른 세 가지 버전의 지침이 있습니다. 실행 환경에 따라 선택하세요.

파일	크기	용도
CLAUDE.md	약 1,000 단어	참조 / 팀 온보딩(onboarding) — 추론 방식 교육
...

사용법

선택한 버전의 이름을 CLAUDE.md로 변경하고 다음 위치에 배치하세요...

GitHub에서 보기