직군별 활용2026-09-08

개발팀의 Claude Code 도입 순서 — CLAUDE.md, 스킬, 훅, CI

개발팀의 AI 도입은 다른 직군과 출발점이 다릅니다. 이미 각자 쓰고 있습니다. 문제는 "쓰느냐"가 아니라 팀이 같은 규칙으로 쓰느냐입니다. 한 사람은 테스트 없이 커밋하게 두고 다른 사람은 린트를 강제하면, 에이전트가 만든 코드의 품질이 사람마다 달라지고 리뷰 부담이 늘어납니다. 이 글은 팀 단위로 규칙을 올리는 네 단계를 순서대로 적습니다. 네 단계는 CCAR-F 도메인 3(Claude Code 설정과 워크플로, 20%)의 수업 순서와 같습니다.

1단계: 저장소 규칙을 CLAUDE.md에 (첫 주)

에이전트가 저장소를 열 때 가장 먼저 읽는 파일이 CLAUDE.md입니다. 여기에 빌드·테스트 명령, 코드 스타일, 건드리면 안 되는 디렉터리, 커밋 메시지 규칙을 적습니다. 개인 취향은 사용자 메모리에, 팀 규칙은 프로젝트 파일에, 하위 모듈 규칙은 하위 디렉터리에 두는 3계층 구조를 씁니다.

검증할 것: 새 팀원이 CLAUDE.md만 읽고 첫 작업을 에이전트에게 시켰을 때 빌드가 통과하는가. 통과하지 못하면 파일에 빠진 것이 있습니다. 규칙이 서로 충돌하는지도 봅니다. 수업 CLAUDE.md 계층 구조가 충돌 실험까지 실습합니다. 설정 방법 전체는 CLAUDE.md로 Claude Code 설정하기에 정리돼 있습니다.

2단계: 반복 절차를 스킬과 명령어로 (둘째 주)

"PR 설명 써 줘", "이 모듈 테스트 뼈대 만들어 줘"처럼 팀에서 매일 반복하는 요청을 슬래시 명령어와 스킬로 굳힙니다. 명령어는 짧은 지시를, 스킬은 절차와 보조 파일을 담습니다. 스킬의 설명(description)이 좋아야 에이전트가 알맞은 때에 스스로 꺼내 씁니다.

검증할 것: 같은 스킬을 세 사람이 각자 돌렸을 때 결과 형식이 같은가. 다르면 스킬이 아니라 사람의 추가 지시에 의존하고 있는 것입니다. 수업 슬래시 명령어와 스킬이 description 품질 실험을 포함합니다.

3단계: 지켜야 할 규칙을 훅으로 강제 (셋째 주)

CLAUDE.md에 적은 규칙은 권고입니다. 모델이 판단해서 따릅니다. 반드시 지켜야 하는 것(프로덕션 설정 파일 수정 금지, 커밋 전 린트, 위험한 명령 차단)은 훅(hook)으로 옮깁니다. 훅은 툴 호출 전후에 코드로 실행되므로 모델의 판단과 무관하게 강제됩니다. 경로별 규칙과 권한 모드를 함께 정하면 "이 디렉터리는 읽기만, 저 디렉터리는 승인 후 쓰기"가 됩니다.

검증할 것: 훅이 막아야 할 행동을 일부러 시켜 봅니다. 막히지 않으면 훅이 아니라 권고입니다. 수업 경로별 규칙과 Agent SDK와 훅이 이 설계입니다. 에이전트에게 권한을 어디까지 줄지의 원칙은 챗봇·어시스턴트·에이전트에 있습니다.

4단계: CI에 넣기 (넷째 주)

사람이 켜야 도는 에이전트는 팀 규모가 커지면 안 돌아갑니다. PR이 열리면 자동으로 리뷰 코멘트를 달고, 실패한 테스트의 원인 후보를 적어 두고, 문서 변경을 제안하는 흐름을 헤드리스 모드로 CI에 붙입니다. 여기서는 에이전트가 쓰기 권한을 갖지 않게 합니다. 코멘트와 제안까지, 병합은 사람이 합니다.

검증할 것: CI 에이전트의 코멘트 중 사람이 실제로 반영한 비율을 한 달간 셉니다. 낮으면 노이즈이고, 노이즈는 곧 무시됩니다. 수업 CI/CD 통합이 헤드리스 실행을 실습합니다.

네 단계를 지탱하는 것: 평가

각 단계에서 "검증할 것"은 전부 측정입니다. 빌드 통과율, 결과 일치율, 차단 성공 여부, 반영 비율. 이 숫자가 없으면 도입이 잘되고 있는지 감으로 판단하게 되고, 감은 사람마다 다릅니다. 생산성 수치를 발표한 실험이 실제로 무엇을 쟀는지는 스테이지의 55.8% 빨라졌다는 그 실험, 끝까지 읽어보면이 뜯어 봤습니다. 남의 숫자를 믿기 전에 우리 숫자를 만들어야 하는 이유입니다.

하지 말 것

시크릿과 키를 CLAUDE.md나 스킬에 적지 않습니다. 에이전트가 읽는 파일은 커밋되고 공유됩니다. 개발자 수업 신원과 비밀값, 키 관리
훅 없이 실행 권한을 넓히지 않습니다. 편의를 위해 권한 확인을 끄면, 그 순간부터 모든 실수가 즉시 실제 변화가 됩니다.
첫 달에 CI 에이전트에 병합 권한을 주지 않습니다. 코멘트 반영률이 안정된 뒤에 검토합니다.

이어지는 학습

네 단계가 자리 잡으면 다음은 서브에이전트 분업입니다. 조사·구현·검토를 서로 다른 에이전트에 나눠 맡기고 구현한 쪽이 자기 결과를 판정하지 않게 하는 구조인데, 오케스트레이션 패턴과 수업 서브에이전트 호출과 컨텍스트가 그 설계입니다.

시험과의 연결: 이 글의 네 단계는 CCAR-F 도메인 3의 수업 여섯 편 중 넷과 일대일로 대응합니다. 개발자 자격증(CCDV-F)에서는 도메인 7(보안과 안전)의 훅·가드레일 문항이 3단계를 묻습니다.

응시 안내: Claude 자격증은 Claude Partner Network 소속 조직의 회사 이메일로만 등록할 수 있고, 개인 이메일로는 응시할 수 없습니다. 자격증보다 도메인 학습 자체에 무게를 두시고, 응시 조건은 자격증 가이드에서 확인하시기 바랍니다.