요즘 내 작업 시간의 상당 부분을 Claude Code 같은 AI 코딩 에이전트가 대신하고 있다. 정확히 말하면 반복 작업을 대신한다. 컴포넌트 스캐폴딩, 시안 기반 마크업 변환, 컨벤션 일괄 리팩토링 같은 것들. 몇 달 굴려보니 패턴이 잡혀서 기록해둔다.

컨벤션 문서가 절반이다

에이전트에게 그냥 "카드 컴포넌트 만들어줘"라고 하면 결과물이 매번 다르다. 어떤 날은 named export, 어떤 날은 인라인 스타일. 복불복이다.

그래서 프로젝트 루트에 CLAUDE.md라는 컨벤션 문서를 두고 규칙을 전부 적었다. 이 블로그 저장소에 실제로 있는 규칙 일부를 옮기면 이렇다.

## Code Rules

- export는 항상 `export default function`
- 인라인 Tailwind 금지 — `tw()` 헬퍼로 CSS 객체 분리
- 반응형은 데스크탑 퍼스트, `max-xl:` / `max-md:` 2단계만 허용
- 아이콘은 react-icons/fa만 사용, 인라인 SVG 금지
- 색상은 CSS 변수 토큰만 (`text-fg`, `bg-surface`, `text-accent`)

이 문서가 있으면 에이전트가 새 컴포넌트를 만들 때 알아서 규칙을 따른다. 사람 신입에게 온보딩 문서 주는 것과 똑같다. 문서화 안 된 컨벤션은 에이전트에게도 없는 컨벤션이다.

잘 먹히는 작업 세 가지

1. 스캐폴딩. "DevCard와 같은 구조로 YouTubeCard를 만들어줘. 데이터 타입은 lib/youtube.ts 참고." 기존 코드를 레퍼런스로 지목하면 스타일이 거의 일치하게 나온다.

2. 마크업 변환. div로 짜인 옛 코드를 시맨틱 태그로 바꾸는 작업. 규칙표를 주면 수십 개 파일을 일관되게 훑는다. 사람이 하면 지루해서 실수하는 종류의 일이다.

3. 일괄 리팩토링. named export를 default export로 통일한다든가, 컴포넌트마다 흩어진 상수를 폴더별 .ts로 분리한다든가. 범위가 명확한 기계적 변경은 거의 실패하지 않는다.

그래도 검수는 사람 몫이다

여기서 제일 중요한 게 있다. 검수 기준이 없는 사람이 시키면 결과물도 기준이 없다. 에이전트는 그럴듯한 코드를 빠르게 만든다. 그럴듯함과 맞음은 다르다. useEffect cleanup이 빠졌는지, 서버 컴포넌트에 불필요한 'use client'가 붙었는지, ISR revalidate 값이 페이지 설정과 충돌하는지 — 이런 건 내가 봐야 잡힌다.

그래서 나는 검수에서 반복적으로 잡히는 실수를 다시 CLAUDE.md에 규칙으로 추가한다. 같은 지적을 세 번 하게 되면 그건 규칙 문서의 구멍이다.

### 품질 검증

- useEffect cleanup, 이벤트 리스너 해제 여부 확인
- 개별 fetch의 next.revalidate가 페이지 레벨과 일치하는지 확인
- 'use client'가 실제로 필요한지 확인 — 불필요하면 SEO 크롤링 차단

에이전트가 지워주는 건 반복 작업이지 판단이 아니다. 판단 기준을 문서로 쌓아가는 사람일수록 에이전트가 강해진다. 퍼블리셔 시절 마크업 가이드를 만들던 습관이 이렇게 다시 쓸모를 찾을 줄은 몰랐다.