AI 코딩 하네스도 리팩토링이 필요합니다: 더 붙이기보다 덜어내야 할 시점

여러분, AI 코딩 환경을 오래 쓰다 보면 어느 순간 설정 파일이 많아집니다. AGENTS.md, CLAUDE.md, Cursor Rules, Skills, Hooks, MCP 서버, 메모리, allowed tools, 브랜치 규칙, 테스트 규칙까지 계속 쌓이죠. 처음에는 전부 필요해 보입니다. 실제로 필요했던 것도 많습니다.

그런데 문제가 하나 있습니다. 한 번 만든 하네스가 영원히 좋은 하네스로 남지는 않는다는 점입니다. 하네스는 코드처럼 낡습니다. 그리고 낡은 하네스는 안전장치가 아니라 마찰이 됩니다.

그래서 이제 중요한 질문은 “무엇을 더 붙일까?”만이 아니라고 봅니다. 오히려 더 자주 물어야 할 질문은 이것입니다.

이 하네스는 아직도 필요한가?

하네스는 왜 빨리 낡는가

하네스가 낡는 이유는 크게 두 가지입니다.

첫 번째는 모델이 계속 좋아지기 때문입니다.

예전에는 모델이 지시를 자주 놓쳤습니다. 그래서 이런 규칙을 많이 붙였습니다.

• 무조건 이 파일부터 읽어라
• 절대 바로 구현하지 마라
• 반드시 계획부터 세워라
• 테스트 전에는 완료라고 말하지 마라
• 특정 작업에서는 항상 이 문서를 참고하라

당시에는 이런 규칙이 실제로 도움이 됐습니다. 모델이 기본적으로 못 하던 행동을 강제로 묶어두는 역할을 했기 때문입니다.

그런데 모델이 좋아지면 상황이 달라집니다. 예전에는 강제로 시켜야 했던 행동을 이제는 모델이 자연스럽게 하기 시작합니다. 작업 전 맥락을 읽고, 위험도를 판단하고, 테스트를 돌리고, 실패하면 수정하는 흐름이 점점 기본 동작에 가까워지죠.

그 순간 과거의 규칙은 더 이상 보조 장치가 아닐 수 있습니다. 이미 잘하는 일을 다시 지시하는, 중복 지시가 되는 겁니다.

두 번째는 코딩 에이전트 제품 자체가 계속 업데이트되기 때문입니다.

Claude Code, Codex, Cursor를 단순한 모델 호출창으로 보면 안 됩니다. 이 도구들은 이미 하나의 하네스입니다. 모델 위에 파일 읽기, 코드 수정, 터미널 실행, 테스트, 리뷰, 메모리, 규칙, 스킬, 브라우저, MCP, 백그라운드 에이전트 같은 기능을 얹어둔 제품입니다.

그러면 우리가 만든 하네스는 사실상 제품 하네스 위에 다시 올린 하네스인 셈입니다.

3개월 전에는 꼭 필요했던 규칙이 지금은 제품 기본 기능으로 들어왔을 수 있습니다. Claude Code가 같은 일을 더 잘 처리하게 됐을 수도 있고, Codex가 더 좋은 검증 흐름을 제공하게 됐을 수도 있고, Cursor가 제품 차원에서 그 워크플로우를 흡수했을 수도 있죠.

그런데 예전 규칙이 그대로 남아 있으면 문제가 생깁니다. 최신 제품은 이미 더 나은 방식으로 판단하려고 하는데, 낡은 규칙이 계속 끼어들어 모델을 과거 방식으로 묶어버리거든요.

좋은 규칙도 항상 좋지는 않다

“계획부터 세워”라는 규칙은 좋은 규칙처럼 보입니다. 큰 기능을 만들거나 인증 구조를 바꾸거나 결제 로직을 건드릴 때는 계획이 필요합니다.

하지만 모든 작업에 계획이 필요한 것은 아닙니다. 문서 오탈자 하나를 고치거나 버튼 색상을 조금 바꾸는 작업까지 매번 계획을 세우게 하면, 작업보다 절차가 커집니다.

