코드 리뷰에서 나온 지적이 대부분 같은 모양이었다

2026-08-09 정정 — 글마다 AI 활용 범위를 표시한다는 기존 약속은 8월 6일 공개 원칙 변경으로 해소됐다. 당시 리팩터링과 현재 프로젝트 데이터·검증 구조도 시점을 구분해 바로잡았다.

만든 지 일주일쯤 된 저장소를 한 번 훑었다. 나온 지적을 정리해 보니 표현은 다 다른데 모양이 같았다. 같은 사실이 두 군데 이상에 적혀 있다.

• 사이트 주소가 네 곳에 하드코딩돼 있었다.
• 프로젝트 목록이 홈과 /projects 에 각각 배열로 박혀 있었다.
• 카테고리 이름이 스키마와 라우트와 필터에 따로 있었다.
• 대표글로 표시된 글이 둘이었다.
• 모든 글 하단에 같은 「AI 활용」 문구가 하드코딩으로 출력되고 있었다.

버그로 잡힌 것은 없었다. 전부 지금은 잘 돌아가고 나중에 어긋날 것들이다. 그리고 어긋났을 때 알아채기 어렵다는 공통점이 있다 — 두 곳 중 한 곳만 고치면 화면은 그대로 뜨고 값만 다르다.

값이 아니라 값의 출처를 하나로 합쳤다

첫 정리에서는 다섯 건을 각각 한 출처로 모았다. 사이트 주소는 src/data/site.ts 의 SITE_URL 이 되고 astro.config.mjs·robots.txt.ts·rss.xml.ts 가 그것을 참조했다. 프로젝트 목록은 당시 src/data/projects.ts 로, 카테고리는 src/data/categories.ts 로 모았다.

프로젝트 쪽은 그 뒤 한 번 더 바뀌었다. 2026-07-29 Content Collection 이관 뒤 프로젝트 본문과 목록의 원본은 src/content/projects/*.md 다. 현재 src/data/projects.ts 에는 상태 표시, 정렬, 개발일지 역산처럼 여러 화면이 함께 쓰는 규칙만 남아 있다. 따라서 「프로젝트 목록은 지금도 projects.ts 에 있다」고 읽으면 현재 구조와 맞지 않는다.

합치는 것 자체는 큰 일이 아니었다. 판단이 필요했던 것은 합친 다음에 무엇이 그것을 강제하느냐였다. 단일 소스를 만들어도 다음에 다시 하드코딩하면 원래대로 돌아간다.

그래서 파생을 코드로 강제했다. 카테고리는 스키마가 z.enum(CATEGORY_NAMES) 로 그 배열을 그대로 읽고, 카테고리 페이지 주소도 같은 파일의 매핑에서 나온다. 목록에 없는 이름을 쓰면 콘텐츠 스키마 검사가 멈춘다. 프로젝트가 참조하는 기술 이름과 글 slug 는 프로젝트 페이지를 만드는 빌드와 scripts/validate-content.mjs 가 함께 확인한다. npm run release 는 저장소 검증 뒤 빌드를 실행한다. 「여기서 가져다 쓰세요」라고 문서에 적는 데서 끝내지 않고, 잘못된 참조가 검증을 통과하지 못하게 한 것이다.

지운 것을 다시 만들지 않기로 했다

이때 함께 정리한 것 중에 다시 만들지 않기로 한 것이 둘 있다.

썸네일 자리다. 목록 카드에 「썸네일」이라고 적힌 회색 상자가 들어 있었다. 이미지를 준비하면 채우겠다는 자리인데, 채울 이미지가 실제로 생기지 않는 동안에는 모든 카드에 빈 상자가 남는다. 상자를 지우고 텍스트 중심 레이아웃으로 바꿨다. 나중에 이미지가 생기면 그때 레이아웃을 다시 짜는 편이, 안 채워진 자리를 계속 보는 것보다 낫다고 봤다.

쓰지 않는 이미지 파일들이다. 여러 번 고쳐 만든 OG 이미지 네 개 중 셋이 아무 데서도 참조되지 않은 채 7MB 넘게 남아 있었다. 지우고 남은 하나만 압축했다.

필드는 사라졌고, 공개 원칙은 나중에 바뀌었다

리뷰에서 고친 것 중 하나는 「모든 글에 같은 AI 활용 문구가 출력된다」였다. 글마다 실제 범위가 다른데 레이아웃이 같은 문장을 찍고 있었으니 그 표시는 아무 정보도 아니었다. 그래서 스키마에 aiAssist 와 verification 필드를 넣고, 값이 있는 글만 자기 범위를 표시하게 바꿨다.

두 필드는 지금 스키마에 없다. Git 이력에서는 2026-07-26 커밋 1cd02f5가 aiAssist 와 verification 을 넣었고, 같은 날 뒤이은 94316c8이 두 필드를 없애고 글 성격을 나타내는 postType 을 넣었다. 「다음 주에 교체됐다」는 기존 설명은 날짜부터 맞지 않았다.

그 뒤 시작 안내에는 한동안 「AI를 활용했다면 글 하단에 그 범위를 표시한다」는 문장이 남아 있었다. 필드와 출력 장치는 사라졌는데 공개 약속만 유지된 시기에는 실제로 문서와 구현이 어긋나 있었다.

그 불일치는 2026-08-06 26b9f12에서 다른 방식으로 닫았다. 현재 시작 안내는 AI를 쓴 범위를 글마다 반복하지 않고, 「AI 활용」 카테고리의 자동 집계와 이 사이트 프로젝트 페이지의 설명이라는 두 공개 지점에서 밝힌다고 적는다. 없어진 글별 필드를 되살린 것이 아니라 공개 원칙을 현재 구현에 맞게 바꾼 것이다.

여기까지가 확인할 수 있는 이력이다. 이 선택이 글마다 비슷한 문구를 붙이는 것보다 낫다는 것은 편집 판단이다. 자동 집계는 코드에서 파생되지만 프로젝트 페이지의 설명은 여전히 사람이 관리하는 산문이므로, 「AI 활용 범위 전체가 스키마로 강제된다」는 뜻도 아니다.

남은 교훈은 같다. 단일 소스로 합치면 한 곳만 고치면 되지만, 약속이 코드가 아니라 산문으로만 적혀 있으면 코드가 바뀔 때 함께 바뀌지 않는다. 이 글도 8월 6일 뒤에는 이미 닫힌 일을 현재형 부채로 계속 적고 있었다. 문서와 구현을 함께 보지 않으면 정정을 설명하는 글마저 다시 낡을 수 있다.