AI 에이전트 규칙 파일 관리법 (하네스 엔지니어링)

매일 Claude Code 와 Cursor 를 붙잡고 살면서 느낀 게 있다. 좋은 모델을 붙여놓는다고 끝이 아니라, AI 에이전트 규칙 파일을 어떻게 두느냐가 결과를 가른다.

에이전트를 어떤 “틀(harness)” 안에 넣고, 어떤 규칙으로 가둘 건지가 결과물 품질을 절반 이상 좌우해요.

이걸 “하네스 엔지니어링(harness engineering)” 이라고 부른다. 프롬프트 한 줄 잘 쓰는 것과는 완전히 다른 얘기다.

하네스 엔지니어링이 뭔데요

모델 자체는 이제 다 똑똑하다. 문제는 그 모델이 실제 코드베이스 안에서, 실제 도구를 쥐고, 반복적으로 작업할 때 어떻게 행동하게 만드느냐다.

시스템 프롬프트, 규칙 파일, 메모리, 도구 접근 권한, 반복 루프 구조를 합쳐 “하네스” 라고 부른다. 에이전트가 폭주하지 않게 잡아주는 고삐다.

제일 많이 헷갈리는 게 “규칙 파일 하나만 잘 써두면 되는 거 아닌가” 하는 생각이다. 아니다. 최소 네 가지 층위를 구분해야 한다.

이걸 뭉뚱그려 md 파일 하나에 다 넣으면 규칙 파일이 세션마다 부풀어 매번 로드되는 토큰만 늘고 정작 중요한 규칙은 파묻힌다.

처음엔 “규칙이든 메모리든 결국 텍스트 파일인데 뭐가 다른가” 했다가, 프로젝트 하나 굴리면서 CLAUDE.md 가 300줄을 넘는 걸 보고 정신을 차렸다.

규칙은 바뀌지 않는 원칙만 담고 나머지는 각자 자리로 보낸다.

이 바닥은 워낙 빨리 바뀌어서 반년 전 글도 이미 틀린 경우가 많다. 최근 기준으로 확인하면 이렇다.

Claude Code: CLAUDE.md — 프로젝트 루트에 두면 세션 시작 시 항상 로드돼요. 너무 길어지면 .claude/rules/ 아래로 쪼개서 모듈화하는 걸 권장합니다.
Cursor: 예전엔 .cursorrules 단일 파일이었는데, 이건 이제 사실상 레거시 취급이에요. 지금은 .cursor/rules/*.mdc 디렉터리 방식으로 넘어갔고, YAML 프론트매터로 “항상 로드” / “특정 파일 패턴에서만” / “AI가 판단해서” / “수동 호출 시에만” 같은 활성화 모드를 지정할 수 있어요. 참고로 Agent 모드에서는 루트 .cursorrules가 조용히 무시되는 경우도 있다고 하니, 마이그레이션을 안 했다면 지금 확인해보는 게 좋다.
Windsurf → Devin Desktop: 2026년 6월 Cognition이 Windsurf를 Devin Desktop으로 리브랜딩하면서 windsurf.com이 devin.ai로 리다이렉트되기 시작했어요. .windsurfrules 단일 파일은 여전히 동작은 하지만, .windsurf/rules/*.md(활성화 모드 지원) 방식을 거쳐 지금은 .devin/rules/가 권장 경로로 바뀌는 중이에요.
AGENTS.md: 특정 도구 종속이 아니라 여러 에이전트 도구가 공통으로 읽으려는 표준화 시도예요. 아직 완전히 자리잡진 않았지만 방향성은 명확하죠 — 도구마다 규칙 파일 포맷이 다른 게 다들 지긋지긋하다는 뜻이니까요.

이 표준화 흐름은 반갑다.

프로젝트 하나에 CLAUDE.md, .cursor/rules/, .windsurfrules 세 개를 다 유지보수하면서 내용이 서로 미묘하게 어긋나는 걸 겪어보면 안다.

자주 하는 착각이 하나 있다. “MCP(Model Context Protocol)도 규칙 설정 아닌가” 인데 아니다.

MCP 는 에이전트가 외부 도구·데이터에 어떻게 연결되는지를 정하는 프로토콜이다. DB 붙이고 Slack 붙이고 사내 API 붙이는 “배선” 층위지, “이 프로젝트에서는 이렇게 코딩해라” 는 지침 층위가 아닙니다.

규칙 파일이 운전 습관이라면 MCP 는 자동차에 어떤 부품을 다느냐다. MCP 서버를 아무리 늘려도 규칙 파일이 부실하면 에이전트는 제멋대로 움직인다.

반대로 규칙만 촘촘해도 MCP로 연결 안 해주면 애초에 손댈 수 있는 범위가 좁고요. 둘은 상호보완이지 대체재가 아니에요.

규칙 과다로 오히려 안 지켜짐: 규칙이 50개 넘어가면 모델도 우선순위를 못 잡아요. 정말 중요한 3~5개가 잡다한 규칙들 사이에 묻혀서 매번 무시당합니다. 규칙은 적을수록 잘 지켜져요.
규칙 파일 방치: 리팩터링하고 아키텍처 바뀌었는데 규칙 파일은 6개월 전 상태 그대로. 에이전트가 “규칙대로” 했는데 실제 코드베이스랑 안 맞아서 오히려 버그를 만들어요. 규칙 파일도 코드 리뷰 대상이어야 합니다.
팀원마다 다른 규칙으로 작업: 로컬에 .claude/settings.local.json이나 개인 규칙을 슬쩍 얹어두고 아무도 공유 안 하면, 같은 저장소인데 사람마다 결과물 스타일이 갈라져요. 공용 규칙은 반드시 커밋해서 git 으로 관리한다.

# CLAUDE.md 예시 (핵심 원칙만, 짧게)
- 테스트 없이 기능 코드 커밋 금지
- DB 마이그레이션은 항상 롤백 스크립트 동반
- 외부 API 호출 실패 시 반드시 재시도 로직 포함

# .cursor/rules/backend.mdc 예시 프론트매터
---
description: 백엔드 API 라우트 작성 규칙
globs: ["src/api/**/*.ts"]
alwaysApply: false
---

핵심은 이거예요.

규칙 파일은 얇고 자주 지켜지게, 메모리는 자동으로 누적되게, 플랜은 작업 단위로 휘발되게, 스킬은 재사용 가능한 절차로. 이 네 개를 헷갈리지 않고 각자 자리에 두는 것부터가 하네스 엔지니어링의 시작입니다.

다들 모델 성능에만 신경 쓰는데, 같은 모델로도 이 세팅 하나로 결과물이 달라진다.