짧은 코딩 규칙 파일은 AI 에이전트가 바로 코드를 쓰기 전에 가정을 밝히고, 요청 범위 안에서만 수정하고, 검증 결과를 남기게 하는 공통 계약으로 쓸 수 있습니다. 그러나 지시문만으로 파일 접근이나 위험한 명령이 기술적으로 차단되는 것은 아닙니다. 효과는 문구의 강도보다 실제 diff, 테스트, 승인 경계로 측정해야 합니다.
이 글은 forrestchang/andrej-karpathy-skills와 multica-ai/andrej-karpathy-skills에 연결된 규칙 사례를 바탕으로 합니다. 저장소의 별 수, 순위, 파일 길이와 지원 도구는 바뀔 수 있으므로 인기 수치나 특정 인물의 공식 보증을 전제로 하지 않습니다. 핵심 질문은 짧은 행동 지침이 팀의 코딩 에이전트 품질을 어떻게 검증 가능하게 만드는가입니다.
에이전트가 넓은 저장소와 모호한 요청을 받으면 학습된 일반 패턴을 따라 관련 없는 리팩터링, 새 추상화나 방어 코드를 함께 제안할 수 있습니다. 계획, 단순성, 최소 변경, 검증 원칙은 선택지를 좁히는 문맥을 제공합니다. ‘사용자 요청으로 설명할 수 없는 라인은 바꾸지 않는다’는 규칙은 리뷰할 때도 변경의 필요성을 묻는 공통 기준이 됩니다.
다만 규칙이 모델의 내부 작동을 특정 방식으로 강제하거나 환각을 원천 차단한다고 단정할 수는 없습니다. 모델은 지시를 잘못 해석할 수 있고, 긴 대화 뒤 앞부분의 규칙을 놓치거나 도구 출력 속 명령과 충돌할 수 있습니다. 규칙 파일은 행동을 유도하는 입력이며, 실제 권한 제어와 성공 보장은 샌드박스, 테스트, 코드 리뷰가 담당합니다.
효과가 큰 규칙은 관찰 가능한 행동으로 씁니다. ‘좋은 코드를 작성하라’보다 ‘코드 전에 불확실한 가정을 나열한다’, ‘수정 허용 경로 밖 파일은 승인 없이 건드리지 않는다’, ‘완료 전에 지정 테스트와 변경 파일 목록을 보고한다’가 검증하기 쉽습니다. 한 문장 안에 서로 충돌하는 목표를 넣지 말고 우선순위를 명확히 합니다.
다음은 원문에 포함된 개념적 Markdown 조각입니다. 실제 저장소의 현재 파일과 문구가 같은지는 링크에서 확인해야 하며, [CRITICAL]이나 [STOP] 표기 자체가 기술적 권한 경계를 만들지는 않습니다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# CLAUDE.md (Core Mechanics Snippet)
## 1. Think Before Coding (사전 억제 레이어)
- [CRITICAL] State your assumptions out loud before writing any code.
- If the request is ambiguous, ASK. Do not just pick one interpretation and run.
## 2. Surgical Changes (컨텍스트 차단 레이어)
- Touch ONLY what you must. Clean up ONLY your own mess.
- [STOP] Don't "improve" adjacent code, comments, or formatting.
- The test: Every changed line MUST trace directly back to the user's explicit request.
## 3. Goal-Driven Execution (검증 루프 레이어)
- Transform vague imperative tasks into verifiable goals.
- Example: Instead of "Add validation", transform to "Write tests for invalid inputs, then make them pass."
첫 원칙은 모호함을 숨기지 않게 합니다. 모든 사소한 결정마다 질문하면 흐름이 느려지므로, 되돌리기 어렵거나 결과를 크게 바꾸는 선택만 질문하고 나머지는 명시한 가정으로 진행하는 임계값이 필요합니다. 예컨대 오류 문구의 띄어쓰기는 가정으로 진행할 수 있지만 데이터 스키마 변경과 호환성 선택은 승인받는 편이 낫습니다.
두 번째 원칙은 diff 범위를 줄이지만 진짜 수정에 필요한 인접 변경까지 막아서는 안 됩니다. 공개 타입을 바꿨다면 소비자와 테스트도 함께 수정해야 할 수 있습니다. ‘한 파일만’처럼 임의의 제한보다 요청의 성공 조건과 의존성으로 설명 가능한 변경만 허용하는 편이 안전합니다.
세 번째 원칙은 명령을 테스트 가능한 목표로 바꿉니다. 기존 테스트가 요구를 정확히 표현하지 않거나 테스트 자체 변경이 필요한 경우에는 에이전트가 assertion을 약하게 만들어 통과할 수도 있습니다. 새 테스트가 실제 실패를 재현하는지 먼저 확인하고, 구현 뒤 회귀 테스트와 정적 검사를 별도로 실행해야 합니다.
회귀 범위를 좁혀야 하는 버그 수정, 보안 패치와 오래된 코드의 작은 호환성 수정에는 최소 diff가 유리합니다. 변경 전 실패를 재현하고, 가장 좁은 원인을 고치고, 같은 테스트가 통과하는 순서를 따르면 각 라인의 이유를 설명하기 쉽습니다. 포맷팅이나 이름 변경을 기능 수정과 섞지 않으면 리뷰와 롤백도 단순해집니다.
반면 라이브러리 전환, 공통 API 폐기와 모듈 분리는 여러 파일을 일관되게 바꾸는 것이 목표입니다. 이때 ‘인접 코드를 건드리지 않는다’를 그대로 적용하면 임시 어댑터와 중복이 늘거나 반쪽짜리 이전이 남습니다. 작업 문서에 허용 범위, 단계별 기준 커밋, 호환 기간과 완료 조건을 선언해 최소 변경의 단위를 한 줄이 아니라 승인된 마이그레이션 단계로 바꿔야 합니다.
긴급 장애에서도 무조건 작은 패치가 정답은 아닙니다. 원인을 모른 채 @Lazy나 캐시를 한 줄 추가하는 식의 예시는 증상을 숨기거나 새 장애를 만들 수 있습니다. 먼저 관측 가능한 재현과 롤백을 준비하고, 임시 완화인지 근본 수정인지 표시합니다. 규칙 파일은 구체적 기술 선택을 대신하지 않습니다.
팀에는 루트 규칙, 하위 디렉터리 지침, 작업 요청, 린터와 CI가 동시에 존재할 수 있습니다. 우선순위와 적용 경로를 문서화하지 않으면 에이전트가 편한 규칙만 따를 수 있습니다. 보안, 법적 정책과 수정 금지 경로를 가장 높은 실행 제약으로 두고, 프로젝트 스타일과 작업별 요구를 그 아래에서 합성합니다.
같은 내용이 여러 파일에 복제되면 시간이 지나며 서로 달라집니다. 공통 규칙의 단일 원본과 버전을 두고, 도구별 파일은 필요한 형식으로 생성하거나 짧은 참조만 유지하는 편이 낫습니다. 규칙 변경도 코드처럼 review하고 대표 작업 회귀를 실행합니다. 새 문구가 질문 횟수를 과도하게 늘리거나 대규모 작업을 불가능하게 만들 수 있기 때문입니다.
도구가 읽은 규칙의 경로와 버전을 실행 로그에 남기면 결과 차이를 설명하기 쉽습니다. 규칙 파일이 누락되거나 파싱되지 않았을 때 조용히 기본 행동으로 진행하지 말고, 고위험 작업에서는 시작 전에 적용 여부를 확인합니다. 저장소 외부에서 받은 README나 이슈 본문이 프로젝트 정책을 덮어쓸 수 없게 입력 출처도 구분합니다.
수정 허용 경로를 파일 시스템 권한이나 diff 검사로 확인하고, 운영 자격 증명과 원격 배포 권한은 일반 코딩 에이전트에 주지 않습니다. 명령 allowlist, 네트워크 제한, 시간, 토큰, diff 크기 상한과 같은 실행 경계는 모델이 규칙을 무시해도 작동해야 합니다. 파괴적 변경과 외부 상태 변경에는 별도 승인이 필요합니다.
완료 조건도 에이전트의 자기 평가에만 맡기지 않습니다. 지정 테스트, 정적 분석, 생성 파일 일치, 변경 경로와 민감 정보 검사를 자동화하고 사람이 공개 인터페이스와 테스트 변경을 검토합니다. 테스트를 삭제하거나 기대값을 낮춘 diff는 성공으로 인정하지 않습니다. 같은 실패를 반복하면 최대 시도 뒤 원인과 시도 내역을 남기고 중단합니다.
규칙은 사용자에게 질문하라고 요구할 수 있지만, 안전하게 진행 가능한 사소한 선택까지 모두 멈추면 전체 시간이 늘어납니다. 질문 횟수, 답변 대기 시간과 잘못된 가정으로 인한 재작업을 함께 측정해 질문 임계값을 조정하세요. 목표는 대화를 늘리는 것이 아니라 비싼 오해를 앞에서 발견하는 것입니다.
대표 작업 20개 정도를 버그 수정, 작은 기능, 테스트 추가와 마이그레이션으로 나눕니다. 동일한 저장소 스냅샷과 모델, 도구 설정에서 기본 조건과 규칙 적용 조건을 번갈아 실행합니다. 요청 밖 수정 파일과 라인, 첫 테스트 통과율, 사람이 되돌린 diff, 질문 수, 모델 비용, 전체 리뷰, 완료 시간을 기록합니다.
평균 diff가 줄었다는 사실만으로 성공이라 할 수 없습니다. 필요한 소비자 파일을 빠뜨려 테스트가 깨지거나, 확인 질문 때문에 간단한 작업 시간이 크게 늘 수 있습니다. 작업 유형별로 품질과 비용을 비교하고 최소 변경, 질문, 검증 규칙을 각각 켜고 꺼 어떤 문구가 영향을 주는지도 봅니다.
팀 도입은 읽기 전용 분석과 작은 버그 수정부터 시작하세요. 합격 기준을 통과하면 일반 기능으로 넓히고, 마이그레이션에는 별도 규칙 세트를 사용합니다. 모델이나 에이전트 버전이 바뀔 때 같은 평가를 다시 돌려야 합니다. 규칙은 한 번 작성하고 끝나는 마법 파일이 아니라 코드와 함께 관리할 운영 정책입니다.
아닙니다. 수정 범위를 줄이는 데 도움을 줄 수 있지만 모델, 도구, 작업에 따라 준수율이 달라집니다. 허용 경로, diff 검토와 테스트 같은 실행 통제가 함께 필요합니다.
버그 수정에는 유용하지만 명시적으로 승인된 마이그레이션이나 구조 개선에는 너무 좁을 수 있습니다. 작업 유형별 범위와 성공 조건을 별도로 선언해야 합니다.
같은 대표 작업을 규칙 적용 전후로 실행해 불필요한 수정 파일, 라인, 테스트 통과, 리뷰 수정량, 질문 횟수와 전체 완료 시간을 비교해야 합니다.
←→ 키와 좌우 스와이프를 지원합니다. 읽던 페이지는 이 기기에 저장됩니다.