Claude Code 규칙 파일이 줄이려는 AI 코딩 실수 4가지

AI 코딩 도구를 사용하다 보면 기능 자체보다 작업 범위가 더 큰 문제가 될 때가 있습니다. 버그 하나를 고쳐 달라고 했는데 관련 파일을 대거 수정하거나, 간단한 기능에 여러 추상화 계층을 만들고, 테스트도 실행하지 않은 채 “수정했습니다”라고 끝내는 식입니다.

andrej-karpathy-skills는 이런 문제를 줄이기 위한 Claude Code 규칙 파일 모음입니다. 새로운 프레임워크나 별도의 실행 엔진이 아니라, AI 에이전트가 코드를 작성하기 전에 어떤 방식으로 판단하고 작업해야 하는지를 Markdown 규칙으로 정리한 오픈소스 프로젝트라는 점이 핵심입니다. GitHub 스타 20만 개를 모았다고 알려져 있지만, 스타 수는 시점에 따라 달라질 수 있으므로 실제 저장소의 현재 상태는 별도로 확인하는 편이 안전합니다.

이 프로젝트가 해결하려는 문제는 코드 생성이 아니다

AI 코딩 도구의 실수는 문법 오류보다 요구사항을 잘못 해석하는 데서 자주 시작합니다. 사용자가 “검색을 빠르게 해줘”라고 말했을 때, AI는 무엇이 느린지 확인하지 않고 캐시, 인덱스, 비동기 처리까지 한 번에 추가할 수 있습니다.

하지만 여기서 빠르게 한다는 말은 여러 의미를 가질 수 있습니다. 첫 화면 응답 시간을 줄이려는 것인지, 동시에 처리할 수 있는 요청 수를 늘리려는 것인지, 사용자가 느끼는 대기 시간을 줄이려는 것인지에 따라 해결 방법이 달라집니다. 목표를 분리하지 않으면 구현은 그럴듯해 보여도 실제 문제는 해결되지 않을 수 있습니다.

기존 프로젝트에 AI 에이전트를 투입할 때는 범위를 넘는 수정도 큰 부담입니다. 타입 힌트나 들여쓰기 정리, 예외 처리 개선, 주변 코드 리팩터링이 함께 들어가면 변경량이 커지고 PR 검토가 어려워집니다. 작은 버그 수정이 구조 변경으로 번지면 원래 문제가 해결됐는지 확인하기도 힘들어집니다.

소개된 규칙들은 바로 이 지점을 겨냥합니다. AI가 더 많은 코드를 만들도록 유도하는 대신, 모호한 요청을 확인하고 필요한 범위 안에서만 변경하며 결과를 직접 검증하도록 행동 방식을 제한합니다.

규칙	막으려는 실수	완료 기준
Think Before Coding	모호한 요청에 바로 구현부터 시작	재현 절차와 기대 결과를 먼저 확인
Simplicity First	아직 없는 요구를 가정한 과설계	현재 조건을 만족하는 최소 수정
Surgical Changes	주변 코드까지 함께 정리	지정한 파일 밖 변경 없음
Goal-Driven Execution	“수정했습니다”로 종료	실행한 명령과 확인한 조건을 보고

첫 번째 원칙은 모르는 상태에서 추측하지 않는 것이다

Think Before Coding으로 소개된 규칙은 AI가 요청을 받자마자 구현부터 시작하는 습관을 막습니다. 모호한 요구사항이 있으면 먼저 질문하거나 저장소의 관련 코드, 설정, 테스트, 실행 방법을 확인해야 한다는 뜻입니다.

예를 들어 “로그인 오류를 고쳐줘”라는 요청만으로는 충분하지 않습니다. 어떤 계정에서 문제가 발생하는지, 로그인 자체가 실패하는지, 로그인 후 세션이 사라지는지, 특정 브라우저나 환경에서만 재현되는지에 따라 조사 지점이 달라집니다. 먼저 재현 절차와 기대 결과를 확인해야 불필요한 수정을 피할 수 있습니다.

이 원칙은 작업 전에 다음과 같은 확인을 요구하는 방식으로 적용할 수 있습니다.

• 관련 파일과 호출 흐름을 먼저 찾는다.
• 기존 테스트나 재현 절차가 있는지 확인한다.
• 요구사항에 포함되지 않은 부분은 임의로 결정하지 않는다.
• 중요한 해석이 여러 가지라면 구현 전에 사용자에게 묻는다.

