확장 가능한 AI 코딩 표준: Cursor, Claude Code 및 그 이상을 위한 버전 관리된 AI 규칙

확장 가능한 AI 코딩 표준: Claude Code를 통해 팀의 AI 규칙을 버전 관리하는 방법

"AI는 모범 사례를 증폭시키기도 하지만... 최악의 사례도 증폭시킵니다."

요약 (TL;DR)

• 공유된 규칙이 없는 AI는 좋은 관행을 증폭시키는 만큼이나 혼란도 빠르게 증폭시킵니다.
• AI 지침을 버전 관리되고 배포 가능한 팀 계약(contract)으로 취급하면 역학 관계가 변화합니다.
• 계층화된 컨텍스트 (보편적 → 기술 특정적 → 프로젝트별)는 노이즈 없이 규칙의 관련성을 유지합니다.
• 두 가지 워크플로 게이트 — 코딩 전 /plan, 병합 전 /review — 는 피드백을 상류(upstream)로 이동시킵니다.
• 여러 팀으로 확장하려면 리포지토리(repo)를 포크(fork)하는 것이 아니라 정체성(identity)을 매개변수화(parameterizing)해야 합니다.
• 이 모든 것이 실제로 작동하는지 측정하는 것은 여전히 해결되지 않은 과제입니다.

AI 보조 개발의 핵심에 있는 역설

AI 코딩 표준은 우리에게 우선순위가 아니었습니다 — 그것이 문제가 되기 전까지는 말이죠. HiPay의 리드 소프트웨어 엔지니어로서, 저는 공유된 설정 없이 Claude Code나 다른 AI 코딩 어시스턴트(assistant)를 도입한 모든 팀에서 동일한 패턴이 반복되는 것을 목격했습니다: 규율 있는 개발자는 더 생산적으로 변했고, 규율 없는 개발자는 정확히 같은 속도로 더 혼란스러워졌습니다.

우리 팀의 모든 구성원이 AI 어시스턴트를 어떻게 설정했는지 살펴보았을 때, 제가 발견한 것은 안심할 만한 것이 아니었습니다. 개발자마다 각기 다른 설정을 가지고 있었습니다. 서로 다른 컨텍스트(context) 파일, 서로 다른 제약 조건, 서로 다른 규칙들이었습니다. 어떤 개발자는 변경 사항을 제안하기 전에 항상 테스트를 확인하도록 어시스턴트를 설정했습니다. 다른 개발자는 어시스턴트에게 아키텍처(architecture) 컨텍스트를 전혀 제공하지 않았습니다. 세 번째 개발자는 비밀 정보(secrets)나 git 컨벤션(convention)에 대한 가드레일(guardrails)이 전혀 없었습니다.

그 결과는 구체적이었습니다. 기능 브랜치(feature branch)에 하드코딩된 API 키가 커밋되었습니다. MR(Merge Request)이 리뷰 단계에서 차단될 때까지 변경 로그(changelog) 항목이 계속 잊혀졌습니다. 불과 10미터 떨어진 곳에 앉아 있는 기여자들 사이에서도 아키텍처 패턴이 극명하게 갈렸습니다. 그리고 어떤 개발자의 AI는 매 요청마다 수백 줄의 무관한 파일을 읽고 있었습니다 — 토큰(token)은 낭비되고, 컨텍스트는 오염되었으며, 아무런 이득 없이 응답 속도만 느려졌습니다.

원인은 AI가 아니었습니다. 모든 도구는 당신이 설정한 제약 조건만큼만 효과적입니다. 진짜 문제는 우리가 AI 설정을 개인적인 선호 사항으로 취급했다는 것이며, 그 대가로 재작업, 리뷰 마찰, 그리고 반복되는 실수를 겪고 있었습니다.

사고의 전환: AI 규칙을 버전 관리되는 팀 계약으로 취급하기

지나고 보니 해결책은 명확해 보였습니다.

우리는 이미 중요한 모든 것들을 버전 관리하고 있습니다. 린터 (linters), CI 파이프라인 (CI pipelines), Docker 설정 (Docker configs), 커밋 메시지 형식 (commit message format) 등이 그렇습니다. 우리는 빌드 도구에 대해 "내 컴퓨터에서는 다르게 작동한다"는 말이 용납될 수 없다는 점에 집단적으로 동의했습니다. 그런데 왜 코드를 작성하고, 리뷰하고, 배포하는 것을 돕는 AI 어시스턴트에게는 그것이 허용되는 것일까요?

