FAQ · 자주 나는 오류와 해결법

각 장에 흩어져 있는 경고·팁 박스를 실습 중 자주 나는 순서대로 한곳에 모았다. 증상으로 먼저 찾고, 필요하면 "자세히" 링크로 원래 설명을 확인하라.

설치·환경

4장 §2 실습 준비 스크립트를 돌렸는데 일부 항목이 ❌로 나온다.

운영체제와 무관하게 setup-common.ts가 체크리스트를 다시 검증해준다. Windows는 스크립트를 관리자 권한으로 실행했는지, macOS/Linux는 --wezterm/--docker 같은 선택 플래그를 빠뜨리지 않았는지 먼저 확인한다. 설치 로그는 Windows 기준 %USERPROFILE%\workshop-setup-logs\에 남는다.

자세히: 4장 §2-A 준비

Antigravity 명령줄 인터페이스(CLI)를 npm으로 전역 설치하려는데 안 된다.

2026-06-18부로 Gemini CLI 서비스가 종료되고 Antigravity CLI(agy)로 대체됐다. agy는 별도 런타임 설치가 필요 없는 단일 컴파일 바이너리로, 압축 해제 후 PATH에 넣기만 하면 된다. npm 설치 안내는 옛 자료다.

자세히: 공통 참고 §도구 비교

서브에이전트 실행

writer 서브에이전트로 파일을 쓰게 했는데, reviewer가 "파일이 없다"고 한다.

writer와 reviewer를 한 메시지에서 동시에(병렬로) 호출했을 가능성이 높다. writer가 파일을 만들기도 전에 reviewer가 검토를 시도해 실패한 것이다. 의존 관계가 있는 작업은 "두 단계를 순서대로 진행해"처럼 순차 실행을 명시적으로 요청해야 한다.

자세히: 4장 §2-A D-1

Claude Desktop App에서 파일 저장 후 감사 스크립트가 자동으로 안 돈다.

정상이다. PostToolUse/TeammateIdle/TaskCompleted 같은 훅은 Claude Desktop App에서는 발화하지 않고 Claude Code(CLI) 세션에서만 자동 실행된다. Desktop App을 쓰는 팀은 훅이 하던 작업을 세션이 끝난 뒤 수동으로 실행해야 한다. Codex는 훅 메커니즘 자체가 없으므로 CODEX.md 지침을 PM이 스스로 실행하는 방식으로 대체한다(4장 §1-C 참조). 이걸 모르고 지나가면 "감사가 도는 줄 알았는데 안 돌았다"는 사고로 이어질 수 있다.

자세히: 공통 참고 §1, 3장 §감사 로그와 관측성

reviewer가 검토만 해달라고 했는데 파일을 수정해버렸다.

tools 필드에 Write가 포함돼 있지 않은지 확인한다. reviewer 같은 읽기 전용 역할은 애초에 tools: Read, Grep처럼 필요한 최소 권한만 부여해, 프롬프트 해석이 애매해도 수정 자체가 불가능하게 막아야 한다.

자세히: 3장 §최소 권한 원칙

에이전트가 같은 작업을 반복하며 끝나지 않는다.

평가자-최적화(Evaluator-Optimizer) 루프에서 평가자가 계속 "부족하다"고 판단하고 최적화자가 다시 시도하는 공회전(spin) 상태다. 해결법: 최대 반복 횟수를 미리 정해두고, 지정한 횟수 안에 기준을 통과하지 못하면 자동 종료하도록 한다. 2장 §오케스트레이션 패턴에서 설명하는 대로 패턴 단위로 풀지 말고, 전체 워크플로우를 9장의 실행 계획(Execution Plan)으로 구조화하면 예방하기 쉽다.

자세히: 2장 §오케스트레이션 패턴, 9장 · 워크플로우 디자인 패턴

서브에이전트가 도구를 호출하다 실패하고 멈춘다.

가장 흔한 원인 두 가지다. 첫째, 네트워크 타임아웃 — API 호출이나 MCP 서버 연결이 일시적으로 끊겼다. Claude Code의 경우 /cost 명령으로 세션 상태를 확인하고, Antigravity의 경우 Agent Manager에서 에이전트 상태를 점검한 뒤 재시도한다. 둘째, MCP 서버 미연결 — 로컬 MCP 서버가 실행 중인지 claude mcp list(Claude Code) 또는 해당 플랫폼의 서버 상태 명령어로 확인한다. 일시적 오류는 비용·성능 카테고리의 타임아웃 해결법을 참고하라.

자세히: FAQ · 비용·성능, 3장 §감사 로그와 관측성

에이전트가 수행한 파괴적 작업이나 파일 수정 이력을 엔터프라이즈 환경에서 모니터링하고 감사(Audit)하려면?