다만 모든 요청에 질문만 반복하라는 의미는 아닙니다. 저장소 안에서 충분히 확인할 수 있는 내용까지 사용자에게 되묻는 것도 비효율적입니다. 핵심은 확인 가능한 사실은 직접 조사하고, 외부 정보나 제품 결정처럼 확인할 수 없는 부분만 분리하는 데 있습니다.

두 번째 원칙은 확장성보다 현재 요구사항을 우선하는 것이다

Simplicity First는 AI가 “나중을 위해” 과도한 구조를 만드는 문제를 줄이는 기준입니다. 기능 하나를 추가하면서 Strategy 패턴, 별도의 설정 객체, 캐시 계층, 검증기, 범용 인터페이스를 동시에 만드는 식의 과설계를 경계합니다.

과설계가 항상 나쁜 것은 아닙니다. 여러 구현체가 실제로 존재하거나, 외부 플러그인 구조가 이미 정해져 있거나, 성능과 장애 격리가 명확한 요구사항이라면 추상화가 필요할 수 있습니다. 문제는 아직 발생하지 않은 미래의 변경을 가정해 현재 코드의 복잡도를 키우는 경우입니다.

AI에게 간단한 기능을 맡길 때는 “확장 가능하게 만들어줘”처럼 범위가 넓은 지시보다 현재 필요한 조건을 구체적으로 주는 편이 낫습니다. 예를 들어 다음처럼 요청할 수 있습니다.

기존 함수 구조를 유지하고, CSV 입력에서 빈 행만 제외하는 최소 수정안을 작성한다. 새로운 인터페이스나 별도 클래스를 추가하지 않는다. 기존 테스트가 깨지지 않는지 확인한다.

이렇게 하면 AI가 구현 선택지를 불필요하게 넓히기 어렵습니다. 코드가 짧다는 이유만으로 좋은 것은 아니지만, 현재 요구사항을 설명하는 데 필요하지 않은 계층은 유지 비용과 리뷰 비용을 늘린다는 점을 고려해야 합니다.

세 번째 원칙은 요청한 부분만 수술하듯 바꾸는 것이다

Surgical Changes는 기존 코드베이스를 다룰 때 특히 실용적인 규칙입니다. 수정 대상과 직접 관련된 코드만 변경하고, 주변 코드를 함께 정리하고 싶은 유혹을 억제합니다.

AI 에이전트는 작업 중 발견한 개선점까지 한 번에 처리하려는 경향이 있습니다. 버그를 고치는 과정에서 변수 이름을 바꾸고, 파일 형식을 정리하고, 예외 처리 방식을 통일하고, 사용하지 않는 코드를 삭제할 수 있습니다. 각각의 변경이 나쁘지 않더라도 한 PR에 섞이면 검토자는 핵심 수정과 부수적인 변경을 구분해야 합니다.

작업 지시에는 수정 범위를 명시하는 것이 좋습니다. “이 함수의 날짜 계산 오류만 수정하고 다른 파일은 변경하지 말라”, “필요하다면 변경 전에 관련 파일 목록을 먼저 보여 달라”, “리팩터링은 별도 작업으로 남겨 달라”처럼 제한 조건을 함께 전달할 수 있습니다.

이 방식은 단순히 diff를 작게 만들기 위한 규칙이 아닙니다. 변경 범위가 작으면 실패 원인을 추적하기 쉽고, 코드 리뷰와 롤백도 수월합니다. 반대로 주변 정리까지 함께 진행해야 하는 상황이라면 그 작업을 별도의 목표로 분리해 기록하는 편이 안전합니다.

네 번째 원칙은 완료를 코드 작성이 아니라 검증으로 정의하는 것이다

Goal-Driven Execution의 핵심은 “수정했다”와 “문제가 해결됐다는 근거를 확인했다”를 구분하는 데 있습니다. AI 에이전트가 코드를 생성한 뒤 작업을 끝내는 것이 아니라, 성공 여부를 판단할 수 있는 조건을 확인해야 합니다.

예를 들어 “API를 고쳐줘”는 완료 기준이 아닙니다. 다음처럼 바꿔야 합니다.

