안녕하세요, 저는 HolySheep AI의 기술 문서 엔지니어입니다. 오늘은 Cursor 편집기에서 나만의 코딩 규칙을 만드는 방법을 초보자도 이해할 수 있도록 단계별로 알려드리겠습니다.

Cursor Rules란 무엇인가요?

Cursor Rules는 AI가 코드를 작성할 때 따르게 될 나만의 규칙 파일입니다. 마치 "코딩 스타일 가이드북"을 만드는 것과 같습니다. 이 규칙을 설정하면:

1단계: HolySheep AI에서 API 키 발급받기

커스텀 규칙을 테스트하려면 먼저 HolySheep AI에서 API 키가 필요합니다. 지금 가입하면 무료 크레딧을 받을 수 있어요.

저는 실제로 HolySheep AI를 사용하면서 Cursor Rules를 설정해 보았고, 정말 편리하다는 것을 확인했습니다. HolySheep AI는 해외 신용카드 없이 로컬 결제를 지원해서 개발자 친화적입니다.

2단계: 프로젝트에 .cursor/rules 폴더 만들기

프로젝트 루트 디렉토리에 아래와 같이 폴더를 생성하세요:

my-project/
├── .cursor/
│   └── rules/
│       ├── default.mdc
│       ├── react-style.mdc
│       └── api-doc.mdc
├── src/
│   └── index.js
└── package.json

3단계: 기본 커스텀 규칙 파일 만들기

가장 기본이 되는 default.mdc 파일을 만들어 보겠습니다. 이 파일에는 프로젝트 전체에 적용할 공통 규칙을 작성합니다.

# 기본 코딩 규칙


개요

이 프로젝트는 Clean Code 원칙을 따릅니다.


규칙

1. 모든 함수에는 JSDoc 주석을 작성한다
2. 변수 이름은 camelCase를 사용한다
3. 상수는 대문자 SNAKE_CASE를 사용한다
4. async/await를优先하고 콜백은 피한다
5. console.log 대신 proper logging 라이브러리를 사용한다


TypeScript 설정

- strict 모드를 활성화한다
- any 타입 사용을 금지한다
- 모든 함수에 반환 타입을 명시한다


테스트 요구사항

- 모든 함수에 대한 단위 테스트를 작성한다
- 커버리지 목표는 80% 이상이다

4단계: HolySheep AI와 연동하기

이제 HolySheep AI API를 사용하여 Cursor에서 AI 응답을 받을 때 커스텀 규칙을 반영하도록 설정해 보겠습니다. 먼저 Node.js 환경에서 테스트를 진행합니다.

// holysheep-test.js
const https = require('https');

const API_KEY = 'YOUR_HOLYSHEEP_API_KEY';
const BASE_URL = 'api.holysheep.ai';

// 커스텀 규칙을 시스템 프롬프트에 포함
const customRules = `
당신은 다음 코딩 규칙을 반드시 따라야 합니다:
1. 변수명은 의미 있게 작성한다
2. 모든 함수에 주석을 추가한다
3. ES6+ 문법을 사용한다
`;

const requestBody = JSON.stringify({
  model: 'gpt-4.1',
  messages: [
    {
      role: 'system',
      content: customRules + '\n\n프로젝트 규칙에 맞춰 코드를 작성해주세요.'
    },
    {
      role: 'user', 
      content: '숫자 배열을 정렬하는 함수를 만들어주세요'
    }
  ],
  temperature: 0.7,
  max_tokens: 1000
});

const options = {
  hostname: BASE_URL,
  path: '/v1/chat/completions',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': Bearer ${API_KEY},
    'Content-Length': Buffer.byteLength(requestBody)
  }
};

const req = https.request(options, (res) => {
  let data = '';
  
  res.on('data', (chunk) => {
    data += chunk;
  });
  
  res.on('end', () => {
    try {
      const response = JSON.parse(data);
      console.log('응답 받음!');
      console.log('사용된 모델:', response.model);
      console.log('토큰 사용량:', response.usage);
      console.log('\n--- AI 응답 ---');
      console.log(response.choices[0].message.content);
    } catch (e) {
      console.error('파싱 오류:', e.message);
    }
  });
});

