코드베이스 아키텍처 개선: 얕은 모듈을 깊은 모듈로 재구성

실패 모드: “잘못된 코드 베이스에서 떠도는 AI”

Matt의 강연에서 네 번째 실패 모드는 그림으로 비유한 것입니다.

"코드베이스의 얕은 모듈은 다음과 같습니다. 작은 덩어리가 많이 있고 AI는 이를 수정하기 전에 여러 모듈을 거쳐 모든 종속성을 이해해야 합니다."

"AI is really good at creating codebases like this. So you'll have a situation where AI doesn't understand what your code is doing. It will attempt to explore the code, but because it's poorly laid out, filled with shallow modules, it doesn't get to the right module in time, or doesn't understand all the dependencies."

이는 AI 프로그래밍 특유의 악순환입니다.

AI 写代码倾向于产生 shallow 模块（小、多、互相依赖）
    ↓
代码库变得 shallow
    ↓
下次 AI 进来探索更难，更容易写错
    ↓
更多 shallow 模块被加进去
    ↓
代码库越来越烂，AI 越来越无能

이 주기를 깨기 위해서는 수동 역리팩토링을 주기적으로 수행하여 얕은 모듈을 깊은 모듈로 병합해야 합니다. 이것이 바로 /improve-codebase-architecture이 하는 일입니다.

고전 이론: Ousterhout의 심층 모듈

John Ousterhout는 스탠포드의 CS 교수이자 Tcl 언어 및 Raft 논문의 저자입니다. 그의 2018년 저서 "A Philosophy of Software Design"은 간단하지만 강력한 통치자를 제안합니다.

모듈의 "깊이" = 인터페이스의 숨겨진 복잡성

이상적인 모듈은 심층적입니다. 사용자는 짧은 인터페이스만 보면 되고 복잡성은 내부에 숨겨져 있습니다. 극단적인 반례는 얕은 모듈입니다. 인터페이스는 구현만큼 복잡하며, 이는 캡슐화가 없음을 의미합니다. 사용자는 구현을 직접 볼 수도 있습니다.

Ousterhout의 판단: 좋은 코드 기반은 소수의 심층 모듈로 구성됩니다. 나쁜 코드 베이스는 수많은 얕은 모듈로 구성됩니다. 이는 "기능을 가능한 한 작게, 파일을 가능한 한 짧게, 모듈을 최대한 많이 유지"하는 전통적인 신조와 완전히 반대입니다. 그는 이러한 종류의 신조가 정확히 얕은 모듈을 생성한다고 믿습니다.

Matt의 확장 프로그램: 삭제 테스트

Matt는 Ousterhout의 이론을 삭제 테스트라고 부르는 운영 엔지니어링 테스트로 번역했습니다.

Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.

인간의 말:

• 삭제하면 복잡함이 사라집니다 → 이 모듈은 원래 pass-through(transit) 모듈이라 작동하지 않으니 잘라주세요.
• 삭제하면 복잡성이 N명의 호출자에게 전파됩니다 → 원래는 복잡성을 숨기는 데 도움이 되므로 정말 깊으므로 그대로 두세요.

이 테스트의 장점은 양방향이라는 것입니다. 즉, "삭제해야 하는 얇은 패키지"와 "추출해야 하는 공통 논리"를 모두 식별할 수 있습니다. 코드 조각을 삭제한 후 복잡성이 5곳으로 퍼지는 것을 발견하면 이 코드를 심층 모듈로 추출할 가치가 있음을 의미합니다.

핵심 용어(Matt의 정확한 정의)

improve-codebase-architecture/SKILL.md에는 이 단어의 엄격한 사용을 요구하는 용어집이 있습니다. "구성 요소", "서비스", "API" 및 "경계"로 이동하지 마십시오.

몇 가지 핵심 원칙:

• 삭제 테스트: 위 참조
• 인터페이스는 테스트 표면입니다: 테스트는 인터페이스를 통해서만 실행될 수 있습니다. 이는 심층 모듈 테스트 가능성의 기초입니다.
• 어댑터 1개 = 가상 솔기. 두 개의 어댑터 = 실제 이음새.: 구현이 하나만 있는 인터페이스는 거짓 이음새입니다. 실제 조인트에는 최소 2개의 어댑터가 필요합니다

마지막은 특히 반직관적입니다. 많은 팀이 "향후 확장을 위해" 미리 인터페이스를 추상화하지만 실제로는 하나의 구현만 있습니다. Matt의 판단: 쓸모 없음, 삭제. 두 번째가 이루어질 때까지 기다리십시오. 이는 YAGNI와 동일한 유래를 갖는다.

스킬 작업흐름

1. 탐색

Skill은 먼저 AI가 CONTEXT.md 및 docs/adr/을 읽은 다음 subagent_type=Explore를 사용하여 하위 에이전트를 코드 베이스로 보냅니다.

경직된 영감 대신 마찰을 신호로 사용하세요.

• Where does understanding one concept require bouncing between many small modules?
• Where are modules shallow — interface nearly as complex as the implementation?
• Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no locality)?
• Where do tightly-coupled modules leak across their seams?
• Which parts of the codebase are untested, or hard to test through their current interface?

의심스러운 점을 발견할 때마다 삭제 테스트를 적용하세요. 삭제하면 복잡성이 사라지나요, 아니면 퍼질까요? '해산'이라는 답은 심화할 가치가 있는 후보다.

2. 현 후보자(성명후보자)

번호가 매겨진 후보자 목록을 제시하십시오.

1. Files: src/orders/parser.ts, src/orders/validator.ts, src/orders/normalizer.ts
   Problem: 三个文件互相调用，理解 Order 入站需要在三处跳转
   Solution: 合并为单一 OrderIntake 模块，对外只暴露 parse(raw) → ValidatedOrder
   Benefits:
     - Locality: Order 入站的所有逻辑、错误处理、bug 修复集中一处
     - Leverage: 调用方从理解 3 个接口降为 1 个
     - Tests: 只需测 parse() 的输入输出，不再需要 mock 内部协作

요구사항:

• CONTEXT.md 어휘를 사용하여 도메인("FooBarHandler"가 아닌 "주문 접수 모듈")에 대해 이야기합니다.
• 용어집("심", "깊이", "지역성")을 사용하여 건축에 대해 이야기합니다.
• 인터페이스 디자인을 즉시 제안하지 마세요 - 사용자가 먼저 흥미로운 후보를 선택하도록 하세요.

후보자가 기존 ADR과 충돌하는 경우 충돌로 인해 ADR을 다시 방문해야 하는 경우에만 이를 언급하고 다음과 같이 명확하게 표시하십시오.

"contradicts ADR-0007 — but worth reopening because…"

ADR에서 금지하는 모든 리팩토링을 파헤치지 마세요.

3. 그릴링 루프

사용자가 후보를 선택한 후 굽기 모드로 전환합니다(/grill-with-docs에서 상속됨).

• 디자인 트리를 살펴보세요 - 제약 조건, 종속성, 심화 후 모듈의 모양, 이음매 뒤에 숨겨진 것, 테스트가 살아남을 수 있음
• 부작용은 즉시 발생합니다:
• 심화 모듈에 CONTEXT.md에 없는 이름을 부여 → 즉시 CONTEXT.md에 추가
• 고문에서 모호한 용어가 날카롭게 표현되었습니다. → CONTEXT.md를 즉시 업데이트하세요.
• 사용자가 합리적인 부하 부담(중요, 미래 탐험가가 알아야 할 사항)으로 후보를 거부 → ADR 생성 제안
• 심화 모듈의 다양한 인터페이스 디자인을 탐색하고 싶음 → INTERFACE-DESIGN.md 별도 프로세스로 이동

