바이브 코딩 시대, 저장소 규칙과 개인 취향의 경계

AGENTS.md의 역할은 개발자를 복제하는 것이 아니라, 사고를 막아야 하는 경계만 고정하는 데 있다.

바이브 코딩을 도입한 팀은 곧 비슷한 질문과 마주친다. 저장소마다 AGENTS.md나 CLAUDE.md를 두고 AI 에이전트에게 규칙을 알려주기 시작하면, 어디까지를 공통 규칙으로 고정해야 하고 어디부터는 개인의 취향으로 남겨둬야 하는지가 애매해지기 때문이다. 이 경계를 잘못 잡으면 두 가지 문제가 동시에 생긴다. 꼭 지켜야 하는 안전 규칙은 느슨해지고, 반대로 취향에 가까운 선택은 불필요하게 경직된다.

최근의 바이브 코딩 논의에서 자주 등장하는 관점도 비슷하다. 인간은 시스템 아키텍처와 취향 같은 고차원 판단에 집중하고, 구현과 보일러플레이트, 반복 리팩터링은 에이전트에게 넘기라는 것이다. 이 말을 실무적으로 번역하면 간단하다. 저장소에는 “누가 작업해도 같아야 하는 것"을 남기고, 사람마다 달라도 괜찮은 영역은 굳이 강제하지 말아야 한다.

이 질문은 이론에 머무르지 않는다. 앞서 정리한 [OpenClaw 사례 분석]¹과 [OpenClaw의 AGENTS.md 해부]²를 보면, 실제로 생산성을 만든 규칙은 취향의 통일이 아니라 경계의 명시성이었다. Steinberger 역시 요즘은 코드를 전부 읽지 않지만 시스템 구조와 설계는 계속 붙들고 있다고 설명한다.³⁴ OpenClaw가 강하게 고정한 것도 탭과 스페이스가 아니라 import boundary, 빌드 게이트, 멀티 에이전트 안전 규칙, 비가역적 작업의 승인 경계다.⁵

핵심은 많이 적는 것이 아니라, 무엇을 닫아두고 무엇을 열어둘지 설계하는 것이다.

왜 이 구분이 중요한가

AI 에이전트는 규칙을 빠르게 따른다. 문제는 규칙의 성격을 스스로 구분하지 못한다는 데 있다. 저장소 지침에 빌드 명령, 시크릿 처리, 브랜치 안전 규칙처럼 반드시 지켜야 하는 제약과 “나라면 이렇게 짠다” 수준의 취향이 뒤섞여 있으면, 에이전트는 둘을 같은 무게로 다룬다. 그러면 중요한 규칙은 묻히고, 덜 중요한 규칙은 과도하게 증폭된다.

예를 들어 pnpm test를 통과시키지 않고 머지하면 버그가 난다. 실제 시크릿을 커밋하면 사고가 난다. 인증 흐름이나 결제 권한 로직을 충분한 검토 없이 바꾸면 운영 리스크가 생긴다. 이런 것은 논쟁의 여지가 없는 운영 계약이다. 반면 함수 이름을 findUser로 할지 getUserById로 할지, 테스트 파일을 소스 옆에 둘지 __tests__로 모을지, import를 어떤 순서로 정렬할지는 결과에 영향을 줄 수는 있어도 대개 정답이 하나로 고정되지는 않는다.

이 차이를 구분하지 않으면 저장소 문서는 금방 비대해진다. 모든 선호를 중앙 규칙으로 끌어올리면 에이전트는 문서를 읽는 데 더 많은 컨텍스트를 쓰고, 팀은 사소한 스타일 합의에 불필요한 에너지를 쓴다. 반대로 객관적 제약을 취향 수준으로 취급하면, 멀티 에이전트 환경에서 충돌과 재작업이 반복된다.

결국 좋은 AGENTS.md는 팀의 취향 사전을 만드는 문서가 아니라, 사고 비용이 큰 영역의 경계를 명확히 그어 두는 문서여야 한다.

OpenClaw가 실제로 보여준 것

이전 글에서 정리했듯 OpenClaw의 AGENTS.md는 단순한 스타일 가이드가 아니라 운영 계약이다.² 흥미로운 점은 그 문서가 “개발자를 어떻게 복제할 것인가"보다 “에이전트가 어디서 사고를 낼 수 있는가"에 훨씬 더 집중한다는 점이다. 실제 지침을 보면 빌드 산출물이나 모듈 경계에 영향을 줄 수 있는 변경에는 pnpm build 통과를 하드 게이트로 요구하고, @ts-nocheck 같은 전형적 회피 패턴도 명시적으로 금지한다.⁵

예를 들어 OpenClaw는 확장이 내부 구현에 직접 손대지 못하도록 import 경계를 규칙으로 잠가 둔다. 또 git stash 금지, 임의 브랜치 전환 금지, 원자적 커밋 유지 같은 멀티 에이전트 안전 규칙을 둔다. 빌드와 테스트도 하드 게이트와 소프트 게이트로 나눠 언제 반드시 검증해야 하는지를 분명히 적어 둔다.²⁵

