[AI활용] AI가 만든 코드, 팀은 어떻게 관리하나?

 

kt cloud 그룹사업기획팀 변세림 님

 

📝 요약 SUMMARY

이 글에서는 팀이 AI 생성 코드의 일관성과 보안을 위해
페르소나, SKILL.md, YAML 기반 Harness 검증 체계를 설계한 과정을 다룹니다.
코드 생성 이후의 검증 병목을 줄이기 위한 팀 규칙의 명문화와 자동 검증, 사람의 최종 판단 원칙을 정리합니다.

#AI생성코드 #코드거버넌스 #SKILLmd #Harness #Terraform

---

Image: AI-Generated Content

 

안녕하세요.

지난 글에서 AI 자동화의 진짜 문제는 "만드는 것"이 아니라 "유지하는 것"이라는 이야기를 나누었습니다. 그리고 그 전제 조건으로, 팀의 암묵지를 먼저 명문화해야 한다는 점도 강조했었죠.

 

그렇다면 실제 현업에서는 이를 어떻게 구현하면 될까요? 이번 글에서는 그 고민을 팀 단위로 확장했을 때 어떤 일들이 벌어지는지, 그리고 저희 팀이 어떤 시행착오를 거쳐 지금의 거버넌스 구조에 이르게 되었는지를 이야기해 보려 합니다.

---

1단계: 혼자 쓸 때는 괜찮았습니다

처음에는 로컬 환경에서 혼자 AI를 활용했습니다. 제가 원하는 결과물을 Claude나 Cursor에게 요청하면 코드가 나왔고, 제가 직접 눈으로 확인하고 수정했습니다. 혼자 쓸 때는 이것만으로도 충분했습니다. 제 머릿속에 모든 맥락이 있었고, 제가 짠 코드이기에 제가 책임지면 그만이었으니까요.

 

그런데 이것을 '팀'의 영역으로 가져오는 순간부터 묘한 문제들이 생기기 시작했습니다.

---

2단계: 팀으로 확장하자 생긴 일

저희 팀은 Terraform을 활용해 Azure 인프라를 관리하고 있습니다. AI 코딩 도구가 팀 안으로 들어오면서 코드 생성 속도는 확실히 빨라졌고, GitHub에 올라오는 PR의 수도 눈에 띄게 늘었습니다. 그런데 속도가 빨라짐과 동시에 새로운 딜레마에 빠졌습니다.

 

코드는 빠르게 쏟아져 나오는데, 그 코드가 팀 기준에 맞는지 확인하는 건 여전히 '사람의 눈'에 달려있었기 때문입니다.

 

저희 팀에는 인프라 코드를 작성할 때 반드시 지켜야 할 기준들이 있습니다. 리소스 명명 규칙, 필수 태그 여부, 보안 정책 준수 여부 같은 것들입니다. 예전에는 모듈 수가 적었기 때문에 PR 리뷰 시 사람이 직접 꼼꼼히 확인하면 되었습니다. 그런데 AI가 코드 생성 속도를 폭발적으로 끌어올리면서 리뷰해야 할 코드의 양은 산더미처럼 늘어났고, 리뷰어의 수는 그대로였습니다. 결국 병목 현상이 '코드 생성'에서 '코드 검증'으로 이동했을 뿐이었습니다.

 

더 큰 문제는 따로 있었습니다. AI는 가끔 "그럴듯하지만 틀린" 코드를 아주 자신 있게 내놓는다는 점입니다. 명명 규칙을 미묘하게 벗어났거나, 필수 태그가 하나 빠졌거나 하는 자잘한 오류들은 리뷰어가 지치면 그냥 스쳐 지나가기 십상입니다. 팀의 인프라 기준이 전적으로 '사람의 주의력'에 의존하는 아슬아슬한 구조가 되어버린 것입니다.

---

3단계: AI에게 맥락을 주는 방법의 진화