에이전트의 터미널 명령 실행 및 도구 사용 이력은 시스템의 감사 로그(Audit Log)로 실시간 수집되어야 한다. 이를 위해 Sandbox 환경 내에서 감사 데몬이나 쉘 후킹(Shell Hooking) 기술을 사용해 실행 기록을 원격 로그 서버로 전송한다. 또한, 중요한 파괴적 작업(예: DB 삭제, Secret Key 파괴)은 사람 승인 게이트(Human Approval Gate)를 강제해, 시스템 관리자 또는 담당자의 최종 승인 없이 실행할 수 없도록 격리 구조를 구축한다.

자세히: 3장 §감사 로그와 관측성

병렬·팀 협업

Antigravity Agent Manager에서 에이전트 두 개가 서로 다른 파일을 수정 중인데 결과가 뒤섞인다.

두 에이전트를 같은 Workspace(같은 폴더)에 배정했을 가능성이 높다. 같은 코드베이스를 공유하면 한 에이전트가 다른 에이전트의 작업 맥락을 자기 것으로 착각하는 "인지적 중첩(cognitive overlap)"이 생길 수 있다. Workspace 또는 git worktree 단위로 반드시 분리한다.

자세히: 공통 참고 §2, 3장 §격리

Claude Desktop App에서 Agent Teams를 켰는데 tmux 옵션이 안 보인다.

정상이다. Desktop App은 teammateMode: in-process만 지원하며, tmux 분할 창 모드는 Claude Code(CLI)에서만 추가로 지원된다.

자세히: 공통 참고 §1

에이전트가 작업을 수행하다가 사람의 최종 승인이나 중간 입력을 받아야 할 때 어떻게 처리하는가?

Human-in-the-Loop (HITL) 패턴을 사용한다. 오케스트레이터가 작업을 진행하다가 중요 분기점이나 권한이 요구되는 지점(예: 배포, 코드 병합)에서 진행을 일시 정지하고 상태를 보존한 채 사용자에게 피드백을 요청한다. 이때 에이전트는 질문의 맥락과 필요 정보를 구조화해 전달해야 하며, 승인이 거부되거나 수정 요청이 들어오면 에이전트 팀이 이전 작업 상태로 롤백(Rollback)하여 피드백 내용을 반영한 뒤 다시 진행을 시도하도록 흐름을 제어한다.

자세히: 9장 · 워크플로우 디자인 패턴

workspace/variant

new-project.ts를 실행했는데 스캐폴딩이 거부되거나 경로가 이상하게 잡힌다.

워크스페이스 루트가 아닌 다른 프로젝트 폴더 안에서 실행했을 가능성이 높다. ai-workspace-standards는 반드시 워크스페이스 자체의 루트로 클론해서 써야 하며(Windows C:\git, macOS/Linux ~/git), 다른 프로젝트 폴더 안에 서브모듈처럼 넣으면 경로 계산이 어긋난다.

자세히: 6장 §1

bun run agent:verify 결과의 "Documented agents" 숫자가 예상과 다르다.

