Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
이 도구는 AI 코딩 에이전트(Claude Code, Gemini CLI 등)의 다양한 설정 파일들을 심볼릭 링크를 이용해 하나의 중앙 집중식 위치로 통합 관리합니다. 이를 통해 모든 설정을 Git으로 추적하고 한 번 편집하여 여러 장치와 에이전트에 일관되게 적용할 수 있습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Claude Ecosystem의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기심볼릭 링크(symlinks)를 통해 AI 에이전트 구성을 관리하세요. 모든 설정을 하나의 git으로 추적되는 위치에 보관할 수 있습니다.
PyPI Downloads
PyPI version
Python Versions
CI
GitHub Contributors
Lines of Code
License
AI 코딩 에이전트(Claude Code, Goose, Gemini CLI, Codex CLI, Amp)의 설정 파일들을 심볼릭 링크를 통해 단일 진실 공급원(single source of truth)으로 통합합니다:
지원 대상: Claude Code, Goose, Gemini CLI, Codex CLI, Amp — 그리고 공유(Shared) 폴더 (AGENTS.md, skills)
| 에이전트 | 설정 디렉터리 | 스킬 디렉터리 |
|---|---|---|
| Amp | ~/.config/amp/ | ~/.config/agents/skills/ |
| ... |
필수 조건: Python 3.10 이상, uv
PyPI를 통해 한 번의 명령어로 설정합니다:
uvx --from ai-agent-rules ai-agent-rules setup
이 명령어는 다음 작업을 수행합니다:
ai-agent-rules (및 ai-rules 별칭)을 시스템 전체에서 사용 가능하도록 만듦설정 완료 후, 어느 디렉터리에서든 ai-agent-rules (또는 줄여서 ai-rules)를 실행할 수 있습니다.
최신 개발 코드를 얻으려면 GitHub에서 설치합니다:
uvx --from ai-agent-rules ai-agent-rules setup --github
이 명령어는 main 브랜치에서 설치하며, 향후 업데이트를 위해 GitHub 소스를 자동으로 감지합니다.
기여하거나 로컬로 개발하려면:
git clone https://github.com/wpfleger96/ai-agent-rules.git
cd ai-agent-rules
uv run ai-agent-rules install
uv run ai-agent-rules <command>를 사용하여 로컬 변경 사항을 테스트할 수 있습니다. 전역 ai-agent-rules 명령어는 설치된 버전(PyPI/GitHub)을 계속 실행합니다.
업데이트 확인 및 설치:
ai-agent-rules upgrade # 업데이트 확인 및 설치 (변경 로그 표시)
ai-agent-rules upgrade --check # 업데이트만 확인
ai-agent-rules upgrade --force # 최신 버전이라도 강제 재설치
...
ai-agent-rules setup # 일회성 설정: 심볼릭 링크(symlinks) 설치 + 시스템 전체에서 사용 가능하게 만듦
ai-agent-rules setup --github # GitHub에서 설치 (프리릴리스)
ai-agent-rules setup --profile work # 특정 프로필로 설정
...
ai-agent-rules install # 모든 에이전트 구성(configs) + 선택적 도구 설치
ai-agent-rules install --agents claude # 특정 에이전트 설치: amp, claude, codex, gemini, goose, shared
ai-agent-rules install --dry-run # 변경 사항 미리 보기
...
ai-agent-rules status # 심볼릭 링크 상태 + 선택적 도구 + 활성 프로필 확인(✓✗⚠○), 차이점 표시
ai-agent-rules diff # 구성 차이점 표시
ai-agent-rules validate # 소스 파일 존재 여부 검증
...
ai-agent-rules config init # 첫 사용자를 위한 대화형 마법사(wizard)
ai-agent-rules config show # 원시 구성 파일 표시
ai-agent-rules config show --merged # 병합된 설정 및 오버라이드 적용 결과 표시
...
ai-agent-rules skill list # 모든 번들된 스킬 목록 표시
ai-agent-rules skill show research # 터미널에 스킬 내용 렌더링
ai-agent-rules skill show research --url # 공유를 위한 버전 관리 GitHub URL 출력
...
ai-agent-rules tool list # 버전 및 업데이트 정보와 함께 관리되는 도구 표시
ai-agent-rules tool show statusline # 특정 도구에 대한 상세 정보
ai-agent-rules tool source list # 설치 소스 기본 설정 목록
...
ai-agent-rules completions install [--shell bash|zsh] # 셸 자동 완성 설치
ai-agent-rules completions uninstall [--shell bash|zsh] # 자동 완성 제거
ai-agent-rules completions update [--shell bash|zsh] # 자동 완성 스크립트 업데이트
...
사용자 레벨 설정을 위해 ~/.ai-agent-rules-config.yaml을 생성합니다:
version: 1
# glob 패턴 지원: *.json, **/*.yaml 등
...
설정 파일 위치:
~/.ai-agent-rules-config.yaml — 사용자별 설정 (제외 및 재정의)~/.ai-agent-rules/state.yaml — 활성 프로필 및 마지막 설치 타임스탬프 (자동 관리)~/.ai-agent-rules/cache/ — 병합된 설정 캐시 (자동 생성)settings_overrides를 사용하면 기기별 고유 값을 허용하면서도 settings.json을 git으로 동기화할 수 있습니다:
# 개인 노트북의 ~/.ai-agent-rules-config.yaml
settings_overrides:
claude:
...
설치 시 병합 파이프라인:
src/ai_rules/config/claude/settings.json에서 기본 설정(Base settings) 가져오기 (git 추적)~/.ai-agent-rules-config.yaml에서 사용자 재정의(User overrides) 사용 (로컬 전용)~/.ai-agent-rules/cache/claude/settings.json에 캐싱~/.claude/settings.json으로 심볼릭 링크(Symlinked)재정의 사항을 변경한 후에는 ai-agent-rules install --rebuild-cache를 실행하세요.
에이전트가 자체 설정 필드(예: MCP 서버 목록, 설치된 플러그인)를 관리하는 경우, ai-agent-rules는 캐시 파일을 통해 병합함으로써 이를 설치 과정에서 보존합니다:
| 에이전트 | 보존되는 필드 | 캐시 경로 |
|---|---|---|
| Claude | enabledPlugins, hooks | ~/.ai-agent-rules/cache/claude/settings.json |
| ... |
재정의 명령어는 복잡하게 중첩된 구조를 위해 배열 인덱스 표기법을 지원합니다:
ai-agent-rules override set claude.hooks.SubagentStop[0].hooks[0].command "uv run ~/my-hook.py"
ai-agent-rules override set claude.env.MY_VAR "value"
...
Codex는 푸터 설정을 ~/.codex/config.toml의 [tui].status_line 아래에 저장하므로, ai-agent-rules는 별도의 상태 표시줄 도구를 설치하는 대신 네이티브 Codex 푸터를 직접 관리합니다.
| Claude 상태 표시줄 | Codex 네이티브 항목 |
|---|---|
model | model-with-reasoning |
| ... | |
기기별로 settings_overrides를 사용하여 재정의할 수 있습니다: |
settings_overrides:
codex:
tui:
...
codex.tui.status_line은 전체 푸터 목록을 대체하므로, 더 짧은 배열을 설정하면 기본값과 병합되는 것이 아니라 번들된 기본값을 제거합니다.
MCP 서버는 src/ai_rules/config/mcps.json에 정의되어 있습니다 (모든 에이전트에서 공유). 각 에이전트의 MCP 매니저는 공유된 정의를 해당 네이티브 설정 형식으로 변환합니다:
| Agent | Format |
|---|---|
| Amp | JSON |
| ... | |
관리되는 MCP는 도구가 해당 항목을 사용자 추가 서버와 구별할 수 있도록 _managedBy: "ai-agent-rules" 마커로 추적됩니다. 사용자의 설정 또는 프로필에서 mcp_overrides를 통해 기기별 MCP를 재정의할 수 있습니다: |
# ~/.ai-agent-rules-config.yaml
mcp_overrides:
my-server:
...
프로필은 서로 다른 기기나 상황에 맞는 이름 지정 사전 설정(preset)으로 구성 오버라이드를 그룹화합니다.
ai-agent-rules profile list # 사용 가능한 프로필 목록 보기
ai-agent-rules profile show work # 프로필 세부 정보 보기
ai-agent-rules profile show work --resolved # 상속이 적용된 상태로 보기
...
도구에는 default -> personal -> work의 상속 체인을 가진 세 가지 내장 프로필이 제공됩니다. default는 일반적이며 누구에게나 적합합니다. personal과 work는 작성자 자신의 사전 설정(예: personal은 auto 권한 모드를 활성화)이며, 일반적인 추천 사항이 아닙니다. 프로필은 다음 키를 지원합니다:
# profiles/work.yaml
name: work
description: Work laptop with extended context model
...
사용자가 정의한 프로필 파일(예: ~/.ai-agent-rules/profiles/<name>.yaml)은 현재 지원되지 않습니다. 기기별 사용자 지정은 ~/.ai-agent-rules-config.yaml에 작성해야 합니다. 우선순위 순서(낮음에서 높음): 프로필 오버라이드 → 로컬 ~/.ai-agent-rules-config.yaml. 사용자의 로컬 설정이 항상 승리합니다.
활성 프로필은 세션 간에 ~/.ai-agent-rules/state.yaml에 유지됩니다.
이 저장소의 작성자가 아니라면, 누구나 사용할 수 있는 일반적인 엔지니어링 기본값을 얻으려면 default 프로필로 설치하세요. 포크(fork)하지 않고도 개인화할 수 있으며, 이때는 ~/.ai-agent-rules-config.yaml 파일을 추가하면 됩니다: agents_md를 사용해 자체 규칙을 ~/AGENTS.md에 추가하고, settings_overrides를 사용해 사용자 기기에 맞는 에이전트 설정을 조정할 수 있습니다. 여러 개의 이름 지정된 프로필로 완전히 맞춤 설정하려면, 저장소를 포크하고 src/ai_rules/config/profiles/ 아래에 자체 프로필 YAML 파일과 조각(fragment) 파일을 추가하세요.
# ~/.ai-agent-rules-config.yaml
agents_md: |
## My Team Standards
...
프로필 또는 사용자 설정에서 Claude Code 플러그인을 선언적으로 지정하세요:
# profiles/work.yaml 또는 ~/.ai-agent-rules-config.yaml
plugins:
- name: feature-dev
...
ai-agent-rules install을 실행할 때 다음이 수행됩니다:
claude plugin marketplace add를 통해 누락된 마켓플레이스를 추가합니다.claude plugin install <name>@<marketplace>를 통해 누락된 플러그인을 설치합니다.ai-agent-rules에 의해 관리되었으나 설정에서 제거된 고아(orphaned) 플러그인을 자동 삭제합니다.플러그인 상태는 ~/.claude/plugins/ai-agent-rules-managed.json에 추적되어 수동으로 설치된 플러그인이 제거되는 것을 방지합니다.
src/ai_rules/config/
├── AGENTS.md # -> ~/AGENTS.md
├── chat_agent_hints.md # 채팅 에이전트 사용자 지정 지침
...
AI Rules는 기능을 향상시키는 선택적 도구를 자동으로 설치합니다:
이러한 도구들은 setup 및 install 중에 자동으로 설치됩니다. 설치 상태를 확인하세요:
ai-agent-rules status # 선택적 도구 섹션 표시
ai-agent-rules tool list # 설치 출처, 버전, 업데이트 가능 여부 표시
만약 도구 설치에 실패하더라도, ai-agent-rules는 정상적으로 계속 진행됩니다 (fail-open 동작).
공유 스킬 추가 (Claude Code, Goose, Codex, Amp):
src/ai_rules/config/skills/my-skill/SKILL.md 파일을 생성합니다:---
name: my-skill
description: "간략한 설명"
...
ai-agent-rules install을 실행합니다.~/.claude/skills/, ~/.config/goose/skills/, ~/.config/agents/skills/ (Amp), 그리고 ~/.agents/skills/ (Codex)에 심볼릭 링크됩니다. Gemini는 내장 별칭(alias)을 통해 ~/.agents/skills/에서 스킬을 발견하므로, 전용 디렉터리가 필요하지 않습니다.Claude 훅 추가:
src/ai_rules/config/claude/hooks/my-hook.py 파일을 생성합니다.ai-agent-rules install을 실행합니다.새 AI 도구 추가:
src/ai_rules/config/<tool>/에 설정을 추가합니다.src/ai_rules/agents/<tool>.py를 구현합니다.src/ai_rules/targets/registry.py::TARGET_CLASSES에 등록합니다.