이 문제를 처음 마주했을 때 가장 먼저 시도한 방법은 '페르소나(Persona) 정의'였습니다.

"너는 우리 팀의 인프라 엔지니어야. 명명 규칙은 이렇고, 태그는 이걸 써야 해."

 

프롬프트 앞에 팀 기준을 줄줄이 적어서 AI에게 역할을 부여하는 방식입니다. 처음엔 꽤 효과가 있었습니다. AI가 맥락을 이해하고 팀 기준에 맞는 코드를 더 잘 생성해 주었죠.

 

그런데 한계가 금방 드러났습니다. 페르소나 정의는 대화가 길어질수록 점차 희석됩니다. 초반에 설정한 역할을 AI가 점점 잊어버리고, 대화 중반쯤 되면 처음과 전혀 다른 스타일의 코드가 튀어나오기 시작합니다. 매번 새로운 대화를 시작할 때마다 같은 맥락을 반복해서 주입해야 하는 피로감도 컸습니다.

 

그래서 다음으로 시도한 것이 'SKILL.md' 방식입니다.

 

팀의 인프라 작성 기준, 명명 규칙, 자주 쓰는 패턴들을 마크다운(Markdown) 파일로 깔끔하게 정리해 두고, AI가 작업을 시작할 때 이 파일을 참조하게 하는 구조입니다.

# SKILL.md

## 명명 규칙
- Resource Group: rg-{service}-{env}-{region}
- Virtual Network: vnet-{service}-{env}-{region}

## 필수 태그
- Environment, Owner, CostCenter, ManagedBy

## 금지 사항
- Public IP 직접 할당 금지
- 하드코딩된 시크릿 금지

 

프롬프트에 매번 직접 적는 게 아니라 파일로 분리해 두니 관리가 훨씬 수월해졌습니다. 팀 기준이 바뀌면 해당 파일만 수정하면 되었으니까요. 페르소나 정의보다 훨씬 안정적이었습니다.

 

하지만 이것도 결국 AI가 파일을 꼼꼼히 읽고 잘 따라주길 "신뢰"해야만 하는 구조였습니다. AI가 SKILL.md를 무시하거나 잘못 해석하더라도, 사전에 이를 강제로 잡아낼 방법이 없었습니다.

---

4단계: 신뢰에서 검증으로 — Harness 설계

그래서 방향을 근본적으로 바꾸기로 했습니다. AI를 그저 '신뢰'하는 구조에서, 확실하게 '검증'하는 구조로 말이죠.

 

핵심 아이디어는 이렇습니다. "AI가 규칙을 잘 따르길 바라는 게 아니라, 애초에 규칙을 어기면 통과할 수 없게 만들자."

 

팀의 거버넌스 규칙을 YAML로 명문화하고, 코드가 GitHub PR에 올라오기 전에 자동으로 검증하는 사내 도구를 만들기 시작했습니다. AI가 생성한 코드든, 사람이 직접 작성한 코드든 동일한 검증을 통과해야만 머지(Merge)될 수 있는 촘촘한 구조입니다.

naming_convention:
  resource_group:
    pattern: "rg-{service}-{env}-{region}"
    required: true
  virtual_network:
    pattern: "vnet-{service}-{env}-{region}"
    required: true

required_tags:
  - Environment
  - Owner
  - CostCenter
  - ManagedBy

security:
  deny_public_ip: true
  deny_hardcoded_secrets: true

 

이 구조가 일종의 안전벨트이자 하네스(Harness) 역할을 합니다. 이를 통해 AI가 아무리 그럴듯한 코드를 만들어내도 팀의 가드레일(기준)을 벗어나면 시스템이 자동으로 걸러내게 됩니다.

 

YAML로 규칙을 정의하면 추가적인 이점도 생깁니다. 팀의 표준이 코드 안에 명시적으로 살아 숨 쉬게 되고, Terraform이나 특정 언어에 익숙하지 않은 사람도 누구나 규칙을 읽고 논의할 수 있게 됩니다. 거버넌스가 특정 소수의 머릿속 암묵지에서 벗어나, 진정한 팀 전체의 자산이 되는 것이죠.

 

