AI 코딩 에이전트, 규칙을 많이 줄수록 결과가 나빠졌다

• 목록
• 답변
• 글쓰기
• 옵션
  • 수정
  • 삭제

AI 코딩 에이전트가 자꾸 엉뚱한 파일을 고치기에 규칙부터 늘렸습니다. 기술 스택, 디렉터리 구조, 금지 명령, 테스트 순서, 응답 형식까지 적으면 실수가 사라질 줄 알았지만 결과는 반대였습니다. 지침 파일이 길어질수록 에이전트는 중요한 제약을 놓쳤고, 간단한 수정에도 불필요한 코드를 잔뜩 만들었습니다.

그래서 같은 저장소와 비슷한 난이도의 작업을 대상으로 규칙의 양을 달리해 사용해 봤습니다. 한 달 동안 프론트엔드 버그 수정, API 응답 필드 추가, 테스트 보강 작업을 반복하면서 확인한 핵심은 분명했습니다. AI 코딩 에이전트에는 많은 규칙보다 우선순위가 선명한 짧은 규칙이 더 효과적이었습니다.

규칙 47개를 넣자 오히려 수정 범위가 커졌다

처음에는 자세할수록 안전하다고 믿었다

첫 번째 설정에는 제가 코드 리뷰에서 자주 남기던 말을 거의 전부 넣었습니다. 컴포넌트 분리 기준, 함수 길이, 변수명, 주석 방식은 물론이고 패키지 설치 금지와 데이터베이스 변경 금지까지 47개 항목을 작성했습니다. 문서만 보면 빈틈없는 개발 표준처럼 보였고, 이제는 요청 한 줄만 입력해도 일관된 코드가 나올 것이라고 기대했습니다.

하지만 로그인 오류 메시지 하나를 수정해 달라고 하자 에이전트는 관련 컴포넌트뿐 아니라 공통 알림 모듈과 테스트 유틸리티까지 손댔습니다. 규칙 중 ‘중복 로직은 공통화한다’와 ‘수정 범위를 최소화한다’가 충돌했는데, 도구는 공통화를 더 중요한 지시로 해석한 듯했습니다. 실제 변경은 문구와 상태 처리 두 곳이면 충분했지만 수정 파일이 11개로 늘어났고, 검토 시간도 직접 고쳤을 때보다 길어졌습니다.

특히 ‘항상’, ‘반드시’, ‘가능하면’ 같은 표현이 섞여 있으면 문제가 커졌습니다. 사람은 문맥으로 강도를 구분하지만 에이전트는 여러 규칙을 동시에 만족시키려다가 과도한 리팩터링을 제안했습니다. 여러분의 지침 파일에도 서로 다른 시기에 추가한 문장이 쌓여 있지 않나요? 그렇다면 규칙 수보다 먼저 서로 충돌하는 문장이 있는지 확인할 필요가 있습니다.

짧은 지침으로 바꾼 뒤 달라진 수치

두 번째 주에는 규칙을 9개로 줄이고 세 단계로 나눴습니다. 가장 위에는 보안과 데이터 보호, 그다음에는 변경 범위와 테스트, 마지막에는 스타일 규칙을 놓았습니다. 동일한 유형의 작업 12건을 처리해 보니 평균 수정 파일 수는 7.4개에서 3.1개로 줄었고, 제가 되돌린 변경도 작업당 평균 4건에서 1건 수준으로 감소했습니다. 정밀한 벤치마크는 아니지만 매일 코드를 검토하는 입장에서는 체감 차이가 컸습니다.

• 1순위: 비밀값 노출, 사용자 데이터 변경, 운영 환경 명령처럼 되돌리기 어려운 행동을 금지했습니다.
• 2순위: 요청받은 범위 밖의 리팩터링은 제안만 하고 실행하지 않도록 했습니다.
• 3순위: 변경 후 실행할 테스트와 실패 시 보고할 내용을 지정했습니다.
• 4순위: 이름이나 포맷 같은 스타일은 기존 파일의 관례를 따르게 했습니다.

