AI 코딩 하네스도 리팩토링해야 한다: 개발동생

Q: AI 코딩 하네스가 뭐예요?

AI 코딩 도구가 더 잘 일하도록 둘러싼 규칙과 도구 묶음임. AGENTS.md, CLAUDE.md, Cursor Rules, MCP, Skill, hook, 테스트 명령, 서브에이전트 사용 규칙 같은 것들이 포함됨.

AI 코딩에서 하네스는 모델을 둘러싼 작업 환경임. AGENTS.md, CLAUDE.md, Cursor Rules, MCP, Skill, hook, 서브에이전트 규칙 같은 것들이 여기에 들어감
한 번 만든 하네스는 영원하지 않음. 모델이 똑똑해지고 Claude Code, Codex, Cursor 자체도 계속 업데이트되기 때문
문제는 우리가 만든 하네스가 이미 코딩 에이전트 안에 들어간 하네스 위에 또 올라간다는 점. 3개월 전엔 필요했던 규칙이 지금은 중복 지시가 될 수 있음
그래서 이제 필요한 질문은 “무엇을 더 붙일까?”가 아니라 “무엇을 이제 빼도 될까?”임
개발동생의 YouTube 커뮤니티 글. AI 코딩 환경에서 하네스, 전역 지침, MCP, Skill을 어떻게 관리할지에 대한 짧은 실전 메모

하네스는 왜 빨리 낡나?

첫 번째 이유는 모델이 좋아지기 때문임
예전 모델은 지시를 잘 안 따라 “반드시 계획부터 세워라”, “테스트 전에는 완료라고 하지 마라”, “이 파일부터 읽어라” 같은 울타리가 필요했음
그런데 모델이 좋아지면 예전에는 강제로 시켜야 했던 행동을 자연스럽게 하기 시작함
두 번째 이유는 코딩 에이전트 제품 자체가 계속 업데이트되기 때문임
Claude Code, Codex, Cursor는 단순한 모델 호출창이 아님. 파일 읽기, 코드 수정, 터미널 실행, 테스트, 리뷰, 메모리, 브라우저, MCP 같은 기능이 이미 얹힌 제품임
그래서 사용자가 만든 규칙은 “하네스 위에 또 올린 하네스”가 됨. 제품이 기본으로 잘하게 된 일을 내가 계속 강제하면, 도와주는 게 아니라 방해가 될 수 있음

낡은 하네스는 어떻게 성능을 떨어뜨리나?

낡은 규칙은 모델을 과거의 작업 방식에 묶어버림
“항상 계획부터 세워”는 큰 변경에는 좋을 수 있지만, 작은 오타 수정이나 단순 버그에는 느리게 만듦
“항상 이 문서를 읽어”는 필요한 작업에는 좋지만, 상관없는 작업에서는 context만 더럽힘
“항상 서브에이전트를 써”는 복잡한 조사에는 좋지만, 작은 수정 하나에는 문제보다 프로세스가 더 커짐
전역 지침이 길어질수록 모든 작업에 과거의 걱정이 따라붙음
로그인 버그를 고치는데 배포 정책, 디자인 철학, 6개월 전 리팩토링 회고까지 매번 읽힐 필요는 없음
AI 코딩에서 context는 작업 공간임. 작업 공간이 깨끗할수록 모델이 지금 문제에 더 집중하기 쉬움

무엇을 덜어내야 하나?

점검 대상	물어볼 질문	정리 방향
전역 규칙	최근에도 실제 실수를 막았나?	막은 적 없으면 삭제
MCP	진짜 자주 쓰나, 멋있어서 켜둔 건가?	자주 쓰는 것만 유지
Skill	아직 필요한가, 제품 기본 기능으로 대체됐나?	기본 기능이면 제거
Hook	안전하게 하나, 매번 모델을 멈추게 하나?	멈춤만 만든다면 완화
문서	모든 세션에서 읽어야 하나?	필요할 때만 읽게 이동
서브에이전트 규칙	문제보다 프로세스가 커지나?	복잡한 작업에만 사용

특히 CLAUDE.md, AGENTS.md, Cursor Rules 같은 전역 지침은 조심해야 함
이 파일들은 편하지만 너무 길어지면 모든 작업에 붙는 짐이 됨
특정 작업에만 필요한 맥락은 전역에서 빼고, 작업할 때만 꺼내 읽히는 쪽이 나음

좋은 하네스는 어떻게 관리하나?

하네스를 버리자는 게 아니라 관리하자는 말임
좋은 하네스는 계속 쌓이는 게 아니라 계속 갱신되는 하네스임
예전에 필요했던 것은 남기고, 이제 제품이 더 잘하는 것은 지워야 함
자주 쓰는 규칙은 짧고 정확하게 남기고, 특정 상황에만 필요한 규칙은 전역에서 빼야 함
코드만 리팩토링하는 게 아니라 에이전트 환경도 리팩토링해야 함
한 달에 한 번 정도 AGENTS.md, CLAUDE.md, MCP, Skill, hook 목록을 열어보고 “이거 아직도 필요한가?”를 물어보는 게 현실적인 주기임

AI 코딩 하네스가 뭐예요?

AI 코딩 도구가 더 잘 일하도록 둘러싼 규칙과 도구 묶음임. AGENTS.md, CLAUDE.md, Cursor Rules, MCP, Skill, hook, 테스트 명령, 서브에이전트 사용 규칙 같은 것들이 포함됨.

AGENTS.md와 CLAUDE.md는 없애야 하나요?

무조건 없앨 필요는 없음. 다만 전역 지침은 모든 작업에 붙기 때문에 길고 오래된 내용이 있으면 성능을 떨어뜨릴 수 있음. 프로젝트 사실, 금지 명령, 테스트 방법처럼 매번 필요한 짧은 정보만 남기는 쪽이 안전함.

하네스는 얼마나 자주 점검해야 하나요?

원문은 한 달에 한 번 정도를 제안함. 모델이나 코딩 에이전트가 업데이트됐거나, AI가 갑자기 느려지고 장황해졌거나, 불필요한 도구 호출이 늘었다면 그때도 바로 점검할 만함.

1인기업 관점

이건 1인기업에 더 세게 맞는 얘기인 듯. 혼자 일하면 불안해서 AGENTS.md, Skill, MCP를 계속 붙이게 되는데, 결국 매 세션에 과거의 불안이 따라붙는 구조가 될 수 있음. 한 달에 한 번 하네스 청소하는 날을 정해서 “최근 실수를 막은 규칙만 남긴다” 정도로 운영하는 게 제일 현실적인 것 같음.

AI 코딩 하네스도 리팩토링해야 한다: 개발동생 (youtube.com) ↗