AGENTS.md 표와 실제 agents/*.md 파일 목록이 어긋난 것이다. 워크스페이스 전용 에이전트(auditor, lifecycle-manager 등)가 표에 남아 있진 않은지, 새로 만든 에이전트가 표에 빠지진 않았는지 다시 확인한다.

자세히: 6장 D-1

승격 파이프라인(l3-to-variant-pipeline.ts)을 실행해도 되는지 확신이 안 선다.

이 명령은 실제 git 이력에 흔적을 남기는 되돌리기 까다로운 작업이다. 강의·워크숍 환경이라면 참가자 전원이 실행하지 말고 강사가 한 번 시연하는 것으로 충분하다. 강의 진행 가이드에 안내가 있다.

자세히: 12장 실습

ai-workspace-standards를 실제 서비스 환경(Docker/Kubernetes)에서 쓰려면?

현재 ai-workspace-standards는 로컬 AI 코딩 도구(Claude Code/App, Antigravity, Codex 등)와 직접 연동되는 방식으로만 동작한다. Docker 또는 Kubernetes 환경에서 Open WebUI 같은 프론트엔드 서비스와 연계하여 개인 단위로 에이전트 팀을 지원하는 형태는 고도화 방향으로 논의 중이며, 아직 구현되지 않았다. 자세히: 8장 §5 고도화 로드맵

여러 프로젝트의 memory/YYYY-MM-DD.md를 한 곳에서 모아볼 수 있는가?

현재는 개별 프로젝트마다 독립적인 memory/YYYY-MM-DD.md를 유지하는 구조이며, 워크스페이스 수준에서 메모리를 취합·정리하는 기능은 고도화 방향으로 계획 중이다. 프로젝트가 늘어날수록 개별 메모리 파일에서 전체 트렌드를 파악하기 어려워지는 점을 개선할 예정이다. 자세히: 8장 §5 고도화 로드맵

variant 템플릿이 업데이트되면 기존 프로젝트에도 자동으로 반영되는가?

아니다. ai-workspace-standards는 포크 모델(Fork Model)을 사용한다. L1(공통 템플릿)의 변경은 이미 스캐폴딩된 L2 variant(templates/co-*/)나 L3 프로젝트(Projects/*/, L2 variant에서 스캐폴딩됨)에 자동으로 전파되지 않는다. 이는 의도한 차이를 보존하기 위한 설계이지만, 보안 패치나 버그 수정이 수동 반영되어야 한다는 운영 부담을 만든다. 동의 기반(consent-based) 선택적 수신 모델과 비동기 배포 파이프라인이 고도화 방향으로 거론되고 있다. 자세히: 8장 §5 고도화 로드맵

신규 베리언트(variant) 생성 시 agent:verify 검증이나 validate-templates에서 실패한다.

가장 흔한 원인은 에이전트 선언 간의 **대칭성(Symmetry) 미준수**다. 예를 들어 researcher 에이전트의 handoff_to에 writer가 지정되어 있다면, writer 에이전트의 handoff_from에도 반드시 researcher가 쌍을 이루어 정의되어 있어야 한다. 또한 variant.json 파일의 JSON 문법 에러나 필수 필드(에이전트 목록 등)가 유효한 명세인지 점검해야 한다.

자세히: 11장 §신규 variant 생성

내가 직접 설계하고 구축한 에이전트 팀이 실전에서 항상 의도한 품질로 동작하는지 어떻게 검증하는가?

정상 동작 평가를 위해 에이전트 테스트 벤치(Test Bench)를 구축해야 한다. 첫째, 대표 입력 요구사항과 예상 산출물(Gold Dataset)을 정의한다. 둘째, 프롬프트나 에이전트 규칙을 수정할 때마다 데이터셋을 투입해 회귀 테스트(Regression Test)를 자동 가동한다. 셋째, 정량 평가가 힘든 자연어 출력은 고성능 모델을 심판(LLM-as-a-Judge)으로 세워 사전에 약속된 정량 점수로 평가하도록 구현한다.

자세히: 14장 §캡스톤 실습

비용·성능

멀티 에이전트팀을 가동하면 토큰 비용이 얼마나 드는가?

비용은 에이전트 수 × 각 에이전트의 모델 티어 × 실행 빈도에 따라 결정된다. 5장에서 설명한 모델 티어링(tier: high/medium/low)은 비용 통제의 핵심 장치다. 예를 들어 co-consult 베리언트(variant)의 10명 에이전트를 모두 high로 돌리면 한 세션에 수만 토큰이 소모되지만, 실제 구현 역할을 medium/low로 내리면 비용을 40~60% 줄일 수 있다. Claude Code의 /cost 명령으로 현재 세션의 누적 토큰을 실시간 확인할 수 있다.

자세히: 5장 §templates와 variant 13종

에이전트 응답이 갑자기 느려지거나 타임아웃된다.

컨텍스트 윈도우가 가득 차면 모델 처리 속도가 급격히 느려진다. Claude Code는 /compact 명령으로 대화 길이를 압축할 수 있다. 또한 병렬로 에이전트 여러 개를 투입할 때 API 요청이 큐에 쌓여 지연되는 현상도 흔하다 — 이 경우 순차 실행으로 전환하거나 WIP 한계를 낮춰 동시 실행 수를 줄이면 된다.

자세히: 공통 참고 §1

다중 에이전트 루프나 긴 워크플로우를 실행하면 API 토큰 비용이 너무 많이 든다. 최적화 방법은?

첫째, 에이전트 역할별로 **모델 티어(Model Tier)**를 구분해 지정한다. 단순 파일 쓰기/테스트 실행은 medium/low 모델을, 전체 흐름 제어나 종합 설계는 high 모델을 배치하면 비용을 40% 이상 절감할 수 있다. 둘째, 프롬프트 캐싱(Prompt Caching)이 동작하도록 대화 맥락이 일정할 때는 시스템 프롬프트를 변경하지 않고 연속된 세션을 유지한다. 셋째, 오케스트레이터와 스페셜리스트의 대화가 무한 공회전하지 않도록 Max Turns와 같은 하드 한계값을 명확히 설정한다.

자세히: 5장 §templates와 variant 13종

플랫폼별 문제

Windows에서 new-project.ts를 실행하면 경로 구분자 오류가 난다.

ai-workspace-standards의 스크립트는 Node.js/Bun 런타임에서 path 모듈로 플랫폼별 경로를 처리하므로 기본적으로 Windows와 macOS/Linux 모두 호환된다. 하지만 Claude Code 세션 안에서 git clone 명령을 직접 실행할 때 Git Bash가 아닌 PowerShell 경로(C:\Users\...)가 섞이면 문제가 생길 수 있다. Claude Code에서는 항상 / 스타일 경로나 Git Bash 형식을 사용하고, 워크스페이스 루트는 C:\git처럼 짧고 깊지 않은 위치에 클론하는 것을 권장한다.

자세히: 6장 §1