그리고 가장 중요한 한 가지. 검증 시스템을 통과하더라도 최종 머지(Merge) 여부는 반드시 사람이 판단합니다. 자동화는 사람의 판단 자체를 대체하는 것이 아니라, '기계가 판별할 것'과 '사람이 고도화된 사고로 판단해야 할 것'을 명확히 분리해 주는 역할일 뿐입니다.

---

 

정리해 보면 저희 팀의 AI 도입 여정은 이렇게 흘러왔습니다.

• 페르소나 정의: 프롬프트에 직접 역할 부여
• SKILL.md: 팀의 암묵지를 파일로 명문화
• Harness: 명문화된 규칙을 시스템으로 자동 검증

각 단계는 이전 단계의 한계를 보완하는 방식으로 진화했습니다. 결국 핵심은 하나였습니다. 팀의 암묵지를 어떤 형태로든 밖으로 꺼내는 것. 페르소나 정의든, SKILL.md든, YAML 룰이든 형태는 달라도 방향성은 같았습니다. 머릿속에 파편화되어 있던 기준을 코드로, 파일로, 규칙으로 명시화하는 과정이었습니다.

 

이 과정을 거치고 나니 확실히 달라진 점이 있습니다. 리뷰어의 소중한 에너지가 단순한 체크리스트 확인에서 벗어나, 전체적인 '아키텍처의 방향성'을 판단하는 데 집중되기 시작했습니다.

 

엔지니어의 역할 역시 서서히 바뀌고 있음을 체감합니다. 코드를 한 줄 한 줄 직접 타이핑하는 사람에서, AI가 안전하게 질주할 수 있도록 규칙과 뼈대를 설계하는 사람으로 말이죠.

 

AI가 코드를 짜는 속도가 기하급수적으로 빨라질수록, 그 코드를 안전하게 감싸는 거버넌스의 중요성은 앞으로 더욱 커질 것입니다. 이 글이 AI 자동화 도입을 고민하며 과도기를 겪고 계신 여러 팀에 작은 이정표가 되었으면 합니다.

 

---

❔자주 묻는 질문 FAQ

Q SKILL.md와 페르소나 정의는 어떻게 다른가요? 

A 페르소나 정의는 프롬프트 앞에 "너는 이런 역할이야"라고 직접 적어주는 방식입니다. 효과는 있지만 대화가 길어지면 AI가 초반 설정을 점점 잊어버리게 됩니다. 반면 SKILL.md는 팀의 기준을 별도의 파일로 분리해 두고 AI가 작업 시작 시 이를 참조하게 하는 방식입니다. 관리가 훨씬 쉽고, 팀 기준이 바뀌면 파일만 수정하면 됩니다. 다만, 둘 다 결국 AI가 잘 따라주길 "신뢰"해야만 하는 구조라는 한계는 동일합니다.

Q Harness를 도입하면 AI 자동화의 속도가 오히려 느려지지 않나요? 

A 오히려 그 반대입니다. Harness 도입 전에는 PR(Pull Request) 리뷰어가 명명 규칙, 태그 누락, 보안 정책 등을 일일이 눈으로 확인해야 했습니다. 이 검증 과정을 자동화하면, 리뷰어의 에너지는 단순 체크리스트 확인에서 '아키텍처에 대한 판단'으로 이동하게 됩니다. 코드 생성은 AI가 빠르게, 검증은 시스템이 자동으로, 최종 판단은 사람이 — 각 역할이 명확하게 분리되면서 전체 개발 흐름이 훨씬 더 빠르고 안전해집니다.

---

📚 관련 / 출처 REFERENCES

🔗

• https://claude.com/blog/skills
• https://www.anthropic.com/engineering/harness-design-long-running-apps

↗