Claude Code 설정 운영 청사진: 전역 편의성과 프로젝트 경계를 분리하는 기준

문서 작성, 서비스 개발, 데이터 조회, 브라우저 자동화를 하나의 개발 환경에서 오가다 보면 설정이 빠르게 쌓입니다. 처음에는 자주 쓰는 규칙과 도구를 전역에 두는 편이 편합니다. 어느 위치에서 Claude Code를 실행해도 같은 명령과 연결을 사용할 수 있기 때문입니다.

문제는 모든 작업이 같은 위험과 같은 완료 조건을 갖지 않는다는 데 있습니다. 파일만 수정하는 업무와 외부 시스템을 조회하거나 변경하는 업무를 같은 설정 안에 넣으면, 현재 작업에 필요 없는 규칙과 도구까지 함께 따라올 수 있습니다. 설정을 나누는 목적은 저장소를 잘게 쪼개는 데 있지 않습니다. 에이전트가 한 번의 작업에서 읽고, 실행하고, 바꿀 수 있는 범위를 업무에 맞게 제한하는 데 있습니다.

기본 원칙은 다음과 같습니다. 산출물의 성격, 접근 대상, 사람의 승인 지점, 실패 후 복구 방법이 달라지면 Claude Code 설정 범위도 분리합니다. 다만 모든 설정을 폴더마다 복사할 필요는 없습니다. 개인 편의 설정은 전역에, 팀이 함께 지켜야 할 개발 원칙은 저장소에, 업무 고유 규칙과 외부 연결은 프로젝트 또는 업무 폴더에 두는 식으로 역할을 나누는 편이 관리하기 좋습니다.

저장소 구조보다 먼저 업무 경계를 정의한다

하나의 저장소에 여러 업무 폴더가 있을 수 있고, 하나의 제품 개발 업무가 여러 저장소에 걸쳐 있을 수도 있습니다. 따라서 “저장소 하나당 설정 하나”를 기계적으로 적용하기보다, Claude Code가 맡을 작업 단위를 먼저 정해야 합니다.

경계를 정할 때는 아래 네 가지를 확인합니다.

1. 만드는 결과물이 같은가
   애플리케이션 코드, 운영 문서, 분석 파일, 인프라 설정은 작성 방식뿐 아니라 검토자와 복구 방식도 다를 수 있습니다.

2. 접근해야 하는 시스템이 같은가
   이슈 트래커, 데이터베이스, 배포 환경, 브라우저 자동화처럼 MCP를 통해 접근하는 대상이 다르면 별도 설정을 검토할 이유가 생깁니다.

3. 실수했을 때 되돌리는 방법이 같은가
   Git 이력으로 되돌릴 수 있는 파일 변경과 외부 서비스에서 발생한 데이터 변경은 같은 자동 실행 기준을 적용하기 어렵습니다.

4. 규칙이 같은 의미로 유지되는가
   테스트 실행이나 코드 스타일처럼 넓게 적용할 원칙도 있습니다. 반면 특정 보고서의 파일명, 특정 데이터의 집계 기준, 특정 서비스의 배포 순서는 업무 폴더 안에 머무는 편이 자연스럽습니다.

네 질문 중 하나라도 다르다면, 설정을 분리할 후보로 볼 수 있습니다. 여기서 말하는 분리는 반드시 별도 저장소를 만들라는 뜻이 아닙니다. 같은 저장소 안에서도 업무 폴더별로 에이전트의 규칙, 스킬, 연결 도구, 실행 권한을 구분할 수 있습니다.

규칙·스킬·MCP·권한은 배치 기준이 다르다

설정 범위를 논의할 때 흔히 모든 항목을 전역 또는 프로젝트 중 한곳에 몰아넣으려 합니다. 하지만 각 항목이 미치는 영향과 변경 빈도가 다르므로, 같은 기준으로 두면 관리가 복잡해집니다.

