AI 코딩 에이전트 작업 원칙

AI 코딩 에이전트 작업 원칙은 언어 모델이 소프트웨어 저장소를 수정할 때 잘못된 가정, 과잉 설계, 무관한 변경, 검증 없는 완료를 줄이기 위한 행동 규칙이다. 이 문서는 공개 저장소 multica-ai/andrej-karpathy-skills가 정리한 네 원칙을 중심으로 설명한다.

개요

코딩 에이전트는 자연어 요청을 코드 변경으로 빠르게 옮길 수 있지만, 요구가 모호해도 하나의 해석을 조용히 선택하거나, 필요하지 않은 추상화와 옵션을 추가하거나, 인접 코드를 함께 정리하는 문제가 생길 수 있다. 생성된 코드가 문법적으로 맞는 것과 사용자의 실제 목표를 충족하는 것은 별개의 문제이다. 작업 원칙은 모델 자체를 다시 학습시키지 않고 프로젝트 지침, 에이전트 스킬, 검증 절차를 통해 이런 실패 가능성을 낮춘다.

해당 저장소는 Andrej Karpathy가 공개적으로 지적한 LLM 코딩의 문제를 바탕으로 작성자가 지침을 재구성했다고 밝힌다. 프로젝트의 네 원칙은 “코딩 전 사고”, “단순성 우선”, “외과적 변경”, “목표 중심 실행”이다. CLAUDE.md, Cursor 규칙, 재사용 가능한 에이전트 스킬과 플러그인 형태로 제공되며 MIT 라이선스이다. 이름에 Karpathy가 들어가지만, 저장소가 그의 공식 프로젝트이거나 그가 내용을 승인했다는 뜻으로 해석해서는 안 된다.

2026년 8월 16일 확인한 공개 저장소에는 README, 예시, Claude·Cursor용 지침과 skills/karpathy-guidelines가 있다. 현재 공개 URL은 multica-ai 소유 아래에 있지만 README의 일부 설치 예시는 이전 또는 다른 경로인 forrestchang/andrej-karpathy-skills를 가리킨다. 설치할 때에는 문서 문자열을 그대로 복사하기보다 실제 저장소와 마켓플레이스 항목을 확인해야 한다.

핵심 구조/작동 방식

코딩 전 사고

첫 원칙은 모호함을 숨기지 않는 것이다. 에이전트는 이해한 요구와 가정을 명시하고, 여러 해석이 결과를 바꾼다면 선택지를 제시하며, 정보가 부족하면 질문한다. 더 단순하거나 안전한 접근이 있으면 사용자의 지시와 충돌하는 지점을 설명한다. 중요한 것은 긴 내부 독백을 출력하는 것이 아니라, 구현 결정을 바꿀 수 있는 불확실성을 작업 전에 노출하는 데 있다.

단순성 우선

두 번째 원칙은 현재 요청을 충족하는 최소 코드를 목표로 한다. 한 번만 쓰는 동작을 위해 범용 프레임워크를 만들거나, 요구되지 않은 설정 가능성·확장 지점·기능을 미리 추가하지 않는다. 단순성은 줄 수만 줄이는 것이 아니라 이해해야 할 상태와 분기, 공개 API, 의존성을 줄이는 것이다. 다만 보안, 데이터 손실 방지, 명시된 오류 처리까지 “불필요한 복잡성”으로 제거해서는 안 된다.

외과적 변경

세 번째 원칙은 수정 범위를 요청과 직접 연결하는 것이다. 기존 스타일을 따르고, 고장 나지 않은 인접 코드를 리팩터링하지 않으며, 발견한 별도 문제는 보고하되 허가 없이 삭제하지 않는다. 반면 이번 변경 때문에 사용되지 않게 된 import, 변수, 함수는 같은 변경 안에서 정리한다. 각 변경 줄이 사용자 요청이나 그 구현에 필요한 결과로 추적될 수 있어야 한다.

목표 중심 실행

