# Boris Cherny의 제안: 팀 지식을 CLAUDE.md·스킬로 남겨라

- 게시: 2026.07.16
- 원문(HTML): https://trendbrief.news/articles/boris-cherny%EC%9D%98-%EC%A0%9C%EC%95%88-%ED%8C%80-%EC%A7%80%EC%8B%9D%EC%9D%84-claude-md-%EC%8A%A4%ED%82%AC%EB%A1%9C-%EB%82%A8%EA%B2%A8%EB%9D%BC.html
- 발행: [트렌드브리프](https://trendbrief.news/)

> Claude Code를 만든 Boris Cherny는 엔지니어 머릿속의 도메인 지식을 CLAUDE.md·스킬·문서로 남겨 AI 에이전트가 바로 활용하게 하라고 제안했다. 자동화의 연장선에서 팀 지식을 인프라로 남기는 실무 방법을 정리했다.

Claude Code를 만든 Boris Cherny(보리스 체르니)가 [X(옛 트위터)에 올린 글](https://x.com/bcherny/status/2077460395279692197)에서 개발자에게 한 가지를 제안했다. 예전엔 뛰어난 엔지니어일수록 자기 일을 자동화하는 데 시간을 많이 썼는데, 이제 AI 에이전트가 등장하면서 그동안 사람 머릿속에만 있던 도메인 지식을 코드 주석·CLAUDE.md·스킬·문서로 옮겨 두라는 것이다. 핵심은 이렇다. 팀마다 에이전트가 추가 설명 없이도 코드베이스에서 제대로 일할 수 있게 만드는 규칙 파일을 미리 써 두라는 것. 이 글은 개발자 팀을 대상으로, 그 주장과 2026년 7월 기준 Claude Code 공식 문서를 근거로 CLAUDE.md·스킬을 실무에서 무엇부터 어떻게 쓰는지 짚는다. 특정 팀의 도입 성과를 측정한 자료는 아니다.

## Boris Cherny가 올린 글의 핵심은 무엇인가

한 줄로 요약하면 '도메인 지식을 인프라로 남겨라'다. Boris Cherny는 자기가 아는 최고의 엔지니어들이 vim·emacs 자동화, 반복되는 코드 문제를 잡는 lint 규칙, 매번 수동으로 확인하지 않아도 되게 하는 e2e(사용자 흐름을 처음부터 끝까지 자동으로 검증하는) 테스트 묶음을 만드는 데 시간을 많이 썼다고 적었다. 여기서 lint(코드에서 잠재적 오류나 스타일 문제를 자동으로 찾아 주는 검사 도구) 규칙과 테스트는 사람의 판단을 코드로 굳혀 둔 결과물이다.

그가 짚은 변화는 이렇다. 예전에는 도메인 지식을 lint 규칙·타입·테스트로만 담을 수 있어서 담을 수 있는 양이 제한적이었다. 반면 에이전트에게는 코드 주석, 스킬, CLAUDE.md 규칙과 메모리 형태로 훨씬 많은 지식을 넘길 수 있다. 사람 머릿속에만 있고 자동화되지 않은 지식은 신입이 온보딩 때 일일이 배워야 하는 장벽인데, Boris Cherny는 그 장벽을 파일로 옮기자고 말한다.

## 예전 자동화의 연장선이라는 뜻

Boris Cherny는 이 접근을 '엔지니어가 늘 해 온 일, 즉 자동화하고 도메인 지식을 인프라로 남기는 일의 자연스러운 연장'이라고 표현했다. lint 규칙을 쓰는 이유와 CLAUDE.md를 쓰는 이유는 같다. 같은 실수를 사람이 매번 잡는 대신 한 번 규칙으로 박아 두는 것이다.

이 발상 자체는 새롭지 않다. 아키텍처 규칙을 문서가 아니라 유닛 테스트로 못 박아 위반을 빌드 단계에서 걸러 내는 [아키텍처 규칙을 테스트로 강제하는 방식](https://trendbrief.news/articles/harmonize%EB%A1%9C-swift-%EC%95%84%ED%82%A4%ED%85%8D%EC%B2%98-%EA%B7%9C%EC%B9%99%EC%9D%84-%EC%9C%A0%EB%8B%9B-%ED%85%8C%EC%8A%A4%ED%8A%B8%EB%A1%9C-%EA%B0%95%EC%A0%9C%ED%95%98%EA%B8%B0.html)도 결국 사람의 판단을 실행 가능한 검사로 굳힌 사례다. CLAUDE.md·스킬은 그 대상이 정적 규칙에서 에이전트가 읽는 자연어 지침으로 넓어진 형태라고 보면 된다.

## CLAUDE.md와 스킬은 실제로 어떻게 쓰나

CLAUDE.md는 Claude가 매 세션 시작 때 읽는 마크다운 규칙 파일이다. Claude Code [공식 문서](https://docs.claude.com)에 따르면 이 파일은 위치에 따라 적용 범위가 달라진다. 프로젝트 루트에 둔 CLAUDE.md는 그 프로젝트에서만 적용되고, 사용자 홈의 ~/.claude/CLAUDE.md는 모든 프로젝트에 적용된다. 그래서 팀 지식은 프로젝트 루트 파일에 넣어 git에 체크인해 함께 쓰고, 개인 취향은 홈 파일에 두는 식으로 나눈다.

| 형태 | 적용 범위 | 주로 담는 것 |
| --- | --- | --- |
| 프로젝트 루트 CLAUDE.md | 해당 프로젝트 | git에 체크인하는 팀 공유 규칙 |
| ~/.claude/CLAUDE.md | 모든 프로젝트 | 개인 워크플로·취향 |
| 스킬(SKILL.md) | 호출 또는 자동 로드 | 재사용 절차·작업 묶음 |

스킬은 SKILL.md 파일로 정의한다. 같은 공식 문서에 따르면 스킬은 /스킬이름으로 직접 부르거나 상황에 맞을 때 자동으로 불러온다. CLAUDE.md가 '항상 지켜야 할 규칙'이라면, 스킬은 '특정 작업을 할 때 꺼내 쓰는 절차 묶음'에 가깝다. CLAUDE.md는 거창할 필요가 없다. 팀이 반복해서 알려 주던 내용을 그대로 문장으로 적으면 된다.

```
# 프로젝트 규칙
- 커밋 전에 반드시 `npm test`를 실행한다.
- 프로덕션 설정과 환경 변수는 수정하지 않는다.
- 새 API 핸들러는 src/api/ 아래에 두고 기존 에러 처리 유틸을 재사용한다.
```

## 팀 도입은 규칙 한 줄에서 시작한다

가장 단순한 출발점은 하나다. 에이전트가 뭔가 틀리게 했을 때, 그 자리에서 다시는 그러지 않도록 규칙 한 줄을 CLAUDE.md에 추가하는 것. Boris Cherny가 반복해서 강조하는 방식이 이것이다. 실수를 매번 사람이 다시 잡는 비용을, 규칙을 한 번 쓰는 비용으로 바꾸는 셈이다.

그다음은 범위를 넓히는 순서다.

- 자주 나오는 지시를 프로젝트 루트 CLAUDE.md로 옮기고 git에 체크인해 팀 전체가 공유한다.
- 코드 리뷰에서 반복 지적되는 항목은 REVIEW.md 같은 리뷰 지침 파일로 분리한다. Boris Cherny는 CLAUDE.md뿐 아니라 REVIEW.md와 스킬, 문서를 함께 갖추라고 제안했다.
- 여러 단계를 거치는 반복 작업, 예컨대 배포 전 점검이나 릴리스 노트 작성은 스킬로 만들어 필요할 때 호출한다.

주의할 점도 있다. 규칙이 늘어날수록 서로 충돌하거나 낡은 규칙이 남는다. 새 규칙을 넣을 때 기존 규칙과 어긋나지 않는지 확인하고, 더 이상 맞지 않는 규칙은 지워야 파일이 신뢰를 유지한다. 규칙 파일도 코드처럼 관리 대상이라는 뜻이다.

## 실무자 입장에서 남는 것

정리하면 에이전트 시대의 자동화는 더 정교한 vim 매크로를 짜는 일이 아니다. 팀이 아는 것을 에이전트가 읽을 수 있는 파일로 옮기는 일이다. CLAUDE.md 한 파일에서 시작해 에이전트가 틀릴 때마다 규칙을 보태 나가면, 그 파일이 곧 신입 온보딩 문서이자 반복 실수를 막는 품질 장치가 된다. 큰 도입 계획을 세우기보다 오늘 규칙 한 줄을 적는 편이 Boris Cherny가 말한 방향에 더 가깝다.

## 관련 글

- [Grok Build 오픈소스 공개, 설치·실행과 사용 한도 초기화](https://trendbrief.news/articles/grok-build-%EC%98%A4%ED%94%88%EC%86%8C%EC%8A%A4-%EA%B3%B5%EA%B0%9C-%EC%84%A4%EC%B9%98-%EC%8B%A4%ED%96%89%EA%B3%BC-%EC%82%AC%EC%9A%A9-%ED%95%9C%EB%8F%84-%EC%B4%88%EA%B8%B0%ED%99%94.md)
- [SwiftUI 성능 개선, 뷰 재평가를 줄여 스크롤 끊김 잡기](https://trendbrief.news/articles/swiftui-%EC%84%B1%EB%8A%A5-%EA%B0%9C%EC%84%A0-%EB%B7%B0-%EC%9E%AC%ED%8F%89%EA%B0%80%EB%A5%BC-%EC%A4%84%EC%97%AC-%EC%8A%A4%ED%81%AC%EB%A1%A4-%EB%81%8A%EA%B9%80-%EC%9E%A1%EA%B8%B0.md)
- [Article 구조화 데이터로 저자·발행일·이미지 마크업하기](https://trendbrief.news/articles/article-%EA%B5%AC%EC%A1%B0%ED%99%94-%EB%8D%B0%EC%9D%B4%ED%84%B0%EB%A1%9C-%EC%A0%80%EC%9E%90-%EB%B0%9C%ED%96%89%EC%9D%BC-%EC%9D%B4%EB%AF%B8%EC%A7%80-%EB%A7%88%ED%81%AC%EC%97%85%ED%95%98%EA%B8%B0.md)
- [Harmonize로 Swift 아키텍처 규칙을 유닛 테스트로 강제하기](https://trendbrief.news/articles/harmonize%EB%A1%9C-swift-%EC%95%84%ED%82%A4%ED%85%8D%EC%B2%98-%EA%B7%9C%EC%B9%99%EC%9D%84-%EC%9C%A0%EB%8B%9B-%ED%85%8C%EC%8A%A4%ED%8A%B8%EB%A1%9C-%EA%B0%95%EC%A0%9C%ED%95%98%EA%B8%B0.md)
- [fenic으로 데이터프레임에 LLM 연산 붙이기](https://trendbrief.news/articles/fenic%EC%9C%BC%EB%A1%9C-%EB%8D%B0%EC%9D%B4%ED%84%B0%ED%94%84%EB%A0%88%EC%9E%84%EC%97%90-llm-%EC%97%B0%EC%82%B0-%EB%B6%99%EC%9D%B4%EA%B8%B0.md)