핵심적인 통찰은 이것입니다: AI 지침 (instructions)은 개인적인 선호 사항이 아닙니다. 그것은 팀의 계약 (contracts)입니다. 제가 AI 어시스턴트에게 "의존성을 먼저 확인하지 않고는 핵심 트랜잭션 서비스를 절대 수정하지 마라"고 말한다면, 그것은 제 개인적인 의견이 아니라 팀의 모든 구성원에게 영향을 미치는 조직적 지식 (institutional knowledge)입니다.

그래서 저는 중앙 집중식 저장소(centralized repository)를 구축했습니다. 우리 AI 어시스턴트들이 어떻게 행동해야 하는지에 대한 단일 진실 공급원 (single source of truth)입니다. 이 저장소는 버전 관리되며, 패키지 (package)로 게시되고, 단 한 번의 명령으로 모든 프로젝트에 배포됩니다.

제가 예상했던 것보다 더 중요하게 작용했던 두 가지 설계 결정은 다음과 같습니다:

규칙은 참조되는 것이 아니라 복사됩니다. 각 프로젝트는 설치 시점에 관련 규칙의 로컬 사본을 가집니다. 이는 한 프로젝트가 v1.8을 유지하는 동안 다른 프로젝트는 v1.9를 채택할 수 있음을 의미합니다. 즉, 저장소 간의 강한 결합 (hard coupling)이 없으며, "상위 저장소의 규칙이 변경되어 우리의 워크플로우가 깨졌다"는 상황이 발생하지 않습니다.

업데이트는 푸시(push)가 아닌 풀(pull) 방식입니다. 팀은 명시적으로 새 버전을 가져옵니다 (pull). 갑작스러운 변화는 없습니다. 스프린트 (sprint) 도중에 당신도 모르는 사이 규칙이 바뀌는 일은 없습니다.

계층화 문제: 여러 도구에 걸쳐 AI 규칙을 구조화하는 방법

표준 저장소(standards repo)의 첫 번째 버전은 관습(conventions)들의 평면적인 목록(flat list)이었습니다. 하나의 팀에게는 효과적이었지만, 확장(scale)되지는 않았습니다.

문제는 "컨텍스트 (context)"가 모든 상황에 일률적으로 적용될 수 없다는 점입니다. NestJS 백엔드에서 작업하는 AI는 육각형 아키텍처 (hexagonal architecture), 포트/어댑터 (port/adapter) 경계, 그리고 유스케이스 (use-case) 배치를 이해해야 합니다. React 프론트엔드에서 작업하는 AI는 훅 (hook) 규칙, 컴포넌트 구조 관습, 그리고 테스트 라이브러리 패턴을 알아야 합니다. Symfony 코드베이스의 AI는 컨트롤러-서비스-리포지토리 (controller-service-repository) 계층화와 PHP 타이핑 (typing) 관습을 알아야 합니다.

이 모든 팀에게 하나의 거대한 단일 규칙 파일 (monolithic rules file)을 제공한다는 것은, 특정 개발자에게 그 파일의 절반은 노이즈 (noise)라는 의미입니다. 그리고 AI 컨텍스트에서 노이즈는 비용이 많이 듭니다. 중요한 규칙을 희석시키고 모든 요청마다 토큰 (tokens)을 낭비하게 만들기 때문입니다.

저는 다음과 같은 3계층 모델 (three-layer model)에 도달했습니다:

계층 1 — 범용 규칙 (Universal rules). 기술 스택과 관계없이 항상 활성화됩니다. 코드 내 비밀 정보 금지. Git 관습 강제. 명시적 확인 없는 파괴적 작업 금지. 이는 조직 전체에서 타협할 수 없는 최소한의 기준 (floor)입니다.

계층 2 — 기술 특정 규칙 (Tech-specific rules). 프로젝트가 사용하는 기술에 따라 자동으로 선택됩니다. NestJS 프로젝트에는 육각형 아키텍처 제약 조건이 적용됩니다. React 프로젝트에는 훅 규칙이 적용됩니다. AI는 자신의 컨텍스트와 관련된 내용만 보게 됩니다.

계층 3 — 프로젝트 컨텍스트 (Project context). 이곳에는 조직의 지식 (institutional knowledge)이 담깁니다. 이 특정 저장소는 무엇을 하는가? 알려진 실패 패턴은 무엇인가? 어떤 모듈이 취약한가? 도메인 모델 (domain model)은 무엇인가? 이 계층은 저장소마다 다르며, 린터 (linter)나 일반적인 규칙이 인코딩할 수 없는 사항들을 포착합니다.

