Spec-Driven Claude Code 운영법: 엔터프라이즈 AI 개발 플랫폼에서 먼저 고정할 기준

Anthropic과 Cognizant의 파트너십 확대 발표에서 개발팀이 볼 만한 부분은 숫자보다 운영 방식입니다. Cognizant는 Claude를 자사 엔지니어링 플랫폼에 넣고, Flowsource의 Spec-Driven Development 모듈에서 Claude Code를 사양서, 코딩 표준, 아키텍처 청사진에 따라 지시한 뒤 산출물을 평가한다고 설명했습니다.

이 문장은 엔터프라이즈 AI 코딩 도구의 방향을 잘 보여줍니다. 이제 AI 코딩은 ‘프롬프트 잘 쓰는 개인 생산성’에서 ‘조직 기준을 읽고, 그 기준 안에서 변경하고, 평가를 통과해야 하는 개발 파이프라인’으로 이동하고 있습니다. 대기업만의 이야기가 아닙니다. 작은 팀도 AI 코딩 에이전트를 제대로 쓰려면 사양, 표준, 평가 기준을 먼저 고정해야 합니다.

Claude Code나 Codex 같은 도구를 도입할 때 흔한 실패는 모델에게 바로 코드를 맡기는 것입니다. 레포 구조, 네이밍, 상태 관리 방식, 테스트 기준, 금지 패턴, 배포 절차가 문서화되어 있지 않으면 에이전트는 그때그때 그럴듯한 코드를 만듭니다. 처음에는 빨라 보이지만, 몇 주 뒤에는 스타일이 섞이고 리뷰 비용이 늘어납니다.

Spec-Driven Development는 긴 문서가 아니라 실행 가능한 기준이다

사양 주도 개발이라고 하면 거창한 PRD나 아키텍처 문서를 떠올리기 쉽습니다. 하지만 AI 코딩 에이전트에 필요한 spec은 더 작고 구체적이어야 합니다. 에이전트가 작업 전에 읽고, 작업 중에 참조하고, 작업 후에 검증할 수 있어야 합니다.

좋은 spec에는 다섯 가지가 들어갑니다. 첫째, 변경 목표입니다. 둘째, 건드려도 되는 파일 범위입니다. 셋째, 금지할 구현 방식입니다. 넷째, 완료 기준입니다. 다섯째, 검증 명령입니다. 이 다섯 가지가 없으면 에이전트는 범위를 넓히고, 불필요한 리팩터링을 하고, 테스트 없이 끝냈다고 말할 가능성이 커집니다.

예를 들어 ‘결제 페이지 개선’이라는 작업은 너무 넓습니다. AI에게 맡길 spec은 이렇게 바뀌어야 합니다. ‘checkout/summary 컴포넌트에서 쿠폰 적용 후 총액 계산 표시를 수정한다. 결제 API 스키마는 바꾸지 않는다. 상태 관리는 기존 Zustand store를 유지한다. 완료 기준은 단위 테스트 3개 추가와 Playwright 결제 플로우 통과다.’ 이 정도로 좁혀야 합니다.

코딩 표준은 사람보다 에이전트에게 더 엄격해야 한다

사람 개발자는 팀 분위기와 과거 코드를 보고 암묵지를 읽습니다. 에이전트는 그렇지 않습니다. 그래서 AI 코딩 표준은 일반 스타일 가이드보다 더 직접적이어야 합니다. ‘깔끔하게 작성’ 같은 말은 쓸모가 없습니다. ‘API 호출은 services/apiClient.ts를 통해서만 한다’, ‘컴포넌트에서 직접 fetch 금지’, ‘날짜 처리는 date-fns만 사용’, ‘에러 메시지는 i18n key로 관리’처럼 판정 가능한 문장이어야 합니다.

금지 패턴도 중요합니다. 에이전트는 문제를 빨리 풀기 위해 우회 코드를 만들 수 있습니다. 테스트를 깨지 않으려고 mock을 과하게 바꾸거나, 타입 오류를 any로 덮거나, 기존 추상화를 무시하고 새 유틸을 만들 수 있습니다. 이런 패턴은 문서에 명시하고 자동 검사로 잡아야 합니다.

작은 팀이라면 AI_CODING_RULES.md 하나로 시작해도 됩니다. 레포 구조, 상태 관리, API 호출, 테스트, 접근성, 보안 금지사항을 한 페이지로 정리합니다. 중요한 것은 문서의 양이 아니라 에이전트가 매 작업에서 반드시 읽도록 워크플로우에 넣는 것입니다.

아키텍처 청사진은 변경 범위를 줄이는 장치다

