일기 같던 작업기록을 개발 일지로 다시 세웠다

이 블로그의 작업기록 10편은 Claude Code가 저장소의 커밋 기록을 읽고 하루 만에 썼다. 발행하고 다시 읽어 보니 글들이 일기에 가까웠다. "이날 이걸 했다, 이것도 붙였다, 이것도 이때 생겼다"처럼 한 일을 날짜순으로 늘어놓았고, 왜 그렇게 했는지와 어떻게 동작하는지는 거의 없었다. 어떤 글은 파일마다 몇 줄이 빠졌는지를 적었고, 어떤 글은 프로젝트 소개에 이미 있는 기능을 다시 설명했다. 관리 화면이 어디에 있고 어떤 인증 뒤에 있는지를 그림까지 그려 설명한 글도 있었다.

원인은 뒤늦게 쓰는 방식이었다

커밋 기록에는 무엇이 바뀌었는지만 남는다. 왜 그 방식을 골랐는지, 어디서 막혔는지, 무엇을 포기했는지는 커밋 메시지에 거의 없다. 그걸 보고 글을 쓰면 남아 있는 재료인 "무엇을 했다"를 날짜순으로 엮는 수밖에 없고, 빈자리는 줄 수 같은 숫자나 소개의 기능 설명으로 채워진다. 글의 문체를 고치기 전에 재료가 모이는 방식부터 바꿔야 했다.

기준: 기록할 만한 것만, 개발 일지 형식으로

공통 글쓰기 가이드의 작업기록 기준을 다시 썼다. 작업기록은 한 편에 문제 하나를 잡아 다른 개발자가 따라올 수 있게 쓰는 개발 일지다. 순서는 문제, 설계와 결정, 구현, 막힌 곳, 감수한 것이다.

무엇을 쓸지도 정했다. 새로 만든 시스템이나 구조, 바꾼 설계와 그 이유, 막혔다가 푼 문제가 기록거리다. 작은 입력 검증, 몇 줄 지운 정리, 테스트 개수 같은 잔가지는 빼고, 숫자는 동작이나 결정을 설명할 때만 쓴다.

공개하면 안 되는 정보의 범위도 넓혔다. 키나 토큰 같은 실제 값만이 아니라, 관리 화면의 위치, 인증과 접근 제어 구성, 서버와 라우팅 구성, 키를 보관하는 방식도 쓰지 않는다. 실제 값이 없어도 어디를 공격하면 되는지와 그 구조를 알려 주기 때문이다.

이 기준으로 공개한 10편을 다시 보고 4편만 남겼다.

체계: 작업하는 그 자리에서 쓴다

재료 문제를 풀려고 Claude Code의 전역 지침에 블로그 기록 규칙을 넣었다. 모든 프로젝트에 적용된다.

1. 작업을 시작할 때 프로젝트 지침에 블로그 게시 여부가 적혀 있는지 본다. 없으면 한 번 묻고, 답을 그 파일에 적어 둔다.
2. 게시할 프로젝트면, 기록할 만한 일이 생길 때마다 그 자리에서 MCP로 초안을 저장한다. 같은 주제가 이어지면 새 글을 만들지 않고 그 초안을 고쳐 키운다.
3. 이때는 저장할 때마다 확인받지 않는다. 초안으로만 저장하고 한 줄로 알린다. 발행은 어드민에서 사람이 한다.

결정한 이유와 막힌 곳은 작업하는 세션 안에 있을 때 가장 정확하다. 확인 없이 저장하게 한 건, 매번 묻는 단계가 있으면 기록을 미루게 되기 때문이다. MCP 서버가 초안까지만 쓸 수 있게 막혀 있어서, 확인을 빼도 공개되는 일은 없다.

감수한 것

초안이 작업하는 동안 계속 쌓이니 검토할 양이 늘어난다. 무엇이 기록할 만한지는 AI가 그 자리에서 판단하므로, 잔가지가 섞이거나 기록거리를 놓치는 일은 검토에서 걸러야 한다. 기준을 엄격하게 잡으면서 공개 글은 10편에서 4편으로 줄었다. 글 수보다 한 편이 다른 개발자에게 쓸모 있는지를 우선하기로 했다.