Molayo

© 2026 Molayo

Zenn헤드라인2026. 05. 18. 23:25

AI 코딩 시 반복되는 주의사항을 규칙 파일(Rule File)로 관리하는 방법

요약

AI 코딩 도구를 사용할 때 반복되는 주의사항을 매번 채팅으로 입력하는 대신, 프로젝트별 규칙 파일(Rule File)을 통해 효율적으로 관리하는 방법을 소개합니다. 모호한 명령 대신 구체적인 행동 지침을 작성하고, 반복되는 실수 패턴을 중심으로 규칙을 점진적으로 확장하는 것이 핵심입니다.

핵심 포인트

  • Claude Code, Cursor, Windsurf 등 도구별 전용 규칙 파일(CLAUDE.md, .cursor/rules 등)을 활용할 것
  • 모호한 추상적 표현(예: 최고 품질) 대신 구체적인 행동 지침(예: 기존 패턴 우선)을 작성할 것
  • 처음부터 길게 작성하기보다 반복되는 실수나 문제 상황을 중심으로 규칙을 추가할 것
  • 개인 개발 시에는 구현하지 않은 기능을 과장하거나 단정적으로 표현하지 않도록 주의할 것

Claude Code, Cursor, Windsurf, Codex, GitHub Copilot을 사용하다 보면, 매번 AI에게 똑같은 주의사항을 쓰고 있는 자신을 발견하게 됩니다.

  • 기존 설계에 맞춰서
  • 마음대로 크게 리팩터링(Refactoring)하지 말고
  • 테스트하지 않았다면 확인 완료라고 쓰지 말고
  • README를 과장해서 작성하지 말고
  • API 키나 .env 파일은 노출하지 말 것

같은 주의사항을 반복해서 쓰고 있다면, 그것은 채팅이 아니라 규칙 파일(Rule File)에 두는 것이 좋습니다.

규칙 파일이란

여기서 말하는 규칙 파일이란, AI 개발 도구에 프로젝트의 작업 방침을 전달하기 위한 파일입니다.