Cognizant 사례에서 언급된 architectural blueprint는 엔터프라이즈에서 특히 중요합니다. AI 에이전트는 파일을 많이 읽고 수정할 수 있기 때문에, 경계가 없으면 작은 작업도 시스템 전체 리팩터링으로 번질 수 있습니다. 아키텍처 청사진은 에이전트에게 ‘이 시스템은 이렇게 나뉘어 있고, 이 계층을 넘어가면 안 된다’고 알려주는 지도입니다.

실무적인 청사진은 복잡한 다이어그램보다 텍스트 규칙이 유용합니다. 예를 들어 프론트엔드에서는 pages는 라우팅만, features는 도메인 UI와 hook, entities는 타입과 순수 함수, shared는 공용 컴포넌트로 제한한다고 적습니다. 백엔드에서는 controller, service, repository, domain 규칙을 적고 의존 방향을 명시합니다.

이 규칙을 테스트나 lint와 연결하면 효과가 커집니다. import boundary 검사, circular dependency 검사, forbidden path 검사, 타입 검사, 스냅샷 테스트가 기본 방어선입니다. 에이전트에게 ‘이 명령을 통과해야 완료’라고 알려주면 리뷰어가 잡아야 할 문제가 줄어듭니다.

산출물 평가는 코드 리뷰 전에 자동으로 끝내야 한다

AI 코딩 도구를 팀에 넣을 때 가장 큰 병목은 리뷰입니다. 에이전트가 PR을 많이 만들수록 사람이 봐야 할 변경도 늘어납니다. 그래서 평가 기준을 코드 리뷰 전에 최대한 자동화해야 합니다.

최소 평가 세트는 다음과 같습니다. 타입체크, 린트, 단위 테스트, 변경 파일 범위 검사, 금지 패턴 grep, 빌드, 필요한 경우 E2E입니다. 여기에 AI 전용 검사를 추가할 수 있습니다. 예를 들어 ‘새 dependency 추가 여부’, ‘환경변수 추가 여부’, ‘권한 scope 변경 여부’, ‘마이그레이션 포함 여부’를 자동으로 요약하게 합니다.

리뷰어는 모든 diff를 처음부터 읽기보다, 자동 검사 결과와 위험 요약을 먼저 봐야 합니다. 에이전트가 만든 변경은 속도가 빠른 대신 의도가 불명확할 수 있습니다. 따라서 PR 설명에는 문제, 접근, 변경 파일, 테스트 결과, 남은 위험을 구조화해 넣어야 합니다.

작은 팀을 위한 도입 순서

처음부터 대형 플랫폼을 만들 필요는 없습니다. 1단계는 작업 템플릿입니다. 작업 목표, 범위, 금지사항, 검증 명령을 포함한 템플릿을 만듭니다. 2단계는 레포 규칙 문서입니다. AI가 매번 읽을 짧은 기준 파일을 둡니다. 3단계는 자동 검사입니다. PR 전에 실행할 명령을 고정합니다. 4단계는 리뷰 요약입니다. 에이전트가 변경 의도와 위험을 정리하게 합니다.

이 네 가지가 잡히면 Claude Code 같은 도구는 개인 생산성 도구에서 팀 개발 시스템으로 바뀝니다. 반대로 이 기준 없이 도입하면 빠른 코드 생성이 느린 리뷰 비용으로 돌아옵니다.

실행 체크리스트

• 모든 AI 코딩 작업에 목표, 파일 범위, 금지사항, 완료 기준, 검증 명령을 포함합니다.
• AI_CODING_RULES.md에 API 호출, 상태 관리, 테스트, 보안 금지 패턴을 판정 가능한 문장으로 적습니다.
• 아키텍처 계층과 import boundary를 문서화하고 가능하면 lint로 강제합니다.
• 에이전트가 새 dependency, 환경변수, 권한 변경, 마이그레이션을 자동 요약하게 합니다.
• PR 생성 전 타입체크, 린트, 테스트, 빌드 중 최소 3개 이상을 필수로 둡니다.
• 리뷰어는 diff 전체보다 자동 검사 결과와 위험 요약을 먼저 확인합니다.
• 실패한 AI 작업의 원인을 규칙 문서에 짧게 반영합니다.

Spec-Driven Claude Code 운영의 핵심은 더 긴 프롬프트가 아닙니다. 조직의 개발 기준을 에이전트가 실행 가능한 형태로 읽고, 그 기준을 자동 검사로 확인하게 만드는 것입니다. AI 코딩 도구가 팀 속도를 높이려면 코드를 쓰기 전에 기준부터 고정해야 합니다.

참고: Anthropic, Expanding our partnership with Cognizant.