첫 글에 AI를 쓰는 방식을 앞으로 가장 많이 쓸 주제로 적어뒀다. 그 첫 번째다.
AI에게 일을 시킬 때 시간이 가장 많이 새는 곳은 같은 걸 또 말하는 자리다. 어제 “이렇게 쓰지 마”라고 했는데 오늘 또 그렇게 쓴다. 매번 다시 설명하면 시키는 시간이 직접 하는 시간보다 길어진다.
그래서 규칙을 대화가 아니라 저장소 안의 파일에 적는다. 이 블로그의 CLAUDE.md가 그 파일이고, 지금 225줄이다.
처음부터 225줄이 아니었다
블로그를 만들 때 88줄로 시작했다. 문체는 평서체, 독자는 실무 개발자, 이런 표현은 쓰지 말 것. 그 정도였다.
글을 쓰면서 늘었다.
| 시점 | 줄 수 |
|---|---|
| 블로그 초기 구축 | 88 |
| 첫 글 발행 | 147 |
| 첫 글을 여섯 번 고친 뒤 | 209 |
| “문장이 직관적이지 않다”는 지적 뒤 | 225 |
미리 다 쓸 수 있었으면 좋았을 텐데 그게 안 된다. 무엇을 적어야 하는지는 틀려봐야 안다.
규칙이 생긴 자리들
세 개만 옮긴다. 전부 지적을 받고 나서 생겼다.
“기간만 남기고 그 기간에 한 일을 빼지 마. 뭘 했는지 모르겠으면 지어내지 말고 나한테 물어봐.”
첫 글 초안이 2년 6개월을 아무 일도 없던 기간처럼 적었다. 그 기간에 만든 것이 따로 있었는데 초안에는 기간만 남고 만든 것이 빠져 있었다. 이 지적을 받고 글을 다시 썼고, 그러고 나서 규칙으로 남겼다. 지금 파일에는 대조표가 들어 있다.
| 쓰지 않는다 | 대신 이렇게 |
|---|---|
| “내실은 그 자리에 있었다” | “실무에서는 자신이 있었다. 다만 그 경험이 정리되지 않은 채 쌓여 있었다” |
| “그 사이 세상이 바뀌었다” | “그 시기는 크게 바뀐 때였고, 나도 그 안에서 직접 만들며 통과했다” |
“제목과 소제목은 본문을 안 읽은 사람도 뜻이 통해야 해. 추상명사로 압축하지 말고 무엇이 어떻게 되는지를 그대로 써.”
두 번째 글 제목을 “버전을 올리는 일의 절반은 세는 일이었다”로 뽑았다. 무엇을 센다는 건지 글을 읽어야만 알 수 있는 제목이었다. 지금 파일에는 이렇게 적혀 있다.
개념을 추상명사 하나로 압축하면 쓴 사람에겐 정확하지만 읽는 사람에겐 그걸 풀 재료가 없다. 글을 다 읽은 사람만 알아듣는 문장이 된다.
제목은 “React 19를 올리면 547개 파일이 함께 바뀐다” 쪽으로 바뀌었다.
“고칠 곳을 다 늘어놓지 마. 네가 먼저 순위를 매겨서 위에서 두세 개만 말하고, 나머지는 내가 물어보면 그때 꺼내.”
원고를 봐달라고 하면 고칠 곳을 일곱 개씩 늘어놓고는 맨 끝에 “이 중 두 개가 중요하다”고 붙였다. 알면서 늘어놓은 것이다. 지금은 이렇게 적혀 있다.
두세 개만 말한다. 가장 중요한 것을 맨 앞에. 이미 결정된 것을 다시 꺼내지 않는다.
셋 다 형태가 같다. 하지 말 것, 대신 할 것, 판단이 안 설 때 어떻게 할 것. 앞의 둘만 적으면 애매한 자리에서 알아서 메꿔버리기 때문에 세 번째가 있어야 한다.
코드에서도 같다
블로그만의 이야기가 아니다. 서비스 저장소에도 같은 파일이 있다.
거기 CLAUDE.md는 112줄이고, 절반이 “무심코 바꾸면 안 되는 것” 목록이다.
React는 18.3.1에 의도적으로 머물러 있다. React 19로 올리면 Chakra 2→3(547파일), styled-components 5→6(293파일), recoil 제거가 연쇄로 딸려온다. React 버전을 올리는 건 이 셋을 함께 하겠다는 결정이다. 단독으로 올리지 마라.
이 문단이 없으면 다음에 이 저장소를 여는 사람은 — 그게 나여도, AI여도 — package.json에서 React 18을 보고 “낡았네, 올리자”고 판단한다. 그러고 나서 547개 파일이 깨지는 걸 본다.
결정의 결과만 코드에 남고 근거는 사라지는 게 문제다. "react": "^18.2.0"이라는 한 줄은 그게 게으름인지 판단인지 말해주지 않는다.
구조 리팩터링 때도 같았다. 규칙을 docs/architecture.md에 316줄로 적었고, 그중 한 절은 통째로 하지 않기로 한 것과 그 이유다. 남은 위반 6건이 왜 단순 이동으로 안 풀리는지, 라우트 184개를 왜 한 번에 안 고치는지가 적혀 있다.
재작업이 줄었다
글 네 편을 쓰면서 파일을 고친 커밋 수다.
| 커밋 | |
|---|---|
| 첫 글 | 8 |
| 두 번째 | 4 |
| 세 번째 | 2 |
| 네 번째 | 1 |
다만 이걸 규칙 덕분이라고만 하면 과장이다. 네 번째 글은 앞의 세 편과 같은 종류라 쓰는 쪽도 익숙해졌고, 소재도 커밋 기록이 다 갖고 있어 지어낼 게 없었다. 규칙이 쌓인 것과 같은 일을 반복한 것이 함께 작용했다.
그래도 확실한 건 하나 있다. 첫 글에서 여섯 번 고치며 했던 지적을 두 번째 글부터는 다시 하지 않았다.
넘길 수 없는 것
규칙을 아무리 적어도 넘어가지 않는 게 있다.
무엇을 쓸지. 이번 글이 네 편을 쓴 뒤에야 나온 건 앞의 셋을 쓰면서 재료가 생겼기 때문이다. 그 판단은 파일에 적을 수 없다.
어디까지 할지. 라우트 184개를 한 번에 정리하지 않기로 한 것, React 19를 이번에 올리지 않기로 한 것. 규칙은 결정한 다음에 적는 것이지 규칙이 결정해주지 않는다.
사실인지. 이 글의 숫자는 전부 커밋 기록과 파일에서 다시 확인했다. 88줄에서 225줄이 됐다는 것도 git show로 커밋마다 세어본 값이다. 확인하지 않은 숫자는 쓰지 않는다.
파일에 적는 건 이 셋을 대신하려는 게 아니다. 이 셋에 쓸 시간을 벌려는 것이다.