dotagents
무엇인가
dotagents는 여러 AI 코딩 도구가 공유할 규칙·명령·훅·스킬의 원본을 하나의 `.agents` 디렉터리로 고정하는 링크 관리 도구다. 규율하는 문제 영역은 설정 파일의 분기다. 도구별로 CLAUDE.md, AGENTS.md, GEMINI.md, commands, hooks, skills를 각각 복사해 두면 한쪽만 수정되어 내용이 어긋나므로, 원본을 하나만 두고 나머지는 링크로 파생시킨다.
어떻게 동작하나
동작은 심링크 생성이다. `.agents/CLAUDE.md`가 있으면 `~/.claude/CLAUDE.md`로, 없으면 `.agents/AGENTS.md`가 대신 연결된다. Gemini도 `.agents/GEMINI.md` 우선, 없으면 AGENTS.md 폴백이다. `.agents/commands`는 Claude·Factory·Codex(prompts)·Cursor·OpenCode·Gemini의 명령 경로로, `.agents/hooks`는 Claude·Factory의 훅 경로로, `.agents/skills`는 Claude·Factory·Codex·Cursor·OpenCode·Gemini의 스킬 경로로 각각 연결된다. Factory·Codex·OpenCode는 항상 `.agents/AGENTS.md`를 쓰며, 덮어쓰기 전에 백업을 만들고 재실행으로 링크를 복구하거나 되돌릴 수 있다.
무엇과 다른가
프롬프트 파일을 도구마다 직접 작성하거나 복사해 두는 방식과 구조적으로 다르다. 복사 방식은 원본이 여러 개가 되어 동기화 책임이 사용자에게 남지만, dotagents는 원본을 `.agents` 하나로 두고 나머지를 심링크로 만들어 수정이 즉시 전파되게 한다. 또한 전역 홈과 프로젝트 폴더 두 범위를 구분해, 전역은 모든 프로젝트에 적용되고 프로젝트 범위는 실행한 디렉터리에만 명령·훅·스킬을 연결한다.
어떻게 쓰나
설치는 Bun 1.3+ 환경에서 `npx @iannuttall/dotagents` 또는 `bunx @iannuttall/dotagents`로 CLI를 실행한다. 워크스페이스(Global home 또는 Project folder)를 고르고 관리할 클라이언트를 선택한 뒤 안내를 따른다. 링크를 고치거나 변경을 취소할 때 같은 명령을 다시 실행하면 되고, 백업은 `.agents/backup/`에 쌓이며 "Undo last change"로 복원한다.
전제와 한계
전제와 한계가 있다. 지원 대상은 Claude Code, Codex, Factory, Cursor, OpenCode, Gemini이며 선택한 클라이언트에만 링크가 생긴다. 프로젝트 범위는 commands·hooks·skills만 연결하고 AGENTS.md·CLAUDE.md·GEMINI.md 규칙 파일은 저장소 루트에 그대로 남겨 사용자가 직접 관리해야 한다. 스킬은 `name`과 `description` 프런트매터를 가진 유효한 SKILL.md가 있어야 하며, `.agents/CLAUDE.md`나 `.agents/GEMINI.md`를 추가·삭제한 뒤에는 심링크 갱신을 위해 dotagents를 재실행해야 한다.