문서 유지 관리와 아키텍처 변환은 동일한 대화에서 이루어지며 두 번 반복되지 않습니다.

실제 사례: 메즈바 아흐메드(Mejba Ahmed)의 사례

타사 개발자 Mejba Ahmed는 이 기술을 사용한 경험을 자세히 기록하기 위해 "Deep Modules: The Claude Code Skill Saving My Codebase"라는 기사를 작성했습니다. 핵심 사항:

• 그는 원래 한 프로젝트에 50개 이상의 파일을 갖고 있었고, 각 파일의 길이는 100줄 미만이었습니다. - 일반적인 얕은 라이브러리
• /improve-codebase-architecture에서 심화 후보 8명을 뽑았습니다.
• 그는 3개의 심화 항목을 선택했습니다(2개의 데이터 처리 모듈 병합, 1개의 도구 세트 병합).
• 결과: 파일 수가 50개 이상에서 30개 이상으로 줄었지만 총 코드 크기는 기본적으로 동일하게 유지됩니다 - 소수의 심층 모듈로 복잡성이 압축되었습니다.
• 이 라이브러리에서 Claude의 후속 코드 변경 적중률이 크게 향상되었습니다. ("60%에서 90%로"라고 말했는데, 이는 엄격하게 측정되지는 않았지만 강하게 느껴졌습니다)

Mejba에는 한 번에 8단계씩 심화하지 마세요라는 알림도 있습니다. 한 번에 하나만 선택하고 테스트 + 커밋 + 관찰을 실행한 후 다음 항목을 선택하세요. 그렇지 않으면 완료한 후 롤백할 수 있는 방법이 없습니다.

설치 및 사용방법

npx skills@latest add mattpocock/skills

improve-codebase-architecture + setup-matt-pocock-skills을 확인하세요.

전화: /improve-codebase-architecture

권장 리듬:

• 일주일에 한 번 또는 각 스프린트가 끝날 때 실행
• 또는 **집약적 개발의 물결을 마친 후 한 번 실행합니다. (특히 AI 코드를 자주 작성한 후 얕은 모듈을 쌓기 쉽습니다.)
• 바쁠 때 뛰지 마세요 - 바쁠 때 소화할 시간이 없을 정도로 큰 변화를 제안합니다.

일반적인 프로세스:

1. /improve-codebase-architecture
2. AI 탐색 + N개 후보 나열(삭제 테스트 인수 포함)
3. 가장 기분이 좋은 것을 고르세요
4. 그릴 루프 정렬 디자인에 드롭
5. AI 구현 리팩토링(/tdd과 함께 실행하는 것이 좋습니다. 리팩토링에는 테스트 보호 기능이 있어야 합니다)
6. 커밋 + 관찰
7. 일주일 뒤에 또 오세요

이 스킬이 Matt 작업 흐름의 "폐쇄 루프"인 이유는 무엇입니까?

Matt의 작업 흐름 다이어그램으로 돌아가서:

/grill-me → /to-prd → /to-issues → /tdd → /improve-codebase-architecture → 回到 /grill-me

시작점으로 되돌아가는 것에 주목하세요. /improve-codebase-architecture은(는) 일회성 도구가 아니며 정기적인 유지 관리입니다. 그 이유는 다음과 같습니다.

1. AI는 계속해서 코드 베이스에 얕은 모듈을 추가합니다. (이것이 기본 경향이며, 너무 많이 쓰면 쌓이게 됩니다.)
2. 비즈니스가 계속 발전함에 따라 오래된 이음새는 쓸모 없게 될 것입니다.
3. CONTEXT.md의 용어는 계속해서 날카로워지고 있으며 이전 이름은 유지되지 않습니다.

이 스킬을 실행할 때마다 코드 베이스의 AI 친화성이 새로워집니다. 이것이 LLM을 사용하여 장기간 코드베이스를 건강하게 유지하는 유일한 방법입니다. 새로 고치지 않으면 3개월 후에 코드베이스에서 AI가 종료됩니다.

