Creatrip Agent Rules Builder

여러 AI 코딩 에이전트를 위한 통합 규칙 변환 도구

개요

하나의 마스터 Markdown 파일을 작성하면 Cursor, Windsurf, Claude 등 각 AI 에이전트가 요구하는 포맷으로 자동 변환해주는 CLI 도구입니다.

특징

• ✨ 단일 소스: 하나의 파일로 모든 AI 에이전트 규칙 관리
• 🚀 간단한 사용법: 단 하나의 명령어로 모든 변환 처리
• 📝 JSONC 설정: 주석이 있는 JSON으로 각 에이전트별 설정 가능
• 🎨 예쁜 출력: 색상과 이모지로 명확한 진행 상태 표시
• ✅ 완전한 테스트: 단위 테스트와 통합 테스트 포함

설치

NPM 패키지 설치

# 글로벌 설치 (권장)
npm install -g creatrip-agent-rules-builder

프로젝트 로컬 설치

npm install --save-dev creatrip-agent-rules-builder

주요 명령어

CI (스마트 동기화) 🎯

# 자동으로 검증하고 필요시 빌드 실행
agent-rules ci

# 재귀 모드
agent-rules ci -r

# JSON 출력 (CI 파이프라인용)
agent-rules ci --json

동작 방식:

• ✅ 이미 동기화됨 → 성공 (exit 0)
• 🔨 빌드 필요 → 자동 빌드 → 성공 (exit 0)
• ❌ 수동 편집 감지 → 실패 (exit 1)

사용법

1. 규칙 파일 작성

AGENTS.md 파일을 생성하고 AI 규칙을 작성하세요:

# AI Coding Rules

## Communication Rules
- 항상 한국어로 대답하기
- 코드 예제는 TypeScript 우선 사용
- 복잡한 문제는 단계별로 나누어 설명

## Code Style
- 변수명은 camelCase 사용
- 함수명은 동사로 시작
- 타입은 명시적으로 선언