예를 들어, 다음과 같은 것들이 있습니다.

  • Claude Code라면 CLAUDE.md
  • Codex라면 AGENTS.md
  • Cursor라면 .cursor/rules/*.mdc
  • GitHub Copilot이라면 .github/copilot-instructions.md
  • Windsurf라면 규칙 관리에 맞춘 프로젝트 규칙

도구마다 세부 사양은 다르지만, 하고자 하는 목적은 비슷합니다.

"이 리포지토리(Repository)에서는 AI가 이렇게 움직였으면 좋겠다"를 매번 전달하기 위한 장소입니다.

처음에 작성해야 할 것

처음부터 긴 규칙을 작성할 필요는 없습니다.

우선은 아래의 4가지로 충분합니다.

## 기본 방침
- 기존 설계, 명명 규칙(Naming), 디렉터리 구성을 우선한다
- 변경은 요청 범위로 한정한다
...

이 정도 내용은 GitHub 무료 버전에도 같은 사고방식을 적용할 예정입니다.

이후에는 도구별 구체적인 파일, 용도별 팩, 실패 사례를 반영한 금지 규칙으로 들어가는 영역입니다.

규칙은 정신론보다 행동으로 작성하라

별로 효과가 없는 작성 방식이 있습니다.

최고 품질로 구현해 주세요.
절대로 버그를 내지 마세요.
완벽한 코드를 작성해 주세요.

마음은 이해하지만, AI에게는 모호합니다.

그보다는 다음과 같이 쓰는 것이 사용하기 좋습니다.

기존 코드 근처에 있는 구현 패턴을 우선해 주세요.
변경 후에는 가능하다면 관련 있는 최소 단위의 테스트를 실행해 주세요.
테스트할 수 없는 경우에는 이유와 미확인 리스크를 보고해 주세요.

규칙 파일에 써야 할 것은 기합이 아니라 행동입니다.

유료 버전에는 이러한 약한 표현과 강한 표현을 나란히 정리한 규칙 개선 BeforeAfter.md를 포함하고 있습니다.

너무 길어지면 오히려 약해진다

규칙 파일은 길다고 좋은 것이 아닙니다.

처음부터 전부 쓰려고 하면 읽기 어려워집니다.

추천하는 방법은, 몇 번이고 똑같은 지시를 했던 것만 추가하는 것입니다.

  • 또 마음대로 포맷팅(Formatting)했다
  • 또 README가 과장되었다
  • 또 확인하지 않은 것을 확인 완료라고 말했다
  • 또 관계없는 파일까지 건드렸다

이런 "또 발생한" 문제들을 규칙으로 옮기면 실용적인 규칙이 됩니다.

유료 버전에서는 이러한 실패 패턴을 AI 실수 사례와 규칙 대응.md로 정리해 두었습니다.

개인 개발에서 특히 넣고 싶은 규칙

개인 개발이라면 아래 내용은 우선순위가 상당히 높습니다.

- 구현하지 않은 기능을 README나 상품 설명에 쓰지 않는다
- 「완전히」, 「반드시」, 「자동으로 전부」와 같은 강한 단정을 피한다
- BOOTH나 Zenn에 올리는 문장에서는 할 수 없는 일이나 제한 사항도 적는다
...

AI로 만드는 속도가 올라가면 공개까지의 거리도 짧아집니다.
그만큼 공개 전의 사고도 일어나기 쉽습니다.

이러한 관점들은 유료 버전에 동봉된 AI에게 맡기지 않는 금지 규칙 모음.md에 안전 / Git / 구현 범위 / 문장 / 고위험 영역의 5개 카테고리로 정리되어 있습니다.

규칙이 작동하지 않을 때는 진단하라

규칙 파일을 두더라도 바로 완벽해지지는 않습니다.

예를 들어, 다음과 같은 일이 일어납니다.

  • 규칙이 너무 길어서 중요한 지시가 묻힌다
  • "불필요한 일을 하지 마라"와 같이 너무 모호하다
  • 도구별 위치가 맞지 않는다
  • 프로젝트 고유의 주의사항이 부족하다

그럴 때는 AI에게 다음과 같이 물어보면 검토하기 쉽습니다.

이 리포지토리의 AI 개발 규칙을 읽어주세요.
규칙을 위반했을 가능성이 높은 행동,
규칙에 적혀 있지는 않지만 적었어야 했을 지시,
...

규칙 파일은 배치하고 끝내는 것이 아니라, 개발하면서 계속 수정해 나가는 것입니다.

요약

AI 코딩에서 매번 똑같은 주의사항을 주고 있다면, 그것은 규칙 파일로 옮기라는 신호입니다.

처음에는 짧아도 괜찮습니다.

  • 기존 설계를 우선할 것
  • 요청 범위를 벗어난 변경을 하지 말 것
  • 비밀 정보를 노출하지 말 것
  • 테스트 미실행 상태를 완료 상태로 간주하지 말 것
  • 미구현 기능을 포함하지 말 것
  • 완료 시 미확인 사항을 보고할 것

이 정도만 설정해 두어도 AI와의 개발을 훨씬 수월하게 진행할 수 있습니다.

먼저 시도해보고 싶은 분들께

최소한의 기본 틀만 테스트해보고 싶다면, GitHub의 무료 버전을 이용해 주세요.

한꺼번에 정비하고 싶은 분들께

5가지 툴(Tool) 분량의 템플릿, 용도별 팩, 실수 사례, 금지 규칙 모음, 진단 프롬프트(Prompt), 도입 체크리스트를 한 세트로 받고 싶다면, BOOTH의 유료 버전을 이용해 주세요.

선착순 10명은 1,480엔, 일반 가격은 2,980엔 예정입니다.

관련

공개 전 확인에는 전작인 AI 개발 공개 전 셀프 체크 키트도 사용할 수 있습니다.

AI 자동 생성 콘텐츠

본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0