Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 16. 05:46

Claude Code와 Cursor를 사용하여 팀을 위한 AI 거버넌스 기반 SDLC를 구축하고 Docker로 로컬에서 실행하는 방법

요약

Claude Code와 Cursor를 활용하여 AI 생성 코드가 포함된 SDLC에 거버넌스를 구축하는 방법을 다룹니다. CLAUDE.md와 .cursorrules를 통해 IDE 단계에서 보안 및 코딩 표준을 강제하는 아키텍처를 제안합니다.

핵심 포인트

  • IDE 단계(CLAUDE.md, .cursorrules)에서 AI 가드레일 설정의 중요성
  • AI 지원 커밋 식별을 위한 태그 컨벤션 적용
  • 보안 및 컴플라이언스를 위한 AI 거버넌스 파이프라인 구축
  • 로컬 환경 중심의 데이터 유출 방지 아키텍처

내가 해결하려 했던 문제

AI 코딩 어시스턴트(AI coding assistants)는 개발자가 일하는 방식을 근본적으로 변화시켰습니다. Claude Code, Cursor, GitHub Copilot 등; 여러분의 팀은 공식적으로 승인되었든 아니든 이미 이들을 사용하고 있을 것입니다.

하지만 아무도 이야기하지 않는 사실이 있습니다: AI가 생성한 코드가 저장소(repo)에 들어온 후에는 어떤 일이 벌어질까요?

아키텍트로서 내가 계속 마주쳤던 몇 가지 어려운 질문들이 있었습니다:

  • AI 도구가 소스 코드에 비밀번호나 API 키를 유출하지 않았음을 어떻게 확인할 수 있는가?
  • Claude Code나 Cursor가 코드베이스 내에서 수행할 수 있는 작업에 대해 어떻게 가드레일(guardrails)을 강제할 것인가?
  • AI 도입의 ROI(투자 대비 효과)를 어떻게 측정할 것인가 - 단순한 느낌이 아니라 실제 지표로써 말이다.
  • 보안 및 컴플라이언스(compliance) 팀에게 AI 지원 변경 사항에 대한 감사 추적(audit trail)을 어떻게 제공할 것인가?

나는 준비된 답을 찾지 못했고, 그래서 직접 만들었습니다.

내가 만든 것: AI 거버넌스 기반 SDLC

아이디어는 간단했습니다: 거버넌스 목적으로 단 1바이트의 데이터도 클라우드로 보내지 않으면서, AI 지원 개발을 관찰 가능하고 정책이 강제되는 파이프라인(pipeline)으로 감싸는 것입니다.

전체 아키텍처는 다음과 같습니다:

┌─────────────────────────────────────────────────────────────────────┐
│                     LOCAL WINDOWS WORKSTATION                        │
│                                                                       │
...

모든 계층(layer)과 그 뒤에 숨겨진 아키텍처 결정 사항들을 하나씩 살펴보겠습니다.

계층 1: AI 가드레일 설정 (단 한 줄의 코드가 커밋되기 전)

첫 번째이자 가장 과소평가된 계층은 저장소 내에서 AI 도구가 무엇을 할 수 있는지 제어하는 것입니다. 이는 코드가 개발자의 머신을 떠나기 전에 발생합니다.

CLAUDE.md

Claude Code는 저장소 루트에 있는 CLAUDE.md 파일을 준수합니다. 이것을 AI의 온보딩 문서(onboarding doc)와 교전 규칙(rules of engagement)이 결합된 것이라고 생각하면 됩니다. 나의 파일에는 다음 내용이 포함되어 있습니다:

  • 준수해야 할 코딩 표준 및 패턴 (Coding standards and patterns)
  • 접근 금지 파일 및 디렉토리 (.env, secrets, 인프라 설정 등)
  • 태그 컨벤션 (Tag convention): 모든 AI 지원 커밋 (AI-assisted commit) 메시지에는 [AI-ASSISTED]를 포함해야 함
  • 컨텍스트 유실을 방지하기 위한 코드베이스의 역할에 대한 리마인더 (Reminder)

.cursorrules

Cursor는 .cursorrules를 읽습니다. 개념은 동일하지만 형식이 다릅니다. 저는 보안 규칙, 준수해야 할 아키텍처 패턴 (Architecture patterns), 그리고 유지해야 할 프레임워크 (Frameworks)를 정의합니다.

이것이 아키텍처 측면에서 중요한 이유

