AI한테도 '온보딩 문서'가 필요하더라고요
팀에 새 개발자가 들어오면 뭐부터 하나요? 코딩 컨벤션 문서 읽히고, PR 올리는 법 알려주고, 테스트는 어떻게 짜는지 가이드를 주잖아요. 그런데 요즘 팀마다 한 명씩(사실은 전원이) 쓰고 있는 Claude Code나 Codex 같은 AI 코딩 에이전트한테는 이런 온보딩을 안 시키는 경우가 많아요. 그 결과가 뭐냐면, 같은 팀인데 A 개발자의 에이전트는 이런 스타일로, B 개발자의 에이전트는 저런 스타일로 코드를 뽑아내는 상황이에요. 사람끼리는 컨벤션을 맞췄는데 AI 컨벤션은 제각각인 거죠.
이 문제를 겨냥한 오픈소스 프로젝트가 나왔어요. 팀의 코딩 표준을 '에이전트 스킬' 형태로 패키징해서 Claude Code와 Codex에 그대로 이식할 수 있게 만든 스킬 모음집이에요.
에이전트 스킬이 뭐냐면요
에이전트 스킬은 쉽게 말해 AI 에이전트에게 주는 '업무 매뉴얼 폴더'예요. 폴더 안에 SKILL.md라는 마크다운 파일을 두고, '이 스킬은 언제 쓰는 건지', '구체적으로 어떤 절차와 기준을 따라야 하는지'를 적어두면, 에이전트가 관련된 작업을 할 때 그 파일을 알아서 찾아 읽고 지시대로 움직여요.
여기서 중요한 특징이 '필요할 때만 읽는다'는 점이에요. CLAUDE.md나 AGENTS.md 같은 프로젝트 지침 파일은 세션 내내 통째로 컨텍스트(AI가 한 번에 기억하는 작업 공간)에 올라가 있거든요. 규칙이 쌓일수록 파일이 비대해지고, 정작 지금 작업과 상관없는 규칙까지 매번 읽게 되는 문제가 있어요. 스킬은 평소에는 한 줄짜리 설명만 올라가 있다가, 관련 작업이 시작될 때 본문이 로드돼요. 필요한 순간에만 서랍을 열어보는 방식이라 컨텍스트를 아낄 수 있죠.
이 프로젝트에는 뭐가 들어있나요
이 스킬 모음은 AI 시대의 개발 생명주기(ADLC, AI-driven Development Life Cycle)라는 관점에서 팀 개발의 각 단계를 스킬로 쪼개놨어요. 예를 들면 이런 것들이에요. 코드 리뷰를 할 때 어떤 기준으로 봐야 하는지를 담은 리뷰 스킬, 테스트를 어떤 구조와 커버리지 기준으로 작성해야 하는지 정의한 테스트 스킬, 커밋 메시지와 브랜치 이름 규칙을 지키게 하는 컨벤션 스킬 같은 식이죠. 핵심은 이걸 개인 설정이 아니라 '팀의 공유 자산'으로 관리한다는 거예요. 스킬 폴더를 저장소에 넣고 팀원 모두가 같은 스킬을 쓰면, 누구의 에이전트가 작업하든 같은 기준으로 코드가 나오게 되는 거죠. Claude Code와 Codex 양쪽에서 쓸 수 있게 만들어져 있어서, 팀원마다 쓰는 도구가 달라도 표준은 하나로 유지할 수 있고요.
기존 방식들과 뭐가 다른가요
사실 'AI에게 팀 규칙 알려주기'는 여러 방식이 경쟁 중인 영역이에요. Cursor에는 rules 기능이 있고, GitHub Copilot에는 instructions 파일이 있고, 도구마다 자기 방식이 있죠. 문제는 포맷이 도구마다 달라서, 팀이 여러 도구를 쓰면 같은 규칙을 여러 벌 관리해야 한다는 거예요. 스킬 방식이 흥미로운 건, 마크다운 기반의 비교적 열린 포맷이라 도구 간 이식이 상대적으로 쉽고, '항상 로드되는 거대한 규칙 파일' 대신 '필요할 때 로드되는 모듈'로 규칙을 구조화한다는 점이에요. 규칙을 코드처럼 모듈화하고, 버전 관리하고, PR로 개선하는 흐름이 자연스럽게 따라오거든요.
우리 팀에는 어떻게 적용해볼까요
바로 해볼 수 있는 건 이거예요. 저장소를 포크해서 스킬 몇 개를 골라 우리 팀 컨벤션에 맞게 내용을 고치고, 팀 저장소에 넣어보는 거죠. 특히 코드 리뷰 기준이나 테스트 작성 규칙처럼 '문서로는 있는데 잘 안 지켜지는' 규칙일수록 효과가 커요. 사람은 문서를 안 읽지만 에이전트는 스킬을 읽거든요. 그리고 스킬 자체를 PR로 다듬는 문화가 생기면, 팀의 암묵지가 명문화되는 부수 효과도 있어요.
한줄 정리: 팀 코딩 표준을 에이전트 스킬로 만들어 공유하면, 팀원 누구의 AI가 작업해도 같은 기준의 코드가 나와요.
여러분 팀은 AI 에이전트 규칙을 어떻게 관리하고 계세요? CLAUDE.md 하나로 버티는 중인지, 스킬로 쪼개기 시작했는지 궁금해요.
🔗 출처: Hacker News