creatrip-agent-rules-builder/README.md

Unified converter for AI coding agent rules across Cursor, Windsurf, and Claude

# Creatrip Agent Rules Builder

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

## 개요

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

## 특징

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

## 설치

### NPM 패키지 설치

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

### 프로젝트 로컬 설치

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

## 주요 명령어

### CI (스마트 동기화) 🎯
```bash
# 자동으로 검증하고 필요시 빌드 실행
agent-rules ci

# 재귀 모드
agent-rules ci -r

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

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

## 사용법

### 1. 규칙 파일 작성

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

```markdown
# 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. 변환 실행

```bash
# 기본 사용법 (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)과 동기화되어 있는지 확인:

```bash
# 기본 검증
agent-rules verify

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

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

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

#### 검증 결과 예시

**단일 디렉토리 모드:**
```bash
# 모든 파일이 동기화된 경우
✓ cursor: 동기화됨
✓ windsurf: 동기화됨
✓ claude: 동기화됨
✓ 모든 파일이 동기화되어 있습니다
✓ 모든 에이전트 검증 성공

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

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

**재귀 모드:**
```bash
$ 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 커맨드 사용 (권장) ✅**
```yaml
# GitHub Actions 예시
- name: Check and sync agent rules
  run: agent-rules ci -r
  # 자동으로:
  # - 빌드 필요하면 실행
  # - 수동 편집 있으면 실패
  # - 적절한 exit code 반환
```

**방법 2: 수동 verify + build**
```yaml
- name: Build agent rules
  run: agent-rules build
  
- name: Verify consistency
  run: agent-rules verify --json
```

**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 출력:**
```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 설정

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

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

### 재귀 빌드

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

```bash
agent-rules build --recursive
```

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

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

### 설정 블록 규칙

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

## 개발

### 요구사항

- Node.js >= 16
- TypeScript

### 개발 환경 설정

```bash
# 저장소 클론
git clone git@github.com: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 팀 내부 프로젝트입니다.