Claude Code를 팀에 도입하기 전에 만드는 '위험 대장'의 속살

금요일 저녁, 동료가 “Claude Code 진짜 편하던데, 다음 주부터 다 같이 쓰자”라고 꺼냈습니다.

저는 불길한 예감이 들었습니다. 그가 혼자 쓸 때는 자기 브랜치를 자기가 리뷰하고 자기가 머지했습니다. 사고가 나도 피해는 본인뿐이죠. 그런데 팀으로 쓰게 되면 이야기가 달라집니다. 누구의 허락으로, 어디까지 건드리게 하고, 누가 변경을 확인할 것인가. 이게 정해지지 않은 채 6명이 쓰기 시작하면, 운영 DB를 날리는 변경이 어느새 머지되어 있는 일이 흔하게 일어납니다.

실제로 다른 팀에서 이걸 겪었습니다. 세 명이 각자 자기 방식대로 Claude Code를 돌리다가, 한 명이 “보기 좋게 정리해 줘”라고 부탁했더니 공용 설정 파일이 덮어써졌고, 월요일 아침에 배포가 전부 깨졌습니다. 원인 찾는 데만 반나절. 누구도 나쁜 의도는 없었습니다. 그저 “팀으로 맡길 때의 규칙”이 없었을 뿐이죠.

그래서 만든 게 이 글에서 소개하는 위험 대장입니다. 대장이라고 해봐야 표 한 장이 전부입니다. 하지만 이게 있느냐 없느냐에 따라, Claude Code 팀 도입이 “편해졌다”로 끝날지 “사고 수습으로 진을 빼는” 일로 끝날지가 갈립니다.

핵심 요약

• 팀 도입 사고는 모델이 똑똑하냐가 아니라 “누가·어디까지·누구의 확인으로”가 정해지지 않아서 일어난다.
• 위험 대장이란 위험한 영역마다 “담당·검증 방법·다음으로 넘어갈 조건”을 한 줄로 적은 표를 말한다. 처음엔 세 줄이면 충분하다.
• 권한(어떤 파일을 건드리게 할지), CI(변경이 깨지지 않았다는 증거), 배포(운영 반영 확인) 세 가지를 가장 먼저 굳힌다.
• Claude Code에 맡기는 건 “초안과 검증 실행”까지. 삭제·운영 DB·과금·force push는 반드시 사람이 승인한다.
• 복붙해서 돌아가는 대장 템플릿과, 위험한 작업을 막는 설정 예시를 실었다. 우선 파일 하나로만 시험하는 게 요령이다.

위험 대장, 결국 뭔가요?

위험 대장은 Claude Code에게 팀으로 일을 맡길 때 “사고 나기 쉬운 곳”을 한눈에 정리한 표입니다.

각 행은 단 세 개의 열이면 됩니다. 어디가 위험한가, 그게 안전하다고 말할 증거는 무엇인가, 누가 그 확인을 하는가. 이게 전부입니다. 거창한 관리 도구는 필요 없습니다. 처음엔 스프레드시트 한 장, 아니면 코드 안의 배열만으로도 충분합니다.

왜 표로 만드냐면, “그냥 알아서 조심하자”가 제일 위험하기 때문입니다. 사람은 바쁘면 반드시 확인을 건너뜁니다. 표로 만들어 “이 행이 다 채워질 때까지 머지 안 한다”고 정해 두면, 바쁜 금요일 저녁에도 사고가 멈춥니다. 앞서 말한 배포 사고도, 공용 설정 파일을 “건드리면 안 되는 영역”으로 한 줄만 적어 뒀다면 막을 수 있었습니다.

가장 먼저 굳힐 세 가지 위험 지점

팀 도입에서 넘어지는 지점은 대개 다음 세 가지로 모입니다. 거꾸로 말하면, 여기만 대장에 적어 두면 첫날의 큰 사고는 거의 막을 수 있습니다.

1. 권한 (어떤 파일을 건드리게 할지)

가장 흔한 사고가 “너무 많이 건드리게 한 것”입니다. “리포지토리를 정리해 줘”라고 부탁하면, Claude Code는 설정 파일도 CI 정의도 아무렇지 않게 고칩니다. 그래서 편집해도 되는 곳과 절대 건드리면 안 되는 곳을 먼저 정해서 글로 남깁니다.

