카르파시 AI 코딩 지침 해설: 코딩 에이전트는 프롬프트보다 검증 루프·중단 조건·CLAUDE.md 경계를 먼저 설계해야 하는 이유

AI타임스는 2026년 6월 29일, 안드레이 카르파시가 작성한 것으로 추정되는 AI 코딩 지침 문서가 개발자 커뮤니티에서 확산되고 있다고 보도했습니다. 진위는 아직 확인되지 않았지만, 이 뉴스가 중요한 이유는 이름값 때문만은 아닙니다. 개발자가 AI에게 “잘 코딩해줘”라고 말하는 단계에서, 이제는 AI가 스스로 테스트하고 멈추고 되돌아보는 작업 루프를 설계하는 단계로 넘어가고 있기 때문입니다.

1. 한 줄 문제 정의

핵심 한 줄: AI 코딩 에이전트의 병목은 프롬프트 문장보다, 잘못된 방향으로 계속 일하지 않게 만드는 검증 루프입니다.

초보 개발자 기준으로 코딩 에이전트는 “코드를 대신 써 주는 챗봇”이 아닙니다. 파일을 읽고, 명령어를 실행하고, 테스트를 돌리고, 여러 단계의 작업을 이어 가는 자동 작업자에 가깝습니다. 그래서 한 번의 답변 품질보다, 작업 중간에 무엇을 확인하고 언제 멈출지가 더 중요해집니다.

이 글의 대상 독자는 Claude Code, Codex, Cursor, Copilot류 도구를 실무에 넣으려는 개발자와 팀 리드입니다. 범위는 특정 유출 문서의 진위 판단이 아니라, AI 코딩 작업지침을 어떻게 운영 규칙으로 바꿀지입니다. 단순 질의응답이나 작은 코드 스니펫 생성만 한다면 이 구조는 다소 과할 수 있습니다.

2. 먼저 결론

핵심 한 줄: 지금 팀이 해야 할 일은 “더 멋진 프롬프트”를 찾는 것이 아니라, 실패를 재현하고 통과 기준을 고정하는 작업 매뉴얼을 만드는 것입니다.

AI타임스 기사에 따르면 이번 문서는 기존 4가지 원칙에 검증, 디버깅, 의존성, 커뮤니케이션, 공통 실패 패턴 같은 항목을 더한 10개 규칙으로 알려졌습니다. 특히 “수정된 것 같다”가 아니라 테스트로 재현하고 다시 통과시켜야 한다는 관점이 핵심입니다.

저는 이 흐름을 카르파시 개인의 문서 여부보다 더 큰 신호로 봅니다. AI 코딩의 경쟁력은 모델 이름이 아니라, 에이전트가 어떤 기준으로 읽고 계획하고 수정하고 검증하고 멈추는지에서 갈립니다. Claude Code 공식 문서도 작업에 테스트·빌드·스크린샷 같은 검증 신호를 주면 에이전트가 스스로 반복할 수 있다고 설명합니다.

추천 대상은 반복적인 버그 수정, 테스트 보강, 리팩터링, 문서화, 마이그레이션을 AI에게 맡기려는 팀입니다. 비추천 대상은 테스트가 없고 완료 기준도 없는 상태에서 “일단 자동화부터 하자”는 팀입니다. 그 경우 AI가 빨라질수록 잘못된 변경도 빨리 퍼집니다.

3. 핵심 구조 분해

핵심 한 줄: 좋은 AI 코딩 지침은 프롬프트 문구, 프로젝트 메모리, 검증 명령, 중단 조건의 네 층으로 나뉩니다.