req.on('error', (e) => {
  console.error('요청 오류:', e.message);
});

req.write(requestBody);
req.end();

이 스크립트를 실행하면 HolySheep AI의 GPT-4.1 모델이 커스텀 규칙을 반영한 코드를 생성해 줍니다. GPT-4.1은 $8/MTok의 가격으로高品质 응답을 제공합니다.

5단계: 언어별 커스텀 규칙 만들기

프로젝트에서 여러 프로그래밍 언어를 사용하는 경우, 언어별로 다른 규칙 파일을 만들 수 있습니다.

// .cursor/rules/react-components.mdc

React 컴포넌트 규칙



컴포넌트 구조

1. functional component만 사용한다
2. props에 대한 PropTypes 또는 TypeScript 타입을 정의한다
3. useState의 초기값을 명시적으로 설정한다


스타일 가이드

- CSS-in-JS( Emotion 또는 Styled-Components )를 사용한다
- 클래스명 대신 의미론적命名法를 따른다


예시 코드


import React, { useState } from 'react';
import styled from '@emotion/styled';

const Container = styled.div`
  padding: 16px;
  background: white;
`;

function WelcomeMessage({ name }) {
  const [isVisible, setIsVisible] = useState(true);
  
  return (
    <Container>
      <h1>안녕하세요, {name}님!</h1>
      <button onClick={() => setIsVisible(!isVisible)}>
        토글
      </button>
    </Container>
  );
}

WelcomeMessage.propTypes = {
  name: PropTypes.string.isRequired
};

export default WelcomeMessage;




Hook 사용 규칙

- 커스텀 Hook은 use 접두사를 반드시 붙인다
- useEffect의 의존성 배열을 항상 확인한다
- 불필요한 리렌더링을 방지하기 위해 useMemo와 useCallback을 적절히 사용한다

6단계: API 문서 자동화 규칙

백엔드 API를 개발할 때 자동으로 문서를 생성하도록 규칙을 설정해 보겠습니다.

# API 문서화 규칙


Endpoints 작성 규칙

모든 API 엔드포인트에는 다음 정보를 반드시 포함해야 합니다:


형식


### [HTTP 메서드] /api/엔드포인트

**설명:** 엔드포인트의 목적