제 기준은 단순합니다. 글이나 초안, 테스트 코드는 건드려도 OK. .github/, 운영 환경 변수, 배포 설정, 데이터베이스 마이그레이션은 “사람이 확인할 때까지 멈춘다”. 이 선 긋기를 각자 취향에 맡기면 사람마다 규칙이 제각각이 되고, 결국 가장 느슨한 사람의 설정이 사고를 냅니다. 팀에서 하나로 맞추는 게 핵심입니다.

2. CI (깨지지 않았다는 증거를 내놓게 한다)

Claude Code가 “고쳤습니다”라고 말해도, 그건 감상이지 증거가 아닙니다. 그래서 변경이 깨지지 않았다는 증거를 내놓는 명령을 대장에 적어 둡니다. 빌드가 통과한다, 테스트가 초록이 된다, 타입 에러가 없다. 이 중 하나를 “성공 보고 전에 반드시 실행한다”고 정합니다.

여기서 중요한 건 검증 명령을 빠르게 해 두는 것입니다. 전체 테스트에 10분이 걸리면 아무도 돌리지 않습니다. 변경한 파일과 관련된 테스트만 30초 안에 돌릴 수 있게 해 두면, 확인이 습관이 됩니다.

3. 배포 (운영에 나가는 변경은 반드시 본다)

블로그 수익 페이지든 API든, 밖으로 나가는 변경은 “진짜 URL로 봤는가”를 남깁니다. 빌드가 통과한 것과, 실제로 사용자가 보는 페이지가 맞는 것은 별개의 문제입니다. 운영 URL을 열어 스크린샷을 한 장 남깁니다. 이걸 완료 조건으로 삼습니다.

공개 URL이 200을 반환해도, 내용이 다른 페이지면 미배포와 같습니다. 한국어 페이지인데 영어 본문이 섞여 있다면 그것도 미완성입니다. 당연해 보여도, 급한 날일수록 여기를 건너뜁니다.

AI에 맡길 범위와, 사람이 정할 범위

선 긋기에서 망설여지면 이 표를 그대로 쓰세요. “되돌릴 수 있는가”가 판단 축입니다.

작업	Claude Code에 맡김	사람이 승인한 뒤 실행
초안 작성·수정	◯
테스트·빌드 실행	◯
변경 내용 설명 (diff 요약)	◯
파일 삭제		◯
운영 데이터베이스 쓰기		◯
과금이 발생하는 작업		◯
force push·히스토리 다시 쓰기		◯
배포·운영 공개		◯

규칙은 하나. 되돌리기 힘든 작업은 처음엔 전부 “사람에게 묻기”로 둔다. 안전하다고 확인된 작업만 나중에 자동으로 승격합니다. 처음부터 느슨하게 해서 사고 내는 것보다, 빡빡하게 해서 조금씩 푸는 쪽이 결과적으로 빠릅니다.

복붙해서 쓰는 위험 대장 템플릿

우선 부탁하기 전에, Claude Code에 건넬 지시문을 템플릿으로 만듭니다. 이걸 매번 붙여 넣기만 해도 제멋대로 범위가 넓어지는 걸 막을 수 있습니다.

작업 전에 다음을 지켜 주세요.
- 편집해도 되는 곳은 src/content/ 와 tests/ 안뿐입니다.
- .github/, 운영 환경 변수, 배포 설정, DB 마이그레이션은 건드리지 않습니다. 건드릴 필요가 있으면 편집하지 말고 이유를 보고합니다.
- 변경 후에는 반드시 `npm run check` 를 실행하고 결과를 보고합니다.
- 삭제·운영 DB·과금·force push 가 필요해지면 실행하지 말고 확인을 요청합니다.
편집 전에, 위 제약을 자기 말로 다시 정리한 다음 작업을 시작해 주세요.

그리고 대장 그 자체. 처음엔 세 줄이면 충분합니다. 자기 팀의 위험 지점으로 바꿔 넣으세요.

