[Coding Standard] 규칙 전달 경로: 코딩 표준은 무엇을 타고 Claude에게 닿는가
배포본의 자바 규칙은 50개 SKILL.md에 있었다. Claude에게 스킬은 이름과 설명만 먼저 들어오고 본문은 Claude가 부르기로 판단해야 들어온다. Controller를 새로 만들면서 DTO 표준을 안 부르면 그 코드는 표준 없이 쓰인다.
Coding Standard
[Coding Standard] Figma 리뷰 댓글: 에이전트는 어디까지 하는가
블로그를 리뉴얼하면서 화면을 Figma에 그리고 있다. 내가 자는 동안 에이전트가 화면을 만들고, 아침에 내가 Figma를 열어 댓글을 단다. 그러면 에이전트가 그걸 읽고 고친다.
[Coding Standard] 디자인 도구의 이름: 코드로 넘어올 때 다시 짓지 않는다
디자인 도구에서 코드로 넘어올 때 같은 것에 이름이 두 번 지어진다.
[Coding Standard] 실패 알림: 터진 것을 사람이 어떻게 아는가
실패 화면 표준이 예상 못 한 예외를 error.js로 잡기로 했다. 화면은 지켜진다. 그런데 터졌다는 사실은 아무 데도 안 간다.
[Coding Standard] 태그 선택: 역할이 있으면 그 태그를 쓴다
후기 목록이 이렇게 생겼다.
[Coding Standard] 화면별 대응: 내용이 같은가로 먼저 가른다
화면 크기마다 다르게 보여야 할 때 방법이 셋 있다.
[Coding Standard] 프론트엔드 토큰 공유: 앱 둘이 무엇을 나눠 갖는가
Next.js 앱이 둘 돌고 있다. 공개 사이트(client)와 관리자(admin)다. 둘이 무엇을 나눠 갖고 무엇을 따로 가질 것인가.
[Coding Standard] 프론트엔드 API 계층: 화면은 서버 필드 이름을 모른다
프론트엔드가 서버를 부르는 자리는 셋으로 갈릴 수 있다.
[Coding Standard] 폼 제출: 두 번 눌러도 한 번만 나가게 한다
폼이 21개인데 폼 규칙이 하나도 없다. 그래서 이렇게 되어 있다.
[Coding Standard] 실패 화면: 예상한 실패와 예상 못 한 예외를 다른 장치로 잡는다
실패에는 두 종류가 있고, 지금 한쪽만 다루고 있다.
[Coding Standard] CSS 자리: 이름 충돌을 규칙이 아니라 도구로 막는다
컴포넌트를 새 자리로 옮기기로 정했다. 그런데 그 CSS 는 따라오지 않는다.
[Coding Standard] 컴포넌트 자리: 누가 그리는가로 가른다
Header는 components/ 루트에 있고 Footer는 components/sections/ 안에 있다. 여기서 Header·Footer처럼 화면의 한 조각을 재사용할 수 있게 만들어 둔 것을 컴포넌트라고 부른다. 같은 레이아웃 조각인데 사는 곳이 다르다.
[Coding Standard] 컴포넌트로 언제 빼는가: 길이는 이유가 아니다
홈은 조각 여덟 개로 쪼개져 있고, about 은 91줄을 한 파일에 다 쓴다.
[Coding Standard] 만들 것인가 가져다 쓸 것인가: 다시 만들어야 하는 것으로 가른다
디자인 시스템에 Dialog 가 있는데 CallConfirmationDialog 를 직접 만들었다. Badge 가 있는데 InquiryStatusBadge 를 직접 만들었다.
[Coding Standard] 멀티 에이전트 위상: 사용자는 누구와 말하는가
에이전트를 여럿 굴릴 때, 사용자는 그중 누구와 말하는가.
[Coding Standard] 일머리: 정확도와 빠름을 어떤 비율로 섞는가
지금까지 표준은 전부 무엇을 만드는가에 대한 것이었다. 패키지를 어떻게 나누고, DTO를 어떻게 만들고, 계약을 어떻게 적는지. 그런데 그 표준들을 어떤 태도로 실행하는가는 어디에도 없었다.
[Coding Standard] 테스트 냄새 어휘: 아픈 곳을 뭐라고 부를 것인가
테스트가 왜 힘든지를 진단하면서 통증을 넷으로 적었다.
[Coding Standard] 접미사 패키지 분할: 어느 계층을 나누고 어느 계층은 두는가
패키지 구조 표준은 도메인 안을 api·application·domain·infra 네 겹으로 나눴다. 컨트롤러 패키지 분리 표준이 거기에 web을 형제로 붙였다. 그 겹 안을 더 나눌지는 어느 쪽도 정하지 않았다.
[Coding Standard] 테스트 층위 선택: 스텁이 통과시킨 것들
계약 커버리지 게이트 표준을 만들면서 유예 여덟 건을 남겼다. 계약은 적어뒀는데 테스트를 못 짜는 칸들이었고, 이유는 이랬다.
[Coding Standard] 라우트-계약 정합성: 계약표가 실제 API와 맞다고 누가 보장하는가
API 테스트 계약표 표준이 계약을 저장소의 enum이 소유하게 만들었다. 계약을 가리키는 애노테이션(지금 이름은 XxxContract.Verify) 덕에 없는 계약을 가리키는 테스트는 컴파일이 막고, TestExecutionListener가 계약과 테스트 실행 결과를 맞춰 색을 ...
[Coding Standard] 계약 커버리지 게이트: 노랑으로 빌드를 막으려면 노랑부터 다시 정의해야 했다
API 테스트 계약표 표준 원칙 7이 색을 넷으로 늘리면서 이렇게 적었다.
[Coding Standard] API 테스트 계약표: 무한한 입력을 어떻게 셀 수 있게 만드는가
AI가 테스트를 빨리 짜준다. 그런데 통과를 봐도 안심이 안 된다.
[Coding Standard] URL 라우팅 네이밍: 경로를 무엇으로 지을 것인가
패키지 구조 표준과 컨트롤러 패키지 분리 표준이 컨트롤러가 사는 자리(api/web)를 정했다. 그런데 그 안의 메서드가 어떤 URL을 받을지는 한 번도 정한 적이 없다.
[Coding Standard] ErrorCode를 계약으로 다루기: 누가 발급하고 언제 죽는가
예외의 종류 원칙 9가 ErrorCode를 업무 도메인까지 세분화하기로 하면서, 마지막 문단에 대가를 이렇게 적어뒀다.
[Coding Standard] 아키텍처 소속: 글에 다는가 원칙에 다는가
바로 앞 글인 URL 라우팅 네이밍 표준의 front matter에 architectures: [ddd, layered]를 달았다. 경로 규칙이니 계층 구조와 무관하다고 봤고, 그건 맞다.
[Coding Standard] 배포 자동화: 사람이 서 있던 문은 어디로 옮겨야 하는가
표준 동기화 표준에서 배포 스크립트에 검사 넷을 붙였다. 밀어내기 직전에 서서, 어긋난 것이 나가지 못하게 막는 문이었다.
[Coding Standard] 목록 조회 요청 계약: page·size·sort는 어디서 막히는가
페이징 방식 표준이 나가는 쪽을 정했다. PagingResult와 CursorResult, 커서의 모양, hasNext 판별까지.
[Coding Standard] 에이전트 운영: 기능 하나에 이슈를 몇 개 만들 것인가
에이전트 여럿에게 일을 시킬 때, 기능 하나에 이슈를 몇 개 만드는가.
[Coding Standard] 표준 동기화: 규칙이 여러 벌로 퍼질 때 무엇이 같게 유지하는가
이 저장소는 규칙을 여러 벌로 복사해서 쓴다. AI 도구마다 읽는 파일 이름이 정해져 있어서다.
[Coding Standard] 커밋 대기: 에이전트는 어디까지 하고 멈추는가
에이전트에게 일을 시키면 어디까지 하고 멈춰야 하는가.
[Coding Standard] 코드 포맷터: 근거를 못 적는 결정을 어떻게 정할 것인가
지금까지 정한 표준은 전부 근거를 적을 수 있는 것이었다. 애그리거트 경계는 트랜잭션으로 갈랐고, 페이징은 임의 페이지 점프로 갈랐다. 버린 안마다 “언제 무엇이 깨지는가”를 적었다.
[Coding Standard] 스키마의 주인: DDL을 어디에 둘 것인가
Entity에 필드를 하나 추가한다고 하자.
[Coding Standard] 페이징 방식: 임의 페이지로 점프할 수 있어야 하는가
목록 조회를 어떻게 반환할지는 이미 정해져 있었다. 계층별 DTO 네이밍 표준이 PagingResult<T>를 만들었고, Repository부터 api까지 그 타입 하나로 올라간다.
[Coding Standard] 컨트롤러 두 종류: JSON과 HTML을 어디서 가를 것인가
패키지 구조 표준은 도메인 안을 네 겹으로 나누고 들어오는 칸을 api라고 불렀다. 그때는 컨트롤러가 한 종류라고 전제하고 있었다.
[Coding Standard] 성공 응답 상태: HTTP 결과와 공통 봉투를 어떻게 맞출 것인가
HTTP는 브라우저와 서버가 요청·응답을 주고받는 규약이고, 그 응답 맨 앞에는 성공·실패를 알려주는 상태 코드가 붙는다. 그 코드 뒤에 실제 데이터가 담기는 자리가 본문이다.
[Coding Standard] DB 시간 저장: Instant를 어떻게 같은 시점으로 왕복할 것인가
애플리케이션 시간 표준에서 실제 사건의 시점은 UTC Instant로 표현한다고 정했다. 하지만 Java의 Instant를 그대로 필드에 썼다고 DB 왕복까지 같은 시점이 되는 것은 아니다. 컬럼 타입, 연결 세션 시간대, 저장 정밀도 중 하나만 어긋나도 저장 전과 조회 후 값이 ...
[Coding Standard] 경계 DTO의 null: Snapshot과 Response는 어떻게 다르게 표시할 것인가
계층별 검증 표준은 Request의 선택 필드에는 @Nullable, Command·Query·Domain의 nullable 필드에는 orNull을 쓰기로 했다. 그런데 요청이 반대 방향으로 돌아올 때 만나는 Snapshot과 Response는 비어 있었다.
[Coding Standard] 애플리케이션 시간: 시점과 날짜를 어떻게 구분할 것인가
마감 시각 같은 정책은 Domain이 판단해야 한다. 그런데 Domain 안에서 LocalDateTime.now()를 부르면 테스트가 실행 시각에 흔들리고, 같은 요청 안에서도 판단 시각과 기록 시각이 달라진다. 그렇다고 생일과 영업일까지 전부 UTC 시점으로 바꾸면 원래 없던 시...
[Coding Standard] 조회 전용 타입: 애그리거트에 담기지 않는 결과를 어디로 내보내는가
관리자 주문 목록 화면을 만든다고 하자. 한 행에 이렇게 나온다.
[Coding Standard] Domain은 어떻게 저장되는가: merge를 쓰지 않는 이유
애그리거트 경계 표준은 조회 쪽을 정면으로 다뤘다. “Domain은 POJO라 지연 로딩이 없다. 그래서 애그리거트 크기가 곧 매 조회의 고정 비용이다.”
[Coding Standard] 벌크와 배치: 도메인의 판단이 개입하는가
Repository 설계 표준에서 대량 연산을 Repository 밖으로 빼면서 이렇게 정했다.
[Coding Standard] 인증 주체: 로그인한 사용자는 어디까지 내려가는가
주문을 만드는 Controller는 이렇게 생겼다.
[Coding Standard] 삭제: 지울 수 있는 것과 지울 수 없는 것
지금까지 XxxRepository에 정의한 것은 둘뿐이다.
[Coding Standard] UseCase 인터페이스: application이 무엇을 공개할 것인가
패키지 구조 표준은 infra를 전부 package-private으로 막아서 “Entity는 패키지 밖으로 나가지 않는다”를 약속이 아니라 사실로 만들었다. domain에 인터페이스를 두고 구현체를 infra에 감춘 덕분이다.
[Coding Standard] Repository 설계 표준: 조회 기술은 하나로 안 끝난다
지금까지 정한 표준들은 Repository의 자리를 정했다. 애그리거트 경계 표준은 “Repository는 애그리거트 루트당 하나”라고 했고, 패키지 구조 표준은 인터페이스는 domain에 public으로, 구현체는 infra에 package-private으로 두라고 했다. DTO...
[Coding Standard] Swagger 문서화 표준: 중복 없이 정확한 API 문서 만들기
API 문서가 코드와 어긋나는 순간, 문서는 없느니만 못한 것이 된다. 클라이언트 개발자는 문서를 믿고 구현했는데 실제 서버는 다르게 동작하기 때문이다. 그리고 이 어긋남은 대개 같은 정보를 두 군데에 적어놓고 한 쪽만 고쳤을 때 생긴다.
[Coding Standard] Service 계층의 assert: 흐름을 드러내고 실패를 숨기지 않기
Service 메서드를 처음 여는 사람은 두 가지를 알고 싶어 한다. 이 메서드가 무엇을 전제하고 동작하는지, 그리고 어디까지 왔을 때 무엇이 보장되는지. 보통은 주석이 그 역할을 한다.
[Coding Standard] 계층별 검증 표준: 형식은 Controller, 규칙은 Service
@Valid 하나 붙이면 검증이 끝난다고 생각하기 쉽다. 그런데 실제로 코드를 열어보면 검증이 여러 군데에 흩어져 있다. CreateOrderRequest의 @NotBlank, OrderDomain 생성자의 Objects.requireNonNull, Entity인 OrderEnti...
[Coding Standard] 패키지 구조: 규칙을 컴파일러가 강제하게
지금까지 세운 표준들을 다시 읽어보면 같은 문장이 반복해서 나온다.
[Coding Standard] 계층별 DTO 네이밍 표준: Request부터 Domain까지
DTO 하나를 Controller부터 JPA Entity까지 그대로 끌고 다니는 구조는 편하다. 필드도 한 번만 정의하면 되고, 변환 코드도 안 짜도 된다. 문제는 편한 만큼 계층 사이의 의존성이 전부 한 클래스에 뭉친다는 것이다. Entity에 컬럼 하나를 추가하면 API 응답이...
[Coding Standard] 예외의 종류: 어디서 터지고 누구 잘못인가
예외 처리 표준에서 ErrorCode와 ErrorCodeException으로 실패를 다루는 방법을 정했다. 그런데 그 글이 다룬 것은 우리가 직접 던지는 예외뿐이다.
[Coding Standard] 예외 처리 표준: 실패가 나가는 길을 하나로
지금까지 정리한 표준들은 요청이 들어오는 길을 다뤘다. 이 글은 반대 방향, 실패가 나가는 길을 다룬다.
[Coding Standard] DTO는 생성자로만 만든다: 상태가 완성되는 지점을 하나로
객체 하나가 어떤 상태로 만들어질 수 있는지 알아내려면 코드를 몇 군데나 봐야 할까. setter가 있는 DTO라면 답은 “전부”다. 어디서든 필드 하나를 바꿀 수 있으니, 이 객체의 가능한 상태를 알려면 이 타입을 쓰는 모든 코드를 확인해야 한다.
[Coding Standard] 애그리거트 경계: 무엇을 한 덩어리로 볼 것인가
패키지 구조 표준에서 “패키지가 애그리거트 경계 역할을 한다”고 적었다. 그런데 그 애그리거트를 어디서 끊을지는 정하지 않았다.
[Java] 상속 vs 합성: 실무에서 어떻게 선택할까?
“상속은 나쁘다”, “합성이 항상 우월하다”는 말을 자주 듣는다. 하지만 실무에서는 이런 이분법적 사고가 오히려 비효율적일 수 있다. 이번 글에서는 상속(Inheritance)과 합성(Composition)을 실무에서 어떻게 선택하고 활용하는지, 실제 경험을 바탕으로 정리해보겠다.
[Java] Assert로 프로그래머의 실수를 잡아내기
Java의 assert는 개발자들 사이에서 “있지만 거의 쓰지 않는” 기능으로 취급받습니다. 왜일까요?
[Java] Null-free 객체 설계와 생성 철학 정리
이번 글은 “애플리케이션 내부에는 null이 없다” 라는 전제에서 출발한다. 여기서 「내부」는 객체가 한 번 만들어진 뒤의 세계다. null은 주로 바깥 — 사용자가 보낸 요청에 담겨 들어온 값, DB에서 읽은 값처럼 내가 만들지 않은 값 — 에서 들어오는데, 그 값이 객체로 만들...
[Java] 팩토리 메소드 패턴으로 Service 레이어 가독성 개선하기
비즈니스 로직이 복잡해 지면서 Service 레이어(서비스 계층과 같은 말)의 코드가 복잡해지기 시작했다. 특히 DTO를 VO로 변환할 때 문제가 두드러졌다. 해당 문제는 로직의 가독성을 크게 떨어뜨렸다. DTO를 왜 VO로 바꿔 쓰는지는 이 글이 다루지 않는다. 이 글은 「바꾸기...