\```jsonc agent-rules-config
{
  // Cursor 설정
  "cursor": {
    "globs": ["*.tsx", "*.ts", "*.jsx", "*.js"],
    "description": "프로젝트별 AI 코딩 규칙"
  },
  "windsurf": {},
  "claude": {}
}
\```

2. 변환 실행

# 기본 사용법 (AGENTS.md 사용)
agent-rules build

# 커스텀 파일 지정
agent-rules build --file MY_RULES.md
agent-rules build -f custom-rules.md

# 재귀 빌드 (하위 디렉토리의 모든 AGENTS.md 처리)
agent-rules build --recursive
agent-rules build -r

# 재귀 검증 (하위 디렉토리의 모든 AGENTS.md 검증)
agent-rules verify --recursive
agent-rules verify -r

# 도움말
agent-rules --help

3. 일관성 검증

생성된 파일들이 원본(AGENTS.md)과 동기화되어 있는지 확인:

# 기본 검증
agent-rules verify

# JSON 출력 (CI 통합용)
agent-rules verify --json

# 조용한 모드 (종료 코드만)
agent-rules verify --quiet

# 재귀 모드 (하위 디렉토리 모두 검증)
agent-rules verify -r
agent-rules verify --recursive

검증 결과 예시

단일 디렉토리 모드:

# 모든 파일이 동기화된 경우
✓ cursor: 동기화됨
✓ windsurf: 동기화됨
✓ claude: 동기화됨
✓ 모든 파일이 동기화되어 있습니다
✓ 모든 에이전트 검증 성공

# AGENTS.md 수정 후 build 안 한 경우
✗ cursor: 내용 불일치
✗ windsurf: 내용 불일치
✗ claude: 내용 불일치
→ 패턴 감지: 모든 파일이 오래됨
→ 해결방법: 'agent-rules build' 실행

# 실수로 출력 파일 하나만 수정한 경우
✓ cursor: 동기화됨
✗ windsurf: 내용 불일치
✓ claude: 동기화됨
→ 패턴 감지: windsurf 파일만 불일치
→ AGENTS.md를 수정하려던 것이 아닌지 확인하세요

재귀 모드:

$ agent-rules verify -r

에이전트 규칙 일관성 검증 중...

📁 /
  ✓ cursor: 동기화됨
  ✓ windsurf: 동기화됨
  ✓ claude: 동기화됨
  ✓ 모든 파일이 동기화되어 있습니다

📁 /packages/web
  ✗ cursor: 내용 불일치
  ✗ windsurf: 내용 불일치
  ✗ claude: 내용 불일치
  → 패턴 감지: 모든 파일이 오래됨
  → 해결방법: 'agent-rules build' 실행

📁 /packages/api
  ✓ cursor: 동기화됨
  ✗ windsurf: 내용 불일치
  ✓ claude: 동기화됨
  → 패턴 감지: windsurf 파일만 불일치
  → AGENTS.md를 수정하려던 것이 아닌지 확인하세요

========================================
📊 전체 요약: 3개 위치 중 2개 불일치
✗ 검증 실패

CI/CD 통합

방법 1: CI 커맨드 사용 (권장) ✅

# GitHub Actions 예시
- name: Check and sync agent rules
  run: agent-rules ci -r
  # 자동으로:
  # - 빌드 필요하면 실행
  # - 수동 편집 있으면 실패
  # - 적절한 exit code 반환

방법 2: 수동 verify + build

- name: Build agent rules
  run: agent-rules build
  
- name: Verify consistency
  run: agent-rules verify --json

JSON 출력 형식 (통일된 스키마):

{
  "status": "fail",
  "locations": [
    {
      "path": "/project",
      "status": "fail",
      "agents": {
        "cursor": { "passed": false, "error": "content mismatch" },
        "windsurf": { "passed": true },
        "claude": { "passed": true }
      },
      "summary": { "total": 3, "passed": 2, "failed": 1 },
      "diagnosis": {
        "pattern": "single_diverged",
        "action": "review",
        "diverged": ["cursor"]
      }
    }
  ],
  "totalLocations": 1,
  "timestamp": "2024-01-01T00:00:00.000Z"
}

재귀 모드에서는 locations 배열에 여러 위치의 결과가 포함됩니다.

CI 커맨드 JSON 출력:

{
  "status": "fail",
  "summary": {
    "total": 3,
    "synced": 1,
    "autoBuild": 1,
    "needsReview": 1
  },
  "needsReview": [
    {
      "path": "/packages/api",
      "issue": "single_diverged",
      "files": ["windsurf"]
    }
  ],
  "message": "Manual review required for 1 location(s)"
}

4. 생성되는 파일

실행하면 다음 파일들이 자동으로 생성됩니다:

• .cursor/rules/rules.mdc - Cursor용 규칙 (frontmatter 포함)
• .windsurfrules - Windsurf용 규칙 (루트 디렉토리)
• CLAUDE.md - Claude용 규칙

설정 옵션

Cursor 설정

"cursor": {
  "globs": ["*.tsx", "*.ts"],        // 적용할 파일 패턴
  "description": "규칙 설명",         // 규칙 설명
  "filename": "rules",               // 파일명 (기본값: "rules")
  "alwaysApply": false               // 항상 적용 여부 (기본값: false)
}

기본 동작: 설정이 없어도 항상 frontmatter가 생성되며, 빈 값은 기본값으로 채워집니다.

재귀 빌드

모노레포나 멀티 프로젝트 환경에서 하위 디렉토리의 모든 AGENTS.md 파일을 자동으로 찾아 처리합니다.

agent-rules build --recursive

• .gitignore에 지정된 디렉토리는 자동으로 제외됩니다
• node_modules, dist, .git 등은 기본적으로 제외됩니다
• 각 AGENTS.md가 있는 디렉토리에 해당 결과물들이 생성됩니다

주의: -f와 -r 옵션은 동시에 사용할 수 없습니다.

설정 블록 규칙

• 코드 블록 언어는 jsonc 또는 json 사용
• 식별자로 agent-rules-config 필수
• 설정은 선택사항 (없어도 기본값으로 작동)

개발

요구사항

• Node.js >= 16
• TypeScript

개발 환경 설정

# 저장소 클론
git clone [email protected]:creatrip/creatrip-agent-rules-builder.git
cd creatrip-agent-rules-builder

# 의존성 설치
npm install

# 개발 모드 (watch)
npm run dev

# 빌드
npm run build

# 테스트
npm test

# 테스트 (watch 모드)
npm run test:watch

프로젝트 구조

src/
├── index.ts          # CLI 진입점
├── build.ts          # 빌드 로직
├── parser.ts         # Markdown & JSONC 파싱
├── commands/         # CLI 커맨드
│   └── verify.ts     # verify 커맨드
├── generators/       # 각 에이전트별 파일 생성기
│   ├── cursor.ts
│   ├── windsurf.ts
│   └── claude.ts
├── verifiers/        # 검증 로직
│   ├── index.ts      # 메인 검증 로직
│   ├── comparator.ts # 내용 비교 유틸리티
│   └── types.ts      # 검증 관련 타입
└── types.ts          # TypeScript 타입 정의

tests/
├── fixtures/         # 테스트용 파일들
├── parser.test.ts    # 파서 단위 테스트
├── generators.test.ts # 생성기 단위 테스트
├── verify.test.ts    # 검증 커맨드 테스트
└── integration.test.ts # 통합 테스트

라이선스

MIT

기여

Creatrip 팀 내부 프로젝트입니다.