스킬 자체보다 이런 사고방식이 더 가치있습니다

/improve-codebase-architecture을 전혀 설치하지 않더라도 다음 세 가지만 기억하시면 PR 리뷰의 질이 한 단계 향상됩니다.

1. 삭제 테스트: 새 모듈을 볼 때마다 "삭제하면 복잡성이 사라지는가, 아니면 퍼질 것인가?"라고 자문해 보세요.
2. 최소 두 개의 어댑터가 실제 연결됨: 단일 구현 인터페이스 = 거짓 추상, 삭제
3. 인터페이스는 테스트 표면입니다: 측정할 수 없음 = 인터페이스 디자인에 문제가 있음

이 세 가지 항목에는 AI나 기술이 필요하지 않습니다. 이는 엔지니어링 미학의 경화입니다. Matt는 이를 일괄 실행을 위한 기술로 묶었지만 실제 활용은 세 가지 원칙 자체입니다.

메모

너무 깊이 들어가지 마세요. Ousterhout 자신은 딥 모듈이 교리라기보다는 목표라고 말했습니다. 모든 기능을 그 안에 집어넣는 대규모 Util 클래스는 딥 모듈이 아니라 신 모듈입니다. 판단 기준은 '간단한 인터페이스 + 응집력 있는 구현'이며 이 두 가지를 모두 충족해야 합니다.

심화에는 테스트 보호 기능이 있어야 합니다. 구조적 변경은 위험도가 높은 작업이며, 테스트 없이 대담하게 리팩토링하는 것 = 책임을 지기를 기다리는 것입니다. 현재 테스트가 없으면 /tdd으로 이동하여 중요 경로에 테스트를 추가한 다음 다시 돌아옵니다.

ADR 결정은 즉흥적으로 이루어져서는 안 됩니다. 굽는 동안 후보자를 거부하면 AI는 쉽게 ADR 생성을 제안합니다. 이유가 실제로 "미래 사람들이 알아야 할 사항"인 경우에만 이를 수락합니다. 그렇지 않으면 docs/adr/이 저널 항목으로 채워집니다.

코드 중 일부가 얕아도 상관없습니다. 로거 래퍼, 상수 파일, 일회용 스크립트 등은 얕아서 문제가 되지 않습니다. 이 기술은 추상화에 도움이 되는 척하지만 실제로는 혼란을 더하는 얕은 모듈을 찾습니다.

참조 리소스

시리즈 결론

지금까지 6개의 글을 모두 읽었습니다. 전체 워크플로를 검토합니다.

/grill-me 或 /grill-with-docs   ← 谈清楚要做什么
        ↓
   /to-prd                       ← 凝固成 PRD
        ↓
   /to-issues                    ← 切成 vertical slice
        ↓
   /tdd                          ← 一个 slice 一个 slice 跑红绿
        ↓
   /improve-codebase-architecture ← 周期性深化
        ↓
        回到 /grill-me

이 프로세스의 정신은 한 문장으로 요약될 수 있습니다.

**AI는 지상의 전술적 군인이고, 당신은 전략적 계층입니다. '문제 정의', '문제 해체', '문제 테스트' 세 가지를 뒤로하고 스스로 해보고, '코드 작성'은 AI에게 맡기는 것이 AI 시대 엔지니어의 진정한 입장이다. **

Matt의 일련의 기술은 궁극적인 답이 아니라 현 단계의 모범 사례입니다. 3개월 후에는 더 나은 것이 있을 수 있지만 영적인 측면은 변하지 않습니다. 좋은 코드 기반은 항상 나쁜 코드 기반보다 더 중요하며 기본 소프트웨어 기술은 항상 가치가 있습니다.

개요로 돌아가거나, 가장 유용한 스킬을 선택하여 설치하여 사용해 보세요.