Molayo

© 2026 Molayo

Dev.to헤드라인2026. 05. 29. 02:05

20개의 파일로 코드베이스의 DNA를 읽어내는 Claude Code 스킬을 만들었습니다

요약

코드베이스의 컨벤션과 규칙을 자동으로 추출하여 Claude Code가 준수하도록 만드는 'Codebase DNA Guardian' 스킬을 소개합니다. 전체 파일을 읽는 대신 핵심적인 15~20개의 파일을 정밀하게 샘플링하여 프로젝트의 DNA를 프로필화합니다.

핵심 포인트

  • 전체 코드베이스 대신 핵심 파일 15~20개만 샘플링하여 효율성 극대화
  • 추출된 규칙은 .claude/dna.md 파일로 저장되어 Claude가 자동 참조
  • 규칙의 심각도(Tier)를 설정하여 Claude의 코드 생성 동작 제어 가능
  • 린터에 없는 팀 고유의 암묵적 규칙을 기계가 읽을 수 있는 형태로 변환

모든 팀에는 코드 리뷰 중에 다음과 같은 코멘트를 남기는 시니어 개발자가 있습니다:

"여기서는 axios를 직접 사용하지 않습니다. apiClient 래퍼(wrapper)를 거쳐가세요."
"모든 에러는 AppError 클래스를 사용해야 합니다. 생 문자열(raw strings)을 throw하지 마세요."
"이 프로젝트의 파일명은 camelCase가 아니라 kebab-case를 사용합니다."

이러한 규칙 중 그 어떤 것도 린터(linter)에 들어있지 않습니다. README에도 없습니다. 오직 한 사람의 머릿속에만 존재합니다.
그 사람이 떠나거나, AI 어시스턴트가 코드를 작성할 때, 이러한 규칙들은 끊임없이 위반됩니다.

저는 이러한 규칙들을 자동으로 찾아내어 기계가 읽을 수 있는 프로필(profile)로 작성하고, Claude가 새로운 코드를 생성할 때마다 이를 강제하는 Claude Code 스킬을 만들었습니다. 저는 이것을 Codebase DNA Guardian이라고 불렀습니다.

이것이 어떻게 작동하는지, 이를 만들며 무엇을 배웠는지, 그리고 1,388개의 파일로 구성된 프로덕션 코드베이스에 대한 실제 스캔 결과는 어떠한지 소개하겠습니다.

핵심 아이디어: 전체 읽기가 아닌 정밀한 샘플링 (surgical sampling)

코드베이스 전체를 읽는 것은 낭비이며 느립니다. 500개의 파일로 구성된 TypeScript 프로젝트는 단 하나의 패턴을 추출하기도 전에 컨텍스트 윈도우(context window)를 모두 소진해 버릴 것입니다.

통찰: 500개의 파일이 모두 필요하지는 않습니다. 여러분에게 필요한 것은 다음과 같습니다:

  1. 설정 파일 (3~5개): tsconfig.json, .eslintrc, pyproject.toml — 이 파일들은 팀이 합의한 규칙을 알려줍니다.
  2. 엔트리 포인트 (2~3개): main.ts, app.ts — 부트스트랩(bootstrap) 패턴, 전역 상태(global state) 설정.
  3. 하나의 수직적 슬라이스 (4~6개 파일): 가장 "평균적인" 기능을 선택하여 route → service → repository → test를 읽습니다. 이 단 하나의 슬라이스가 무작위 파일 50개보다 프로젝트의 컨벤션(conventions)에 대해 더 많은 것을 드러냅니다.
  4. 에러 처리 샘플 (2~3개): catch, throw, AppError를 grep으로 검색.
  5. 테스트 (2~3개): 프레임워크, 모킹(mocking) 전략, 파일 명명 규칙.

총 15~20개의 파일입니다. 8가지 카테고리에 걸쳐 신뢰할 수 있는 패턴을 추출하기에 충분한 양입니다.

스캔 결과물

프로젝트에서 /dna-scan을 실행한 후, 이 스킬은 .claude/dna.md 파일을 작성합니다:

| ID | Tier | Rule | Example | Counter-example |
|----|------|------|---------|---------------|
| A1 | 🔴 HARD | frappe-ui의 createResource를 통한 프론트엔드 HTTP 호출 — raw fetch/axios 사용 금지 | `createResource({ url: 'hrms.api...' })` | `axios.get(...)` |
| ... |

모든 규칙에는 **심각도 계층 (severity tier)**이 있습니다:

TierClaude의 동작
🔴 HARD중단합니다. 규칙을 설명합니다. 진행하기 전에 사용자에게 확인을 요청합니다.
...

.claude/dna.md 파일이 생성되면, Claude는 모든 코드 생성 전에 이를 읽습니다 — 별도의 추가 명령은 필요하지 않습니다. DNA는 항상 활성화되어 있습니다.