• 작업 의도 층: 사용자가 원하는 결과를 기계적으로 검증 가능한 문장으로 바꿉니다. 예를 들어 “입력 검증 추가”보다 “빈 이메일과 잘못된 이메일 형식에서 오류를 반환하고 테스트가 통과한다”가 좋습니다.
• 프로젝트 메모리 층: CLAUDE.md, AGENTS.md, 스킬 문서처럼 에이전트가 매번 읽어야 할 규칙을 둡니다. Claude Code 공식 문서는 CLAUDE.md가 매 세션 시작 시 읽히지만 강제 설정이 아니라 컨텍스트라고 설명합니다.
• 검증 게이트 층: 테스트, 타입체크, 린트, 빌드, 스크린샷 비교처럼 통과/실패가 분명한 신호를 둡니다. 이 신호가 없으면 에이전트는 “보기엔 된 것 같음”에서 멈춥니다.
• 중단 조건 층: Kitchen Sink, Wrong Abstraction, Optimistic Path, Runaway Refactor 같은 실패 패턴이 보이면 계속 진행하지 않고 멈추게 합니다. 이 층이 없으면 작은 수정이 과한 구조 변경으로 번질 수 있습니다.

중요한 점은 네 층이 서로 대체 관계가 아니라는 것입니다. 좋은 프롬프트만 있어도 부족하고, CLAUDE.md만 있어도 부족합니다. 에이전트에게 기억할 규칙을 주고, 실행할 검증을 주고, 실패 패턴을 만나면 멈출 권한까지 줘야 합니다.

4. 설계 의도 해설

핵심 한 줄: 규칙의 의도는 AI를 더 자신 있게 만드는 것이 아니라, 근거 없는 자신감을 줄이는 것입니다.

사람 개발자도 버그를 고칠 때는 먼저 재현합니다. 어떤 입력에서 실패하는지 확인하고, 실패하는 테스트를 만들고, 코드를 바꾼 뒤 같은 테스트가 통과하는지 봅니다. AI 에이전트에게도 이 절차가 필요합니다. 이유는 AI가 그럴듯한 설명을 매우 잘하기 때문입니다.

이번 지침에서 주목할 부분은 “쓰기 전 생각하기”에서 “쓰기 후 검증하고, 실패 패턴이면 멈추기”로 이동했다는 점입니다. 프롬프트 엔지니어링이 요청 문장을 다듬는 기술이었다면, 루프 엔지니어링은 작업자가 매 단계에서 어떤 신호를 보고 다음 행동을 선택할지 설계하는 기술입니다.

이 설계가 얻는 것은 안정성입니다. 테스트 결과, 오류 메시지, diff 범위, 의존성 추가 이유가 남으면 리뷰가 쉬워집니다. 포기하는 것도 있습니다. 매 작업마다 완료 기준과 검증 명령을 쓰는 비용이 듭니다. 하지만 장시간 코딩 에이전트나 자동 수정 루프에서는 이 비용이 보험 역할을 합니다.

5. 근거 및 비교

핵심 한 줄: 비교 기준은 “답변이 똑똑한가”가 아니라 “작업이 검증 가능하고 되돌릴 수 있는가”입니다.

Claude Code 공식 문서는 “검증할 수 있는 방법을 주라”고 강조합니다. 테스트, 빌드 종료 코드, 스크린샷 비교처럼 에이전트가 읽을 수 있는 신호를 주면, 작업자가 결과를 보고 다시 고치는 루프가 닫힙니다. 또한 /goal 문서는 별도의 평가 모델이 매 턴 조건 충족 여부를 확인해 계속 작업하게 만드는 구조를 설명합니다.

반대로 CLAUDE.md 문서는 이 파일이 강제 정책이 아니라 컨텍스트라고 분명히 말합니다. 그래서 보안이나 위험 행동 차단은 지침 파일만 믿으면 안 됩니다. 실제 차단이 필요하면 PreToolUse hook, 권한 설정, 샌드박스 같은 실행 제어가 필요합니다.

6. 실제 동작 흐름 / 단계별 실행 방법

핵심 한 줄: 팀에 적용할 때는 거창한 규칙집보다 작은 버그 수정 루프 하나를 먼저 고정하는 편이 낫습니다.