**요청 본문:**
\\\`json
{
  "필드명": "타입 - 설명"
}
\\\`

**응답:**
- 200: 성공 응답 설명
- 400: 잘못된 요청 설명
- 401: 인증 오류 설명

**예시 요청:**
\\\`bash
curl -X POST https://api.example.com/endpoint \\
  -H "Authorization: Bearer TOKEN" \\
  -d '{"key": "value"}'
\\\`




응답 형식 표준

모든 API 응답은 다음 구조를 따라야 합니다:

{
  "success": true,
  "data": {},
  "message": "작업 성공 메시지",
  "timestamp": "ISO 8601 형식의 시간"
}




에러 응답 형식


{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "사용자 친화적인 에러 메시지",
    "details": {}
  }
}

7단계: 규칙 파일을 Cursor에 적용하기

설정한 규칙 파일을 실제로 Cursor 편집기에서 사용하려면:

이제 Cursor에서 AI와 대화하면 설정한 커스텀 규칙이 자동으로 적용됩니다.

실전 활용 팁

저는 실제로 여러 프로젝트에서 HolySheep AI와 Cursor Rules를 함께 사용하고 있습니다. 특히 비용 최적화 측면에서 큰 효과를 보았어요. DeepSeek V3.2 모델은 $0.42/MTok으로 매우 경제적이어서 반복적인 코드 생성 작업에 적합합니다.

프로젝트 규모와 목적에 따라 모델을 다르게 선택하면 비용을 절감할 수 있습니다:

자주 발생하는 오류와 해결책

오류 1: "API Key가 유효하지 않습니다" 오류

이 오류는 API 키가 잘못되었거나 만료된 경우에 발생합니다.

# 해결 방법

1. HolySheep AI 대시보드에서 새로운 API 키 발급


2. 기존 키가 만료되지 않았는지 확인


3. 키를 복사할 때 앞뒤 공백이 포함되지 않도록 주의



잘못된 예시 (공백 포함)

API_KEY="  YOUR_HOLYSHEEP_API_KEY  "


올바른 예시

API_KEY="YOUR_HOLYSHEEP_API_KEY"


Node.js에서 올바르게 사용

const response = await fetch('https://api.holysheep.ai/v1/chat/completions', {
  headers: {
    'Authorization': Bearer ${process.env.API_KEY},
    'Content-Type': 'application/json'
  }
});

오류 2: "규칙 파일이 로드되지 않습니다" 오류

규칙 파일 경로가 잘못되었거나 파일 형식이 맞지 않는 경우 발생합니다.

# 해결 방법

1. 파일 경로 확인 (프로젝트 루트 기준)


올바른 구조:


project-root/


  └── .cursor/


      └── rules/


          └── my-rule.mdc



2. .mdc 파일의 첫 줄은 반드시 #으로 시작하는 제목


올바른 예시:


# 내 커스텀 규칙


## 첫 번째 규칙


content...



3. 파일 인코딩 확인 (UTF-8로 저장)


VS Code에서 우측 하단 인코딩이 "UTF-8"인지 확인



4. 파일 이름에 특수문자나 공백 사용 금지


잘못된 예: "my rule.mdc", "규칙@#$%.mdc"


올바른 예: "my-rule.mdc", "coding-style.mdc"

오류 3: "Connection timeout" 또는 네트워크 오류

네트워크 연결 문제로 HolySheep AI API에 접근할 수 없는 경우입니다.

# 해결 방법

1. 네트워크 연결 상태 확인

ping api.holysheep.ai


2. 프록시 설정 확인 (회사망 사용 시)


환경변수 설정

export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"


3. Node.js에서 타임아웃 설정 추가

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 30000);

const response = await fetch('https://api.holysheep.ai/v1/chat/completions', {
  signal: controller.signal,
  method: 'POST',
  headers: {
    'Authorization': Bearer ${process.env.API_KEY},
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(requestData)
});

clearTimeout(timeout);


4. 방화벽/안티바이러스가 요청을 차단하는지 확인


HolySheep AI 도메인을 화이트리스트에 추가

오류 4: "Rate limit 초과" 오류

요청 횟수가 너무 많아서 일시적으로 제한된 경우입니다.

# 해결 방법

1. 요청 사이에 딜레이 추가

async function delayedRequest(data) {
  await new Promise(resolve => setTimeout(resolve, 1000)); // 1초 대기
  return await sendToAPI(data);
}


2. 재시도 로직 구현 (지수적 백오프)

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => 
        setTimeout(resolve, Math.pow(2, i) * 1000)
      );
    }
  }
}


3. HolySheep AI 대시보드에서 사용량 확인 및 플랜 업그레이드


대시보드: https://www.holysheep.ai/dashboard

마무리하며

Cursor Rules 커스텀 규칙을 잘 설정하면 AI 협업 개발의 품질과 효율성을 크게 높일 수 있습니다. HolySheep AI의 다양한 모델을 상황에 맞게 활용하면 비용도 최적화할 수 있어요.

저의 경험상, 처음에는 간단한 규칙부터 시작해서 점점 복잡하게 확장해 나가는 것이 좋습니다. 프로젝트 특성에 맞는 규칙을 직접 만들어 보세요!

궁금한 점이 있으면 HolySheep AI 문서나 커뮤니티를 활용해 주세요. Happy coding!

👉 HolySheep AI 가입하고 무료 크레딧 받기

관련 리소스

관련 문서