반대로 그 문서는 “세미콜론을 꼭 써라”, “함수 이름은 반드시 이런 톤으로 지어라” 같은 개인 취향을 중심으로 설계되어 있지 않다. 즉 OpenClaw가 보여준 핵심은 간단하다. 저장소 문서가 다뤄야 하는 것은 미적 통일감이 아니라 구조적 안전성이다.

리포지토리와 함께 관리해야 하는 규칙

다음은 저장소와 함께 버전 관리되어야 하는 영역이다. 공통점은 하나다. 위반했을 때 버그, 충돌, 보안 사고, 운영 혼선이 발생한다는 점이다.

• 빌드와 테스트 명령
• 멀티 에이전트 환경에서의 Git 안전 규칙
• 공개 API surface, import boundary, 패키지 경계 같은 아키텍처 제약
• 시크릿, 개인정보, 운영 설정값 같은 보안 경계
• 인증, 결제, 권한, DB 스키마처럼 수동 검토가 필요한 고위험 영역
• PR/커밋 단위와 같은 변경 관리 원칙
• Research → Plan → Implement처럼 오류 비용을 낮추는 작업 순서
• AI 사용 시 투명성 요구사항
• 팀이 이미 검증한 품질 게이트와 자동화 기준

이 항목들은 “좋아 보이는 추천"이 아니라 저장소 운영 계약에 가깝다.

예를 들어 빌드 명령은 npm run build인지 pnpm build인지 사람마다 다르게 해석하면 안 된다. 자동화 파이프라인과 로컬 검증이 같은 명령을 기준으로 움직여야 하기 때문이다. Git 규칙도 마찬가지다. 멀티 에이전트로 동시에 작업하는 환경에서는 임의의 stash 사용, 요청되지 않은 브랜치 변경, 넓은 범위의 비원자적 커밋이 실제 충돌을 만든다.

보안 경계는 더 말할 필요가 없다. 실제 전화번호, 운영 환경 변수, 비공개 키, 고객 데이터 샘플 같은 것은 팀의 스타일 선호가 아니라 금지 목록이다. 이런 내용은 개인 프롬프트나 암묵지로 두면 안 되고, 저장소 문서와 자동 스캔 규칙에 함께 남아 있어야 한다.

워크플로 순서도 같은 맥락이다. 구현 전에 기존 코드를 읽고, 계획을 세우고, 그다음 바꾸도록 하는 절차는 단순한 형식주의가 아니다. 에이전트는 질문을 덜 할수록 빨라지지만, 잘못된 가정 위에서 빨라지면 나중에 더 비싸게 되돌아온다. 그래서 탐색과 계획을 먼저 요구하는 규칙은 취향이 아니라 비용 절감 장치다.

여기서 중요한 포인트가 하나 더 있다. 팀이 이미 자동화에 의존하고 있다면, 그 자동화가 기대하는 형식 역시 공통 규칙이 된다. 예를 들어 Conventional Commits 형식이 릴리스 노트, 체인지로그, CI 라우팅에 연결되어 있다면 그것은 더 이상 취향이 아니다. 반대로 단지 “읽기 좋다” 수준의 형식 선호라면 팀 차원의 합의일 수는 있어도, 반드시 저장소 핵심 규칙으로 격상할 필요는 없다.

반복 절차를 어디에 둘지도 같은 기준으로 볼 수 있다. OpenClaw는 릴리스나 보안 점검처럼 복잡한 반복 업무를 AGENTS.md 본문에 길게 쓰기보다 별도 스킬로 분리한다.²⁶ 이 역시 좋은 구분이다. 저장소 핵심 문서에는 원칙과 경계를 남기고, 절차적 세부사항은 재사용 가능한 실행 표면으로 분리하는 편이 더 오래 간다.

개인의 취향으로 남겨둬도 되는 영역

반대로 다음과 같은 영역은 개인이나 팀의 취향으로 남겨둘 수 있다. 물론 팀이 일관성을 위해 표준화할 수는 있지만, 그것이 저장소의 핵심 안전 계약일 필요는 없다.

• 세미콜론 사용 여부, 공백 수, trailing comma 같은 포매팅 세부사항
• 함수명과 변수명의 세부 뉘앙스
• import 정렬 방식
• 주석을 어느 정도까지 다는지에 대한 스타일
• 테스트 파일 배치 방식과 테스트 서술 스타일
• 추상화를 일찍 할지 늦게 할지에 대한 선호
• feature-based 구조와 layer-based 구조 사이의 선호
• 에러 처리 패턴의 세부 선택
• 프롬프트를 길게 쓰는지 짧게 쓰는지 같은 개인 작업 방식

