AI 코딩 에이전트 설정 가이드 (한국어)

주요 코딩 에이전트에는 모두 두 가지 수단이 있습니다. 하나는 전체 자동 승인 스위치(Cursor의 Run Everything, Claude Code의 --dangerously-skip-permissions, Codex, Gemini CLI, Copilot CLI의 --yolo, Cline의 YOLO Mode)이고, 다른 하나는 신뢰하는 명령만 미리 승인하는 범위 지정 allowlist입니다. 더 안전한 기본값은 allowlist입니다. 전체 스위치는 컨테이너, VM 또는 버려도 되는 프로젝트에서만 사용하십시오.

Cursor는 .cursor/rules의 .mdc 파일과 AGENTS.md를 읽습니다. Claude Code는 CLAUDE.md를 읽고, CLAUDE.md가 없으면 AGENTS.md를 대신 읽습니다. Codex, Amp, Kiro, Junie는 AGENTS.md를 기본으로 읽습니다. Gemini CLI는 GEMINI.md를 읽으며 context.fileName으로 AGENTS.md를 지정할 수 있습니다. GitHub Copilot은 .github/copilot-instructions.md, .github/instructions/*.instructions.md, AGENTS.md를 읽습니다. Cline은 .clinerules/를 읽고 .cursorrules, .windsurfrules, AGENTS.md도 감지합니다. 저장소 루트의 AGENTS.md 하나로 대부분의 에이전트를 지원할 수 있습니다.

Claude Code는 ~/.claude/settings.json과 프로젝트의 .claude/settings.json, .claude/settings.local.json을 사용합니다. Codex는 ~/.codex/config.toml과 신뢰된 프로젝트의 .codex/config.toml을 사용합니다. Gemini CLI와 Qwen Code는 ~/.gemini/settings.json과 ~/.qwen/settings.json, 그리고 프로젝트별 .gemini 또는 .qwen 폴더를 사용합니다. OpenCode는 ~/.config/opencode/opencode.json과 opencode.json을, Amp는 ~/.config/amp/settings.json과 .amp/settings.json을, Factory Droid는 ~/.factory/settings.json을 사용합니다. Cursor는 AI 설정을 Cursor Settings 패널에 두고, permissions.json 같은 에이전트 파일을 ~/.cursor와 .cursor에 둡니다. 모든 도구에서 프로젝트 파일이 사용자 파일보다 우선합니다.

대부분의 에이전트는 mcpServers 객체가 있는 JSON 파일을 읽습니다. Cursor는 .cursor/mcp.json, Claude Code는 .mcp.json, Kiro는 .kiro/settings/mcp.json, Factory Droid는 .factory/mcp.json, Junie는 .junie/mcp/mcp.json입니다. 예외는 VS Code(.vscode/mcp.json의 servers 키), Codex(~/.codex/config.toml의 [mcp_servers.NAME] 테이블), OpenCode(opencode.json의 mcp 키), Zed(설정의 context_servers), goose(config.yaml의 extensions)입니다. Claude Code, Codex, Gemini CLI, Amp, Factory Droid에는 mcp add 명령도 있습니다.

Claude Code는 .claude/settings.json의 hooks 블록을, Gemini CLI는 .gemini/settings.json의 hooks 블록을 읽습니다. Cursor는 .cursor/hooks.json, Factory Droid는 .factory/hooks.json, GitHub Copilot은 .github/hooks/*.json, Kiro는 .kiro/hooks/의 모든 JSON 파일을 읽습니다. 모두 이벤트를 stdin의 JSON으로 스크립트에 전달합니다. 도구 호출을 차단하려면 Claude Code, Cursor, Gemini CLI, Factory Droid, Kiro CLI에서는 코드 2로 종료하거나, deny 결정을 JSON으로 출력합니다(Copilot은 permissionDecision, Cursor는 permission 사용).

이 에이전트들은 모두 name과 description이 있는 YAML frontmatter를 가진 SKILL.md 파일이 담긴 폴더를 읽습니다. Claude Code는 .claude/skills/와 ~/.claude/skills/를 사용합니다. Codex, Amp, OpenHands는 저장소의 .agents/skills/와 개인용 ~/.agents/skills/를 사용합니다. Cline은 .cline/skills/와 ~/.cline/skills/를 사용하며 .claude/skills/도 읽습니다. Amp도 .claude/skills/를 읽습니다. 따라서 .agents/skills/의 skill은 Codex, Amp, OpenHands를, .claude/skills/의 사본은 Claude Code, Cline, Amp를 지원합니다.

Claude Code는 모든 도구 호출을 설정 파일의 권한 규칙과 대조합니다. 규칙은 permissions.allow, permissions.ask, permissions.deny에 넣고 Tool 또는 Tool(specifier) 형식을 사용하며, deny, ask, allow 순서로 평가됩니다. /permissions로 모든 규칙과 그 규칙이 정의된 파일을 확인하거나, 한 세션에만 적용하려면 --allowedTools와 --disallowedTools를 전달합니다.

Shift+Tab을 눌러 권한 모드를 순환하거나, claude --permission-mode <mode>로 시작하거나, .claude/settings.json에 Bash(npm run *) 같은 permissions.allow 규칙으로 특정 명령을 사전 승인합니다. Auto 모드는 분류기가 작업을 검토하는 동안 일상적인 확인 없이 실행됩니다. --dangerously-skip-permissions는 컨테이너나 VM 전용입니다.

Settings > Agents > Approvals & Execution을 열고 Run Mode를 선택합니다. Run Everything은 sandbox나 검토 없이 모든 도구 호출을 자동 실행합니다. Allowlist는 나열한 명령만 실행합니다. Auto-review는 allowlist에 있는 호출을 즉시 실행하고, 다른 셸 명령은 가능하면 sandbox로 보냅니다.

저장소의 .cursor/rules 폴더에 .mdc 파일을 만들고, 각 파일에 description, globs, alwaysApply를 지정하는 frontmatter를 작성합니다. 가장 빠른 방법은 Agent 채팅에서 /create-rule을 입력하는 것입니다. 메타데이터 없는 일반 마크다운을 원하면 대신 AGENTS.md 파일을 사용합니다.

원격 서버는 claude mcp add --transport http NAME URL, 로컬 stdio 서버는 claude mcp add [options] NAME -- COMMAND [args]를 실행합니다. 서버는 기본적으로 local 스코프에 저장되므로 현재 프로젝트에서 본인에게만 보입니다. 공유 .mcp.json을 작성하려면 --scope project를, 모든 프로젝트에서 서버를 사용하려면 --scope user를 사용합니다.

다섯 도구 모두 파일로 커스텀 에이전트를 정의할 수 있습니다. Claude Code, Cursor, Gemini CLI, Copilot은 YAML frontmatter가 있는 Markdown을 사용합니다. Codex는 독립 TOML 파일을 사용합니다. 각 도구에는 내장 subagent가 있습니다. Claude Code의 Explore, Codex의 explorer, Cursor와 Copilot의 explore, Gemini CLI의 codebase_investigator가 그 예입니다. Claude Code, Cursor, Gemini CLI, Copilot은 description을 보고 스스로 에이전트를 선택할 수 있습니다. Codex에서는 직접 subagent를 요청하거나 AGENTS.md 또는 skill 지침이 요청합니다. 도구 간 차이는 도구 제한, 모델 선택, 백그라운드 또는 병렬 실행 방식에서 가장 큽니다.