Coding Standard — 아직 정하지 않은 것

열린 항목

여기는 아직 정하지 않았거나, 정한 것끼리 부딪히는 지점을 모아두는 곳이다.

표준을 읽다가 빈틈을 발견하면 그 자리에서 여기에 적는다. 대화가 끊겨도 남아야 하기 때문이다. 적을 때는 무엇이 비었는지를 한 줄로 남긴다. 자세한 경로는 그 빈틈을 닫는 글이 든다.

모순 — 두 표준이 서로를 부정한다. 코드를 짜면 그 자리에서 막힌다
미정의 — 정한 적이 없다. 사람마다 다르게 구현하게 된다

닫을 때는 여기서 지우지 않고 닫힌 항목으로 옮긴다. 무엇이 왜 열려 있었는지가 그 표준을 만든 이유이기 때문이다. 이 장부를 페이지 둘로 나눈 것도 그래서다 — 새 표준을 쓰기 전에 읽어야 하는 건 열린 쪽뿐인데, 한 페이지에 두면 이미 닫힌 것까지 매번 따라온다.

아키텍처 자체가 비어 있는 자리

#	항목	종류	무엇을 정해야 하나	파급
1	3계층만의 표준	미정의	계층과 패키지 구조는 정해졌는데 Controller 네이밍·Mapper XML처럼 3계층에서만 의미가 있는 규칙은 0개다. Route는 URL 라우팅 네이밍 표준이 양쪽으로 닫았다. 여기에 「도메인 드리븐 전용」 표시가 붙은 원칙 3개가 얹힌다 — 정렬 화이트리스트의 소유 자리, `DELETE`의 범위, 상태 전이 동사의 출처. 돌아가는 프로젝트가 없어 미루고, 프로젝트가 서면 한꺼번에 닫는다	높음

요청 한 사이클에서 비어 있는 자리

여섯 중 다섯(로깅·추적 키, ErrorCode의 수명주기·진단 정보 경계·도메인 판별·공용 클라이언트 소유권)은 ErrorCode 계약 표준이 닫았다. 하나가 남았다.

#	항목	종류	무엇을 정해야 하나	파급
7	`If-Match`로 수정 충돌을 막을지	미정의	조회에 `ETag`를 붙이면서 수정 충돌을 HTTP에서 막을 재료가 생겼다. 앞당길지, `412`를 공통 봉투와 `ErrorCode`로 어떻게 표현할지가 비어 있다	중간

이미 정한 표준이 조회를 막고 있는 자리

브라우저에서 DB까지 조회 하나가 흐르는 길을 한 칸씩 짚으면서 나왔다. 새로 정하는 것으로 끝나지 않고 이미 닫은 표준을 다시 열어야 한다.

#	항목	종류	무엇을 정해야 하나	파급
8	조회 캐시를 어느 계층에 두는가	미정의	캐시·Redis가 표준 전체에서 0건이다. `@Cacheable`도 프록시 기반이라 Service를 package-private으로 감춘 구조와 부딪히고, 무효화 책임도 비어 있다	중간

조회 요청이 들어오는 쪽에서 비어 있는 자리

같은 검색에서 나왔다. 기존 표준과 부딪히지는 않는다 — 정한 적이 없을 뿐이라 새로 정하면 된다.

#	항목	종류	무엇을 정해야 하나	파급
9	CORS preflight 실패의 응답	미정의	`OPTIONS`는 Controller도 Advice도 안 타서 실패해도 공통 봉투가 안 나간다. 허용 출처를 어디서 설정할지, `ErrorCode`로 표현할 수 있는지가 비어 있다	중간

데이터베이스 쪽에서 비어 있는 자리

같은 검색에서 나왔다. 요청 흐름 그림의 마지막 칸 바깥이라 지금까지 한 번도 안 보이던 자리다.

#	항목	종류	무엇을 정해야 하나	파급
12	트랜잭션 격리 수준	미정의	격리 수준이 0건이다. 경계와 `readOnly`는 정했지만 격리는 DB 기본값에 맡겨져 있고, MariaDB의 REPEATABLE READ가 의도한 것인지 확인한 적이 없다	중간
14	읽기 복제본과 `readOnly = true`의 관계	미정의	복제본을 두면 `readOnly`가 라우팅 힌트가 되고 쓰고 바로 읽기가 깨진다. 다만 이 프로젝트에 복제본이 있는지부터 확인해야 한다	중간

컨트롤러를 둘로 가르면서 새로 열린 자리

컨트롤러 패키지 분리 표준을 정하는 순간 따라 나온 빈틈 둘 중 하나가 남았다. 나머지 하나(소속 판정 단위)는 아키텍처 소속 표준이 닫았다.