설정 항목	우선 검토할 위치	배치 판단 기준
실행 별칭, 터미널 표시, 개인 편집 환경	전역	업무 결과물과 접근 권한을 바꾸지 않는 개인 편의 항목
코드 스타일, 테스트 원칙, 리뷰 절차	저장소 또는 추적 가능한 공용 문서	여러 작업에서 같은 뜻으로 적용되는 팀 기준
파일명, 산출물 형식, 도메인별 작업 순서	프로젝트 또는 업무 폴더	특정 업무의 입력과 결과물에 묶인 규칙
MCP 연결	필요한 프로젝트 또는 업무 폴더	해당 업무에서만 외부 시스템 접근이 필요한 경우
승인 생략, 자동 명령 실행	가능한 한 좁은 범위	작업 영향과 복구 가능성을 함께 확인해야 하는 경우

전역에는 편의 기능을 중심으로 남기고, 업무 판단이나 외부 연결을 포함하는 항목은 가까운 작업 경계에 두는 방식이 출발점으로 적합합니다. 공통 규칙도 개인의 전역 설정에만 두면 동료가 같은 환경을 재현하기 어렵습니다. 팀 규칙이라면 저장소에서 변경 이력을 남길 수 있는 위치에 두는 편이 낫습니다.

MCP는 특히 목적과 범위를 분명히 적어야 합니다. 브라우저 자동화가 필요한 업무라면 일상적으로 사용하는 브라우저와 분리된 프로필 또는 실행 환경을 고려할 수 있습니다. 개인 로그인 세션, 열어 둔 탭, 자동화 대상 계정을 섞지 않기 위해서입니다. 그러나 브라우저를 분리해도 외부 서비스에 대한 변경 권한까지 자동으로 제한되지는 않습니다. 어떤 계정으로 접속하는지, 조회만 하는지, 생성·수정·삭제까지 수행하는지를 별도 기준으로 관리해야 합니다.

요구사항 문서는 지시문보다 금지선부터 적는다

초기 설정 문서를 길게 쓰기 시작하면, 아직 겪지 않은 예외까지 미리 규칙으로 만들기 쉽습니다. 대신 각 업무 폴더에 짧은 작업 계약을 먼저 둡니다. 이 문서는 에이전트가 참고할 맥락이면서, 담당자가 설정 변경을 검토할 때 보는 기준표가 됩니다.

업무 목적:
허용된 산출물:
읽을 수 있는 경로와 시스템:
수정할 수 있는 경로와 시스템:
사용 가능한 MCP:
사람의 승인이 필요한 작업:
작업 실패 시 복구 방법:
검증 명령 또는 검토 절차:
담당자:

이 중에서 빠지기 쉬운 항목은 “사람의 승인이 필요한 작업”입니다. 외부 API 호출, 배포, 데이터 변경, 계정 관련 조작처럼 결과가 저장소 밖으로 나가는 업무는 편의성만으로 승인 절차를 없애기 어렵습니다. 복구 수단이 불명확하거나 영향 범위를 바로 확인하기 힘든 작업이라면, 실행 전 또는 실행 후에 사람이 판단하는 단계를 남겨 두는 편이 안전합니다.

반대로 제한된 경로 안의 문서 수정, 버전 관리되는 코드 변경, 테스트 실행처럼 결과를 검토하고 되돌릴 방법이 명확한 작업은 폴더 단위 자동화를 검토할 수 있습니다. 이 경우에도 권한 확인을 모두 없애기보다, 어떤 명령과 어떤 경로까지 허용할지 좁게 시작하는 편이 좋습니다.

구현은 최소 설정, 도구 목록, 실패 검증 순으로 진행한다

전사 공통 설정부터 만들기보다, 반복 업무가 있고 외부 도구가 필요한 프로젝트 하나를 골라 시작하는 편이 변경 영향을 살피기 쉽습니다. 구현 산출물은 아래 순서로 준비합니다.

1. 최소 규칙 파일