네 번째 원칙은 명령을 검증 가능한 성공 조건으로 바꾼다. “버그를 고쳐라”는 요청은 재현 테스트가 실패하고 수정 후 통과하는 상태로, “검증을 추가하라”는 요청은 잘못된 입력 테스트가 통과하는 상태로 구체화한다. 여러 단계라면 각 단계와 확인 방법을 짧게 계획하고, 구현·테스트·관찰을 반복해 성공 조건을 확인한다. 테스트가 없는 프로젝트에서는 빌드, 정적 분석, 최소 재현, 수동 확인 절차 등 가능한 근거를 제시하고 검증하지 못한 부분을 구분한다.

이 네 원칙은 순차적인 체크리스트로 결합된다. 먼저 범위와 불확실성을 정하고, 가장 작은 설계를 택하며, 필요한 파일만 수정하고, 처음 정한 성공 조건으로 결과를 검사한다. 프로젝트별 언어 버전, 코딩 스타일, 금지된 의존성, 실행 명령을 함께 적으면 일반 원칙을 실제 저장소의 제약으로 바꿀 수 있다.

활용

이 원칙은 기능 추가, 버그 수정, 리팩터링, 테스트 작성, 문서 갱신, 코드 리뷰 대응에 활용할 수 있다. 예를 들어 COG 웹 가시화에서 리프로젝션 성능을 개선한다면 먼저 병목이 CPU 메시 생성인지 GPU 리드백인지 측정하고, 한 렌더링 경로만 최소 수정한 뒤 동일한 Playwright 시나리오로 비교한다. Qt 도킹 UI를 도입할 때에는 전체 UI를 동시에 바꾸지 않고 한 패널과 레이아웃 복원 테스트부터 검증할 수 있다.

에디토리얼 다이어그램 생성에서도 같은 원리가 적용된다. 독자와 핵심 관계를 먼저 확인하고, 필요한 노드만 남기며, 원본에 없는 관계를 만들지 않고, 렌더링·접근성·내용 정확성을 각각 확인한다. 즉 원칙은 코드 작성에만 한정되지 않고 에이전트가 파일을 변경하는 일반 작업에 적용할 수 있다.

한계 및 주의점

지침 파일은 행동을 유도할 뿐 올바른 결과를 보증하지 않는다. 모델이 규칙을 놓치거나, 테스트 자체를 잘못 작성하거나, 부분 테스트의 성공을 전체 성공으로 오인할 수 있다. 위험한 변경은 사람의 리뷰, 권한 분리, CI, 백업과 배포 승인으로 보완해야 한다. 특히 인증, 암호화, 의료·금융 판단, 데이터 마이그레이션은 단순성보다 도메인 규정과 안전 요구가 우선한다.

“질문하라”는 원칙을 모든 사소한 작업에 동일하게 적용하면 진행이 느려진다. README도 단순 오타나 명백한 한 줄 수정에는 판단을 사용하라고 설명하며, 이 지침이 속도보다 신중함에 편향되어 있음을 밝힌다. 반대로 자동 실행을 위해 질문을 없애려면 입력 계약, 실패 시 중단 조건, 테스트 가능한 성공 기준을 더 구체적으로 제공해야 한다.

또한 규칙을 프로젝트의 기존 지침에 무작정 덧붙이면 상충하거나 문맥이 과도해질 수 있다. 우선순위, 중복, 예외를 정리하고 실제 실패 사례에 맞춰 짧게 유지하는 편이 낫다. 설치 경로와 호스트별 규격은 바뀔 수 있으므로 2026년 8월 16일 이후에는 현재 README와 각 도구의 공식 플러그인 규격을 다시 확인해야 한다.

함께 보기

출처

Karpathy-Inspired Claude Code Guidelines 공개 저장소 — 프로젝트 목적, 네 원칙, 설치, 라이선스. 2026년 8월 16일 확인.
공식 CLAUDE.md — 에이전트에 적용되는 원칙 원문. 2026년 8월 16일 확인.
공식 예시 — 문제 행동과 개선 행동의 비교. 2026년 8월 16일 확인.