Metadata-Version: 2.4
Name: agrules
Version: 0.3.0
Summary: 통합 에이전트 규칙 동기화 도구 - 하나의 소스에서 모든 AI 코딩 도구 규칙 생성
Author: Jinwoo
License-Expression: MIT
Project-URL: Homepage, https://github.com/JINWOO-J/agent-rules
Project-URL: Repository, https://github.com/JINWOO-J/agent-rules
Project-URL: Issues, https://github.com/JINWOO-J/agent-rules/issues
Keywords: ai,coding,agent,cursor,kiro,claude,rules
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# agrules

[![PyPI version](https://badge.fury.io/py/agrules.svg)](https://pypi.org/project/agrules/)
[![Python](https://img.shields.io/pypi/pyversions/agrules.svg)](https://pypi.org/project/agrules/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

하나의 소스(`content/agent-rules/`)에서 모든 AI 코딩 도구에 맞는 규칙 파일을 자동 생성합니다.

```
content/
  ├── agent-rules/         ← 원본 규칙 소스 (Single Source of Truth)
  │   ├── ai-coding-dx-agent.md
  │   ├── frontend-agent.md
  │   ├── database-agent.md
  │   └── ...
  ├── cursor-agents/       ← Cursor 전용 커스텀 서브에이전트 소스
  │   └── agent-rules-manager.md
  ├── skills/              ← 스킬 소스 (55개)
  ├── commands/            ← 슬래시 커맨드 소스 (24개)
  ├── prompts/             ← 프롬프트 소스 (5개)
  └── coding-rules/        ← 코딩 규칙 소스 (언어별)

        ↓  agrules

.cursor/rules/*.mdc        ← Cursor 규칙 (파일 패턴 기반 자동 적용)
.cursor/agents/*.md        ← Cursor 서브에이전트 (AI 위임 호출용)
.kiro/agents/*.json        ← Kiro (커스텀 에이전트)
.claude/rules/*.md         ← Claude Code 규칙
.claude/commands/*.md      ← Claude Code 슬래시 커맨드 (스킬+커맨드+프롬프트)
CLAUDE.md                  ← Claude Code (summary)
AGENTS.md                  ← Google Jules
.windsurfrules             ← Windsurf
.clinerules                ← Cline / Roo Code
```

## Agent Rules vs Cursor Subagents

| 구분 | Agent Rules (규칙) | Cursor Subagents (서브에이전트) |
|------|-------------------|--------------------------------|
| **적용 방식** | 파일 패턴에 따라 자동 적용 | AI가 위임하여 호출하는 독립 에이전트 |
| **출력 경로** | `.cursor/rules/*.mdc` | `.cursor/agents/*.md` |
| **소스** | `content/agent-rules/*.md` | `content/agent-rules/*.md` + `content/cursor-agents/*.md` |
| **생성** | 프리셋 기반 에이전트 → 규칙 파일 | 동일 소스에서 자동 변환 + 커스텀 추가 |

**핵심:** `content/agent-rules/*.md` 한 소스에서 규칙과 서브에이전트 **양쪽 모두** 자동 생성됩니다. `content/cursor-agents/`에는 규칙에 없는 전용 커스텀 서브에이전트(예: agent-rules-manager)를 보관합니다.

## Installation

### PyPI 패키지 설치 (권장)

```bash
pip install agrules
```

### 개발자용 로컬 설치

```bash
git clone https://github.com/JINWOO-J/agent-rules.git
cd agent-rules
pip install -e .
```

## Quick Start

```bash
# 1. 프리셋 선택 후 실행
agrules fullstack

# 2. 특정 도구만
agrules fullstack --tools cursor,claude

# 3. 에이전트 + 스킬 + 커맨드 + 프롬프트 모두 생성
agrules fullstack --all-content

# 4. 다른 프로젝트 경로에 생성
agrules fullstack --dir /path/to/project

# 5. 홈 디렉토리에 글로벌 설치
agrules fullstack --global

# 6. 코딩 규칙 설치 (언어별)
agrules install-rules typescript python
```

## Usage

```
agrules <preset> [options]
```

| 옵션 | 설명 | 기본값 |
|------|------|--------|
| `<preset>` | 프리셋 이름 또는 `all` / `list` | (필수) |
| `--tools <list>` | 대상 도구 (쉼표 구분) | `all` |
| `--dir <path>` | 출력 프로젝트 경로 | `.` (현재 디렉토리) |
| `--global` | 홈 디렉토리에 글로벌 설치 | - |
| `--dry-run` | 실제 파일 생성 없이 미리보기 | - |
| `--clean` | 기존 생성 파일 삭제 후 재생성 | - |
| `--always-load` | Claude: paths 제한 없이 전체 에이전트 항상 로드 | - |
| `--skills` | 스킬 파일도 함께 생성 | - |
| `--prompts` | 프롬프트 파일도 함께 생성 | - |
| `--commands` | 커맨드 파일도 함께 생성 | - |
| `--all-content` | 에이전트 + 스킬 + 프롬프트 + 커맨드 모두 생성 | - |

### 명령 (Commands)

| 명령 | 설명 |
|------|------|
| `list` | 프리셋 목록 |
| `list-agents` | 전체 에이전트 목록 |
| `list-skills` | 전체 스킬 목록 |
| `list-prompts` | 전체 프롬프트 목록 |
| `list-commands` | 전체 커맨드 목록 |
| `list-rules` | 사용 가능한 코딩 규칙 목록 |
| `install-rules <lang...>` | 코딩 규칙 설치 (common + 언어별) |
| `status` | 배포 상태 확인 (매니페스트 기반 drift 감지) |
| `uninstall` | 관리 파일 전체 삭제 + 매니페스트 제거 |

```bash
# 프리셋 목록 보기
agrules list

# 전체 에이전트/스킬/커맨드/프롬프트 목록 보기
agrules list-agents
agrules list-skills
agrules list-commands
agrules list-prompts

# 프로젝트에 설치 (로컬)
agrules fullstack --tools cursor,claude

# 에이전트 + 스킬 + 커맨드 + 프롬프트 모두 생성
agrules fullstack --all-content

# 홈 디렉토리에 글로벌 설치 (~/.cursor, ~/.claude, ~/.kiro)
agrules fullstack --global

# Claude: 전체 에이전트 항상 로드
agrules fullstack --always-load

# dry-run으로 미리보기
agrules fullstack --dry-run

# 기존 파일 정리 후 재생성
agrules fullstack --clean

# 배포 상태 확인 / 언인스톨
agrules status
agrules uninstall

# 코딩 규칙 설치 (common + 언어별)
agrules install-rules typescript python
agrules install-rules golang --global
```

### Local vs Global

| 모드 | 명령 | 규칙 경로 | 서브에이전트 경로 | 적용 범위 |
|------|------|-----------|-------------------|-----------|
| Local (기본) | `--dir <path>` | `<project>/.cursor/rules/` | `<project>/.cursor/agents/` | 해당 프로젝트만 |
| Global | `--global` | `~/.cursor/rules/` | `~/.cursor/agents/` | 모든 프로젝트 |

Global 모드는 cursor, kiro, claude만 지원 (jules, windsurf, cline은 프로젝트 레벨 전용).

## Presets

| 프리셋 | 에이전트 수 | 주요 구성 |
|--------|-------------|-----------|
| `minimal` | 5 | DX + 리뷰 + 보안 + QA + 성능 |
| `frontend` | 11 | + 프론트엔드, i18n, UX, 시각화, 문서, 의존성 |
| `backend` | 12 | + DB, API, 이벤트, DevOps, 검색, 컴플라이언스 |
| `fullstack` | 13 | 프론트 + 백엔드 통합, i18n |
| `infra` | 11 | K8s, EKS, OKE, DevOps, 서버리스, SRE, FinOps, 모노레포 |
| `mobile` | 10 | 모바일, 애널리틱스, i18n, 의존성 |
| `data` | 10 | 데이터 파이프라인, MLOps, 시각화, 컴플라이언스 |
| `gamedev` | 7 | 게임 개발, 모노레포 |
| `web3` | 8 | 블록체인, 스마트 컨트랙트 |
| `all` | 36 | 전체 에이전트 |

프리셋별로 스킬, 프롬프트, 커맨드도 자동 구성됩니다. `--skills`, `--prompts`, `--commands` 또는 `--all-content` 옵션으로 함께 생성할 수 있습니다.

## Supported Tools

| 도구 | 키 | 출력 경로 |
|------|-----|-----------|
| Cursor IDE | `cursor` | `.cursor/rules/*.mdc` + `.cursor/agents/*.md` |
| Kiro IDE/CLI | `kiro` | `.kiro/agents/*.json` |
| Claude Code | `claude` | `CLAUDE.md` + `.claude/rules/*.md` + `.claude/commands/*.md` |
| Google Jules | `jules` | `AGENTS.md` |
| Windsurf | `windsurf` | `.windsurfrules` |
| Cline / Roo | `cline` | `.clinerules` |

## Agent Rules 목록 (36개)

### Always Apply
| 에이전트 | 설명 |
|----------|------|
| `ai-coding-dx-agent` | AI 코딩 DX — 에이전트 설정, 컨텍스트 엔지니어링, 프롬프트 패턴 |

### File-pattern Based (파일 패턴 매칭)
| 에이전트 | 설명 | 파일 패턴 |
|----------|------|------------|
| `frontend-agent` | 프론트엔드 아키텍처 | `*.tsx, *.jsx, *.vue, *.svelte` |
| `mobile-agent` | 모바일 아키텍처 | `*.swift, *.kt, *.dart` |
| `database-agent` | 데이터베이스 설계 | `*.sql, *.prisma, *.graphql` |
| `qa-agent` | QA/테스트 전략 | `*.test.*, *.spec.*` |
| `docs-agent` | 문서 작성 | `*.md, *.mdx, docs/**` |
| `devops-agent` | DevOps, CI/CD | `Dockerfile*, .github/workflows/**` |
| `kubernetes-agent` | Kubernetes 설계 | `k8s/**, helm/**` |
| `eks-agent` | Amazon EKS | `eks/**, aws/**` |
| `oke-agent` | Oracle OKE | `oke/**, oci/**` |
| `serverless-agent` | 서버리스 아키텍처 | `serverless.*, lambda/**` |
| `blockchain-agent` | 블록체인/Web3 | `*.sol, contracts/**` |
| `embedded-iot-agent` | 임베디드/IoT | `*.ino, firmware/**` |
| `gamedev-agent` | 게임 개발 | `project.godot, Assets/**` |
| `monorepo-agent` | 모노레포 | `turbo.json, nx.json` |
| `i18n-agent` | 국제화/현지화 | `locale*/**, i18n/**` |
| `data-pipeline-agent` | 데이터 파이프라인 | `dags/**, dbt/**` |
| `mlops-agent` | MLOps | `models/**, training/**` |

### Agent Requested (요청 시 활성화)
| 에이전트 | 설명 |
|----------|------|
| `security-agent` | 보안 아키텍처, OWASP, Threat Modeling |
| `reviewer-agent` | 코드 리뷰, 클린 코드, SOLID |
| `performance-agent` | 성능 최적화, 프로파일링, 캐싱 |
| `api-designer-agent` | API 설계, REST/GraphQL/gRPC |
| `refactor-agent` | 리팩토링, Code Smell, 디자인 패턴 |
| `sre-agent` | SRE, SLO/SLI, Chaos Engineering |
| `finops-agent` | FinOps, 클라우드 비용 최적화 |
| `tech-lead-agent` | 테크 리드, Sprint Planning, RFC |
| `dependency-manager-agent` | 의존성 관리, SemVer |
| `prompt-engineer-agent` | 프롬프트 엔지니어링, RAG |
| `event-driven-agent` | 이벤트 기반 아키텍처, CQRS |
| `compliance-agent` | 컴플라이언스, GDPR, SOC2 |
| `analytics-agent` | 애널리틱스, A/B 테스트 |
| `search-agent` | 검색 시스템, Elasticsearch |
| `ux-reviewer-agent` | UX 리뷰, Nielsen 휴리스틱 |
| `data-visualization-agent` | 데이터 시각화, 대시보드 |
| `developer-experience-agent` | 개발자 경험(DX), SDK/CLI 설계 |
| `deslop-agent` | AI 코드 슬롭 제거, 스타일 정리 |

## 슬래시 커맨드 목록 (24개)

프리셋별로 자동 포함되며, `--commands` 또는 `--all-content` 옵션으로 생성됩니다.
Claude Code에서는 `.claude/commands/<name>.md`로 배포되어 `/name`으로 호출 가능합니다.

### workflow
| 커맨드 | 설명 |
|--------|------|
| `/plan` | 계획 수립 — 요구사항 분석, 리스크 평가, 단계별 구현 계획 |
| `/tdd` | TDD 워크플로우 — 인터페이스→테스트→구현→리팩토링, 80%+ 커버리지 |
| `/code-review` | 코드 리뷰 — 보안, 품질, 베스트 프랙티스 종합 검토 |
| `/verify` | 검증 — 빌드, 테스트, 린트, 타입체크 종합 실행 |
| `/build-fix` | 빌드 에러 수정 — 최소한의 안전한 변경으로 점진적 수정 |
| `/refactor-clean` | 리팩토링 — 데드 코드 제거, 테스트 검증 포함 |
| `/e2e` | E2E 테스트 — Playwright 기반 테스트 생성/실행 |
| `/evolve` | 진화 — 인스팅트를 스킬/커맨드/에이전트로 클러스터링 |
| `/orchestrate` | 오케스트레이션 — 복잡한 태스크를 에이전트 순차 워크플로우로 처리 |
| `/security` | 보안 감사 — OWASP, 인젝션, 인증, 암호화 취약점 스캔 |

### testing
| 커맨드 | 설명 |
|--------|------|
| `/test-coverage` | 테스트 커버리지 — 갭 분석 및 누락 테스트 생성 (80%+ 목표) |

### docs
| 커맨드 | 설명 |
|--------|------|
| `/update-docs` | 문서 동기화 — 소스 코드 기반으로 문서 자동 생성/업데이트 |
| `/update-codemaps` | 코드맵 업데이트 — 코드베이스 구조 분석 및 아키텍처 문서화 |

### language
| 커맨드 | 설명 |
|--------|------|
| `/go-build` | Go 빌드 에러 수정 — go vet, 린터 이슈 점진적 해결 |
| `/go-review` | Go 코드 리뷰 — 관용적 패턴, 동시성 안전성, 에러 처리 |
| `/go-test` | Go TDD — 테이블 기반 테스트 우선, 80%+ 커버리지 |

### session
| 커맨드 | 설명 |
|--------|------|
| `/checkpoint` | 체크포인트 — 워크플로우 상태 저장/검증 |
| `/eval` | 평가 기반 개발 — eval 워크플로우 관리 |

### learning
| 커맨드 | 설명 |
|--------|------|
| `/learn` | 학습 — 세션 분석 후 패턴을 스킬로 추출 |
| `/instinct-export` | 인스팅트 내보내기 — 팀/프로젝트 간 공유용 |
| `/instinct-import` | 인스팅트 가져오기 — 팀원/다른 소스에서 임포트 |
| `/instinct-status` | 인스팅트 상태 — 학습된 인스팅트와 신뢰도 표시 |
| `/skill-create` | 스킬 생성 — git 히스토리에서 코딩 패턴 추출, SKILL.md 생성 |

### utility
| 커맨드 | 설명 |
|--------|------|
| `/setup-pm` | 패키지 매니저 설정 — npm/pnpm/yarn/bun 선택 및 구성 |

## 스킬 목록 (55개)

프리셋별로 자동 포함되며, `--skills` 또는 `--all-content` 옵션으로 생성됩니다.
Claude Code에서는 `.claude/commands/<name>.md`로 배포됩니다.

전체 스킬 목록 펼치기

| 스킬 | 설명 |
|------|------|
| `code-review` | 코드 리뷰 절차 — 체크리스트, 심각도, 피드백 |
| `bug-analysis` | 버그 분석 — 근본 원인 조사 워크플로우 |
| `feature-implementation` | 기능 구현 — 스펙→코드→테스트 절차 |
| `pr-creation` | PR 작성 — 제목, 설명, 리뷰 가이드 베스트 프랙티스 |
| `refactor-safely` | 안전한 리팩토링 — 회귀 방지 패턴 |
| `api-design` | REST API 설계 패턴 — 리소스 네이밍, 상태 코드, 페이지네이션 |
| `backend-patterns` | 백엔드 아키텍처 패턴 — API 설계, DB 최적화 |
| `clickhouse-io` | ClickHouse 데이터베이스 패턴 — 쿼리 최적화, 분석 |
| `coding-standards` | 범용 코딩 표준 — TypeScript/JavaScript/React/Node.js |
| `configure-ecc` | ECC 인터랙티브 설치 — 스킬/규칙 선택 설치 |
| `content-hash-cache-pattern` | SHA-256 콘텐츠 해시 기반 캐싱 패턴 |
| `continuous-learning` | 자동 패턴 추출 — Claude Code 세션에서 스킬 학습 |
| `continuous-learning-v2` | 인스팅트 기반 학습 — 후크 관찰, 신뢰도 스코어링 |
| `cost-aware-llm-pipeline` | LLM API 비용 최적화 — 모델 라우팅, 예산 추적 |
| `cpp-coding-standards` | C++ 코딩 표준 — C++ Core Guidelines 기반 |
| `cpp-testing` | C++ 테스팅 — GoogleTest/CTest, 커버리지, 새니타이저 |
| `database-migrations` | 데이터베이스 마이그레이션 — 스키마 변경, 롤백, 제로 다운타임 |
| `deployment-patterns` | 배포 워크플로우 — CI/CD, 컨테이너화, 롤백 전략 |
| `django-patterns` | Django 아키텍처 패턴 — DRF, ORM, 캐싱 |
| `django-security` | Django 보안 — 인증, 인가, CSRF, SQL 인젝션 방지 |
| `django-tdd` | Django 테스트 전략 — pytest-django, TDD, factory_boy |
| `django-verification` | Django 검증 루프 — 마이그레이션, 린트, 테스트, 보안 스캔 |
| `docker-patterns` | Docker/Compose 패턴 — 로컬 개발, 보안, 네트워킹 |
| `e2e-testing` | Playwright E2E 테스팅 — POM, CI/CD 통합 |
| `eval-harness` | 평가 프레임워크 — eval 기반 개발(EDD) 원칙 |
| `foundation-models-on-device` | Apple FoundationModels — 온디바이스 LLM, iOS 26+ |
| `frontend-patterns` | 프론트엔드 패턴 — React, Next.js, 상태 관리 |
| `golang-patterns` | Go 관용 패턴 — 베스트 프랙티스, 견고한 Go 앱 |
| `golang-testing` | Go 테스팅 — 테이블 기반, 서브테스트, 벤치마크, 퍼징 |
| `iterative-retrieval` | 점진적 컨텍스트 검색 — 서브에이전트 컨텍스트 문제 해결 |
| `java-coding-standards` | Java 코딩 표준 — Spring Boot 서비스 |
| `jpa-patterns` | JPA/Hibernate 패턴 — 엔티티 설계, 쿼리 최적화 |
| `liquid-glass-design` | iOS 26 Liquid Glass — 동적 유리 머티리얼, SwiftUI |
| `nutrient-document-processing` | Nutrient DWS API — 문서 변환, OCR, 추출 |
| `postgres-patterns` | PostgreSQL 패턴 — 쿼리 최적화, 스키마 설계, 인덱싱 |
| `project-guidelines-example` | 프로젝트 가이드라인 예시 — 스킬 템플릿 |
| `python-patterns` | Python 관용 패턴 — PEP 8, 타입 힌트 |
| `python-testing` | Python 테스팅 — pytest, TDD, 픽스처, 모킹 |
| `regex-vs-llm-structured-text` | 정규식 vs LLM 결정 프레임워크 |
| `search-first` | 리서치 우선 워크플로우 — 코딩 전 기존 도구/패턴 탐색 |
| `security-review` | 보안 리뷰 — 인증, 사용자 입력, 시크릿, API 보안 |
| `security-scan` | 보안 스캔 — .claude/ 설정 취약점, MCP 서버 검사 |
| `skill-stocktake` | 스킬 감사 — Quick Scan/Full Stocktake 모드 |
| `springboot-patterns` | Spring Boot 패턴 — REST API, 레이어드 서비스 |
| `springboot-security` | Spring Security — 인증/인가, 검증, CSRF |
| `springboot-tdd` | Spring Boot TDD — JUnit 5, Mockito, Testcontainers |
| `springboot-verification` | Spring Boot 검증 루프 — 빌드, 정적 분석, 테스트 |
| `strategic-compact` | 전략적 컴팩션 — 논리적 간격에서 컨텍스트 압축 |
| `swift-actor-persistence` | Swift Actor 기반 영속성 — 스레드 안전 캐시 |
| `swift-concurrency-6-2` | Swift 6.2 Concurrency — 기본 싱글스레드, @concurrent |
| `swift-protocol-di-testing` | Swift 프로토콜 DI — 목 파일시스템, 네트워크 테스팅 |
| `swiftui-patterns` | SwiftUI 패턴 — @Observable 상태 관리, 뷰 조합 |
| `tdd-workflow` | TDD 워크플로우 — 테스트 우선, 80%+ 커버리지 |
| `verification-loop` | 종합 검증 시스템 — 빌드/테스트/린트 루프 |
| `visa-doc-translate` | 비자 문서 번역 — 이미지→영어 번역→이중 언어 PDF |

### 프리셋별 스킬 구성

| 프리셋 | 스킬 |
|--------|------|
| `minimal` | code-review, coding-standards, security-review |
| `frontend` | code-review, feature-implementation, pr-creation, coding-standards, frontend-patterns, e2e-testing, tdd-workflow |
| `backend` | code-review, bug-analysis, feature-implementation, pr-creation, coding-standards, backend-patterns, api-design, security-review, postgres-patterns, tdd-workflow, database-migrations |
| `fullstack` | code-review, bug-analysis, feature-implementation, pr-creation, refactor-safely, coding-standards, frontend-patterns, backend-patterns, api-design, security-review, tdd-workflow, e2e-testing, deployment-patterns, docker-patterns, database-migrations |
| `infra` | code-review, pr-creation, coding-standards, docker-patterns, deployment-patterns, security-review |
| `mobile` | code-review, feature-implementation, pr-creation, coding-standards, tdd-workflow, swift-actor-persistence, swiftui-patterns |
| `data` | code-review, bug-analysis, pr-creation, coding-standards, python-patterns, postgres-patterns, database-migrations |
| `gamedev` | code-review, feature-implementation, pr-creation, coding-standards, tdd-workflow |
| `web3` | code-review, bug-analysis, pr-creation, coding-standards, security-review |

## 프롬프트 목록 (5개)

프리셋별로 자동 포함되며, `--prompts` 또는 `--all-content` 옵션으로 생성됩니다.

| 프롬프트 | 카테고리 | 설명 |
|----------|----------|------|
| `strict-coder` | system | 엄격한 코딩 표준 시스템 프롬프트 |
| `helpful-reviewer` | system | 공감적 리뷰어 시스템 프롬프트 |
| `bug-report-analysis` | templates | 버그 분석 요청 템플릿 |
| `feature-spec` | templates | 기능 스펙 작성 템플릿 |
| `plan-code-test` | chains | 계획→구현→테스트 체인 워크플로우 |

## 코딩 규칙 (Coding Rules)

`install-rules` 명령으로 언어별 코딩 규칙을 `~/.claude/rules/coding-rules/`에 설치합니다.
common 규칙은 항상 함께 설치됩니다.

```bash
# 사용 가능한 규칙 목록
agrules list-rules

# 설치 (common + 지정 언어)
agrules install-rules typescript python
agrules install-rules golang --global
agrules install-rules swift --dry-run
```

| 언어 | 포함 규칙 |
|------|-----------|
| `common` (항상 설치) | agents, coding-style, development-workflow, git-workflow, hooks, patterns, performance, security, testing |
| `typescript` | coding-style, hooks, patterns, security, testing |
| `python` | coding-style, hooks, patterns, security, testing |
| `golang` | coding-style, hooks, patterns, security, testing |
| `swift` | coding-style, hooks, patterns, security, testing |

## 커스텀 에이전트 추가

### 방법 1: 로컬 프로젝트에 추가

1. 프로젝트에 `content/agent-rules/` 디렉토리 생성
2. `content/agent-rules/my-custom-agent.md` 파일 작성
3. `agrules` 실행 시 자동 인식

```markdown
---
name: my-custom
description: "My custom agent description"
version: "1.0.0"
tags: ["custom"]
---

# My Custom Agent

에이전트 규칙 내용...
```

### 방법 2: 패키지 확장 (개발자용)

1. 저장소 클론 및 개발 모드 설치
```bash
git clone https://github.com/JINWOO-J/agent-rules.git
cd agent-rules
pip install -e .
```

2. `content/agent-rules/my-custom-agent.md` 추가 (frontmatter에 메타데이터 포함)
3. 원하는 프리셋에 에이전트 이름 추가 (`__main__.py`의 `PRESETS`)

메타데이터는 frontmatter에서 자동 스캔됩니다 (`AGENT_META` 하드코딩 불필요):

```markdown
---
name: my-custom
description: "My custom agent description"
short_desc: "Custom agent for X"
cursor_globs: "*.custom"
claude_paths: "custom/**"
---
```

## Cursor 서브에이전트

Cursor 도구 선택 시 `agrules`가 다음을 자동 수행합니다:

1. **규칙 → 서브에이전트 변환:** 프리셋에 포함된 `content/agent-rules/*.md`를 `.cursor/agents/*.md` 형식으로 변환하여 배포
2. **커스텀 서브에이전트 배포:** `content/cursor-agents/*.md`를 그대로 `.cursor/agents/`에 복사

`--global` 사용 시 `~/.cursor/agents/`에 설치되어 모든 프로젝트에서 사용 가능합니다.

| 서브에이전트 | 소스 | 설명 |
|--------------|------|------|
| (프리셋 에이전트) | `content/agent-rules/*.md` | 규칙과 동일 내용, 서브에이전트 형식으로 자동 변환 |
| `agent-rules-manager` | `content/cursor-agents/agent-rules-manager.md` | agrules 프로젝트 관리 전문가 (규칙 생성/편집/동기화/확장) |

서브에이전트 파일 형식 (`content/cursor-agents/` 또는 변환 결과):

```markdown
---
name: my-agent
description: 에이전트 설명 (Cursor가 위임 판단에 사용)
---

시스템 프롬프트 내용...
```

## 배포 매니페스트

`agrules`는 실행 시 `.agrules.lock` 파일을 생성하여 배포 상태를 추적합니다.

```bash
# 현재 배포 상태 확인 (파일 drift 감지 포함)
agrules status

# 관리 파일 전체 삭제 + 매니페스트 제거
agrules uninstall
agrules uninstall --dry-run  # 미리보기
```

매니페스트에 기록되는 정보:
- 동기화 시점, 패키지 버전, 프리셋, 도구 목록
- 배포된 파일 경로 + SHA-256 해시 (drift 감지용)
- 에이전트, 스킬, 커맨드, 프롬프트 목록

`--clean` 옵션은 매니페스트 기반으로 관리 파일만 삭제합니다 (수동 추가 파일은 보존).

## 환경변수

| 변수 | 설명 | 기본값 |
|------|------|--------|
| `AGENT_RULES_DIR` | 규칙 소스 디렉토리 경로 | `./content/agent-rules` (로컬 우선) |
| `CURSOR_AGENTS_DIR` | Cursor 서브에이전트 소스 디렉토리 경로 | `./content/cursor-agents` (로컬 우선) |
| `SKILLS_DIR` | 스킬 소스 디렉토리 경로 | `./content/skills` (로컬 우선) |
| `PROMPTS_DIR` | 프롬프트 소스 디렉토리 경로 | `./content/prompts` (로컬 우선) |
| `COMMANDS_DIR` | 커맨드 소스 디렉토리 경로 | `./content/commands` (로컬 우선) |
| `CODING_RULES_DIR` | 코딩 규칙 소스 디렉토리 경로 | `./content/coding-rules` (로컬 우선) |

패키지는 다음 순서로 규칙 파일을 검색합니다:
1. 현재 디렉토리의 `content/agent-rules/` (로컬 커스텀 규칙)
2. 패키지 내부 번들 데이터 (기본 규칙)

## 프로젝트 구조

```
agent-rules/
├── content/                      ← 콘텐츠 소스 루트
│   ├── agent-rules/              ← 원본 규칙 소스 (36개 .md)
│   ├── cursor-agents/            ← Cursor 전용 서브에이전트
│   ├── skills/                   ← 스킬 소스 (55개 .md)
│   ├── commands/                 ← 슬래시 커맨드 소스 (24개 .md)
│   ├── prompts/                  ← 프롬프트 소스 (5개 .md)
│   │   ├── system/               ← 시스템 프롬프트
│   │   ├── templates/            ← 요청 템플릿
│   │   └── chains/               ← 체인 워크플로우
│   └── coding-rules/             ← 코딩 규칙 소스 (언어별)
│       ├── common/               ← 공통 규칙 (항상 설치)
│       ├── typescript/
│       ├── python/
│       ├── golang/
│       └── swift/
├── src/
│   └── agrules/
│       ├── __init__.py
│       └── __main__.py           ← 메인 로직 (CLI 진입점)
├── tests/
├── pyproject.toml
├── Makefile
├── README.md
└── LICENSE
```

> `src/agrules/data/`는 빌드 시 자동 생성됩니다 (`make build`).
> Git에는 포함되지 않습니다.

## Alternative: Manual Setup

PyPI 패키지 대신 수동으로 설정하려면:

```bash
# 1. 저장소 클론
git clone https://github.com/JINWOO-J/agent-rules.git

# 2. 프로젝트에 복사
cp -r agent-rules/src/agrules/data/content/agent-rules /path/to/your-project/content/
cp -r agent-rules/src/agrules/data/content/cursor-agents /path/to/your-project/content/

# 3. Python 모듈로 직접 실행
python -m agrules fullstack
```

## License

MIT