대부분의 팀은 AI 거버넌스 (AI governance)가 파이프라인에서 시작된다고 생각합니다. 그렇지 않습니다. 그것은 IDE에서 시작됩니다. 이러한 설정 파일들은 여러분의 첫 번째 방어선입니다. 또한 이 파일들은 버전 관리 (Version-controlled)가 가능하며, 리뷰할 수 있고, PR 정책을 통해 강제할 수 있습니다.

레이어 2: Jenkins CI/CD - 자동화된 품질 게이트 (Automated Quality Gate)

개발자(PoC를 위해 Git worktrees를 통해 시뮬레이션됨)의 모든 푸시(Push)는 casc.yaml을 통해 코드로 구성된 Jenkins 파이프라인을 트리거합니다. 클릭 한 번 없이 프로비저닝 (Zero-click provisioning)됩니다.

파이프라인은 다음 6개 단계를 순서대로 실행합니다:

스테이지 1: detect-secrets (비밀 정보 스캐닝, Secret Scanning)

stage('Secret Scanning') {
    steps {
        sh 'detect-secrets scan --baseline .secrets.baseline'
...

사람이든 AI든 개발자가 비밀번호, API 키 또는 연결 문자열 (Connection string)을 하드코딩하면, 이 단계에서 파이프라인을 차단 (BLOCKs) 합니다. 예외는 없습니다.

저는 PoC에서 이를 의도적으로 테스트했습니다:

echo 'DB_PASSWORD = "super-secret-password-123"' >> app/src/main.py
git add . && git commit -m "feat: add database connection"
git push origin feat/dev1-auth-module
...

마지막 부분인 Grafana에서 지표가 증가하는 것이 바로 이것을 단순한 체크가 아닌 '거버넌스'로 만드는 요소입니다.

스테이지 2: Semgrep SAST

모든 푸시에 대해 정적 분석 (Static analysis)이 실행됩니다. 탐지된 결과는 심각도 (Severity)에 따라 분류되어 지표 (Metrics)로 전송됩니다:

sast_findings_total{severity="high"}
sast_findings_total{severity="medium"}
sast_findings_total{severity="low"}

스테이지 3: AI 정책 체크 (AI Policy Check)

이 단계는 AI 지원 커밋(AI-assisted commits)이 올바르게 태그되었는지([AI-ASSISTED] 컨벤션)를 검증합니다. 가벼운 과정이지만, 컴플라이언스(Compliance) 팀이 필요로 하는 감사 추적(Audit trail)을 생성합니다.

스테이지 4: pytest + Coverage

자동화된 테스트가 실행되며, test_coverage_percent가 Prometheus로 푸시(Push)됩니다. 만약 AI 테스트 생성(AI Test Generation) 에이전트(자세한 내용은 아래 참조)를 사용 중이라면, 커버리지(Coverage) 추이를 실시간으로 확인할 수 있습니다.

스테이지 5 & 6: Metrics Push + Notification

모든 메트릭(Metrics)은 다음과 같은 흐름으로 전달됩니다: Jenkins → Prometheus Pushgateway (:9091) → Prometheus (:9090) → Grafana (:3001)

레이어 3: CrewAI 에이전트 - 에이전트 기반 SDLC 역할 (Agentic SDLC Roles)

여기서부터 흥미로워집니다. 세 명의 CrewAI 에이전트가 전통적으로 숙련된 인간의 리소스가 필요한 역할들을 처리합니다.

코드 리뷰 에이전트 (Code Review Agent)

poetry run python agents/code_review_agent.py \
  --branch feat/dev1-auth-module \
  --output reports/review-dev1.md

아키텍처 표준(Architectural standards), 보안 패턴(Security patterns), 그리고 코드베이스 컨벤션(Codebase conventions)에 따라 차이점(Diff)을 검토합니다. 구조화된 마크다운(Markdown) 보고서를 출력합니다.

테스트 생성 에이전트 (Test Generation Agent)

poetry run python agents/test_gen_agent.py \
  --source app/src/ \
  --output app/tests/generated/

기존 소스 코드에 대한 pytest 테스트 케이스를 생성합니다. 샘플 앱을 대상으로 한 벤치마크 결과, 이 에이전트는 첫 실행에서 커버리지를 지속적으로 70% 이상으로 끌어올렸습니다.

아키텍처 리뷰 에이전트 (Architecture Review Agent)

poetry run python agents/arch_review_agent.py \
  --readme README.md \
  --output reports/arch-review.md

README에 기록된 아키텍처 결정 사항들을 베스트 프랙티스(Best practices)와 비교하여 검토합니다. PoC(Proof of Concept) 검증 및 지속적인 ADR(Architecture Decision Record) 관리(Hygiene)에 유용합니다.

여기서 핵심적인 아키텍처 결정 사항은 다음과 같습니다: 에이전트는 메인 파이프라인의 일부가 아니라 스크립트로 호출됩니다. 이를 통해 에이전트 기반 작업은 온디맨드(On-demand) 또는 비동기(Asynchronously)로 실행되는 동안, CI 파이프라인은 빠르고 결정론적(Deterministic)인 상태를 유지할 수 있습니다.

레이어 4: Grafana 관측성 (Observability) - 세 개의 대시보드

Grafana는 grafana/dashboards/에서 자동으로 프로비저닝(Auto-provisioned)되므로 수동 임포트가 필요하지 않습니다. 서로 다른 이해관계자를 대상으로 하는 세 개의 대시보드가 준비되어 있습니다:

대시보드 1: AI SDLC 상태 (AI SDLC Health)

엔지니어링 팀 및 DevOps를 위한 대시보드입니다. 다음 항목을 보여줍니다:

  • 시간에 따른 파이프라인 (Pipeline) 통과/실패율
  • 심각도별 SAST (정적 애플리케이션 보안 테스트) 탐지 트렌드
  • 비밀 정보 유출 (Secret leak) 시도 횟수
  • 테스트 커버리지 (Test coverage) 백분율 트렌드
  • 파이프라인 소요 시간 (개발자 피드백 루프 속도의 대리 지표)

대시보드 2: 도입 및 ROI (Adoption & ROI)

엔지니어링 리더십을 위한 대시보드입니다. 다음 항목을 보여줍니다:

  • ai_suggestions_accepted_total 대 ai_suggestions_rejected_total - 수락률 (Acceptance rate)을 통해 AI 도구가 얼마나 잘 조정(Calibrated)되어 있는지 알 수 있습니다.
  • 시간에 따른 개발자 도입 (Adoption) 트렌드
  • 전체 커밋 대비 AI 지원 커밋 (AI-assisted commits)의 백분율

대시보드 3: 거버넌스 및 컴플라이언스 (Governance & Compliance)

보안, 리스크 및 컴플라이언스 팀을 위한 대시보드입니다. 다음 항목을 보여줍니다:

  • 정책 위반 (Policy violations) 타임라인
  • 가드레일 (Guardrail) 강제 적용 이벤트
  • AI 지원 변경 사항에 대한 감사 추적 (Audit trail) (모든 [AI-ASSISTED] 태그가 붙은 커밋)

이 마지막 대시보드는 엔터프라이즈 환경에서 아키텍처 리뷰 승인을 받는 데 핵심적인 역할을 합니다. 감사관(Auditors)들은

지표 (Metric)측정 대상
ai_suggestions_accepted_total저장소(repo)에 병합된 AI 제안 수
...

이것들은 단순한 허영 지표 (Vanity metrics)가 아닙니다. 수락률 (Acceptance ratio)과 정책 위반 횟수 (Policy violation count)를 함께 살펴보면 AI 설정 (AI configs)이 적절하게 조정되었는지 알 수 있습니다. 거부율이 높다면 가드레일 (Guardrails)이 너무 제한적인 것이고, 위반 횟수가 높다면 너무 느슨한 것입니다.

10분 만에 설정하기 (사전 요구 사항 완료 후)

사전 요구 사항: Docker Desktop, Python 3.11, Poetry, Semgrep, detect-secrets, Claude Code CLI.

# 저장소 복제 (Clone the repo)
git clone https://github.com/saurabh-oss/ai-sdlc-poc
cd ai-sdlc-poc
...

서비스는 다음 주소에서 실행됩니다:

전체 단계별 설정 방법은 STEP_BY_STEP_SETUP.md에 기술되어 있습니다.

발표를 위해 Grafana 대시보드에 데모 데이터를 채우려면(Seed):

poetry run python scripts/seed_demo_data.py

주요 아키텍처 결정 사항 및 트레이드오프 (Trade-offs)

왜 GitHub Actions가 아닌 Jenkins인가요?
엔터프라이즈 온프레미스 (On-prem) 팀은 클라우드 호스팅 러너 (Cloud-hosted runners)를 사용할 수 없는 경우가 많습니다. Jenkins + CasC (Configuration as Code)는 클라우드 의존성 없이 Docker에서 실행되는 완전한 선언적 (Declarative)이고 버전 관리되는 파이프라인을 제공합니다. 또한, Jenkins는 대부분의 엔터프라이즈 파이프라인 엔지니어들이 이미 익숙하게 사용하는 도구입니다.

왜 실제 Git 호스트가 아닌 Gitea인가요?
이유는 동일합니다. 이 PoC (Proof of Concept)는 완전히 에어갭 (Air-gapped)된 환경을 시뮬레이션합니다. Gitea는 GitHub나 GitLab을 사용하지 않고도 웹훅 (Webhooks), PR 흐름, 그리고 익숙한 UI를 제공합니다.

에이전트(Agents)를 위해 왜 CrewAI를 사용했나요?
CrewAI의 역할 기반 에이전트 모델 (Role-based agent model)은 SDLC 페르소나 (리뷰어, 테스터, 아키텍트)와 깔끔하게 매핑됩니다. 역할/목표/배경 스토리 (Role/goal/backstory) 스키마는 에이전트를 감사하기 쉽고 기술적이지 않은 이해관계자들에게 설명하기 용이하게 만듭니다. 이는 거버넌스 위원회에 이 프로젝트를 제안할 때 매우 중요한 요소입니다.

왜 데이터베이스 대신 Prometheus에 메트릭을 저장해야 할까요?

파이프라인 메트릭(pipeline metrics)에는 시계열(Time-series) 데이터 모델이 적합합니다. Prometheus + Grafana는 사실상의 표준(de facto) 오픈 소스 관측성(observability) 스택입니다. 여기에 로그 집계(log aggregation)를 위한 Loki를 추가하면 Grafana에서 로그와 메트릭이 상관관계가 있는 뷰(correlated log + metric views)를 가질 수 있으며, 이는 특정 가드레일(guardrail)이 왜 작동했는지 디버깅할 때 필수적입니다.

다음 단계

이것은 의도적으로 진행된 PoC(Proof of Concept, 개념 증명)입니다. v2를 위해 고려 중인 사항들은 다음과 같습니다:

  • MCP 통합: CrewAI 에이전트를 MCP 도구로 노출하여 Claude Code가 IDE에서 직접 호출할 수 있도록 합니다.
  • PR 레벨 에이전트 코멘터리: 코드 리뷰 에이전트의 출력물을 Gitea PR 코멘트로 자동 게시합니다.
  • Policy-as-code (코드로서의 정책): 가드레일 설정을 모든 프로젝트가 상속받는 공유된 버전 관리 정책 리포지토리(policy repo)로 이동합니다.
  • Ollama 지원: 완전한 에어갭(air-gapped) 운영을 위해 Anthropic API를 로컬 Ollama 모델로 교체합니다.

핵심 요점

AI 코딩 도구는 차단해야 할 위험 요소가 아니라, 거버넌스(governance)를 통해 가속화해야 할 요소입니다. SDLC 래퍼(wrapper)는 AI 도구 그 자체만큼이나 중요합니다.

대부분의 팀은 이를 거꾸로 하고 있습니다. AI 도구를 먼저 도입하고, 거버넌스를 나중에 구축하거나(또는 아예 구축하지 않거나) 합니다. 이 PoC는 거버넌스 계층을 먼저 구축할 수 있음을 보여주며, 이는 보안 및 컴플라이언스(compliance) 팀에 '승인(yes)'을 내리는 데 필요한 가시성을 제공함으로써 AI 도구를 실제로 더 채택하기 쉽게 만든다는 것을 입증합니다.

Repo: github.com/saurabh-oss/ai-sdlc-poc

만약 여러분이 SDLC에서 AI 거버넌스를 작업 중이거나, AI 코딩 도구에 대한 기업의 승인을 얻으려고 노력 중이라면, 어떤 패턴을 사용하고 계신지 듣고 싶습니다. 아래에 댓글을 남겨주세요.

Saurabh Srivastava는 엔터프라이즈 아키텍처, AI/GenAI 및 오픈 소스 툴링 분야에서 16년 이상의 경력을 가진 시니어 엔터프라이즈 아키텍트(Senior Enterprise Architect)입니다. github.com/saurabh-oss에서 공개적으로 빌드하고 있습니다. X 팔로우: @sauvast | LinkedIn: linkedin.com/in/saurabh-tcs

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0