init-project-rules

프로젝트 루트에 AGENTS.md(팀 공유 에이전트 지침)를 생성하고, 이를 네이티브로 읽지 못하는 에이전트를 위한 브릿지 파일을 함께 설정한다.

AGENTS.md는 60,000개 이상의 오픈소스 프로젝트가 채택한 도구 중립적 표준이다. 한 번 작성하면 Cursor, GitHub Copilot, Windsurf, Codex CLI 등 30개 이상의 에이전트가 자동으로 읽는다. 이 스킬은 단순히 파일을 만드는 것이 아니라, 에이전트 생태계의 파편화를 브릿지로 해결한다.

가드레일

#	검증	실패 시
1	CWD가 Git 저장소임	"Git 저장소에서 실행해주세요"
2	AGENTS.md가 이미 존재	"이미 AGENTS.md가 있습니다. 덮어쓸까요, 병합할까요?"

워크플로우

1단계: 프로젝트 자동 분석

코드를 읽으면 알 수 있는 것은 AGENTS.md에 넣지 않는다. 자동 분석의 목적은 AGENTS.md에 쓸 내용을 결정하기 위함이지, 분석 결과를 그대로 옮겨 적기 위함이 아니다.

수집 항목:

소스	수집 내용
package.json / pom.xml / build.gradle / pyproject.toml 등	패키지 매니저, 주요 의존성, 스크립트 명령어
디렉토리 구조 (ls, tree)	모노레포 여부, src/test 분리 방식
.eslintrc / prettier / tsconfig 등	린터·포매터 존재 여부 (있으면 AGENTS.md에서 스타일 규칙 생략)
Dockerfile / docker-compose.yml	컨테이너 기반 여부
.github/workflows/ / .gitlab-ci.yml	CI/CD 존재 여부
기존 README.md	프로젝트 설명, 설치 방법

2단계: AGENTS.md 생성

아래 섹션 구조를 기반으로 생성한다. 프로젝트에 해당하지 않는 섹션은 생략한다.

references/agents-md-template.md를 읽고 템플릿 구조를 따른다.

섹션 포함 판단 기준:

섹션	포함 조건
Commands	항상 (빌드, 테스트, 린트 명령어가 있으면)
Tech Stack	비표준 스택이거나 버전이 중요할 때
Project Structure	디렉토리가 5개 이상이거나 모노레포일 때
Code Style	린터/포매터로 커버되지 않는 규칙이 있을 때
Testing	테스트가 존재할 때
Git Workflow	팀 규모 2인 이상이거나 브랜치 전략이 있을 때
Common Pitfalls	생략 (자동 분석으로 알 수 없음. 사용자가 나중에 추가)
Boundaries	항상 (최소 Never do 목록은 포함)

작성 원칙:

• 에이전트가 코드·package.json·git history를 읽어서 알 수 있는 것은 쓰지 않는다
• 설명보다 코드 스니펫을 보여준다
• 명령어는 플래그까지 포함한다 (예: npm test -- --coverage O, npm test X)
• 150줄 이하로 시작, 300줄을 넘기지 않는다
• "write clean code" 같은 자명한 조언은 넣지 않는다

3단계: 브릿지 파일 생성

AGENTS.md를 네이티브로 읽지 못하는 주요 에이전트를 위해 브릿지 파일을 생성한다.

Claude Code → CLAUDE.md

@AGENTS.md

한 줄이면 충분하다. Claude Code의 @import 기능으로 AGENTS.md 전체를 로드한다. CLAUDE.md에 프로젝트 규칙을 중복 작성하지 않는다.

Gemini CLI → 안내 메시지

Gemini CLI는 기본적으로 GEMINI.md를 읽는다. settings.json은 프로젝트 외부 파일이므로 직접 수정하지 않고 안내한다:

💡 Gemini CLI 사용자는 아래 설정을 추가하면 AGENTS.md를 자동으로 읽습니다:
   ~/.gemini/settings.json → "context": { "fileName": ["AGENTS.md", "GEMINI.md"] }

   또는 GEMINI.md 파일을 만들어 AGENTS.md 내용을 참조하도록 할 수 있습니다.

.gitignore 확인

브릿지 파일(CLAUDE.md 등)은 팀 공유 대상이므로 .gitignore에 포함되지 않아야 한다. 확인 후 필요 시 안내한다.

4단계: 결과 요약

생성된 파일 목록과 각 파일의 역할을 간단히 보여준다:

✅ 생성 완료:
  - AGENTS.md (팀 공유 에이전트 지침)
  - CLAUDE.md (Claude Code 브릿지)

💡 Gemini CLI 사용자 설정 안내 출력됨

AGENTS.md는 언제든 수정할 수 있습니다.
팀 금기사항, 코드 스타일, 자주 하는 실수 등을 추가하면 에이전트가 더 정확하게 동작합니다.

개인 설정이 필요하면 /init-local-rules 를 실행하세요.

에이전트 호환성 매트릭스

이 스킬이 커버하는 에이전트별 지원 방식:

에이전트	AGENTS.md 읽기	브릿지 방식
Cursor	자동	불필요
GitHub Copilot	자동	불필요
OpenAI Codex CLI	자동	불필요
Windsurf	자동	불필요
JetBrains Junie	자동	불필요
Roo Code	자동	불필요
Amp	자동	불필요
Devin	자동	불필요
Claude Code	미지원	CLAUDE.md → @AGENTS.md
Gemini CLI	설정 필요	안내 메시지 출력