AI AGENT PLAYBOOK
Claude Code, Claude Cowork, Antigravity CLI 같은 AI 에이전트의 활용법을 원본 자료 40건에서 읽어 114개 페이지로 정리한 위키입니다.
WHAT'S NEW
2026-10-19~26 업데이트 · 9가지
2026-10-19~21에 공식 문서 위주로 자료를 더 모았고, 아래 항목들이 AI 에이전트를 처음 쓰는 사람에게 달라진 점이다. 가장 최근(2026-10-26)에는 공식 문서 다섯 건으로 낡은 정보 네 가지(/code-review 고치기, 할 일 목록 도구, 메모리 도구 베타, GitHub용 Gemini 앱 종료)를 바로잡고, 명령·내장 도구·프롬프트 캐싱 페이지를 새로 만들었다(10번). 각 항목은 "무엇이 바뀌었나"와 "나에게 무슨 뜻인가"를 원본이 말한 범위에서 적었다. 낯선 말은 용어 사전에서 찾는다.
처음에는 Manual이라 Claude가 동작 전에 묻는다. 내 컴퓨터의 파일·앱을 쓰는 작업은 Claude Desktop이 열려 있는 동안에만 된다. 원본은 메시지 보내기나 중요한 파일 바꾸기처럼 결과가 실제로 남는 일은 가까이서 검토하라고 권한다.
Help Center 문서는 Cowork와 채팅을 합친 화면을 설명한다. 확인 방식은 입력창에서 Auto 또는 Manual(기본값)로 고르고, Cowork의 Global instructions는 Settings > General의 Instructions for Claude로 합쳐졌다. 출시 기간에는 나뉜 화면과 통합 화면이 계정마다 함께 있다.
개인 계정으로 쓰던 사람에게 저장소 공지는 Antigravity CLI로 옮기라고 안내한다.
2026-06-18부터 Gemini CLI가 Google AI Pro·Ultra·무료 개인 계정의 요청 처리를 멈췄다. Gemini Code Assist Standard·Enterprise는 2026-10-09부터 새로 살 수 없고, 라이선스 추가와 연간 자동 갱신은 2027-01-31까지, 월간 자동 갱신은 2027-12-31까지 된다(2026-10-13 기준).
개인 계정으로 쓰던 사람에게 저장소 공지는 Antigravity CLI로 옮기라고 안내한다. 기업 라이선스·API 키 사용자는 2026-06-18 기준 영향이 없다고 밝혔고 기존 구독은 계약 종료까지 지원되지만, Google은 최종 갱신일이나 계약 종료일 전에 Gemini Enterprise로 전환을 계획하라고 권한다. 그래서 "Gemini CLI는 끝났다"고 한 번에 말하면 원본보다 세다. 개인 계정만 멈췄고, 기업 라이선스·API 키는 아직 쓸 수 있다.
권한 규칙(allow는 묻지 않고 허용, ask는 매번 확인, deny는 거부)은 deny, ask, allow 순서로 처음 맞는 것이 정하고 Claude Code가 강제한다.
Claude Code의 권한 규칙 문법, 작업 공간 신뢰, 자동 모드 설정, 샌드박스 공식 문서를 수집했다.
권한 규칙(allow는 묻지 않고 허용, ask는 매번 확인, deny는 거부)은 deny, ask, allow 순서로 처음 맞는 것이 정하고 Claude Code가 강제한다. 다만 설치한 mod(도구 호출을 승인·거부할 수 있는 확장)는 managed settings나 Team·Enterprise 로그인이 없으면 deny 규칙이 거부한 호출도 승인할 수 있다(자세히는 Claude Code 권한 규칙 문법). Bash 규칙은 명령 글자만 맞춰 다르게 쓴 같은 프로그램은 막지 못하므로, 원본은 반드시 지킬 제한을 샌드박스나 PreToolUse 훅(도구를 쓰기 직전에 도는 검사 스크립트)과 짝지으라고 한다. 남의 저장소가 주는 allow 규칙은 그 폴더를 신뢰한 뒤에만 적용되지만, 상위 폴더만 신뢰했거나 -p·SDK(대화 화면 없이 돌리는 방식)로 돌릴 때는 settings 파일의 훅·env 블록처럼 이 폴더를 신뢰하지 않아도 쓰이는 설정이 있다(목록은 작업 공간 신뢰 페이지). 샌드박스는 기본으로 꺼져 있고 셸 명령(Bash·PowerShell·Monitor 도구가 돌리는 명령)과 그 명령이 띄운 하위 프로세스만 가두며, 기본값에서는 샌드박스가 뜨지 못하면 샌드박스 없이 명령을 돌린다(failIfUnavailable: true면 시작 때 종료). 샌드박스에서 실패한 명령은 Claude가 샌드박스 밖에서 다시 돌리자고 할 수 있고, 누가 승인하는지는 권한 모드가 정한다(끄려면 allowUnsandboxedCommands: false). 자동 모드에서는 개인이 더한 허용 항목이 조직이 정한 '보통 막기'(soft_deny) 항목을 넘을 수 있어, 원본은 이 합치기 방식을 강제 경계가 아니라고("not a hard policy boundary") 하고, 절대 막을 동작은 managed settings(조직이 배포하는 설정)의 permissions.deny로 막으라고 한다.
조직이 managed settings로 정한 키는 내 설정 파일이나 명령줄 --settings로 덮어쓰지 못한다.
조직이 managed settings로 정한 키는 내 설정 파일이나 명령줄 --settings로 덮어쓰지 못한다. 다만 managed model은 시작 기본값이지 잠금이 아니고, 기기 관리자 권한이 있는 개발자는 관리 파일 자체를 고칠 수 있으며, managed settings는 Claude Code만 묶는다(다른 도구로 API를 부르면 적용되지 않는다. 예외 전체는 managed settings). 설정이 안 먹을 때 확인하는 순서는 설정 바꾸기 페이지에 있다.
설정 파일 네 곳(사용자·공유 프로젝트·로컬 프로젝트·managed)과 우선순위, 설정 키 표, CLI 플래그 표가 공식 문서 기준으로 생겼다.
조직이 managed settings로 정한 키는 내 설정 파일이나 명령줄 --settings로 덮어쓰지 못한다. 다만 managed model은 시작 기본값이지 잠금이 아니고, 기기 관리자 권한이 있는 개발자는 관리 파일 자체를 고칠 수 있으며, managed settings는 Claude Code만 묶는다(다른 도구로 API를 부르면 적용되지 않는다. 예외 전체는 managed settings). 설정이 안 먹을 때 확인하는 순서는 설정 바꾸기 페이지에 있다.
서브에이전트는 기본으로 메인 대화 아래 세 층까지 중첩한다(블로그의 "최대 5단계"는 v2.1.172~v2.1.216의 동작이다). 기본 코딩 지시를 빼는 것은 커스텀 출력 스타일이고 내장 네 스타일은 유지한다.
서브에이전트는 기본으로 메인 대화 아래 세 층까지 중첩한다(블로그의 "최대 5단계"는 v2.1.172~v2.1.216의 동작이다). 기본 코딩 지시를 빼는 것은 커스텀 출력 스타일이고 내장 네 스타일은 유지한다. 출력 스타일은 아무것도 강제하지 않으므로, 공식 문서는 보장돼야 하는 일을 훅에 두라고 한다.
훅 이벤트·입출력 규칙과 설정 레시피, 서브에이전트 정의 파일과 중첩 한도, 출력 스타일의 범위가 공식 문서로 들어왔다.
서브에이전트는 기본으로 메인 대화 아래 세 층까지 중첩한다(블로그의 "최대 5단계"는 v2.1.172~v2.1.216의 동작이다). 기본 코딩 지시를 빼는 것은 커스텀 출력 스타일이고 내장 네 스타일은 유지한다. 출력 스타일은 아무것도 강제하지 않으므로, 공식 문서는 보장돼야 하는 일을 훅에 두라고 한다.
루트 CLAUDE.md는 디스크에서 다시 넣고 출력 스타일은 계속 적용되지만, 앞서 훅이 더한 컨텍스트는 대화와 함께 요약된다. 대화 초반의 자세한 지시는 사라질 수 있어 원본은 계속 지킬 규칙을 CLAUDE.md에 두라고 한다.
루트 CLAUDE.md는 디스크에서 다시 넣고 출력 스타일은 계속 적용되지만, 앞서 훅이 더한 컨텍스트는 대화와 함께 요약된다. 대화 초반의 자세한 지시는 사라질 수 있어 원본은 계속 지킬 규칙을 CLAUDE.md에 두라고 한다. 훅과 컴팩션의 관계는 블로그와 공식 문서가 다르게 말해 상충 표시가 아직 열려 있다.
공식 컨텍스트 창 문서가 압축 전후에 무엇이 남는지 표로 준다.
루트 CLAUDE.md는 디스크에서 다시 넣고 출력 스타일은 계속 적용되지만, 앞서 훅이 더한 컨텍스트는 대화와 함께 요약된다. 대화 초반의 자세한 지시는 사라질 수 있어 원본은 계속 지킬 규칙을 CLAUDE.md에 두라고 한다. 훅과 컴팩션의 관계는 블로그와 공식 문서가 다르게 말해 상충 표시가 아직 열려 있다.
훅 이벤트는 6개이고, 훅이 실행하는 방식(핸들러)은 지금 명령 실행(command) 하나뿐이다. 서브에이전트 중첩은 메인 에이전트 아래 최대 10단계라 Claude Code 기본(세 층)과 다르다.
훅 이벤트는 6개이고, 훅이 실행하는 방식(핸들러)은 지금 명령 실행(command) 하나뿐이다. 서브에이전트 중첩은 메인 에이전트 아래 최대 10단계라 Claude Code 기본(세 층)과 다르다. AGENTS.md·GEMINI.md 규칙은 작업 파일의 폴더에서 워크스페이스 루트(작업 공간으로 연 맨 위 폴더)까지 올라가며 모두 합치고, 충돌하면 더 구체적인 폴더 규칙이 앞선다.
Antigravity 공식 Hooks·서브에이전트·Rules 문서를 수집했다.
훅 이벤트는 6개이고, 훅이 실행하는 방식(핸들러)은 지금 명령 실행(command) 하나뿐이다. 서브에이전트 중첩은 메인 에이전트 아래 최대 10단계라 Claude Code 기본(세 층)과 다르다. AGENTS.md·GEMINI.md 규칙은 작업 파일의 폴더에서 워크스페이스 루트(작업 공간으로 연 맨 위 폴더)까지 올라가며 모두 합치고, 충돌하면 더 구체적인 폴더 규칙이 앞선다.
코드 없이 시작하려면 Claude Cowork 갈래(첫 세팅 → 첫 업무 위임 → 보고서·슬라이드), 작업 폴더를 직접 다루는 에이전트를 쓰려면 Claude Code 갈래(설치·작동 방식 → 권한 모드 → 샌드박스·작업 공간 신뢰 → CLAUDE.md → 스킬)를 순서대로 따라간다.
코드 없이 시작하려면 Claude Cowork 갈래(첫 세팅 → 첫 업무 위임 → 보고서·슬라이드), 작업 폴더를 직접 다루는 에이전트를 쓰려면 Claude Code 갈래(설치·작동 방식 → 권한 모드 → 샌드박스·작업 공간 신뢰 → CLAUDE.md → 스킬)를 순서대로 따라간다. 단계마다 됐는지 확인하는 법과 흔한 막힘이 있고, Claude Code 첫 설치 절차처럼 이 위키에 아직 없는 것은 없다고 적었다. "AI가 내 파일을 지울 수 있나", "자동 모드는 안전한가" 같은 질문의 답은 조건과 예외까지 함께 읽는다.
새 원본 없이 기존 페이지를 엮어, 비개발자가 따라 할 입문 코스와 자주 묻는 질문 20개를 만들었다.
코드 없이 시작하려면 Claude Cowork 갈래(첫 세팅 → 첫 업무 위임 → 보고서·슬라이드), 작업 폴더를 직접 다루는 에이전트를 쓰려면 Claude Code 갈래(설치·작동 방식 → 권한 모드 → 샌드박스·작업 공간 신뢰 → CLAUDE.md → 스킬)를 순서대로 따라간다. 단계마다 됐는지 확인하는 법과 흔한 막힘이 있고, Claude Code 첫 설치 절차처럼 이 위키에 아직 없는 것은 없다고 적었다. "AI가 내 파일을 지울 수 있나", "자동 모드는 안전한가" 같은 질문의 답은 조건과 예외까지 함께 읽는다.
대화 도중 모델·생각 깊이(effort)를 바꾸거나, 도구 검색이 꺼진 환경에서 MCP 서버를 붙이면 다음 응답 한 번이 느리고 비싸질 수 있다(도구 검색이 켜져 있으면 MCP 연결로는 캐시가 깨지지 않는다).
대화 도중 모델·생각 깊이(effort)를 바꾸거나, 도구 검색이 꺼진 환경에서 MCP 서버를 붙이면 다음 응답 한 번이 느리고 비싸질 수 있다(도구 검색이 켜져 있으면 MCP 연결로는 캐시가 깨지지 않는다). 그래서 공식 문서는 모델과 effort를 세션 처음에 정하라고 권한다. 세션 중에 고친 CLAUDE.md는 다음 /clear·/compact·재시작 전까지 반영되지 않는다. 처음이라면 입력창에 /만 쳐서 쓸 수 있는 명령부터 본다(플랜·플랫폼에 따라 안 보이는 명령이 있다).
(1) /code-review는 리뷰만 하는 것이 아니라 --fix를 주면 찾은 문제를 Claude가 고친다. (2) Claude Code의 할 일 목록 도구는 TodoWrite에서 Task 도구 네 개로 바뀌었고, Opus 4.7·Sonnet 4.6·Haiku 4.5 이하 모델에서만 기본으로 주어진다. (3) Developer Platform 메모리 도구는 베타 헤더 없이 쓴다(문서는 "정식 출시"라고 쓰지는 않는다). (4) GitHub용 Gemini Code Assist 앱 소비자판은 2026-07-17에 종료됐다(엔터프라이즈판은 영향 없음). - 새로 생긴 페이지: 명령을 작업 흐름별로 고르는 Claude Code 슬래시 명령, 도구 이름과 확인 여부를 정리한 Claude Code 내장 도구, 무엇이 비용·속도를 갑자기 늘리는지 설명하는 프롬프트 캐싱.
대화 도중 모델·생각 깊이(effort)를 바꾸거나, 도구 검색이 꺼진 환경에서 MCP 서버를 붙이면 다음 응답 한 번이 느리고 비싸질 수 있다(도구 검색이 켜져 있으면 MCP 연결로는 캐시가 깨지지 않는다). 그래서 공식 문서는 모델과 effort를 세션 처음에 정하라고 권한다. 세션 중에 고친 CLAUDE.md는 다음 /clear·/compact·재시작 전까지 반영되지 않는다. 처음이라면 입력창에 /만 쳐서 쓸 수 있는 명령부터 본다(플랜·플랫폼에 따라 안 보이는 명령이 있다).
START HERE
AI 에이전트를 처음 쓰는 분은 입문 코스를 순서대로 따라가면 됩니다. 각 페이지는 맨 위 “쉽게 말하면” 상자부터 읽으면 됩니다.
AI 에이전트를 처음 쓰는 사람이 "어디서부터, 무엇을, 어떤 순서로" 하면 되는지를 한 장에 모은 길잡이다. 코드 없이 문서·메시지·표 업무를 맡기고 싶으면 A 갈래(Claude Cowork), 내 컴퓨터의 작업 폴더에서 파일을 고치고 명령을 실행하는 에이전트를 안전하게 써 보고 싶으면 B 갈래…
FAQAI 에이전트를 처음 쓰는 비개발자가 실제로 묻는 질문 20개에, 이 위키에 있는 원본 범위 안에서 짧게 답했다. 안전·통제 질문은 "대부분은 막지만 이런 예외가 있다"까지 함께 적었으니, 강의나 제안서에 옮길 때 조건을 빼지 않는다. 더 자세한 내용은 답마다 단 근거 페이지를 따라간다.
Claude Code는 기본으로 내 컴퓨터의 작업 폴더에서 파일을 읽고 고치고 명령을 실행하며, 일이 끝날 때까지 스스로 단계를 이어 가는 AI 에이전트다. 코딩에 가장 강하지만 문서 쓰기, 파일 찾기, 자료 조사처럼 명령으로 할 수 있는 일이면 무엇이든 도울 수 있다고 공식 문서는 말한다.
권한 모드는 에이전트가 무엇을 묻지 않고 바로 하고, 무엇 앞에서 멈춰 내 허락을 받을지 정하는 설정으로, Claude Code에서는 읽기만 알아서 하는 모드부터 거의 모든 것을 묻지 않는 모드까지 고른다. 설정에 적은 금지 규칙은 모든 모드에 기본으로 걸리지만, 명령을 글자 그대로 맞춰 보는 한계가 있다.
샌드박스는 Claude가 내 컴퓨터에서 실행하는 명령이 닿을 수 있는 파일과 인터넷 주소를 운영체제가 제한하는 장치다(비유로 말하면 명령 둘레의 울타리). 켜 두면 모델이 무엇을 실행하기로 했든 그 명령에 경계가 유지되지만, 기본으로 꺼져 있고 Claude가 실행하는 명령만 감싼다(파일 편집 기능 등은 밖에서 돈다).
CLAUDE.md는 Claude Code가 세션을 시작할 때 읽는 메모 파일이다. 새 세션은 이전 대화를 모른 채 시작하므로, 안 적어 두면 매번 다시 설명하게 될 빌드 방법·규칙·프로젝트 구조를 여기에 적는다.
스킬은 Claude에게 특정 일을 하는 방법이나 참고 지식을 적어 두는 문서 파일이다. 필요할 때만 읽어 들이므로, 같은 지시나 체크리스트를 채팅에 계속 붙여 넣고 있다면 스킬로 만들 때라고 원본은 말한다. 이름으로 직접 부를 수도 있고, 관련 있다고 판단하면 Claude가 알아서 불러 쓰기도 한다.
Claude 데스크톱 앱에 내 폴더와 업무 앱을 연결해 두고, 실제 업무를 통째로 맡기는 방식이다. Claude가 단계마다 무엇을 하는지 보여 주므로 지켜보다가 틀리면 바로잡을 수 있고, 제품 가이드는 다운로드·삭제·공유 변경 같은 민감한 동작 앞에서는 확인을 받는다고 말한다…
BROWSE BY TYPE
도구 사용법, 알아야 할 개념, 바로 따라 할 기법, 근거가 된 원본 자료로 나눠 두었습니다.
SOURCE
위키의 근거가 된 원본 자료 1건당 요약 1개
KEY IDEAS
위키 전체를 종합한 개요에서 뽑은 주요 흐름입니다.
Claude Code 확장은 "무엇을 항상 알게 할지, 무엇을 필요할 때만 부를지, 무엇을 강제할지"의 배분이다.
셋업은 불편이 생길 때 하나씩 키운다.
Cowork의 첫걸음은 연결·권한 확인·실제 업무 하나다.
컨텍스트는 유한한 자원이다.
CLAUDE.md는 확인할 수 있게, 짧게, 모순 없이 쓴다.
지시를 어디에 둘지는 "언제 로드되나, 압축 뒤 남나, 얼마나 권위를 갖나"로 정한다.
반복 업무 절차는 스킬로 만들고, 켠 채와 끈 채로 비교해 검증한다.
"에이전트가 마음대로 하지 않나"의 답은 모드·규칙·관리자 설정 세 층이다.
같은 AGENTS.md라도 Codex와 Claude Code가 읽는 규칙은 다르다.
업무 위임은 "결과·자료·검토 지점"을 정해 주는 데서 시작한다.
부서별 업무는 직무별 플러그인을 출발점으로 삼아 회사에 맞게 고친다.
자동화는 가장 단순한 해법에서 시작해, 결과가 입증 가능하게 나아질 때만 한 칸씩 올린다.
Gemini CLI에서 Antigravity CLI로 옮길 때 지시 파일은 그대로, 경로는 바뀐다.
Claude Code는 "모델 + 도구"의 에이전트 루프이고, 확장은 그 위의 층이다.
훅은 "매번 일어나게" 하는 장치이고, 무엇을 강제하는지는 matcher와 권한 규칙이 정한다.
서브에이전트는 "격리해서 맡기고 요약만 받는" 장치이고, 권한을 좁히는 말에는 조건이 붙는다.
설정은 "어느 파일에 두느냐"가 "누구에게 적용되느냐"다.
샌드박스는 "모델이 무엇을 하기로 했든" 셸 명령을 운영체제가 묶는 층이지만, 셸 명령만 묶는다.
RECENTLY UPDATED
권한 모드는 에이전트가 무엇을 묻지 않고 바로 하고, 무엇 앞에서 멈춰 내 허락을 받을지 정하는 설정으로, Claude Code에서는 읽기만 알아서 하는 모드부터 거의 모든 것을 묻지 않는 모드까지 고른다. 설정에 적은 금지 규칙은 모든 모드에 기본으로 걸리지만, 명령을 글자 그대로 맞춰 보는 한계가 있다.
CLAUDE.md는 Claude Code가 세션을 시작할 때 읽는 메모 파일이다. 새 세션은 이전 대화를 모른 채 시작하므로, 안 적어 두면 매번 다시 설명하게 될 빌드 방법·규칙·프로젝트 구조를 여기에 적는다.
샌드박스는 Claude가 내 컴퓨터에서 실행하는 명령이 닿을 수 있는 파일과 인터넷 주소를 운영체제가 제한하는 장치다(비유로 말하면 명령 둘레의 울타리). 켜 두면 모델이 무엇을 실행하기로 했든 그 명령에 경계가 유지되지만, 기본으로 꺼져 있고 Claude가 실행하는 명령만 감싼다(파일 편집 기능 등은 밖에서 돈다).
서브에이전트는 메인 대화와 떨어진 자기 작업 공간에서 곁가지 일(넓은 검색, 많은 파일 읽기 등)을 하고 결과 요약만 돌려주는 보조 작업자다. 메인 대화가 다시 볼 일 없는 검색 결과나 파일 내용으로 가득 차지 않게 하는 것이 핵심 이점이다. 다만 보조 작업자가 쓰는 양도 메인 대화와 같은 사용량 한도에 잡힌다.
서브에이전트(메인 대화가 일을 떼어 맡기는 별도 AI 작업자)를 정의하는 마크다운 파일의 형식을 찾아보는 페이지로, 꼭 필요한 항목은 이름(name)과 설명(description) 둘뿐이고 쓸 도구·모델·권한 모드 같은 나머지는 선택이다.
스키마 파일은 AI 에이전트에게 '이 위키(또는 프로젝트)는 이렇게 구성돼 있고, 이런 규칙과 순서로 일한다'를 알려 주는 문서로, Claude Code에서는 CLAUDE.md, Codex에서는 AGENTS.md가 그 역할을 한다.
INGEST LOG