#	항목	종류	무엇을 정해야 하나	파급
15	`web` 패키지 안에서 무엇을 하라는 규칙이 하나도 없다	미정의	SSR·템플릿·`ModelAndView`가 0건이고 응답 규칙은 전부 JSON 전제다. 실패 처리와 뷰 모델 규칙이 통째로 없는데, SSR 프로젝트가 없어 미룬다	높음

AI가 Java 코드를 부분만 읽을 방법이 비어 있는 자리

블로그 색인(_ai/index.yml · _ai/map.yml)을 Java에도 옮길 수 있는지 보다가 나왔다.

#	항목	종류	무엇을 정해야 하나	파급
18	블로그의 색인 층을 Java 코드에 어떤 모양으로 옮길 것인가	미정의	블로그 색인은 44편을 재고 나서 정했는데 Java엔 소스가 없다. 줄 번호(A) · 심볼(B) · 유스케이스 횡단(C) 중 C가 유력하나 임계점은 도메인 둘이 `application`에서 만나는 유스케이스다	중간

포맷터를 도구에 맡기면서 IDE 쪽이 확인되지 않은 자리

코드 포맷터 표준에서 Spotless는 돌려봤지만 IDE 쪽은 재보지 않았다.

#	항목	종류	무엇을 정해야 하나	파급
19	IDE가 만드는 모양과 빌드가 만드는 모양이 같은지 확인되지 않았다	미정의	Spotless는 Eclipse JDT, IntelliJ는 자기 엔진이라 같은 XML로 같은 출력이 나온다는 보장이 없다. 어댑터로 한 벌이 되는지, 안 되면 IDE 포맷을 끌지가 비어 있다	중간

컨트롤러의 봉투 조립을 그대로 두기로 하면서 남은 자리

끝까지 안을 좁혀놓고 지금은 하지 않기로 한 것이다. 다시 열 조건만 적어둔다.

#	항목	종류	무엇을 정해야 하나	파급
20	성공 봉투 조립을 컨트롤러 밖으로 뺄 것인가	미정의	성공 팩토리를 헬퍼로 옮기는 안(B-3)까지 골라놓고 접었다. 이름이 Swagger `@ApiResponses`와 겹치고, 복사본이 아직 몇 벌 없다. 쌓이면 다시 본다	중간
21	컨트롤러 본문을 흐름으로 읽히게 하는 방법	미정의	`Optional` 체인(F-5)·실패를 값으로(F-4)·우리 타입에 `map`(F-2)은 버렸다. 남은 것은 지역변수(F-6)인데 `var`가 0건이라 그 선을 먼저 그어야 한다	중간

이슈 하나를 여러 세션이 이어받을 때 무엇이 남아야 하는가

에이전트 운영 표준에서 본문과 댓글의 소유가 확정되자 그 둘로도 안 덮이는 자리가 드러났다.

#	항목	종류	무엇을 정해야 하나	파급
25	이슈를 쪼갤지 묻는 계약 개수를 무엇으로 재는가	미정의	기준 개수가 지어낸 값이다. 신호는 앞에서 띄우는데 정답은 뒤에서만 나오므로, 무엇을 어디에 관측할지와 몇 건을 봐야 고칠지가 비어 있다	낮음

계약을 표로 바꾸면서 새로 열린 자리

API 테스트 계약표 표준을 정하면서 끝까지 못 정한 것 중 남은 둘이다. 실제로 API 하나에 만들어봐야 답이 나온다.

#	항목	종류	무엇을 정해야 하나	파급
26	어노테이션에서 행을 어디까지 뽑을 수 있는가	미정의	`@Min`·`@Max`·`@NotNull`은 경계가 명확한데 `@Pattern`은 정규식이라 경계가 자동으로 안 나온다. 커스텀 검증(`@SortKey`)도 같다. 생성기가 못 뽑는 것을 어떻게 표시할지가 비어 있다	중간
27	API 수십 개의 표를 어디서 모아 보는가	미정의	표준은 API 하나의 표만 정했다. API 50개면 HTML 50장인데 노랑이 어디 있는지 한눈에 볼 층이 없다. 지금은 도메인마다 리스너 하나·HTML 하나뿐이라 통합 뷰가 없다. 요약 페이지를 둘지, 노랑이 있으면 CI를 실패시킬지가 비어 있다	중간

이슈 상태를 표준이 건드리기 시작하면서 열린 자리

커밋 대기 표준이 원칙 4-1·4-2로 이슈 전환을 가져갔다. 표준이 저장소 밖(트래커)의 상태를 처음으로 건드린 것이라, 그 바깥을 다루는 규칙이 아직 없다.

#	항목	종류	무엇을 정해야 하나	파급

접미사로는 더 못 쪼개는 큰 폴더가 남은 자리

접미사 패키지 분할 표준이 api·application만 나누기로 하면서 접미사로 안 풀리는 자리가 숫자로 드러났다.

