ai-agent-rules

AI Rules는 여러 AI 코딩 에이전트의 설정을 단일 git 추적 위치에 유지하고 각 에이전트의 예상 설정 디렉토리에 심볼릭 링크로 연결하는 명령줄 도구입니다. 명시된 목표는 "한 번 편집하면 모든 곳에 적용"이며, 동시에 에이전트별 및 머신별 사용자 지정을 허용합니다. 지원되는 에이전트 및 해당 설정 디렉토리: - Amp: ~/.config/amp/ (스킬은 ~/.config/agents/skills/) - Claude Code: ~/.claude/ (스킬은 ~/.claude/skills/) - Codex CLI: ~/.codex/ (스킬은 ~/.agents/skills/) - Gemini CLI: ~/.gemini/ (~/.agents/skills/를 통해 스킬 검색) - Goose: ~/.config/goose/ (스킬은 ~/.config/goose/skills/) - AGENTS.md 및 스킬과 같은 공유 자료 설치에는 Python 3.10+ 및 uv가 필요합니다. 권장 경로는 PyPI에서 한 번의 명령으로 설정하는 것입니다(uvx --from ai-agent-rules ai-agent-rules setup). 이 명령은 심볼릭 링크를 설치하고, ai-agent-rules 명령(및 ai-rules 별칭)을 시스템 전체에서 사용할 수 있게 하며, 선택적으로 헬퍼 도구를 설치합니다. --github 플래그는 대신 메인 브랜치에서 설치하며, 로컬 개발은 uv run ai-agent-rules install을 사용합니다. 업그레이드 명령은 업데이트를 확인하고 설치하며, 확인 전용, 강제, 업그레이드 후 설치 건너뛰기, 특정 도구만 업그레이드하는 플래그가 있습니다. 핵심 명령은 설정, 설치/동기화, 상태 및 검사, 구성, 제외 및 오버라이드, 스킬, 도구, 셸 완성을 다룹니다. 주목할 만한 동작: - install은 특정 에이전트 선택, 드라이런 미리보기, 자동 확인, 캐시 재빌드, 프로필 선택을 지원합니다. - status는 심볼릭 링크 상태, 선택적 도구, 활성 프로필을 상태 기호와 diff로 보고합니다. validate는 소스 파일이 존재하는지 확인하고, uninstall은 심볼릭 링크를 제거합니다. - config init/show/edit은 원시 또는 병합된 설정을 선택적으로 에이전트별로 표시합니다. - exclude add/remove/list는 심볼릭 링크되지 않아야 하는 파일(예: 회사 관리 파일)에 대한 glob 패턴을 관리합니다. - override set/unset/list는 중첩 설정을 편집하며, 후크 명령 배열과 같은 구조에 대한 배열 인덱스 표기법을 지원하고, 오타 시 유효한 키를 제안하는 경로 검증이 있습니다. - skill list/show는 번들된 스킬을 렌더링하고, 공유를 위한 버전이 있는 GitHub URL을 인쇄하거나 파이프용 원시 마크다운을 출력할 수 있습니다. - tool list/show 및 tool source get/set은 선택적 도구와 해당 설치 소스(pypi, github, 로컬 경로, 재설정)를 관리합니다. - completions install/uninstall/update/status 및 원시 bash/zsh 스크립트 출력이 제공됩니다. 구성은 계층화되어 있습니다. ~/.ai-agent-rules-config.yaml의 사용자 수준 파일은 제외 및 머신별 settings_overrides를 보유합니다. 상태(활성 프로필, 마지막 설치 타임스탬프)는 ~/.ai-agent-rules/state.yaml에 있으며, 병합된 설정은 ~/.ai-agent-rules/cache/에 캐시됩니다. 문서화된 병합 파이프라인은 기본 git 추적 설정, 프로필 오버라이드, 사용자 오버라이드, 캐시에서 병합된 보존 에이전트 관리 필드, 캐싱, 에이전트 디렉토리로의 심볼릭 링크 순서입니다. 보존 필드에는 Claude의 enabledPlugins 및 hooks, Goose의 extensions, Codex의 projects, Gemini의 ide가 포함됩니다. 오버라이드를 변경하려면 install --rebuild-cache를 실행해야 합니다. 프로필은 오버라이드를 명명된 사전 설정으로 그룹화하고 상속을 지원합니다. 도구에는 default -> personal -> work 체인의 세 가지 내장 프로필이 제공되며, default는 일반적인 것으로, personal/work는 일반 권장 사항이 아닌 작성자 자신의 사전 설정으로 설명됩니다. 프로필은 settings_overrides, plugins, marketplaces, 관리 도구 설치 소스, AGENTS.md 조각(agents_md_file, 상속을 통해 부모 우선 추가, 인라인 agents_md와 상호 배타적), 제외 및 MCP 오버라이드를 정의할 수 있습니다. 로컬 사용자 구성은 프로필 오버라이드보다 우선합니다. 사용자 정의 프로필 파일은 현재 지원되지 않습니다. 머신별 사용자 지정은 사용자 구성 파일로 이동합니다. MCP 서버는 공유 mcps.json에 한 번 정의되며 각 에이전트의 관리자가 네이티브 형식(Amp, Claude, Gemini의 경우 JSON, Codex의 경우 TOML, Goose의 경우 YAML 확장)으로 변환합니다. 관리 항목은 사용자 추가 서버와 구별하기 위해 _managedBy 마커를 전달하며, mcp_overrides는 API 키와 같은 머신별 값을 허용합니다. Claude Code 플러그인은 프로필 또는 사용자 구성에서 선언할 수 있습니다. install은 누락된 마켓플레이스 및 플러그인을 추가하고, 이전에 관리된 고아 플러그인을 자동으로 제거하며, 수동으로 설치된 플러그인에 대해 경고하지만 제거하지는 않습니다. 플러그인 상태는 관리 JSON 파일에 추적됩니다. 안전 기능에는 첫 실행 경고, 타임스탬프 백업, 대화형 프롬프트, 드라이런 모드, 심볼릭 링크만 관리되고 실제 파일은 삭제되지 않는다는 주장, 상황별 오류 메시지가 포함됩니다. 문제 해결 가이드는 잘못된 대상, 백업 복원, 제외를 통한 심볼릭 링크 비활성화, 오버라이드가 적용되지 않을 때 캐시 재빌드, 병합된 설정 보기, 사전 v0.35 구성 경로에서 자동 마이그레이션을 다룹니다. 프로젝트는 MIT 라이선스입니다.