개발자 가이드: Claude Code에서 오픈소스 정책 자동 준수
1. 이 챕터에서 하는 일
01~07챕터로 오픈소스 관리 체계 구축이 완료되었습니다. 이제 남은 과제는 일상적인 개발 과정에서 정책이 자동으로 지켜지게 하는 것입니다.
담당자가 매번 모든 PR을 검토하는 방식은 지속 가능하지 않습니다. 이 챕터는 Claude Code를 활용하여 개발자가 무의식적으로 정책을 준수하게 만드는 4가지 방법을 설명합니다.
목표: "담당자가 매번 검토하지 않아도 Claude Code가 정책을 지켜준다"
이 챕터는 앞서 구축한 우리 조직 정책(output/policy/)을 개발 일상에 자동 적용하는 4가지 방법입니다.
정책을 아직 안 세웠고 AI 코딩 도구용 Rules 파일만 빠르게 만들려면 공통 Rules 템플릿을 쓰세요.
2. 배경: 왜 자동화가 필요한가
SBOM·라이선스 관련 용어가 낯설면 용어집을 참고하세요.
실제 발생하는 문제 상황
시나리오 1: GPL 패키지 무심코 추가
개발자가 편리한 유틸리티 라이브러리를 발견합니다.
npm install some-gpl-utility를 실행하고 PR을 올립니다.
담당자가 검토하기 전까지 GPL 오염 위험이 잠재됩니다.
배포 후에 발견되면 소스코드 공개 의무가 발생할 수 있습니다.
시나리오 2: 취약한 버전 그대로 사용 의존성 업데이트 없이 오래된 버전을 계속 사용합니다. CVSS 9.0의 Critical 취약점이 공개되었지만 팀이 인지하지 못합니다. 보안 사고가 나면 "몰랐다"는 변명은 통하지 않습니다.
시나리오 3: 담당자 모르게 정책 위반
허용 라이선스 목록(license-allowlist.md)에 없는 라이선스를 가진 패키지가 추가됩니다.
사용 승인 절차(usage-approval.md)를 거치지 않고 배포됩니다.
인증 갱신 시점에서야 위반이 발견됩니다.
해결 원칙
정책 준수를 개발자의 기억과 의지에 맡기지 않습니다. 도구와 자동화가 기본값이 되게 합니다.
3. 해결 방법 개요
아래 4가지 방법을 조합하여 적용합니다. 보장 수준이 높을수록 구현 복잡도도 높아집니다.
| 방법 | 설명 | 보장 수준 | 구현 난이도 |
|---|---|---|---|
| CLAUDE.md 정책 명시 | Claude Code에게 지켜야 할 정책을 직접 알린다 | 70% | 매우 쉬움 |
| Skill 정의 | 라이선스·취약점 확인 절차를 재사용 가능한 skill로 만든다 | 80% | 쉬움 |
| Hooks 자동 검증 | 의존성 파일 변경 시 자동으로 경고를 발생시킨다 | 90% | 보통 |
| CI/CD 파이프라인 | PR 시 자동 체크, 위반 시 머지 차단 | 99% | 다소 복잡 |
완벽한 보장을 위해서는 4가지를 모두 적용해야 합니다. 각 방법은 독립적으로 작동하지만, 조합할수록 누락 위험이 줄어듭니다.
4. 각 방법 상세 가이드
가장 쉬운 방법 1부터 시작해 3·4로 보강하는 순서를 권장합니다. 아래는 핵심 예시 요약이며, 전체 설명은 각 링크 문서에 있습니다.
방법 1 — CLAUDE.md에 정책 명시 (보장 70%, 매우 쉬움)
프로젝트 루트 CLAUDE.md에 허용·금지 라이선스와 패키지 추가 절차를 적어 두면, Claude Code가 패키지 추가를 도울 때 이 정책을 자동으로 참조합니다.
## 오픈소스 정책 (자동 준수)
### 금지 라이선스
- GPL-2.0, GPL-3.0, AGPL-3.0 (Copyleft — 소스코드 공개 의무)
- 전체 허용 목록: output/policy/license-allowlist.md 참조
- 효과: Claude Code가 정책을 인지하고 위반 시 경고합니다.
- 한계: 개발자가 터미널에서 직접
npm install을 실행하면 개입하지 못합니다.
전체 예시: 방법 1: CLAUDE.md에 정책 추가하기
방법 2 — Skill로 검사 절차 표준화 (보장 80%, 쉬움)
라이선스·취약점 확인 절차를 /oss-policy-check skill로 만들어, 누구나 한 명령으로 같은 검사를 실행합니다.
npx license-checker --summary # 라이선스 수집
grype dir:. --fail-on high # 취약점 조회 (High 이상이면 실패)
- 효과: 검사 절차가 재사용 가능한 한 명령으로 표준화됩니다.
- 한계: 개발자가 실행을 잊으면 검사되지 않습니다.
전체 예시: 방법 2: Skill 정의하기
방법 3 — Hooks로 자동 환기 (보장 90%, 보통)
.claude/settings.json에 Hook을 걸어 두면, 의존성 파일이 변경될 때마다 자동으로 경고가 표시됩니다.
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "... 의존성 파일 변경 시 경고 출력 ..."
}
]
}
]
}
}
- 효과:
package.json·requirements.txt·pom.xml·go.mod등 변경 시 자동으로 환기됩니다. - 한계: Claude Code 외부에서 파일을 수정하면 감지하지 못하므로 CI/CD로 보완합니다.
전체 예시: 방법 3: Hooks 설정하기
방법 4 — CI/CD로 머지 차단 (보장 99%, 다소 복잡)
PR에서 syft·grype로 자동 검사하고, 정책 위반 시 머지를 차단합니다. 사람이나 도구의 누락과 무관하게 마지막 관문을 지킵니다.
on:
pull_request:
paths: [package.json, requirements.txt, pom.xml, go.mod]
# syft로 SBOM 생성 → grype --fail-on high 로 High 이상 취약점 차단
- 효과: 개발 환경과 무관하게 모든 PR을 강제로 검사합니다.
- 한계: 초기 설정과 예외 관리에 약간의 노력이 필요합니다.
전체 예시: 방법 4: CI/CD 파이프라인 추가하기
상황별 적용 조합 권장
네 가지를 한 번에 도입할 필요는 없습니다. 상황에 맞는 조합부터 시작하세요.
| 상황 | 권장 조합 | 이유 |
|---|---|---|
| 1~2인 소규모 / 빠른 시작 | 방법 1 + 3 | 설정이 가볍고 Claude Code 안에서 즉시 환기 |
| 정식 배포 제품 / 외부 납품 | 방법 1 + 3 + 4 | CI/CD 머지 차단으로 누락 없이 강제 검사 |
| 검사 절차를 팀 표준으로 | 위 조합 + 방법 2 | 누구나 같은 명령으로 동일한 검사 수행 |
처음에는 방법 1을 5분 만에 적용해 효과를 확인하고, 배포 빈도가 높아지면 방법 4로 강제력을 더하는 단계적 도입을 권장합니다.
5. 상세 구현 안내
각 방법의 실제 구현 예시, 트러블슈팅, 다양한 언어·빌드 시스템별 설정을 claude-oss-policy-guard 프로젝트에서 제공할 예정입니다. (준비 중)
이 챕터는 개념과 기본 예시를 제공합니다.
실제 프로덕션 환경 적용, 예외 처리, 복잡한 모노레포 구성 등은
claude-oss-policy-guard 프로젝트의 상세 가이드를 참조합니다.
6. 완료 확인
충분한 시간을 갖고 각 단계를 이해하며 진행합니다.
아래 항목을 모두 완료하면 이 챕터가 완성됩니다.
- 프로젝트
CLAUDE.md에 오픈소스 정책 섹션 추가 완료 -
.claude/skills/oss-policy-check.md생성 완료 -
/oss-policy-check실행하여 동작 확인 -
.claude/settings.jsonHook 설정 완료 - 의존성 파일 수정 시 경고 메시지 출력 확인
-
.github/workflows/oss-policy-check.yml생성 완료 - 테스트 PR을 올려 라이선스·취약점 검사 자동 실행 확인
7. 다음 단계
이 챕터까지 완료했다면, 오픈소스 관리 체계가 구축을 넘어 운영까지 완성된 것입니다.
유지 관리 권고:
- 18개월마다 OpenChain 자체 인증 갱신 (자체 인증 선언: 마지막 단계 참조)
- 분기마다
license-allowlist.md검토 및 갱신 - 신규 CVE 발생 시 grype 재스캔
더 나아가기:
- claude-oss-policy-guard 프로젝트 (준비 중)
- OpenChain 커뮤니티 참여
- 공급망 파트너와 SBOM 공유 (
output/sbom/sbom-sharing-template.md활용)