agrules

agrules

하나의 소스(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

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

Installation

PyPI 패키지 설치 (권장)

pip install agrules

개발자용 로컬 설치

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

Quick Start

# 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]

명령 (Commands)

# 프리셋 목록 보기
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

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

Presets

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

Supported Tools

Agent Rules 목록 (36개)

Always Apply

File-pattern Based (파일 패턴 매칭)

Agent Requested (요청 시 활성화)

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

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

workflow

testing

docs

language

session

learning

utility

스킬 목록 (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

프리셋별 스킬 구성

프롬프트 목록 (5개)

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

코딩 규칙 (Coding Rules)

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

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

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

커스텀 에이전트 추가

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

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

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

# My Custom Agent

에이전트 규칙 내용...

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

1. 저장소 클론 및 개발 모드 설치

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 하드코딩 불필요):

---
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/cursor-agents/ 또는 변환 결과):

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

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

배포 매니페스트

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

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

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

매니페스트에 기록되는 정보:

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

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

환경변수

패키지는 다음 순서로 규칙 파일을 검색합니다:

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 패키지 대신 수동으로 설정하려면:

# 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