// 팀 도입 위험 대장: 위험 지점마다 "담당·증거·다음으로 넘어갈 조건"을 한 줄로 적는다
type RolloutRisk = {
  area: string;       // 위험한 영역
  risk: string;       // 무슨 일이 일어날 수 있는가
  owner: string;      // 확인하는 담당
  proof: string;      // 안전하다고 말할 증거
  nextGate: string;   // 다음으로 넘어가도 되는 조건
};

const rolloutRisks: RolloutRisk[] = [
  {
    area: "권한",
    risk: "Claude Code가 공용 설정까지 덮어쓴다",
    owner: "리드",
    proof: "편집 가능·편집 금지 목록이 문서화되어 있다",
    nextGate: "우선 파일 하나로만 시험한다",
  },
  {
    area: "CI",
    risk: "검증 명령이 느리거나 아예 없다",
    owner: "개발 담당",
    proof: "빌드가 초록, 또는 관련 테스트만 초록",
    nextGate: "PR 템플릿에 검증 절차를 넣는다",
  },
  {
    area: "배포",
    risk: "운영에 나가는 변경을 실물로 확인하지 않았다",
    owner: "운영 담당",
    proof: "공개 URL의 스크린샷",
    nextGate: "되돌리는 절차를 메모로 남긴다",
  },
];

console.table(rolloutRisks);

node로 돌아가게 저장해서 실행하면 표가 출력됩니다. 화려하진 않지만, 가치는 “작업을 시작하기 전에 위험 지점을 말로 표현할 수 있다”는 데 있습니다. 각 행이 다 채워질 때까지 머지 안 한다는 규칙으로 두면, 대장이 사고의 문지기가 됩니다.

이런 팀에서 효과가 난다 (실제 예시 3가지)

비슷한 상황이 있으면 대장을 새로 만들지 말고 이름만 바꿔서 쓰세요.

1. 둘이서 하는 작은 팀 공용 코드를 건드리기 전에, 편집해도 되는 곳·건드리면 안 되는 곳·사람의 승인이 필요한 작업을 함께 읽어 보고 한 장으로 만듭니다. 이것만으로 “한쪽이 모르는 사이에 설정을 깨는” 사고가 사라집니다. 작은 팀일수록 “말 안 해도 알겠지”로 사고가 나니, 처음에 글로 남기는 가치가 큽니다.

2. 리뷰를 거치는 팀 리드는, Claude Code가 만든 변경이 리뷰로 넘어가기 전에 “검증 명령을 실행한 결과”와 “변경점 요약”을 필수로 만듭니다. 이게 없는 PR은 보지 않는다고 정하는 거죠. 리뷰어가 diff를 읽고, 검증을 다시 돌리고, 되돌리는 법을 설명할 수 있는 상태까지 가져가는 게 목표입니다.

3. 수익 페이지를 가진 팀 블로그나 상품 페이지처럼 돈에 직결되는 페이지의 변경은, 완료로 처리하기 전에 공개 URL의 스크린샷을 남깁니다. “빌드 통과”로 끝내지 말고, 사용자가 실제로 보는 화면을 확인합니다. 제목·본문·이미지·동선이 의도대로인지를 눈으로 봅니다.

자주 하는 실패와, 그 고치는 법

솔직히 적자면, 이 대장도 처음엔 잘 돌아가지 않았습니다. 삽질 세 가지를 공유합니다.

각자 자기 규칙을 만들었다 처음에 설정을 개인에게 맡겼더니, 사람마다 편집 가능한 범위가 제각각이 되었습니다. 가장 느슨한 설정의 사람이 사고를 냅니다. 고치는 법은 단순합니다. 편집 가능·금지 목록을 팀에서 하나로 통일해 리포지토리에 두었습니다.

CI 실패를 뒤로 미뤘다 “나중에 한꺼번에 고치자”가 입버릇이 되면, 첫 팀 도입이 “Claude Code 넣었더니 깨진다”는 나쁜 인상으로 끝납니다. 검증 명령이 떨어지면 그 자리에서 멈추고, 초록이 될 때까지 드래프트 취급하는 규칙으로 바꿨습니다.