핵심 설계 원칙은 계층들이 충돌하는 것이 아니라 결합(compose)된다는 것입니다. 계층 2는 기술 특정 사례에 대한 구체성을 더할 수 있습니다. 계층 3은 아무것도 대체하지 않으면서 컨텍스트를 추가합니다. AI는 모순된 혼란이 아니라, 일관되고 계층화된 그림을 보게 됩니다.

우리가 배포하는 방식을 바꾼 두 가지 워크플로우: Claude Code의 /plan 및 /review

계층화된 규칙은 토대였습니다. 하지만 실제 일상적인 개발 방식을 바꾼 것은 그 위에 구축된 두 가지 구조화된 워크플로우였습니다.

저는 이것들을 처음부터 설계하지 않았습니다. mattpocock/skills 및 기타 오픈 소스 AI 스킬 프레임워크(AI skill frameworks)에서 영감을 얻은 뒤, 우리의 맥락에서 가장 중요한 요소들을 조합했습니다. 즉, 과거의 아키텍처 결정 사항에 대한 지속적인 메모리 (persistent memory), 코드를 한 줄 쓰기 전에 영향 범위(blast radius)를 감지하기 위한 영향 분석 (impact analysis), 그리고 AI가 스스로의 불확실성을 드러내도록 강제하는 구조화된 프롬프팅 (structured prompting) — 즉, 틀린 답을 자신 있게 내놓는 대신 질문을 던지게 만드는 방식입니다.

코드 리뷰 (code review)의 근본적인 문제: 피드백이 작업이 완료된 후에 도착한다는 점입니다. 개발자가 두 시간 동안 코드를 작성하고 MR (Merge Request)을 열면, 자신이 고려하지 않았던 모듈을 변경 사항이 망가뜨렸다는 사실을 뒤늦게 알게 됩니다. 그러면 개발자는 상당한 양의 코드를 다시 작성해야 하거나, 리뷰어는 실제 아키텍처 관련 질문 대신 "변경 로그 (changelog) 업데이트를 잊으셨네요"와 같은 사소한 지적에 리뷰 시간을 낭비하게 됩니다.

해결책은 AI 가이드를 상류 (upstream)로 이동시키는 것이었습니다.

단 한 줄의 코드를 쓰기 전에: /plan

새로운 티켓 (ticket)을 시작할 때, 개발자는 /plan을 호출합니다. AI는 코드베이스를 맹목적으로 읽는 대신, 전용 도구를 사용하여 타겟 검색 및 영향 분석 (impact analysis)을 수행합니다. 즉, 과거의 결정 사항을 메모리에서 쿼리하고, 제안된 변경 사항이 무엇을 건드릴지 식별하며, 관련 있는 스택 컨벤션 (stack conventions)만을 읽습니다.

결과로 돌아오는 것은 코드가 아닙니다. 그것은 구조화된 계획입니다: 검증된 범위 (scope), 식별된 리스크, 권장 접근 방식입니다.

구체적인 예로, 한 개발자가 트랜잭션 모듈에 CSV 내보내기 필터를 추가하려 했습니다. /plan이 없었다면, 그들은 핵심 트랜잭션 서비스 (core transaction service)를 수정했을 것입니다. 이는 합리적인 첫 번째 직관입니다. 하지만 영향 분석을 수행한 후, AI는 이 서비스가 다른 세 개의 모듈에서 사용되고 있으며, 서비스의 시그니처 (signature)를 변경하는 것이 그 모든 모듈에 파괴적 변경 (breaking change)이 될 것임을 발견했습니다. 대신 AI는 기존 계약 (contract)을 그대로 유지하면서 새로운 유스케이스 (use-case)를 생성할 것을 권장했습니다.

이 발견에는 3분이 걸렸습니다. /plan이 없었다면, 이 문제는 코드가 작성된 후인 코드 리뷰 단계에서야 드러났을 것입니다.

MR을 열기 전에: /review

코드가 작성된 후, /review는 체계적인 체크리스트를 실행합니다: 올바른 형식의 변경 로그 (changelog) 항목 작성, 하드코딩된 비밀 정보 (secrets) 없음, 디버그 코드 잔류 여부, 아키텍처 경계 준수, 영향 범위 (blast radius) 식별 등입니다.

출력물은 명확한 통과(pass)/경고(warn)/차단(block) 판정이 포함된 구조화된 보고서 형식입니다:

🔍 Review — PROJ-1234 : CSV Export Filter

✅ CHANGELOG : [feat][PROJ-1234]: Add CSV export filter — format OK
...