사용 팁: 지침을 읽은 뒤 바로 코딩시키지 말고, 먼저 ‘적용할 규칙 세 가지와 수정하지 않을 범위’를 답하게 해보세요. 작업 전 해석 오류를 발견하는 비용이 작업 후 코드를 되돌리는 비용보다 훨씬 작습니다.

제가 실제로 남긴 것은 규칙이 아니라 판단 순서였다

전역 지침과 작업 지침을 분리했다

긴 설정을 줄일 때 모든 내용을 삭제한 것은 아닙니다. 저장소 전체에서 변하지 않는 원칙과 이번 작업에서만 필요한 조건을 분리했습니다. 전역 지침에는 사용 언어, 기본 테스트 명령, 비밀정보 취급, 패키지 관리자처럼 반복해서 설명할 가치가 있는 내용만 남겼습니다. 반면 ‘결제 화면의 UI만 변경’, ‘API 스키마 변경 금지’ 같은 조건은 작업 요청에 직접 넣었습니다.

이 방식은 토큰 사용량도 줄였습니다. 도구마다 과금 구조와 컨텍스트 계산법은 다르지만, 긴 지침이 매 요청에 반복되면 사용량과 응답 지연이 함께 늘어날 수 있습니다. 제 환경에서는 지침을 축약한 뒤 짧은 수정 작업의 왕복 대화가 대체로 한두 차례 줄었습니다. 구체적인 요금은 이용 중인 제품의 공식 가격표를 확인해야 하지만, 자주 반복되는 설명을 줄이는 것 자체가 비용 관리에 도움이 된다는 점은 공통적이었습니다.

보안 원칙은 축약 과정에서도 빼지 않았습니다. 코드 보안의 기본 개념이 낯설다면 코드 보안 용어 설명을 함께 읽어두면 지침의 우선순위를 잡기 쉽습니다. 저는 ‘환경 파일을 읽지 않는다’에서 멈추지 않고, 필요한 설정 키는 이름만 요청하고 실제 값은 출력하지 않도록 행동까지 명시했습니다.

한 문장에는 하나의 판단만 담았다

효과가 좋았던 규칙은 길이가 짧아서가 아니라 검증할 수 있다는 공통점이 있었습니다. ‘좋은 품질의 코드를 작성한다’는 말은 결과를 판정하기 어렵지만, ‘새 분기를 추가하면 해당 분기의 실패 테스트를 하나 추가한다’는 말은 준수 여부가 분명합니다. 비슷하게 ‘안전하게 작업한다’보다 ‘마이그레이션과 배포 명령은 실행하지 말고 필요한 명령만 제시한다’가 훨씬 안정적으로 작동했습니다.

1. 행동을 먼저 씁니다. 확인한다, 제안한다, 실행하지 않는다처럼 관찰 가능한 동사를 사용했습니다.
2. 적용 조건을 붙입니다. 모든 작업이 아니라 새 의존성이 필요할 때, 공개 API가 바뀔 때처럼 범위를 한정했습니다.
3. 충돌 시 우선순위를 씁니다. 스타일보다 기존 동작 보존을 우선한다는 식으로 선택 기준을 줬습니다.
4. 완료 증거를 요구합니다. 실행한 테스트, 실패한 명령, 수정한 파일을 마지막 응답에 적게 했습니다.
5. 예외 처리 방식을 정합니다. 확신이 없으면 추측 구현을 하지 않고 선택지를 제시하도록 했습니다.

제가 가장 자주 사용하는 작업 요청은 ‘목표, 수정 가능 범위, 수정 금지 범위, 검증 방법’ 네 줄로 끝납니다. 예를 들어 ‘회원가입 중복 이메일 메시지를 통일한다 / 인증 UI와 관련 테스트만 수정한다 / API와 데이터베이스는 건드리지 않는다 / 지정 테스트와 타입 검사를 실행한다’처럼 씁니다. 코드 자체를 설명해야 할 때는 로 코드의 개념처럼 용어 범위를 확인할 수 있는 자료를 연결해, 모호한 표현 대신 구체적인 대상을 가리켰습니다.

