AI 에이전트, 커스텀 규칙(Rules)과 MCP(Model Context Protocol)

 

AI 에이전트 확장 가이드

규칙(Rules) & MCP 아키텍처 설계와 디렉토리 구조 비교

1. 확장 개념 핵심 비교 (Concepts Comparison)

규칙, 스킬, MCP는 에이전트 기능을 정의하는 세 가지 다른 추상화 레이어입니다.

구분	규칙 (Rules)	스킬 (Skills)	MCP (Model Context Protocol)
쉽게 말해 (비유)	프로젝트의 "헌법과 개발 원칙" (상시 켜짐)	특정 기술/도메인 "가이드북" (상황별 동적 로드)	에이전트가 쓰는 "외부 도구/앱" (런타임 연동)
동작 원리 (Mechanism)	세션 시작 시 에이전트 콘텍스트에 상시 자동 주입됨	특정 키워드/디렉토리 감지 시 지침을 동적으로 주입	외부 자원(DB, API) 접근 필요 시 에이전트가 도구 직접 호출
공유/호환 방식 (Sharing)	각 에이전트마다 전용 설정 파일 생성하여 동기화	에이전트 고유 기능 (타 에이전트는 규칙에 내포하여 사용)	프로토콜 표준이므로 서버 코드 변경 없이 100% 호환

2. 한눈에 보는 에이전트별 구성 디렉토리 비교

개념적 모델은 같지만 에이전트 도구별로 참조하는 네임스페이스와 파일 경로가 다릅니다.