“항상 이 문서를 읽어”라는 규칙도 마찬가지입니다. 프로젝트 전체 맥락이 필요한 작업에서는 도움이 됩니다. 하지만 지금 작업과 무관한 문서를 매번 읽히면 컨텍스트만 더러워지죠. AI 코딩에서 컨텍스트는 작업 공간입니다. 작업 공간이 어수선하면 모델도 집중하기 어렵습니다.

“항상 서브에이전트를 써”도 항상 좋은 규칙은 아닙니다. 복잡한 리뷰나 대규모 리팩토링에서는 역할 분리가 유용합니다. 하지만 작은 버그 하나 고치는데 에이전트 팀을 소환하면, 문제보다 프로세스가 더 커집니다.

하네스의 함정이 바로 여기 있습니다. 처음에는 모델을 도와주려고 만든 구조가, 시간이 지나면 모델을 방해하는 레거시가 됩니다.

전역 지침은 가장 먼저 의심해야 한다

특히 조심해야 할 게 전역 지침입니다.

CLAUDE.md, AGENTS.md, Cursor Rules 같은 파일은 매우 편리합니다. 한 번 작성해두면 모든 세션에서 에이전트가 같은 기준을 읽고 움직이니까요. 그런데 바로 그 이유 때문에 위험합니다.

전역 지침은 모든 작업에 따라붙는 짐입니다. 생각해보면, 로그인 버그 하나 고치는데 배포 정책, 디자인 시스템 철학, 6개월 전 리팩토링 회고까지 전부 읽힐 필요는 없죠. 작은 문서 수정에 DB 마이그레이션 정책, PR 생성 규칙, 장기 작업 보고서 규칙이 모두 필요한 것도 아닙니다.

전역에는 정말 전역적인 것만 남겨야 합니다.

• 보안상 절대 하면 안 되는 행동
• DB, 시크릿, 결제, 운영 배포처럼 실패 비용이 큰 영역의 규칙
• 프로젝트의 기본 빌드와 테스트 명령
• 모든 작업에 영향을 주는 코딩 컨벤션
• 에이전트가 모르면 반복적으로 실수하는 비자명한 예외

반대로 특정 작업에서만 필요한 맥락은 전역에서 빼는 게 좋습니다. 필요할 때만 불러오는 스킬, reference, 프로젝트별 문서, 작업별 체크리스트로 옮기는 편이 낫습니다.

하네스 리팩토링 체크리스트

한 달에 한 번 정도는 내 에이전트 환경을 열어보고 아래 질문을 던져보면 좋겠습니다.

1. 이 규칙은 최근에도 실제 실수를 막았나

규칙은 존재 자체로 정당화되지 않습니다. 최근에 실제 실수를 막은 적이 있는지 봐야 합니다. 막은 적이 없다면 두 가지 가능성이 있죠.

정말 필요 없어졌거나, 아니면 너무 넓어서 효과를 측정할 수 없는 규칙이 됐거나입니다.

2. 이 문서는 모든 세션에서 읽어야 하나

모든 세션에서 읽히는 문서는 컨텍스트 비용을 가집니다. 그 비용을 낼 만큼 자주 필요한 문서인지 확인해야 합니다.

작업별로 필요한 문서는 전역 지침이 아니라 필요 기반으로 불러오는 구조가 더 좋습니다.

3. 이 Skill은 반복 업무인가

Skill은 긴 프롬프트 저장소가 아닙니다. 반복되는 절차를 패키징한 작은 워크플로우에 가깝습니다.

한 번 쓰고 거의 다시 쓰지 않는 스킬, 너무 넓어서 매번 컨텍스트만 많이 먹는 스킬, 제품 기본 기능으로 대체된 스킬은 정리 대상입니다.

4. 이 MCP는 진짜 자주 쓰이나

MCP는 강력하지만, 켜져 있다는 것만으로 좋은 건 아닙니다. 외부 시스템 연결은 권한 표면과 설명 비용을 늘리니까요.