1. 반복되는 실패 3개를 고릅니다. 예: 테스트 없이 수정 완료 주장, 불필요한 의존성 추가, 한 파일 수정이 대규모 리팩터링으로 번짐.
2. 각 실패를 중단 조건으로 바꿉니다. 예: 새 패키지 추가 전 기존 의존성 확인, 파일 5개 이상 변경 시 계획 재확인, 재현 테스트 없으면 버그 수정 완료 금지.
3. 프로젝트 지침 파일에 짧게 씁니다. 200줄짜리 철학 문서보다 20줄짜리 검증 규칙이 더 잘 지켜집니다.
4. 검증 명령을 고정합니다. 예: pnpm test, pnpm typecheck, 특정 테스트 파일, Playwright 스크린샷 비교.
5. 작업 프롬프트에 완료 기준을 넣습니다. “수정해줘”가 아니라 “실패 테스트 작성 → 수정 → 테스트 통과 출력 제시”로 요청합니다.
6. 리뷰 때 증거를 봅니다. 코드 설명보다 실제 실행한 명령, 실패 로그, 통과 로그, 변경 파일 수를 먼저 확인합니다.

# CLAUDE.md 예시: 코딩 에이전트 작업 규칙

## Verification
- 버그 수정은 실패를 재현하는 테스트 또는 명령 출력 없이 완료로 주장하지 않는다.
- 구현 후 관련 테스트와 타입체크 결과를 요약한다.

## Scope Control
- 요청 범위를 넘어 새 기능을 추가하지 않는다.
- 변경 파일이 5개를 넘으면 계속 진행하기 전에 계획을 다시 제시한다.

## Dependencies
- 새 패키지 추가 전 기존 라이브러리와 표준 라이브러리로 해결 가능한지 확인한다.
- 추가한다면 이유와 대안을 PR 설명에 남긴다.

## Stop Conditions
- 원인 확인 없이 여러 부분을 동시에 고치고 있다면 멈춘다.
- 정상 입력만 가정한 코드가 보이면 엣지 케이스 테스트를 먼저 추가한다.

작업 요청 예시:
로그인 세션 만료 후 새로고침하면 401이 반복됩니다.
먼저 실패를 재현하는 테스트를 추가하고,
원인을 설명한 뒤 최소 변경으로 수정하세요.
완료 기준은 관련 테스트 통과와 pnpm typecheck 통과입니다.

7. 실수/함정(Pitfalls)

핵심 한 줄: AI 코딩 규칙은 길수록 좋은 것이 아니라, 실제로 멈추게 만들 수 있을 때 좋습니다.

1. 함정: CLAUDE.md를 만능 정책으로 착각한다.
   예방: 지침 파일은 컨텍스트이고, 강제 차단은 hook·권한·샌드박스로 분리합니다.
   복구: 위험 명령, 외부 전송, 시크릿 접근은 PreToolUse hook이나 권한 정책으로 옮깁니다.
2. 함정: 규칙을 너무 길게 쓴다.
   예방: “제거하면 실수가 늘어나는가?”를 기준으로 20~50줄 안에 핵심만 둡니다.
   복구: 장문 튜토리얼은 별도 문서나 스킬로 빼고, 매 세션 규칙은 짧게 유지합니다.
3. 함정: 테스트 없는 레포에서 자동 반복만 켠다.
   예방: 먼저 가장 자주 깨지는 흐름 하나에 재현 테스트를 만듭니다.
   복구: 테스트가 없는 영역은 스크립트, 샘플 입력, 스크린샷, 타입체크 중 하나라도 통과 신호로 둡니다.
4. 함정: 실패 패턴을 발견해도 계속 진행하게 둔다.
   예방: Kitchen Sink, Wrong Abstraction, Optimistic Path, Runaway Refactor를 명시적 중단 조건으로 적습니다.
   복구: 변경 범위가 커진 순간 현재 diff를 요약하고, 새 계획 승인을 받도록 루프를 끊습니다.
5. 함정: AI가 한 검증을 사람이 다시 보지 않는다.
   예방: 최소한 명령어, 종료 코드, 실패 후 통과 변화, 변경 파일 목록은 PR에서 확인합니다.
   복구: “통과했다”는 문장만 있는 결과는 반려하고 실제 출력 근거를 요구합니다.

8. 강점과 한계