실제 스캔: frappe/hrms (1,388개 파일, 18개 샘플링)

저는 오픈 소스 HR 및 급여 관리 시스템인 frappe/hrms에서 이를 실행했습니다. Python 백엔드 + Vue 3 PWA 프론트엔드 + TypeScript 로스터(roster) 서비스 — 세 가지 언어, 세 가지 프레임워크, 하나의 모노레포 (monorepo)로 구성되어 있습니다.

18개 파일 샘플링. 19개 규칙 추출. 스캔 시간: 3분 미만.

결과:

Consistency Score: 90/100

🔴 HARD rules: 10 — all passing ✅
...

좀비 의존성 (zombie dependency) 하나만으로도 스캔할 가치가 충분합니다. html2canvas는 0.8 MB입니다. 이는 모든 사용자에게 전달됩니다. 하지만 아무도 이를 임포트(import)하지 않습니다.

대시보드

이 프로젝트에는 스캔 결과를 시각적으로 렌더링하는 React 대시보드가 포함되어 있습니다 — 애니메이션 점수 링, 서비스별 일관성 바, 좀비 트래커, 진화 스파크라인 (evolution sparkline) 등이 제공됩니다.

DNA Guardian Services Tab

DNA Guardian Rules Tab

이는 스캔 결과로 채워지는 DNA_DATA 객체에 의해 구동됩니다. Claude Code 내부에서 /dna-preview를 실행하면 자동으로 번들링, 서빙 및 스크린샷을 찍어줍니다.

모노레포 (Monorepo) 지원

멀티 서비스 프로젝트의 경우, 스캔은 여러 단계(waves)로 실행됩니다:

Wave 1: root — 공통 설정 (shared config), CI, 공통 유틸리티 (shared utilities)
Wave 2: per-service — 각 서비스별 수직적 슬라이스 (vertical slice) 하나씩
Wave 3: cross-comparison — 서비스 간 패턴 차이 비교 (diff patterns)
...

출력 결과는 .claude/dna/root.md 및 서비스별 오버라이드(overrides) 파일로 저장됩니다. 우선순위(Resolution order)는 서비스 DNA > 루트 DNA 순입니다. 만약 aegis.md에는 "JOSE를 사용하라"고 되어 있고 root.md에는 "jsonwebtoken을 사용하라"고 되어 있다면, 해당 서비스 내부의 코드에 대해서는 Aegis의 설정이 승리합니다.

내가 만든 스킬에서 발견한 잘못된 점들

발표하기 전에 엄격한 코드 리뷰를 진행했습니다. 7개의 독립적인 리뷰어 관점을 적용하여 11개의 확정된 버그를 찾아냈습니다. 가장 교훈적이었던 것들은 다음과 같습니다:

쉘 연산자 우선순위 (Shell operator precedence):

# 잘못됨 — -maxdepth 2가 첫 번째 -name 절에만 적용됨
find . -maxdepth 2 -type f -name "*.json" -o -name "*.toml" -o -name "*.yaml"

...

괄호가 없으면 -o 연산자가 .toml 및 .yaml 파일에 대해 -maxdepth 2 제약 조건을 깨뜨립니다. 실제 프로젝트에서 이대로 실행하면 node_modules/ 디렉토리까지 재귀적으로 탐색하여 수천 개의 파일을 반환하게 됩니다.

GNU grep 교대 (GNU grep alternation):

# Linux에서 잘못됨 (BRE 모드 — 리터럴 문자열 "catch|Error|throw"와 일치함)
grep -rl "catch\|Error\|throw" src/

...

두 개의 점(..) vs 세 개의 점(...) git diff:

# 잘못됨 — 현재 브랜치에 없는 main 브랜치의 커밋까지 포함함
git diff main..feature/my-branch --name-only

...

실행 가능한 코드가 전혀 없고 오직 지침(instructions)으로만 구성된 스킬에서 세 가지 쉘 레벨의 버그를 발견한 것은 다음과 같은 사실을 상기시켜 주었습니다: AI 에이전트 지침은 코드입니다. 지침은 프로그램과 동일한 실패 모드(failure modes)를 가집니다.

설치

npx skills add mturac/codebase-dna-guardian

또는 npm을 통해 설치할 수 있습니다:

npm install -g codebase-dna-guardian

GitHub → mturac/codebase-dna-guardian

이 스킬은 MIT 라이선스를 따르며, Cursor/Copilot/Windsurf 호환성을 위한 AGENTS.md를 포함하고 있고, React 대시보드 컴포넌트와 함께 제공됩니다.

제가 계속해서 되새기는 생각은 이것입니다: 모든 코드베이스에는 파일 히스토리, 명명 패턴(naming patterns), 에러 처리 전략 속에 시니어 개발자가 내재되어 있다는 사실입니다. 이 스킬은 단지 그것을 읽어낼 뿐입니다.

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0