정말 자주 쓰는 연결인지, 아니면 멋있어 보여서 켜둔 것인지 한번 구분해보면 좋겠습니다.

5. 이 hook은 안전장치인가, 마찰인가

좋은 hook은 위험한 행동을 자동으로 막습니다. 예를 들어 DB 쓰기 차단, 시크릿 접근 차단, 보호 브랜치 차단 같은 것은 명확한 안전장치입니다.

반대로 매번 false positive를 내고 사람이나 모델을 멈추게 하는 hook은 마찰일 수 있습니다. 이 경우 완전히 삭제하기보다 조건을 좁히거나, 더 위험한 작업에만 작동하도록 조정해야 합니다.

삭제보다 먼저 할 일: 좁히고, 옮기고, 나누기

하네스 리팩토링은 무조건 지우는 작업이 아닙니다. 좋은 하네스는 계속 쌓이는 것이 아니라 계속 갱신되는 것입니다.

정리할 때는 삭제보다 먼저 다음 선택지를 생각하는 편이 안전합니다.

방식	의미	예시
유지	여전히 전역적으로 필요한 규칙을 남긴다	DB 직접 접근 금지, 시크릿 노출 금지
축소	너무 넓은 규칙을 더 구체적으로 바꾼다	”항상 계획”을 “고위험 변경은 계획”으로 변경
이동	전역 규칙을 작업별 문서나 스킬로 옮긴다	특정 프로젝트 운영 규칙을 프로젝트 문서로 이동
분리	긴 스킬을 reference, examples, scripts로 나눈다	SKILL.md 본문을 짧게 만들고 세부 자료를 lazy-load
보관	당장 쓰지 않지만 복구 가능하게 archive한다	오래된 MCP 설정, 더 이상 쓰지 않는 스킬
삭제	실제로 필요 없고 복구 가치도 낮은 항목을 제거한다	중복 지시, 제품 기본 기능과 겹치는 낡은 규칙

중요한 것은 하네스를 버리는 것이 아닙니다. 관리하는 것입니다.

앞으로의 하네스는 더 적고 더 정확해야 한다

제가 더 중요하게 보는 건 방향입니다. AI 코딩 에이전트가 발전할수록 하네스는 더 많이 붙이는 쪽으로만 갈 수 없습니다. 오히려 더 적고, 더 정확하고, 더 조건부로 작동해야 합니다.

작은 작업은 가볍게 처리하고, 큰 작업은 계획을 세우고, 위험한 작업은 검증을 붙입니다. 맥락이 부족한 작업은 필요한 문서만 읽고, 실패 비용이 큰 작업은 사람 승인과 강제 hook을 둡니다. 작업 성격에 따라 무게를 다르게 줘야 한다는 거죠.

모든 작업에 같은 무게의 하네스를 씌우는 방식은 점점 비효율적이 됩니다.

이 관점은 Loop Engineering과도 연결됩니다. 덜어낸 통제를 포기하는 것이 아니라, 필요한 순간에만 작동하는 루프 안으로 옮기는 것입니다.

마무리

결론부터 말하면, 하네스도 리팩토링이 필요합니다. 코드만 리팩토링할 게 아니라, 내 에이전트 환경도 리팩토링해야 합니다.

한 달에 한 번 정도는 AGENTS.md, CLAUDE.md, Cursor Rules, Skills, Hooks, MCP 설정을 열어보고 이렇게 물어보면 좋겠습니다.

이거 아직도 필요한가?

아직도 실제 실수를 막고 있다면 남기면 됩니다. 하지만 제품이 더 잘하게 된 일, 특정 작업에서만 필요한 맥락, 아무도 쓰지 않는 스킬, 매번 모델을 멈추게 하는 hook은 줄이거나 옮기는 편이 낫다고 봅니다.

제가 말하고 싶은 건 이겁니다. 하네스의 목적은 AI를 묶어두는 게 아닙니다. AI가 더 잘 일할 수 있는 조건을 만드는 것입니다.