Claude Code 설정 파일을 정리했더니 「형태」는 19%뿐이었다——4층×2축으로 본, 정리를 시작으로 하는 설계의 질문

이 기사의 실시 기록 (2026년 5월): はてなブログ(Hatena Blog) 개설 29일째, 52개의 포스팅을 한 시점에서 Claude Code의 설정·운용 파일군(약 299건)을 「4층×2축」으로 인덱스화했다. 그 결과, 범용화할 수 있는 「형태 (Shape)」는 불과 19%, 나머지 81%는 개인·사업 고유의 「내용 (Content)」이었다. 「파일이 늘어나서 정리하고 싶을 뿐」인 사람이야말로, 우선 이 비율의 의미를 알아두었으면 한다.

또한 본 기사는 「나의 Claude Code 환경 해체신서」 시리즈의 첫 번째 글이다. 정리의 전체상을 다루며, 속편에서 각 층에 대한 심층 분석으로 들어간다.

시작은 「정리하고 싶다」는 충동이었다

Claude Code로 블로그 운영을 시작한 지 29일째, 공개한 기사는 52개가 되었다.

기사 수가 늘어남에 따라, 또 다른 카운터도 조용히 늘어나고 있었다. CLAUDE.md, .claude/rules/, ops/playbooks/, scripts/, .claude/commands/, memory/ —— AI가 움직이는 「무대 뒤」의 파일들이 쌓여, 어느덧 약 299건에 달했다.

계기는 GA4에서 기사별 퍼포먼스를 살펴보고 있을 때였다. 「이 환경, 정리할 수 없을까?」라는 충동이 일었다. 다중 에이전트(Multi-agent) 조직을 운영하다 보면 거버넌스 사고 기록도 쌓인다 (이 시점에서 11건). 사고가 날 때마다 규칙을 추가한다. 추가할 때마다 「어디에 썼는지」 찾는 시간이 늘어난다. 정리해야 할 이유는 충분했다.

첫 번째 아이디어는 심플했다. 「3개 층으로 나눌 수 있지 않을까」 ——.

3층 모델이라는 첫 번째 가설

파일군을 살펴보니, 크게 세 가지 성질이 보였다.

L1: 범용 하네스 (General Harness). 가치관 거버넌스의 헌법·trigger list·에이전트 조직의 골격·global-rules. 「언제·어떤 프로젝트에서도 사용할 수 있는 규칙」의 집합으로, 변화 속도는 분기 단위.

L2: 기사 작성 프레임워크 (Article Creation Framework). 소재 노트 → writer → reviewer → reader → 3축 품질 게이트 → 공개 → 액세스 분석이라는 일련의 플로우 정의. 「이 블로그 사업에 특화된 워크플로우」이며, 변화 속도는 월 단위.

L3: 개인적 설정 (Personal Settings). /todo · /health 등의 스킬군, Evernote/Obsidian 통합, 위스키 사업 설정. 「자신의 생활·취향에 특화된 설정군」이며, 변화 속도는 주 단위로 증감함.

이 「변화 속도의 차이」가 층을 나누는 직관적인 기준임을 깨달았다. 빠른 것과 느린 것을 함께 두었기에, 변경할 때마다 영향 범위를 예측할 수 없게 되었던 것이다.

3층으로는 부족했다

이 가설을 다듬어 나가다 보니, 세 곳에서 경계가 모호해졌다.

문제 1: L1과 L2 사이에 있는 「횡단적 관심사 (Cross-cutting Concerns)」.

경로 기술 규칙 (path-policy.md), git 조작 규칙 (git -C 강제), 명명 규칙 (파일명·slug 규칙), 권한 관리 (settings.local.json 패턴) —— 이것들은 L1에도 L2에도 L3에도 속하지 않는다. 모든 층에 걸쳐 영향을 미친다. 어디에 두어도 「겉도는」 느낌이다.

문제 2: L3가 사실 4종류.

「개인적 설정」을 분해하면, 스킬 실행 로직·비밀 정보·외부 통합·사업 설정이라는 4종류가 혼재되어 있었다. 이것을 일괄적으로 「개인 설정」이라 부르기에는 입도(Granularity)가 너무 다르다.

