Arlo Belshee의 6단계 네이밍 프로세스와 Clean Code 네이밍 규칙을 적용해, 여러 파일에 흩어진 개별 이름 스멜(타입 반복·-er/-Utils·불용어·축약어 등)을 탐지하고 배치 교체하여 코드 가독성 향상. 단, 하나의 긴 메서드를 통째로 관통(grouping→extract→rename)하는 것은 /intent-revealing-names가 적합. /naming-process로 호출.
インストールする前に、エージェントに与えられる指示の中身を確認できます。
Arlo Belshee의 6단계 네이밍 진화와 Clean Code 7가지 네이밍 원칙을 적용하여:
../../references/refactoring-procedure.md §0·§3-A)git add -A 금지, 변경된 파일만 명시// 1. Obvious Nonsense
int x;
// 2. Honest (타입 반복)
int intValue;
// 3. Completely Honest (맥락 포함)
int orderItemCount;
// 4. Does the Right Thing (역할 명확)
int itemsInCart;
// 5. Intent Revealing (의도 표현)
int pendingOrderItems;
// 6. Domain Abstraction (도메인 언어)
int itemsAwaitingFulfillment;
| # | 원칙 | 핵심 | 예시 |
|---|---|---|---|
| 1 | Reveal Your Intent | 동작이 아니라 목적을 담는다 | process() → placeOrder() |
| 2 | Describe the Problem | 매직 값 대신 도메인 언어 | INCLUDE_FIRST → OPEN_LEFT, TWENTYFOURBITGROUP → BITS_PER_GROUP |
| 3 | Avoid Disinformation | 타입/역할을 속이지 않는다 | accountList(실제 List 아님) → accounts |
| 4 | Pronounceable Names | 팀 대화에서 발음 가능해야 함 | genymdhms → generationTimestamp |
| 5 | Avoid Encodings | 헝가리안·타입/스코프 접두사 금지 | IService → Service, m_memberName → memberName |
| 6 | Parts of Speech | 클래스=명사, 메서드=동사, boolean=서술어 | 아래 상세 |
| 7 | The Scope Rule | scope에 따라 길이 조절 | 아래 상세 |
d는 의미가 불명확하다.// Good: 변수 scope 규칙 (정비례)
for (int i = 0; i < 10; i++) { ... } // 극히 짧은 scope → 짧은 이름
private Customer currentlyAuthenticatedCustomer; // 클래스 필드 → 긴 이름
static final int WORK_DAYS_PER_WEEK = 5; // 정적 필드 → 가장 긴 이름
// Good: 함수 scope 규칙 (반비례)
public void serve(Socket s) { ... } // public, 자주 호출 → 짧게
private void closeEnclosingServiceInSeparateThread() { ... } // private → 길게(자체 문서화)
클래스도 함수와 같은 방향: 기반 클래스(넓은 scope)는 짧게 Employee, 파생 클래스(좁은 scope)는 형용사를 더해 길게 PartTimeHourlyEmployee.
| 상황 | 허용 여부 |
|---|---|
루프 변수 (i, j, k — 1~5줄) | 허용 |
exception 핸들러 (e — 3줄 이내) | 허용 |
| 인스턴스 필드 | 불허 |
| 10줄 이상 지역변수 | 불허 |
도메인 의미 있는 파라미터 (x 대신 sourceAmount) | 불허 |
// Good
if (employee.isLate()) {
employee.reprimand();
}
// Bad
if (employee.late()) { // 서술어 아님
employee.punishment(); // 명사
}
이름의 체계가 도메인을 전달해야 함. 한 개념에는 한 단어만 사용한다 (fetch ≠ retrieve ≠ get — 같은 의미면 하나로 통일).
// Good: 일관된 네이밍 체계
class OrderService {
void placeOrder(Order order) { ... }
void validateOrder(Order order) { ... }
void fulfillOrder(Order order) { ... }
}
// Bad: 체계 없음 (do/check/execute가 같은 계열 동작에 뒤섞임)
class OrderHandler {
void doOrder(Order order) { ... }
void checkOrder(Order order) { ... }
void executeOrder(Order order) { ... }
}
from(factory, 인자 1개) / of(factory, 인자 2개+) / canXXX(검증 boolean) / validateXXX(검증 exception) / markXXX(상태 변경) / 동사구(일반)-er 접미사(Manager/Helper) 지양, -Utils 금지invoicing, invoice 아님). Bounded Context 내부에서는 접두사 불필요 — invoicing.Customer이지 InvoicingCustomer가 아니다name, street, state를 단독으로 쓰면 의미가 불명확하다. 해결 우선순위:
Address 클래스에 street, state 필드를 담는다addrState// Bad
void onCreate() { ... }
void onDestroy() { ... }
// Good
void initialize() { ... }
void cleanup() { ... }
// Bad
String nameString;
List<Order> orderList;
// Good
String name;
List<Order> orders;
// Bad
class OrderProcessor { ... }
class StringUtils { ... }
// Good
class OrderService { ... } // 또는 구체적 역할명
class TextFormatter { ... }
// Bad
class OrderData { ... }
class CustomerInfo { ... }
void processData() { ... }
// Good
class Order { ... }
class Customer { ... }
void calculateTotal() { ... }
// Bad
int qty;
String custNm;
// Good
int quantity;
String customerName;
정보가 없으면서 정보가 있는 것처럼 보이는 이름 — 가장 위험한 종류.
// Bad
void process() { ... }
void handle() { ... }
void execute() { ... }
// Good
void placeOrder() { ... }
void refundPayment() { ... }
이름이 모호해서 온갖 책임이 계속 누적되는 클래스.
// Bad: 계속 커지는 MemberService (등록·포인트·알림·통계...)
// Good: 책임별 분리
class MemberRegistration { ... }
class MemberPointsCalculator { ... }
process, handle, execute)fetch/retrieve/get 혼재)i, j, k는 관례상 허용 (1~5줄)e는 3줄 이내 핸들러에서 허용x, y, z는 맥락상 명확한 경우 허용공통 골격(대상 파일 수집 → 후보 제시(계열별 승인 규칙) → 적용 → 테스트 → 커밋/되돌리기, 브랜치·PR이
필요한 조건)은 이 스킬 디렉터리 기준 ../../references/refactoring-procedure.md가 정본이다.
아래는 이 기법에 고유한 부분만 규정한다.
발견된 Naming Smells 5개:
1. OrderProcessor.java (클래스)
현재: OrderProcessor
단계: 2 (Honest) - -er 클래스
제안: OrderService (단계 5: Intent Revealing)
2. OrderProcessor.java:15 (변수)
현재: List<Order> orderList
단계: 2 (Honest) - 타입 반복
제안: List<Order> pendingOrders (단계 5: Intent Revealing)
3. Customer.java:30 (메서드)
현재: void processData()
단계: 2 (Honest) - 불용어
제안: void calculateLoyaltyPoints() (단계 6: Domain Abstraction)
→ 승인 없이 적용 (Tidy 계열)
커밋 메시지: refactor: improve naming in <클래스명> (공통 절차 6단계)
완료: Naming Process
변경 내용:
- OrderProcessor.java → OrderService.java
(단계 2 → 5: -er 제거)
- orderList → pendingOrders (단계 2 → 5: 타입 반복 제거)
- processData() → calculateLoyaltyPoints()
(단계 2 → 6: 불용어 제거, 도메인 언어 사용)
테스트: 모든 테스트 통과 (23 tests)
커밋: refactor: improve naming in OrderService
제안: Customer.java에 축약어 3개가 남아 있음. 다음 리팩토링 대상에 포함한다.
공통 실패 조건(계열별 승인 규칙 위반, 테스트 실패 방치, 테스트 수정, 커밋 단위, git add -A, heredoc
한글 메시지)은 ../../references/refactoring-procedure.md에 있다. 아래는 이 기법에 고유한 것만.
get 계열인데 fetch로 rename)이 스킬의 원칙·표는 아래 vault 문서를 소스로 보강되었다. 런타임 의존성이 아니며, 없어도 스킬은 완전하게 동작한다.
999-MOC/Clean-Code-2nd-Edition-Naming-원칙과-실천법.md — 7가지 원칙, Scope Rule 심화(1판 vs 2판), 한 글자 허용 기준, 요소별 패턴의 원 노트まだレビューはありません。使ってみた感想をお寄せください。
概要と使いどころ
동일한 결과를 내는 여러 조건문(OR 나열·중첩 AND)을 하나로 통합하고 의미 있는 boolean 메서드로 추출. "조건문 합쳐", "같은 결과 반환하는 if 정리", "중첩 if 평탄화", "/consolidate-conditional" 요청 시 사용. 단, 여러 메서드에 흩어진 동일 조건을 호출자 쪽으로 올리는 것은 /lift-up-conditional, 복잡한 조건식·분기를 메서드로 쪼개는 것은 /decompose-conditional이 적합. /consolidate-conditional [commit-ref]로 호출.
日本語の概要は準備中です。原文の説明を表示しています。
기능의 external behavior를 Cucumber 인수 테스트(주 검증층)로 구축 — .feature 실행으로 문서↔코드 드리프트를 구조적으로 차단, Four Layer(Steps→Protocol Driver→SUT), 태그 기반 가역 제외, 기존 JUnit 인수 테스트 이관. "인수 테스트 도입", "Gherkin을 실행 가능하게", "cucumber 셋업" 요청 시 사용. /cucumber-acceptance로 호출.
日本語の概要は準備中です。原文の説明を表示しています。
복잡한 if/then/else의 조건식과 각 분기를 의미 있는 메서드로 추출하여 가독성 향상. "조건문 분해", "if 가독성", "복잡한 조건식에 이름 붙여", "/decompose-conditional" 요청 시 사용. 단, 같은 결과를 내는 조건문들을 하나로 합치는 것은 /consolidate-conditional, 타입별 분기를 클래스로 바꾸는 것은 /replace-conditional-with-poly가 적합. /decompose-conditional [commit-ref]로 호출.
日本語の概要は準備中です。原文の説明を表示しています。
Primitive Obsession 제거 — 검증·연산이 따라다니는 primitive 필드(금액+통화, 이메일 문자열 등)를 도메인 개념을 담은 Value Object로 치환. "값 객체 도입", "primitive obsession", "Money 클래스로", "/discover-value-object" 요청 시 사용. 단, 함께 전달되는 파라미터 묶음을 객체로 바꾸는 것은 /introduce-parameter-object, 컬렉션을 감싸는 것은 /first-class-collection이 적합. /discover-value-object [commit-ref]로 호출.
日本語の概要は準備中です。原文の説明を表示しています。
컬렉션 getter가 내부 List/Set을 직접 노출하는 것을 방지 — unmodifiable 반환 + add/remove 메서드 제공. "컬렉션 캡슐화", "getter가 List 그대로 노출", "unmodifiable로", "/encapsulate-collection" 요청 시 사용. 단, 컬렉션과 관련 로직을 전용 클래스로 뽑는 것은 /first-class-collection이 적합. /encapsulate-collection [commit-ref]로 호출.
日本語の概要は準備中です。原文の説明を表示しています。
암묵적 의존성(전역 변수·클래스 필드·싱글턴 접근)을 명시적 파라미터로 전환하여 메서드 투명성 향상. "숨은 의존성 드러내", "필드 대신 파라미터로", "전역 참조 제거", "/explicit-parameters" 요청 시 사용. 단, 파라미터가 많아져 묶어야 하면 /introduce-parameter-object, I/O와 계산 분리는 /segregate-functional-core가 적합. /explicit-parameters [commit-ref]로 호출.
日本語の概要は準備中です。原文の説明を表示しています。