서론

AI 코딩 에이전트(AI Coding Agent)를 본격적으로 사용하기 시작하면, 리포지토리(Repository)의 루트가 이렇게 되지 않나요?

CLAUDE.md ← Claude Code용
.cursor/rules/project.mdc ← Cursor용
.github/copilot-instructions.md ← GitHub Copilot용
...

적혀 있는 내용은 거의 동일합니다. 프로젝트 개요, 기술 스택(Tech Stack), 테스트 명령어, 코딩 규약, 해서는 안 될 일——. 그런데 파일 형식만 다르기 때문에, 규약을 하나 바꿀 때마다 5~6개의 파일을 수정해야 하며, 반드시 그중 하나는 오래된 정보가 됩니다. 팀에서 "Copilot은 괜찮다고 했는데 Claude Code는 화를 냈다"라는 상황이 발생하는 원인의 대부분은 바로 이 규칙의 드리프트(Rules Drift) 때문입니다.

그래서 폼에 한 번 입력하면 모든 에이전트용 규칙 파일을 일괄 생성하는 도구를 만들었습니다.

이 기사에서는 설계 방식(AGENTS.md를 단일 소스로 만들기)과 각 파일 형식의 차이를 흡수하는 방법을 해설합니다.

설계 방침: AGENTS.md를 Single Source of Truth로 만들기

생성 로직의 핵심은 "본문은 하나만 구성하고, 모든 파일은 거기서 파생시킨다"는 것입니다.

export function generateAll(input: RulesInput, targets: AgentTarget[]): GeneratedFile[] {
const body = buildAgentsMd(input); // ← 본문은 이 한 번만 생성
const files: GeneratedFile[] = [
...

다행히 주요 에이전트의 규칙 파일은 내용이 단순한 Markdown이라는 점에서 공통적입니다. 즉, "내용의 공통화"는 본문을 재사용하는 것만으로 성립하며, 차이점은 파일 경로와 일부 메타데이터뿐입니다.

유일한 예외: Cursor의 MDC 프론트매터(Frontmatter)

Cursor의 새로운 형식(.cursor/rules/*.mdc)만은 Markdown 본문 앞에 **프론트매터(Frontmatter)**가 필요합니다. 적용 조건을 여기서 선언합니다.

const mdcFrontmatter = [
'---',
`description: ${t.cursorDescription}`,
...

alwaysApply: true는 프로젝트 공통 규칙을 위한 설정입니다. 반대로 "특정 디렉토리에서만 적용하고 싶은 규칙"은 globs: src/api/**와 같이 작성하여 여러 개의 .mdc로 분할하는 것이 Cursor 방식입니다.

규칙 파일에는 무엇을 써야 하는가

도구의 폼 항목은 그대로 "AI 에이전트에게 전달했을 때 효과가 큰 순서"로 되어 있습니다.

경험상 특히 효과적인 것은 명령어와 금지 사항입니다. 테스트 명령어를 알고 있는 에이전트는 변경 후에 스스로 검증을 수행하며, 금지 사항은 "하고 나서 혼나는 것"을 "처음부터 하지 않는 것"으로 바꿔줍니다.

구현 팁: 입력의 정규화

폼의 자유 입력을 Markdown 리스트로 정형화할 때, 사용자가 - 나 ・를 붙여서 작성하는 경우를 흡수하고 있습니다.

const splitLines = (value: string): string[] =>
value
.split('\n')
...

"TypeScript, Astro, Tailwind라고 쉼표로 구분하여 쓰는 사람"도 "줄바꿈으로 나열하는 사람"도 "・를 붙여 쓰는 사람"도 출력은 모두 동일하고 깔끔한 글머리 기호가 됩니다. 사소하지만, 이런 종류의 정규화가 도구의 체감 품질을 결정합니다.

운용의 팁: 규칙은 "짧게" 유지하기

간과하기 쉽지만, 규칙 파일은 에이전트와의 거의 모든 대화에서 컨텍스트(Context)에 포함됩니다. 즉, 규칙이 길어지면 = 매번 토큰 비용(Token Cost)이 증가하고 + 중요한 지시 사항이 묻히게 됩니다.

• 「README에 적혀 있는 내용」을 그대로 베껴 쓰지 말 것 (에이전트는 README도 읽을 수 있습니다)
• 코드를 보면 알 수 있는 규칙(명명 규칙 등)은 쓰지 말고,
  코드에서 읽어낼 수 없는 제약 사항에 집중할 것
• 정기적으로 다시 읽어보고, 더 이상 지켜지지 않거나 오래된 규칙은 삭제할 것

체감상으로는, 50~100행 정도 내외로 유지되는 규칙 파일이 가장 잘 작동합니다.

요약

• 에이전트별 규칙 파일의 실체는
  거의 공통된 Markdown입니다. 단일 소스(AGENTS.md)로부터 파생 생성하면 드리프트(Drift) 현상이 발생하지 않습니다.
• 형식 차이를 흡수해야 하는 것은 실질적으로
  Cursor의 MDC 프론트매터(Frontmatter)뿐입니다.
• 내용은 「명령(Command)」과 「금지 사항」이 특히 효과적입니다.
• 그리고
  짧게 유지하세요

새로운 프로젝트에서 규칙 파일을 정비할 때 초안으로 꼭 활용해 보세요. 입력 내용은 브라우저 내에서 처리되며 외부로 전송되지 않습니다.

그 외에도 개발에 사용할 수 있는 유용한 도구들을 공개하고 있습니다.

Discussion