2026년 5월 24일 기준 공식 문서와 CLI 동작을 기준으로, 이 글은 Claude Code background agents: 병렬 작업을 안전하게 나누는 법에서 먼저 확인할 설정과 실패 지점을 정리합니다. 핵심 판단은 claude agents --json으로 세션을 확인하고, 각 agent에는 서로 다른 디렉터리나 검증 작업을 맡기며 같은 파일을 동시에 수정하지 않게 합니다.
빠른 답
claude agents --json으로 세션을 확인하고, 각 agent에는 서로 다른 디렉터리나 검증 작업을 맡기며 같은 파일을 동시에 수정하지 않게 합니다.
실무 원칙은 단순합니다. 에이전트 권한은 작업 범위보다 좁아야 합니다. 설치, 설정, MCP 도구, 저장소 지침은 일회성 준비가 아니라 코드 품질을 지키는 운영 장치로 봐야 합니다.
언제 중요한가
Claude Code background agents는 병렬 세션을 볼 수 있지만 작업 범위, 권한, 로그 확인 없이 쓰면 충돌이 생긴다. 이 설정은 긴 프롬프트 하나로 모든 일을 맡기려는 상황보다, 반복 가능한 AI agent 작업 흐름을 만들 때 중요합니다. 좋은 설정은 세 가지를 분명히 합니다. agent가 읽어도 되는 것, 바꿔도 되는 것, 사람이 검증할 방법입니다.
팀에 도입한다면 넓게 쓰기 전에 결정을 문서화하세요. 어떤 계정이나 인증 방식을 쓸지, 어느 디렉터리에서 시작할지, 어떤 파일은 건드리면 안 되는지, 어떤 명령이 통과 기준인지 먼저 정해야 합니다.
기본 명령
claude agents --json
claude agents --cwd .
claude logs <session-id>
claude attach <session-id>
명령은 agent가 실제로 작업할 같은 셸과 프로젝트 루트에서 실행하세요. 어떤 터미널에서는 되고 다른 터미널에서는 안 된다면, 코드 수정 전에 PATH, 셸, 계정, 현재 디렉터리 문제를 먼저 해결해야 합니다.
설정 패턴
For dispatched sessions, pass explicit --cwd, --permission-mode, --model, or --effort instead of relying on memory.
이 블록은 그대로 복사할 정답이 아니라 시작 패턴입니다. 개인 노트북, 회사 보안 장비, CI 작업은 같은 권한 모델을 쓰면 안 됩니다. 저장소 테스트와 롤백 경로가 분명해질 때까지는 읽기 전용 또는 계획 모드가 안전합니다.
반복해서 쓸 설정이라면 저장소 옆에 짧은 운영 메모를 남기세요. CLI 버전, 선택한 permission mode, 실제로 로드된 지침 파일, 마지막 검증 명령을 함께 적어두면 팀원이 다른 결과를 봤을 때 기준선을 빠르게 맞출 수 있습니다.
검증 체크리스트
- one branch or worktree per editing agent.
- clear owner for each task.
- read logs before merging results.
설정이 동작하면 바로 편집을 맡기지 말고 먼저 읽기 전용 요약을 요청하세요. 그다음 좁은 계획을 요청합니다. 두 응답이 저장소 현실과 맞을 때만 파일 수정이나 외부 도구 호출을 허용하는 편이 안전합니다.
흔한 실수
- parallel agents editing shared files.
- losing session IDs.
- treating background output as reviewed code.
비싼 실수는 대개 모델 답변 하나가 틀린 것이 아니라 운영 경계가 모호한 것입니다. 인증, MCP scope, 설정 우선순위, 지침 파일이 불명확하면 세션은 생산적으로 보이지만 위험은 코드 리뷰 단계로 밀려납니다.
자주 묻는 질문
전역 설정과 프로젝트 설정 중 어디에 둬야 하나요?
개인 취향은 전역에 두고, 저장소 규칙은 프로젝트 파일에 둡니다. 그래야 팀원과 이후 세션이 같은 제약을 봅니다. 비밀값, 개인 로컬 경로, 실험 설정은 커밋되는 프로젝트 파일에 넣지 않습니다.
언제 agent에게 파일 수정을 허용해야 하나요?
agent가 작업 목표, 수정할 파일, 검증 명령을 먼저 정확히 말할 수 있을 때 허용합니다. 낯선 저장소에서는 계획 모드나 읽기 전용 검토부터 시작하세요.
설정이 끝난 뒤 무엇을 기록해야 하나요?
설치 방식, 버전 확인, 계정 또는 API 키 정책, permission mode, 지침 파일 위치, MCP scope, 첫 검증 명령을 기록합니다. 그래야 다음 세션도 같은 기준에서 시작할 수 있습니다.
Leave a comment