개념 레이어	Antigravity	Cursor	Claude Code	Codex
상시 규칙 (Rules)	.agents/AGENTS.md	.cursorrules	CLAUDE.md	AGENTS.md
모듈형/동적 규칙	-	.cursor/rules/*.mdc	.claude/rules/*.md	.codex/rules/*.rules
온디맨드 스킬 (Skills)	.agents/skills/	.mdc 파일 내 globs 매칭	.claude/skills/	외부 스킬 바인딩
외부 도구 (MCP)	mcp_config.json	.cursor/mcp.json	~/.claude.json	.codex/config.toml

3. Antigravity 설정 및 구조

Google DeepMind에서 설계한 컴플라이언스 및 도메인 지식 최적화 에이전트입니다. 비표준 스킬 경로 지정을 위해 skills.json을 사용합니다.

디렉토리 트리

📦 프로젝트 루트
 ┗ 📂 .agents/                       # Antigravity 로컬 설정 루트
   ┣ 📄 AGENTS.md                    # [Rules] 프로젝트 전용 상시 규칙
   ┣ 📄 skills.json                  # [Skills] 비표준 스킬 경로 등록 설정 파일
   ┗ 📂 skills/                      # [Skills] 특정 태스크용 동적 지침 폴더
     ┗ 📂 sto-helper/
       ┗ 📄 SKILL.md                 # Frontmatter 헤더를 갖춘 마크다운

4. Cursor 설정 및 구조

최신 Cursor는 legacy .cursorrules 대신 개별 규칙을 모듈화하여 필요한 파일군(globs)에만 적용하는 .mdc 파일 방식을 권장합니다.

디렉토리 트리

📦 프로젝트 루트
 ┣ 📂 .cursor/
 ┃ ┣ 📄 mcp.json                     # [MCP] 프로젝트 레벨 MCP 도구 선언
 ┃ ┗ 📂 rules/                       # [Rules] 최신 모듈형 규칙 폴더
 ┃   ┗ 📄 ReactComponent.mdc         # 대상 파일 패턴(globs) 지정 마크다운 규칙
 ┗ 📄 .cursorrules                   # [Rules] (Legacy) 프로젝트 전역 룰

MDC 규칙 예시

---
description: React 컴포넌트 개발 시 규칙
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

# React Rules
- Always use functional components.

5. Claude Code 설정 및 구조

Anthropic 공식 CLI 도구입니다. CLAUDE.md로 빌드 및 테스트를 관리하며, 개별 태스크 지침은 .claude/skills/에서 온디맨드 스킬로 정의합니다.

디렉토리 트리

📦 프로젝트 루트
 ┣ 📂 .claude/                       # Claude Code 로컬 설정 디렉토리
 ┃ ┣ 📂 rules/                       # [Rules] 모듈화된 규칙 폴더 (@참조 지원)
 ┃ ┃ ┗ 📄 api-rules.md
 ┃ ┗ 📂 skills/                      # [Skills] 온디맨드 로드용 개별 스킬 폴더
 ┃   ┗ 📂 deploy-script/
 ┃     ┗ 📄 SKILL.md                 # YAML Frontmatter 헤더 가이드
 ┗ 📄 CLAUDE.md                      # [Rules] 빌드/테스트 규칙 문서

6. Codex 설정 및 구조

실행 샌드박스와 디렉토리 레벨 상속 구조를 지닌 백엔드 파이프라인 지향 에이전트입니다.

디렉토리 트리

📦 프로젝트 루트
 ┣ 📂 .codex/
 ┃ ┣ 📄 config.toml                  # [Config] 모델 및 샌드박스 환경 설정
 ┃ ┗ 📂 rules/
 ┃   ┗ 📄 default.rules              # [Rules] 쉘 실행 정책 파일
 ┗ 📄 AGENTS.md                      # [Rules] 프로젝트 상시 규칙

7. 실무 적용 구체적 설정 파일 예시

앞서 다룬 규칙, 스킬, MCP의 실제 프로젝트 셋업 예시 코드입니다.

① 규칙 (Rules) 실제 내용: TOKIT STO 개발 원칙

프로젝트 로컬 AGENTS.md에 추가되어 에이전트가 항상 준수하는 코어 개발 규칙입니다.

# 🏛️ TOKIT STO — AI Agent Instructions & Guidelines

## 📌 1. Core Principles (핵심 원칙)
1. **불변성 유지 (Immutability)**:
   - DTO/객체는 record 구조를 사용하여 불변으로 설계합니다.
2. **테스트 주도 개발 (TDD, Coverage 80%+)**:
   - 단위/통합/E2E 테스트 작성을 필수로 진행합니다.

## ⚡ 2. 핵심 비즈니스 도메인 아키텍처 규칙
1. **멱등성 보장 (Idempotency Key)**:
   - 쓰기(CUD) 요청 시 HTTP 헤더에 `X-Idempotency-Key` (UUIDv4) 검증 로직 필수.
2. **결산 및 배당 분배 동시성 제어 (Pessimistic Lock)**:
   - 예치금 차감/홀딩 연산 시 `SELECT ... FOR UPDATE` 비관적 락 전략 적용.
3. **가스비 대납 메타 트랜랙션 (Gasless Relayer)**:
   - `personal_sign` 서명 복원 후 `fromAddress`와 대소문자 구분 없이 매칭 검증.

② 스킬 (Skills) 파일 예시: Solidity 스마트 컨트랙트 헬퍼

SKILL.md 파일로 저장되어 Solidity 관련 태스크 수행 시 동적으로 로드되는 가이드라인입니다.

---
name: solidity-contract-helper
description: Solidity 컨트랙트 최적화 및 ERC-1400 토큰증권 구현 요청 시 로드됩니다.
---

# Solidity 최적화 및 토큰 지침
1. 모든 컨트랙트는 OpenZeppelin의 표준을 기본 준수합니다.
2. `view`와 `pure` 키워드를 엄격하게 사용하여 가스비를 최소화하세요.
3. ERC-1400의 파티션 분할을 활용해 `transferByPartition` 함수를 통해 화이트리스트 검증을 통과하도록 유도합니다.

③ MCP 서버 실제 코드 예시: Slack Notifier

에이전트가 외부 슬랙 채널로 직접 메시지를 쏠 수 있도록 확장해 주는 물리 도구 코드의 일부입니다.

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/transport.js";

const server = new Server({
  name: "slack-notifier",
  version: "1.0.0"
}, {
  capabilities: { tools: {} }
});

// 도구 스키마 선언
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: "send_slack_message",
    description: "개발 완료 알림 메시지를 슬랙으로 전송합니다.",
    inputSchema: {
      type: "object",
      properties: {
        message: { type: "string" }
      },
      required: ["message"]
    }
  }]
}));

8. 효율적인 규칙 공유 방법 (자동화)

에이전트마다 요구하는 규칙 파일 이름이 달라 한 번에 관리하기 어려울 경우, 심볼릭 링크를 사용하면 관리가 편리해집니다.

# 프로젝트 루트에서 마스터 룰 연결 스크립트 실행
ln -sf COMMON_RULES.md .cursorrules
ln -sf COMMON_RULES.md CLAUDE.md
mkdir -p .agents
ln -sf ../COMMON_RULES.md .agents/AGENTS.md

보안 주의 사항

MCP 연동 설정 파일(mcp.json)에 직접 비밀번호나 API Key를 하드코딩하여 Git에 올리지 마세요. 로컬 환경 변수(`env` 객체)를 통해서 안전하게 주입받도록 구성해야 유출을 예방할 수 있습니다.