#	항목	종류	무엇을 정해야 하나	파급

표준이 코드가 아니라 태도를 다루기 시작하면서 열린 자리

일머리 표준이 처음으로 만들어지는 코드가 아니라 만드는 과정의 판단을 규칙으로 적었다. 그러면서 다른 표준에는 없던 문제가 두 개 따라왔다.

#	항목	종류	무엇을 정해야 하나	파급
44	일머리가 이 저장소와 배포본 밖에서는 안 걸린다	미정의	38번을 닫으면서 덮이지 않은 자리가 남았다. 일머리는 이제 `coding-standards/CLAUDE.md`(자바 프로젝트)와 이 저장소의 `CLAUDE.md` 두 곳에서 걸리는데, 그 밖의 프로젝트에서는 여전히 안 걸린다. 전역 `~/.claude/CLAUDE.md` 에 두면 전부 덮이지만 저장소 밖이라 검사가 못 미치는 것이 38번을 그 방식으로 안 닫은 이유 그대로 남아 있다 — 장부가 거기 심링크가 있다고 적어둔 것이 실제로는 없었고 아무도 몰랐다. 검사가 닿는 전역 자리를 만들 수 있는지, 아니면 일머리를 「표준을 깐 프로젝트에서만 도는 규칙」으로 범위를 좁혀 못 박을지가 비어 있다	보통

테스트의 통증에 이름을 붙이면서 열린 자리

테스트 냄새 어휘 표준이 진단의 통증 넷을 Meszaros 의 이름으로 부르기로 했다. 이름은 들였는데 그 이름이 가리키는 곳을 볼 수단이 없는 자리가 둘 드러났다. 그중 40번은 패키지 구조 표준 원칙 7이 닫았다. 하나가 남았다.

#	항목	종류	무엇을 정해야 하나	파급
39	프로젝트 냄새를 볼 사람도 자리도 없다	미정의	Meszaros 는 냄새를 누가 알아채는가로 셋으로 가르는데, 세 번째(프로젝트 냄새)의 전제가 「코드도 안 보고 테스트도 안 돌리는 사람」이다. 이 프로젝트에 그 역할이 없어서 주기 점검 자리를 만드는 안을 버렸다 — 안 도는 자리는 덮여 있다는 착각을 만들기 때문이다. 그런데 진단의 통증 넷 중 하나(`High Test Maintenance Cost`)가 정확히 거기 있어 진단의 4분의 1이 안 보이는 채로 남는다. 에이전트가 그 자리에 앉을 수 있는지(코드를 읽으므로 정의상 안 된다), 아니면 「고치는 데 든 시간」을 사후에라도 재는 다른 수단이 있는지가 비어 있다	높음

실패 화면을 정하면서 열린 자리

실패 화면 표준이 예상 못 한 예외를 error.js 로 잡기로 했다. 화면은 지켜지는데 그 예외가 있었다는 사실이 사람에게 닿는 길은 안 정했다.

#	항목	종류	무엇을 정해야 하나	파급

디자인 리뷰를 표준으로 만들면서 열린 자리

Figma 리뷰 댓글 표준이 에이전트가 어디서 멈추는지는 정했다. 그 이력을 프로젝트마다 어디에 어떤 형태로 두는지는 안 정했다.

#	항목	종류	무엇을 정해야 하나	파급
53	리뷰 이력을 프로젝트마다 어디에 두나	미정의	이 블로그는 `_data/design-review.yml` + `_pages/design-review.md` 로 뒀는데, 그건 Jekyll 구조라 배포본을 쓰는 자바·Next.js 프로젝트에는 그 자리가 없다. 표준은 「저장소 안에 두되 데이터와 표시용을 나눈다」까지만 말하고 실제 경로와 형식을 정하지 않았다 — 그러면 프로젝트마다 다른 자리에 다른 모양으로 생기고, 에이전트가 어디를 읽어야 할지 매번 찾는다. Figma 를 실제로 쓰는 프로젝트가 아직 이 블로그뿐이라 두 번째가 나오면 그때 공통 자리를 정한다	중간
54	핀이 며칠째 안 닫히면 무엇을 하나	미정의	표준은 「쌓인 핀은 확인이 밀린 만큼이고 그게 보이는 게 맞다」고 정했다. 그런데 밀린 것을 알려주는 장치는 없다. 이력의 `waiting` 이 몇 건이든 아무도 말해주지 않아서, 확인을 잊으면 그대로 쌓인다. 실패 알림 표준이 터진 것을 사람에게 밀어주듯 밀린 리뷰도 밀어줄지가 비어 있다. 며칠을 기준으로 볼지, 어디로 보낼지 둘 다 안 정했다	낮음

이미 닫힌 것은 닫힌 항목에 있다.