핵심 한 줄: 검증 루프는 AI 코딩의 품질을 올리지만, 나쁜 완료 기준까지 자동으로 고쳐 주지는 않습니다.

강점은 세 가지입니다. 첫째, 에이전트의 작업 결과를 사람 리뷰어가 빠르게 판단할 수 있습니다. 둘째, 같은 실수를 반복할 때 지침 파일과 검증 명령으로 재발 방지 규칙을 남길 수 있습니다. 셋째, 장시간 작업에서도 “언제 끝났는지”를 테스트와 목표 조건으로 확인할 수 있습니다.

한계도 분명합니다. 완료 기준이 틀리면 에이전트는 틀린 기준을 성실히 만족시킬 수 있습니다. 테스트가 허술하면 통과해도 버그가 남습니다. 또 CLAUDE.md가 너무 길거나 모호하면 실제 작업 지시보다 약하게 작동합니다.

그래서 저는 이 방식을 “AI를 믿는 방법”이 아니라 “AI를 의심하는 절차를 자동화하는 방법”으로 봅니다. 좋은 팀은 에이전트에게 자유를 주되, 통과해야 할 증거와 멈춰야 할 조건을 더 명확히 둡니다.

9. 더 깊게 공부할 포인트

핵심 한 줄: 이 주제는 프롬프트 작성법보다 테스트 전략, 작업 메모리, 훅, 권한 모델과 함께 공부해야 합니다.

• 프로젝트 메모리: CLAUDE.md가 어디서 로드되고, 어떤 내용이 매 세션에 적합한지 확인합니다.
• 검증 신호: 테스트, 빌드, 린트, 타입체크, 스크린샷 비교 중 레포에 맞는 최소 신호를 정합니다.
• 목표 기반 반복: /goal처럼 완료 조건을 별도 평가자가 확인하는 방식을 실험합니다.
• 훅과 권한: 지침 파일로는 강제할 수 없는 위험 행동을 실행 단계에서 막는 방법을 봅니다.
• 리뷰 프로세스: PR 설명에 AI가 실행한 검증과 변경 범위, 중단 조건 위반 여부를 남기게 합니다.

초보 개발자라면 먼저 “좋은 프롬프트 모음”을 찾기보다, 내가 맡은 프로젝트에서 “성공/실패를 명확히 알려주는 명령어가 무엇인가”부터 정리하는 편이 좋습니다. 그 명령어가 AI 코딩 루프의 계기판입니다.

10. 실행 체크리스트 + 작성자 관점

핵심 한 줄: 도입 완료 기준은 규칙 파일을 만든 날이 아니라, AI가 같은 실패를 반복하지 않게 된 날입니다.

Definition of Done: 팀의 대표 AI 코딩 작업 5건에서 실패 재현, 최소 변경, 관련 검증 통과, 변경 범위 요약, 중단 조건 위반 없음이 PR 증거로 남으면 1차 도입이 완료된 것으로 봅니다.

작성자 관점에서 이번 뉴스의 핵심은 “카르파시가 썼는가”보다 “AI 코딩을 한 번의 프롬프트가 아니라 운영 가능한 루프로 봐야 한다”는 데 있습니다. 저는 모든 개발팀에 장문 규칙집을 추천하지 않습니다. 대신 자주 깨지는 작업 하나를 골라 실패 재현 → 수정 → 검증 → 중단 조건 확인 루프를 먼저 고정하길 권합니다. 이 작은 루프가 안정적으로 돈 뒤에야 장시간 에이전트 작업을 넓히는 것이 맞습니다.

참고자료

• AI타임스 - '카르파시 AI 코딩 지침' 확산…"프롬프트에서 루프 시대로 진화" (발행일: 2026-06-29)
• Claude Code Docs - Best practices for Claude Code (확인일: 2026-06-29)
• Claude Code Docs - How Claude remembers your project (확인일: 2026-06-29)
• Claude Code Docs - Keep Claude working toward a goal (확인일: 2026-06-29)
• Claude Code Docs - Hooks reference (확인일: 2026-06-29)