AI 코딩 에이전트가 자주 망가지는 이유
Karpathy Guidelines로 줄이는 4가지 실수

1. 왜 AI 코딩 에이전트에 별도 규칙이 필요한가

최근 AI 코딩 도구는 간단한 함수 작성, 버그 수정, 문서화, 테스트 작성에서 상당히 유용하다. 문제는 작업이 조금만 복잡해질 때 나타난다. 모델은 요구사항이 애매해도 질문하지 않고 한 방향을 골라 진행한다. 사용자가 원하지 않은 기능까지 추가하거나, 지금 필요 없는 확장 구조를 만들기도 한다.

실무에서 더 큰 문제는 변경 범위다. 버그 하나를 고치라고 했는데 주변 파일을 리팩토링하고, 기존 주석을 바꾸고, 사용자가 요청하지 않은 스타일 정리를 해버리면 검토 비용이 커진다. 코딩 에이전트는 작업 속도를 높이기 위해 쓰는 도구인데, 결과적으로 사람이 다시 뒤집어엎어야 한다면 생산성은 오히려 떨어진다.

2. Karpathy Guidelines의 핵심 4원칙

3. 실제로 무엇이 달라지는가

4. OpenClaw에서는 Skill로 두는 편이 맞다

이 저장소에는 Agent Skills 형식의 skills/karpathy-guidelines/SKILL.md가 포함되어 있다. OpenClaw에서는 이 파일을 워크스페이스의 skills/karpathy-guidelines/ 아래에 두면 된다. 전역 지침에 길게 붙이는 것보다, 코딩·리팩토링·리뷰 작업에서만 발동하도록 두는 편이 효율적이다.

workspace/
└── skills/
    └── karpathy-guidelines/
        └── SKILL.md

5. AI에게 일을 시킬 때는 “작업”보다 “성공 기준”을 줘야 한다

Karpathy Guidelines의 핵심은 AI에게 모든 판단을 맡기지 않는 것이다. “이거 고쳐줘”보다 “이 조건을 만족하면 성공”이라고 말하는 편이 더 안전하다.

목표: 로그인 실패 시 오류 메시지가 정확히 표시되게 수정한다.
성공 기준:
1. 잘못된 비밀번호 입력 테스트가 현재 실패를 재현한다.
2. 수정 후 해당 테스트가 통과한다.
3. 정상 로그인 테스트도 계속 통과한다.
4. 로그인 모듈 외 파일은 수정하지 않는다.

이렇게 요청하면 AI가 인증 구조를 새로 만들거나, UI 전체를 바꾸거나, 관련 없는 파일을 건드릴 가능성이 줄어든다. AI에게 자율성을 주되, 검증 가능한 울타리를 함께 주는 방식이다.

6. 한계도 있다

이 지침은 AI를 더 신중하게 만든다. 그래서 아주 단순한 오탈자 수정이나 한 줄 변경에는 과할 수 있다. 모든 작업에 긴 계획과 테스트를 요구하면 속도가 떨어진다. 중요한 것은 작업 크기에 맞춰 적용 강도를 조절하는 것이다.

7. 결론 — AI 코딩의 핵심은 모델보다 운영 규칙이다

AI 코딩 도구를 쓰다 보면 모델 성능에만 관심이 가기 쉽다. 하지만 실무에서는 모델 이름보다 더 중요한 것이 있다. 어떤 범위까지 고치게 할 것인지, 모호할 때 질문하게 할 것인지, 성공 기준을 어떻게 확인할 것인지다.