• 잘못된 인증 토큰을 보냈을 때 401 응답이 반환되는가
• 정상 토큰으로 기존 성공 경로가 유지되는가
• 해당 오류를 재현하는 테스트가 통과하는가
• 변경한 파일 외의 테스트도 실패하지 않는가

검증 방법은 작업에 따라 달라집니다. 단위 테스트, 통합 테스트, 린터, 타입 검사, 빌드, 직접 재현 등 여러 수단 중 적절한 것을 선택해야 합니다. 테스트가 없는 레거시 코드라면 최소한 재현 명령과 확인해야 할 출력 형태를 먼저 정할 수 있습니다.

여기서 주의할 점은 테스트가 통과했다고 모든 문제가 해결된 것은 아니라는 사실입니다. 테스트 범위가 좁거나, 실제 실행 환경과 로컬 환경이 다르거나, 성능 요구사항을 검증하지 못하는 경우가 있습니다. 따라서 에이전트에게 “테스트 통과 여부”뿐 아니라 어떤 명령을 실행했고 어떤 조건을 확인했는지도 보고하도록 하는 편이 좋습니다.

규칙 파일을 팀 작업에 적용할 때 확인할 부분

이런 규칙 모음은 복사해 넣는 것만으로 품질이 자동으로 보장되는 도구는 아닙니다. 규칙이 너무 추상적이면 AI가 지시를 형식적으로만 따를 수 있고, 반대로 모든 예외와 절차를 길게 적으면 중요한 기준이 묻힐 수 있습니다.

저장소의 규칙 파일에는 팀이 실제로 중요하게 보는 내용을 우선 넣는 편이 낫습니다. 예를 들면 다음과 같은 항목입니다.

• 코드를 수정하기 전에 확인해야 하는 테스트와 실행 명령
• 변경해서는 안 되는 generated 파일이나 외부 연동 코드
• 버그 수정 시 허용되는 파일 범위
• 완료 보고에 반드시 포함할 검증 결과
• 모호한 요구사항이 있을 때 질문해야 하는 기준

규칙을 적용한 뒤에는 작은 작업으로 동작을 확인하는 것이 좋습니다. 파일 하나의 오류 수정, 테스트 추가, 단순한 조회 조건 변경처럼 결과를 비교하기 쉬운 작업을 맡기고, 실제 diff와 실행 로그를 확인합니다. 규칙을 넣었는데도 AI가 계속 주변 코드를 수정한다면 지시가 부족한 것인지, 저장소 구조가 복잡한 것인지, 에이전트가 읽는 규칙 파일 위치와 형식이 맞는지부터 점검해야 합니다.

또한 팀의 코딩 규칙과 충돌하지 않아야 합니다. 예를 들어 “최소 수정”을 지나치게 강조하면 보안 취약점이나 명백한 오류를 발견하고도 그냥 지나칠 수 있습니다. 요청 범위를 지키되, 보안·데이터 손상·빌드 실패처럼 즉시 알려야 하는 문제는 별도로 보고하도록 예외를 두는 식이 현실적입니다.

이 규칙이 특히 유용한 상황과 한계

이 규칙이 필요한 쪽은 작은 수정인데 AI가 넓은 범위를 건드리는 팀, 요구사항을 임의로 해석하는 작업이 잦은 경우, 테스트 기준 없이 “고쳐줘”나 “정리해줘”로 업무를 맡기는 경우입니다. PR 크기와 리뷰 부담을 줄이고 싶은 팀에도 방향이 맞습니다.

반면 탐색 단계의 프로토타입이나 대규모 마이그레이션처럼 변경 범위 자체가 넓은 작업에서는 수술식 수정만 고집하기 어렵습니다. 이런 경우에도 원칙을 버리기보다, 먼저 작업을 여러 목표와 단계로 나누고 각 단계의 완료 조건을 정하는 방식으로 적용할 수 있습니다.

가장 실질적인 변화는 AI에게 더 정교한 코드를 요구하는 데 있지 않습니다. 작업을 시작하기 전에 무엇을 알고 있는지 확인하고, 현재 필요한 만큼만 바꾸며, 끝났다고 말하기 전에 결과를 검증하게 만드는 데 있습니다. 규칙 파일을 도입할 때도 저장소 전체를 한 번에 바꾸기보다 실제로 반복되는 실수 하나를 골라 짧은 규칙으로 명시하고, 이후 diff와 테스트 결과가 달라지는지 확인하는 접근이 안전합니다.