이런 항목은 서로 다른 선택지가 모두 합리적일 수 있다. 예를 들어 어떤 팀은 strict한 타입 설정을 선호하고, 어떤 팀은 온보딩 비용을 낮추기 위해 점진적으로 엄격도를 높인다. 어떤 팀은 Result 패턴을 좋아하고, 어떤 팀은 예외 기반 흐름을 더 명확하다고 느낀다. 어느 쪽이든 일관되게 운영된다면 충분히 합리적일 수 있다.

중요한 것은 이런 취향을 완전히 무시하자는 뜻이 아니라는 점이다. 취향도 생산성에 영향을 준다. 다만 그것을 어디에 두느냐가 중요하다. 저장소 핵심 계약으로 다루기보다는 formatter, linter, 템플릿, 샘플 코드, 개인 프롬프트, 팀 플레이북 같은 가벼운 장치로 다루는 편이 낫다. 그래야 취향은 유지하면서도 저장소 지침이 과도하게 무거워지지 않는다.

특히 바이브 코딩에서는 이 차이가 더 중요해진다. 에이전트에게 모든 취향을 강하게 주입하면 코드 생성은 오히려 경직되고, 작은 변화에도 규칙 충돌이 많이 난다. 반면 취향을 느슨한 가이드로 두고, 안전과 품질에 직결되는 경계만 강하게 고정하면 에이전트는 훨씬 안정적으로 일한다.

이 점에서도 OpenClaw는 좋은 힌트를 준다. 그 저장소의 코딩 스타일 규칙이 진짜로 막고 있는 것은 탭과 스페이스의 선택이 아니라 @ts-nocheck 남발, 동적 import 혼용, 프로토타입 변이 같은 구조적 결함이다.²⁵ 겉으로는 스타일 섹션처럼 보여도, 실제 내용은 취향이 아니라 시간 폭탄 방지 장치에 가깝다.

한 줄 판별 기준

실무에서는 복잡하게 생각할 필요가 없다. 다음 기준 하나면 대부분 분류된다.

위반했을 때 버그, 충돌, 보안 사고, 리뷰 혼선이 나면 저장소 규칙이다.
위반했을 때 “나라면 이렇게 안 짠다” 정도면 취향이다.

이 기준이 좋은 이유는 기술 스택이 바뀌어도 유효하기 때문이다. React든 Go든, 모노레포든 단일 서비스든, 사람과 에이전트가 함께 일하는 한 “사고를 막는 규칙"과 “선호를 표현하는 규칙"은 구분되어야 한다.

실전 설계: 네 층으로 나누면 깔끔해진다

저는 저장소 운영 규칙을 다음 네 층으로 나누는 방식을 권한다.

첫째, AGENTS.md에는 하드 가드레일만 둔다. 빌드/테스트 명령, 금지 영역, 리뷰 필수 조건, Git 안전 규칙, 고위험 변경 승인 경계처럼 틀리면 사고 나는 것들이다.

둘째, 팀 공통 컨벤션은 코드 포매터와 린터, 템플릿, 예시 코드에 둔다. 네이밍 선호, import 순서, 파일 배치 방식, 주석 스타일처럼 일관성이 중요하지만 문서로 길게 읽힐 필요는 없는 것들이다.

셋째, 반복되는 복잡한 절차는 스킬이나 플레이북으로 분리한다. 릴리스, 보안 점검, PR 운영처럼 단계가 많은 업무를 본문에 장황하게 넣기보다 실행 가능한 워크플로로 떼어내는 방식이다.

넷째, 개인의 작업 방식은 로컬 프롬프트와 에디터 설정에 남긴다. 프롬프트 문체, 병렬 에이전트 수, 탐색 습관, 임시 체크리스트 같은 것은 개인 생산성의 영역으로 두는 편이 낫다.

이렇게 나누면 저장소는 가벼워지고, 팀 합의는 자동화되며, 개인은 자신에게 맞는 작업 스타일을 유지할 수 있다. 무엇보다 에이전트가 읽는 지침의 우선순위가 선명해진다.

중요한 것은 개발자를 복제하는 것이 아니다

바이브 코딩의 핵심은 AI가 사람처럼 코드를 쓰게 만드는 것이 아니다. 오히려 사람과 완전히 똑같이 쓰지 않아도 되는 영역을 받아들이고, 대신 반드시 같아야 하는 부분만 명확히 고정하는 데 있다.

좋은 저장소 지침은 “우리 팀은 이런 취향을 가진 사람들이다"를 길게 설명하지 않는다. 대신 “이 저장소에서는 이것만큼은 반드시 지켜야 한다"를 짧고 명확하게 말한다. 취향은 열어두고, 경계는 닫아두는 것이다.

그게 결국 AI 에이전트를 잘 쓰는 팀과, AI를 쓰면서도 계속 피곤해지는 팀을 가르는 차이일 가능성이 크다.

---