처음에는 파일 위치, 결과물 형식, 금지된 변경, 완료 조건만 적습니다. 규칙은 가상의 위험을 길게 나열하기보다, 반복된 재작업이나 실제로 혼동이 있었던 지점부터 추가합니다. 규칙이 늘어날수록 에이전트가 판단할 맥락도 많아지므로, 더 이상 필요하지 않은 항목은 정기적으로 걷어낼 수 있어야 합니다.

2. MCP와 권한 목록

연결한 도구마다 목적, 읽기·쓰기 여부, 사용 계정, 중단 조건, 담당자를 기록합니다. 어떤 도구가 왜 필요한지 설명할 수 없다면 연결을 유지할 이유도 다시 검토해야 합니다. 업무 폴더에 MCP를 둔 경우, 다른 폴더에서 같은 도구가 필요해졌다고 곧바로 전역화하지 말고 두 업무의 접근 대상과 승인 기준이 같은지 먼저 비교합니다.

3. 정상 흐름과 차단 흐름 검증

설정은 문서로만 검토하지 말고, 실제 실행 위치와 실패 상황에서 확인해야 합니다. 다음 항목을 검증 시나리오에 넣을 수 있습니다.

• 지정한 업무 폴더에서 실행했을 때 필요한 규칙과 도구만 사용할 수 있는가
• 상위 폴더나 다른 작업 폴더에서 실행했을 때 업무 전용 설정이 의도치 않게 적용되지 않는가
• 허용하지 않은 파일 경로나 외부 시스템 변경을 요청했을 때 중단하거나 승인을 요구하는가
• 작업 실패 뒤 파일, 임시 산출물, 브라우저 프로세스, 세션이 어떤 상태로 남는가
• 새 담당자가 문서와 시작 절차만으로 같은 작업 위치와 검증 과정을 재현할 수 있는가

폴더 단위 설정은 Claude Code를 시작하는 위치에 영향을 받을 수 있습니다. 따라서 팀은 어느 디렉터리에서 실행할지까지 표준으로 정해야 합니다. IDE 작업 공간, 터미널 프로필, 시작 스크립트 가운데 팀 환경에 맞는 방법 하나를 정하고, 설정이 적용되는 경로를 눈으로 확인할 수 있게 만듭니다.

운영에서는 공용화보다 변경 이유를 먼저 추적한다

업무별 설정은 시간이 지나면서 늘어납니다. 이때 중요한 것은 규칙 수를 줄이는 것보다 각 항목이 왜 존재하는지 잃지 않는 일입니다. 새 스킬, MCP, 권한 변경에는 변경 이유와 적용 범위를 함께 남깁니다. 반복 오류를 막기 위한 규칙인지, 다른 업무에서도 재사용할 수 있는 원칙인지 구분해야 합니다.

같은 이름의 작업이라고 해서 공용 스킬이 되는 것은 아닙니다. 입력 자료, 산출물 형식, 검증 절차, 실패했을 때의 영향까지 같을 때에만 공용화 후보가 됩니다. 한쪽 업무의 요구 변경이 다른 업무의 동작까지 흔들 수 있다면, 이름이 같아도 분리된 스킬이 더 나을 수 있습니다.

운영 중에는 경계가 흐려지는 신호도 살펴볼 만합니다. 문서 작업인데 관련 없는 도구가 자주 나타나거나, 담당자가 작업 시작 위치를 혼동하거나, 승인 생략 설정을 여러 폴더에 복사하는 상황이 반복된다면 범위와 권한을 다시 점검할 시점입니다. 반대로 여러 업무에서 같은 규칙을 각각 수정하고 있다면, 공용 기준으로 올릴 조건이 갖춰졌는지 검토할 수 있습니다.

다음 설정 회의에서는 전역 파일을 먼저 정리하지 않아도 됩니다. 자동화하려는 업무 하나를 고른 뒤, 그 업무가 읽을 수 있는 것, 바꿀 수 있는 것, 사람에게 넘겨야 하는 것을 한 장으로 합의하십시오. 그 문서가 있어야 규칙, 스킬, MCP, 권한을 서로 다른 범위에 배치할 근거가 생깁니다.