담당을 애매하게 둔 채 어려운 판단을 피했다 “누가 승인할지”를 정하지 않으면, 가장 어려운 운영 반영 판단이 공중에 떠 버립니다. 대장의 owner 열을 반드시 채운다. 빈칸인 채로 진행하지 않는다. 이것만으로 판단이 멈추지 않게 되었습니다.

작업이 슬슬 넓어진다고 느끼면, 지시문 전체를 다시 쓰는 게 아니라 건드리는 범위를 좁힌다·검증을 먼저 내놓게 한다·확인 담당을 한 명 정한다의 순서로 조입니다. 실패를 팀 안에 공유로 남기는 것도 중요합니다. 성공 사례만 보면, 자신이 위험한 상태에 들어가 있다는 걸 알아채지 못합니다.

자주 묻는 질문

Q. 작은 팀에도 대장이 필요한가요? 둘이어도 필요합니다. 오히려 소수일수록 “말 안 해도 알겠지”라고 착각해서 사고가 납니다. 처음엔 세 줄짜리 템플릿이면 충분하니, 5분 만에 만들어 공유하세요. 막 도입하는 단계라면 Claude Code 시작 가이드부터 함께 보면 좋습니다.

Q. Claude Code의 권한 설정만으로는 부족한가요? 권한 설정은 “건드리지 못하게 하는 장치”이고, 대장은 “누가 무엇으로 확인하는가”의 운영 규칙입니다. 둘 다 필요합니다. 설정으로 기술적으로 막고, 대장으로 사람의 확인을 돌립니다. 자세한 건 권한 설정 가이드를 보세요.

Q. 검증 명령은 무엇을 고르면 되나요? 그 팀에서 “깨지지 않았다”고 말할 수 있는 가장 짧은 명령입니다. 타입 체크, 관련 테스트만 실행, 빌드 중 하나. 전체 테스트로 10분이 걸리면 아무도 안 돌리니, 우선 30초 안에 끝나는 걸 하나 정합니다.

Q. 엔지니어가 아닌 멤버가 있어도 돌아가나요? 돌아갑니다. 대장은 표를 읽고 채우기만 하면 되니, 코드를 못 읽어도 운영할 수 있습니다. 비엔지니어를 위한 시작법은 비엔지니어를 위한 사용법이 참고가 됩니다.

Q. 프로젝트 고유 규칙은 어디에 적으면 되나요? 리포지토리의 CLAUDE.md에 적으면 Claude Code가 매번 읽어 줍니다. 편집 금지 영역이나 검증 명령을 여기에 모으면 대장과 일치시키기 쉽습니다. 적는 법은 CLAUDE.md 작성법에 정리해 두었습니다. Anthropic 공식 Claude Code 문서도 1차 정보로 확인하세요.

실제로 시험해 본 결과

앞서 말한 배포 사고 이후, 저는 “Claude Code를 믿을까”로 고민하는 걸 그만뒀습니다. 대신 보는 건, 대장의 어떤 행이 채워지지 않았는가입니다.

실제로 세 줄짜리 대장을 도입하고, 공용 설정 파일을 “건드리면 안 되는 영역”으로 명문화했더니, 설정을 깨는 머지가 0이 되었습니다. 검증 명령을 “성공 보고 전에 필수”로 했더니, 리뷰에서야 처음 깨진 걸 알아채는 일이 없어지고, 되돌림이 눈에 띄게 줄었습니다. 공개 페이지에 스크린샷 확인을 넣고 나서는, “빌드는 통과했는데 다른 페이지가 나가 있던” 누락도 멈췄습니다.

확인한 건 이 세 가지뿐입니다. 똑똑한 에이전트를 찾기보다, 넘어져도 되돌릴 수 있는 운영을 먼저 만든다. 돌아가는 것처럼 보여도, 팀 도입에서는 이게 가장 빠르다는 게 지금의 실감입니다.

회사에서 Claude Code 도입을 본격적으로 진행하고 싶다, 운영 규칙을 함께 설계하고 싶다는 단계라면, 연수·상담에서 구체적인 절차까지 함께 짤 수 있습니다. 우선 자기 팀의 위험 지점을 세 줄, 적어 보는 것부터 시작하세요.