문제 3: 동일한 파일에 여러 층이 공존.

에이전트 정의 파일 (.claude/agents/*.md)을 열어보면, L1적인 행동 패턴·L2적인 도메인 규약·L3적인 개별 지식이 한 파일 안에 혼재되어 있었다. 「어느 층의 파일인가」라는 질문에 답할 수 없는 파일이 생각보다 훨씬 많았다.

이 세 가지 문제를 해결하기 위해서는 3층 모델에 두 가지 확장이 필요했다.

「L0 횡단」과 「형태/내용의 2축」을 더했더니 4층×2축이 되었다

처음에는 3층이면 충분하다고 생각했다 —— 4층이 된 것은, 3층으로 정리하려고 했을 때 「이건 어디에 넣어야 하지?」라는 질문이 생겨났기 때문일 뿐이다.

먼저, 횡단적 관심사의 거처를 만들기 위해 L0 (횡단 규약) 을 추가했다. 경로 규칙·git 운용·명명 규칙·권한 관리 패턴이 여기에 수렴한다.

다음으로, 「어느 층인가」라는 세로축만으로는 부족하다는 것을 깨달았다. 「형태 (범용 패턴)」인가 「내용 (규약·설정값)」인가라는 가로축이 필요했다.

동일한 L2 기사 작성 프레임워크 (Article Creation Framework)라 하더라도, 「플로우 정의 구조」(다른 블로그 사업으로 가져갈 수 있는 형태)와 「공개 순서나 품질 게이트 (Quality Gate)의 임계값」(이 블로그 고유의 값)은 성질이 완전히 다르다. 전자는 일반적으로 적용할 수 있지만, 후자는 불가능하다.

이 2개의 축을 조합하면 8개 셀의 그리드 (Grid)가 된다.

약 299건을 스캔했더니, 형태는 19%뿐이었다

가설을 세웠던 단계에서는 「어느 정도 범용화할 수 있는 것들이 섞여 있을 것이다」라고 생각했다. 실제로 스캔해 보니 그 낙관론은 무너졌다.

2026년 5월 5일 실시, 약 299건의 Step 1 INDEX화 결과 (architect 실시):

형태 (범용 패턴)	내용 (규약·구현·값)
L0 횡단 규약	3건
L1 범용 하네스 (Harness)	12건
L2 기사 작성 프레임워크	8건
L3 개인적 설정	5건

합계: 형태=28건(19%), 내용=119건(81%)

(스캔한 약 299건 중, 이 그리드에 대표 파일로서 분류한 것이 147건. 나머지는 자동 생성물·바이너리·세밀한 중복 파일 등의 이유로 개별 판단 대상으로 처리했다)

「범용화할 수 있는 형태는 2할도 되지 않는다」——이 숫자가 예상 밖이었다. 19%라는 한 줄이 스캔 전의 기대를 그대로 상쇄했다.

충격은 여기서 끝이 아니었다. 그 28건을 더욱 심층 분석했을 때, 낙관론의 절반이 무너졌다. 형태 열의 28건 중, 일반화의 부하가 「낮음」(지금 바로 추출 가능)이라고 판정된 것은 8건이었다. 「중」이 12건, 「높음」(개인적 설정과의 분리가 어려워 대규모 작업이 필요)이 8건이었다.

즉, 「지금 바로 일반적으로 적용할 수 있는 형태」는 전체 147건 중 8건——약 5% 남짓에 불과하다.

정리를 가로막는 「형태와 내용의 공존」 22건

스캔을 통해 드러난 가장 큰 구조적 문제는 「형태와 내용이 공존하는 파일 22건」이다.

에이전트 정의 파일이 그 전형적인 사례로, 「범용적인 워크플로우 (Workflow, 형태)」와 「이 프로젝트 고유의 규칙 (내용)」이 동일한 파일에 작성되어 있다. 「어느 층인가」라고 물어도 1개의 파일이 양쪽 모두에 속해 있다——정리의 첫 번째 관문이 바로 여기에 있다.

또 다른 전형적인 사례는 settings.local.json이다. 610행에 달하는 이 파일에는 L0(범용적인 권한 관리 패턴)와 L3(나 개인의 CLI 경로 및 API 키 설정)가 혼재되어 있다. 층을 나누어 정리하려면 「어디가 L0이고 어디가 L3인지」를 한 줄씩 판별하여 분할해야 한다.

정리의 첫 단계에 필요한 것은 「형태와 내용의 파일 분할」——이것이 스캔을 통해 얻은 첫 번째 결론이었다. 일반화는 그 이후의 옵션에 불과하다.

「내용」을 더욱 분해하니 4개의 계층이 보였다

「4층×2축」 그리드를 사용하다 보니, 「내용」 열 또한 더욱 분해할 수 있다는 사실을 깨달았다.

내용에는 사실 3가지 종류가 혼재되어 있다.

• 설정값 (API 키·ID·고정 파라미터) —— 개인 고유, 절대 비공개
• 커스텀 구현 (Custom Implementation) (이 프로젝트 전용 로직) —— 범용화하면 「형태」로 승격 가능
• 학습 파라미터 —— 관찰·시행착오·사고를 통해 발견한 규칙이나 임계값

「학습 파라미터」가 가장 흥미로운 발견이었다.

품질 게이트의 임계값 「90점」은 처음부터 정해진 값이 아니다. 60점에서 시작하여 시행착오를 통해 수렴한 값이다. 「Hatena → 24시간 후 → Zenn」이라는 공개 순서도 운영 시도를 통해 확정한 규칙이다. 「Bash의 cd 금지」는 2026년 5월 3일의 사고 기록에서 탄생했다. 이것들은 「설정값」(단정적 값)도 「커스텀 구현」(코드)도 아니다. **길러낸 지견 (Knowledge)**이다.

4개 계층을 시각화하면 다음과 같다.

아래에서 위를 향해 「경험 → 추상화 → 범용화」라는 경로가 있다. 설정값에서의 실패가 학습 파라미터가 되고, 학습 파라미터가 추상화되어 커스텀 구현이 되며, 커스텀 구현이 범용화되어 「형태」(일반화의 대상)가 된다.

Claude Code 운영 정리가 다음 설계 과제를 시각화했다

이 스캔을 통해 나온 「다음에 할 일」은 2단계가 있다.

Step 2 (정리의 첫 수): 22건의 공존 파일을 분할한다. 형태와 내용이 공존하는 파일의 분할부터 착수한다. 여기를 해결하는 것이 4층×2축 정리를 진정한 의미에서 움직이기 시작하는 첫걸음이다.

Step 3 (정리 너머에 보인 것): L1의 「형태」 열을 범용화한다. 형태 열의 28건을 정밀 조사해 보니, 다른 환경으로 가져갈 수 있는 후보가 보이기 시작했다. 정리가 진행될수록 어디까지가 고유한 것이고 어디부터가 범용인지 명확해진다. 정리를 계속하는 이유 중 하나다.

또한 정리 과정에서 이미 범용화(Generalization)에 가까운 상태인 것들도 소수 보이기 시작했다 (상세 내용은 파생 기사에서 다룬다). 자율 탐지 패턴을 기술한 운영 Playbook이나 거버넌스 사고 기록의 포맷이 그 후보들이다.

그리고 스캔을 마친 뒤에 깨달은 「최대의 메타 발견(Meta-discovery)」이 있다.

11건의 사고 기록을 축적하면서 「trigger list를 추가한다」, 「Playbook에 추기한다」를 반복해 온 행위——그것은 「설정값에서의 실패 → 학습 파라미터화 (Learning Parameterization) → 커스텀 구현 (Custom Implementation) → 형태(Form)로의 승격」이라는 4계층의 승격 경로(Promotion Path)를 자신도 모르는 사이에 돌리고 있었던 것이 아닐까.

가치관 거버넌스(Values Governance) 메커니즘이, 동시에 「설계가 자동으로 성장하는 파이프라인(Pipeline)」으로서 기능하고 있었다.

이 발견의 상세한 내용은 다음 기사에서 쓰겠다. 이번에는 「정리하려고 했더니, 정리하는 방법 그 자체가 질문받게 되었다」는 이야기다. 그리고 사실, 위에서 언급한 Step 2 (22건의 동거 파일 분할)에 착수하는 것 자체가, 그 승격 파이프라인을 의도적으로 돌리기 시작하는 첫 번째 수이기도 하다.

3층을 사용하고 싶은 분들에게

여기까지 읽고 「나에게는 상관없는 규모 아닌가?」라고 생각하는 분들에게 답을 드린다.

52개·11건의 사고라는 것은 1개월의 실적이다. 블로그 첫 번째 글부터 4층×2축을 설계할 필요는 없다. 다만, 10개를 넘어가는 시점에서 「Playbook이 너무 많아졌다」, 「CLAUDE.md가 비대해졌다」고 느껴진다면, 한 번 이 관점을 가져보는 것이 정리의 실마리가 될 것이다.

「4층×2축은 너무 복잡하다」라는 감상도 이해할 수 있다. L1/L2/L3의 3층부터 시작해도 충분하며, L0 (횡단 규약)은 파일이 「어디에 넣어야 하지?」라며 떠오르는 시점에 추가하면 된다. 처음부터 4층을 설계할 필요는 없다.

「변화 속도의 차이」를 의식하는 것만으로도, 어떤 파일이 어느 층에 속하는지에 대한 직관은 단련된다. 빠른 것과 느린 것을 나누어 두면 변경의 영향 범위(Blast Radius)를 읽기 쉬워진다——그것만으로도 운용은 조금 편해진다.

Claude Code의 운용 설계를 체계적으로 배우고 싶은 분들에게는 다음과 같은 서적도 참고가 될 것이다.

자주 묻는 질문: Claude Code 설정 파일 정리

Q. 「형태」 19%라는 것은 너무 적은 느낌이 드는데, 정확한 수치인가?

A. 2026년 5월 5일에 약 299건을 스캔한 결과 (Step 1 INDEX화, architect 실시). 형태=28건 / 내용=119건의 합계 147건으로 계산하면 19.0%이다. 「약 299건」과의 차이는 그리드에 분류한 「대표 파일」의 집계치이기 때문이다 (자동 생성물, 바이너리, 미세한 중복 파일 등은 개별 판단 대상으로 처리함). 내역의 상세 내용은 별도로 집계 완료되었으며, 본 기사의 숫자는 그 실측치에 기반하고 있다.

Q. 22건의 동거 파일은 어떻게 분할하는가?

A. 파일을 열어 「어떤 기술이 범용적인가 (형태) / 어떤 기술이 고유한가 (내용)」를 한 문장씩 판정한다. 범용 부분은 별도 파일로 분리하고, 고유 부분은 원래 파일에 남긴다. 판정에 망설여질 때는 「변화 속도」를 묻는다——빠른 것이 고유(내용), 느린 것이 범용(형태)에 가깝다. 자동화는 불가능하며, 수작업이 필요하다.

Q. 어떤 도구·프레임워크를 사용하고 있는가?

A. Claude Code (Anthropic) + Hatena Blog + Zenn + GitHub Issues를 베이스로 한 자체 제작 다중 에이전트(Multi-agent) 조직이다. 스킬은 독자 구현 (/todo, /health 등). 외부 의존성은 GA4, Evernote, Obsidian, Slack이다.

실제 현장에서 어떻게 사용하는지 자세히 알고 싶은 분들에게는 실천적인 해설서가 있다.

이 실천의 경위와 전체상을 책으로 정리했습니다

코드를 쓸 줄 모르는 내가 Claude Code로 「AI 팀」을 만들기까지 (Zenn Books / 900엔)

「나의 Claude Code 환경 해체신서」 시리즈 첫 번째

다음 편: 사고 기록 11건이 「설계의 승격 파이프라인」이 되어 있었던 이야기 (파생 1)

이 기사는 Hatena Blog로부터의 크로스 포스트입니다.