한 규칙을 지웠을 때 결과가 달라지지 않는다면 그 규칙은 장식일 가능성이 큽니다. 지침 파일도 코드처럼 사용 여부를 확인하고 정기적으로 삭제해야 합니다.

에이전트가 흔들릴 때 규칙부터 추가하면 안 됐다

실패 원인을 지침 부족으로 단정한 실수

가장 많이 저지른 실수는 결과가 마음에 들지 않을 때마다 새 규칙을 붙이는 것이었습니다. 테스트를 빠뜨리면 ‘모든 테스트 실행’을 추가하고, 파일을 많이 고치면 ‘최소 변경’을 추가했습니다. 그러나 실제 원인은 테스트 명령이 저장소 안에 명확히 적혀 있지 않거나, 요청 범위를 제가 모호하게 전달한 경우가 더 많았습니다. 원인을 구분하지 않고 지침만 늘리면 다음 작업에서는 필요 없는 제한으로 남습니다.

이제는 실패가 발생하면 먼저 세 가지를 확인합니다. 에이전트가 필요한 파일을 찾을 수 있었는지, 두 규칙이 충돌하지 않았는지, 완료 조건이 검증 가능한 형태였는지를 봅니다. 예를 들어 테스트가 누락됐다면 단순히 태도 문제로 취급하지 않고 실행 명령, 예상 소요 시간, 외부 서비스 필요 여부부터 점검합니다. 전체 테스트가 30분 걸리는 저장소에서 무조건 전부 실행하라는 규칙은 실용적이지 않기 때문입니다.

• 실수 1: 특정 버그 때문에 만든 임시 규칙을 저장소 전체의 영구 규칙으로 남겨두는 것입니다.
• 실수 2: ‘깔끔하게’, ‘최선으로’, ‘프로답게’처럼 사람마다 해석이 달라지는 표현을 완료 조건으로 쓰는 것입니다.
• 실수 3: 테스트 통과만 확인하고 수정 파일 수, 공개 인터페이스 변화, 새 의존성 추가 여부를 보지 않는 것입니다.

규칙 수정도 작은 실험으로 검증했다

새 규칙이 정말 필요한 경우에도 바로 영구 반영하지 않았습니다. 우선 비슷한 작업 두세 건에만 임시로 적용하고, 수정 파일 수와 재작업 횟수, 에이전트가 질문한 횟수를 기록했습니다. 규칙을 넣은 뒤 질문이 지나치게 늘거나 단순 작업까지 멈춘다면 표현이 너무 강한 것입니다. 반대로 위험한 명령을 실행하기 전에 확인을 요청하고 수정 범위가 안정적으로 줄었다면 전역 규칙으로 승격했습니다.

보안 관련 규칙에서는 편의보다 보수적인 기준을 유지했습니다. 특히 프롬프트나 로그에 인증 토큰, 고객 데이터, 내부 URL을 그대로 넣는 행동은 코드 품질과 별개의 위험입니다. 코드 보안 핵심 설명을 참고해 입력 데이터와 접근 범위를 구분했고, 민감한 값이 필요할 때는 사용자가 직접 로컬 환경에 설정하도록 했습니다.

마지막으로 피해야 할 것은 규칙 파일을 팀의 면책 문서처럼 사용하는 태도입니다. 규칙이 길다고 검토 책임이 사라지지 않으며, 에이전트가 ‘지침을 따랐다’고 답했다고 실제 변경이 안전한 것도 아닙니다. 저는 지금도 작업이 끝나면 변경 파일 목록, 실행한 명령, 실패한 검증, 남은 불확실성을 직접 확인합니다. 규칙을 추가하는 대신 이 네 가지 증거를 요구했을 때, AI 코딩 에이전트는 더 적게 말하고 더 예측 가능한 코드를 만들었습니다.

1. 새 규칙은 우선 한 작업에서만 시험합니다.
2. 기존 규칙과 충돌하면 더 낮은 우선순위의 문장을 삭제합니다.
3. 한 달 이상 결과에 영향을 주지 않은 규칙은 제거 후보로 표시합니다.
4. 위험 작업은 자동 실행 규칙이 아니라 사용자 승인 단계로 분리합니다.