사람 리뷰어는 비밀 정보를 찾아낼 필요가 전혀 없습니다. 대신 리뷰 시간을 아키텍처 질문에 집중할 수 있습니다: 이 유스케이스 (use-case)가 적절한 위치에 있는가? 추상화 (abstraction)가 올바른가? 하는 질문들 말입니다.

/review가 수행하는 기능 중 간과하기 쉬운 마지막 한 가지는, 결정된 사항들—선택된 접근 방식, 수용된 트레이드오프 (trade-offs)—을 영구적인 메모리에 저장한다는 점입니다. 다음에 누군가 동일한 코드베이스에서 /plan을 호출하면, 그 결정 사항들이 이미 그곳에 존재하게 됩니다. 시스템은 매 사이클을 통해 학습합니다.

이것이 바로 변화의 핵심입니다. AI는 체크리스트를 처리하고, 사람은 판단을 처리합니다. 그리고 그 어떤 것도 잊히지 않습니다.

단도직입적으로 말하자면:

여러 팀으로의 확장: 어려운 부분

이 시스템은 한 팀에게는 잘 작동했습니다. 그러다 두 번째 팀이 이를 도입하고 싶어 했습니다.

문제는 모든 컨텍스트 (context) 파일이 암묵적으로 우리 팀을 위해 작성되었다는 점이었습니다. 우리 팀의 티켓 접두사, 우리 팀 이름, 우리의 릴리스 워크플로 (release workflows) 등이 포함되어 있었죠. 두 번째 팀이 기술적으로 패키지를 설치할 수는 있겠지만, 매 순간 잘못된 컨텍스트를 참조하는 규칙들을 마주하게 될 것이었습니다.

단순한 해결책은 저장소(repo)를 포크(fork)하는 것입니다. 이것이 왜 실패하는지 설명하겠습니다. 포크하는 순간, 하나의 표준 대신 두 개의 표준이 존재하게 됩니다. 공통 규칙(universal rules)에 대한 개선 사항이 전파되지 않습니다. 6개월이 지나면 두 표준은 병합이 불가능할 정도로 서로 달라집니다. 단기적인 도입 문제는 해결했을지 모르나, 장기적인 유지보수 문제를 만들어낸 셈입니다.

제가 도달한 원칙은 다음과 같습니다: 구조를 표준화하고, 정체성을 매개변수화(parameterize)하라.

공통 규칙(Universal rules) — 보안 가드레일(security guardrails), 아키텍처 제약 사항(architecture constraints), git 컨벤션(git conventions) — 은 보편적인 상태로 유지됩니다. 이는 특정 팀이 아닌 조직(org)에 속한 것입니다.

팀의 정체성은 설치 시점(install time)에 주입됩니다. AI 어시스턴트의 컨텍스트 파일(context file)에는 올바른 팀 이름, 티켓 접두사(ticket prefix), 그리고 팀별 컨텍스트가 채워집니다. 설치 프로세스에서 이러한 값들을 한 번만 입력받아 내장(bake in)합니다.

팀별 워크플로(workflows)는 코어(core)가 아닌 전용 네임스페이스(namespace)에 존재합니다. 팀은 공유 규칙을 건드리지 않고도 자신들만의 릴리스 런북(release runbook)이나 알려진 장애 패턴(known failure patterns)을 추가할 수 있습니다.

이로 인해 형성되는 거버넌스(governance) 모델은 다음과 같습니다: 한 팀이 표준 저장소(standards repo)를 소유하며(버전을 발행하고 공통 규칙의 변경 사항을 검토함), 다른 팀들은 풀 리퀘스트(pull requests)를 통해 자신들의 컨텍스트를 기여합니다. 즉, 프로젝트 컨텍스트 파일, 팀별 런북, 알려진 장애 패턴 등을 추가하는 방식입니다. 파편화 없는 공동 소유(Shared ownership)가 가능해집니다.

실질적인 결과는 이렇습니다: 새로운 팀은 단 몇 분 만에 아무런 설정 없이도 완전히 구성된 AI 어시스턴트를 사용할 수 있게 됩니다. 조직 전체의 가드레일을 자동으로 상속받은 다음, 그 위에 자신들만의 구체적인 컨텍스트를 추가하기만 하면 됩니다.

다음 단계: AI 표준 거버넌스의 미결 과제들

다중 팀 일반화(multi-team generalization, v1.10)는 프로젝트의 범위를 변화시킨 이정표였습니다. 프로젝트의 성격이 "우리 팀의 내부 도구"에서 "다른 팀들이 포크하지 않고도 실제로 채택할 수 있는 무언가"로 바뀌었습니다. 이러한 변화는 또 다른 질문들을 던집니다.