Codex와 Claude Code에서 함께 쓰는 수동 개발로그 작성 규칙

오늘의 목표와 맥락

개발 작업을 마친 뒤에는 구현 내용과 판단 과정을 기록으로 남기고 싶지만, 매번 같은 형식의 글을 처음부터 구성하는 일은 생각보다 번거롭다. 특히 AI에게 글 작성을 맡길 때는 대화 맥락을 활용하면서도 사실이 아닌 내용을 그럴듯하게 덧붙이지 않고, 공개하면 안 되는 정보를 지키는 규칙이 필요하다.

이번 작업의 목표는 특정 프로젝트의 API나 배포 환경에 묶이지 않는 수동 개발로그 작성 규칙을 만드는 것이었다. Codex와 Claude Code 어느 쪽에서 작업했는지와 관계없이 같은 요청 방식과 같은 결과물 형식을 사용할 수 있도록 했다.

수동 작성으로 남긴 이유

여기서 “수동”은 글의 소재를 자동 수집하거나 바로 블로그에 발행하지 않는다는 뜻이다.

작성자는 AI에게 현재 세션이나 직접 제공한 메모를 바탕으로 글을 정리해 달라고 요청한다.
AI는 로컬 Markdown 초안만 만든다.
글을 읽고 수정하고 발행하는 결정은 사람이 직접 한다.

이 흐름을 남겨 두면 기록의 편의성과 공개 전 검토의 안전성을 함께 지킬 수 있다.

구현한 내용

두 도구에서 공통으로 인식할 수 있는 manual-devlog 스킬을 만들었다. 이 스킬은 개발로그를 작성하거나 요약하거나 아카이브해 달라는 요청이 들어왔을 때 적용된다.

파일 저장 규칙

규칙의 핵심은 다음과 같다.

글의 근거는 현재 AI 세션, 사용자가 명시적으로 제공한 메모, 그리고 작업 범위로 허용된 로컬 파일로 제한한다.
GitHub 이벤트 수집, 외부 API 업로드, 자동 발행, 저장된 외부 인증정보 사용은 하지 않는다.
생성 문서는 docs가 아닌 프로젝트 루트의 devlogs 폴더에 저장한다.
파일명은 날짜와 순번을 포함한 YYYYMMDD_[N]_제목.md 형식을 사용한다.
같은 날짜에 여러 글을 만들면 [1], [2], [3] 순으로 번호를 높인다.

핵심 판단: 개발로그를 일반 문서나 설계 문서와 분리하면 시간순 탐색과 블로그 원고 관리가 쉬워진다. 파일 하나가 곧 하나의 독립적인 글 초안이므로 나중에 블로그 에디터로 옮기거나 다른 형식으로 변환하기도 쉽다.

문서 형식을 단순하게 고정한 이유

글의 본문 구조를 지나치게 복잡하게 정하면 짧은 기록을 남기는 데 오히려 방해가 된다. 반대로 제목만 있는 자유 형식은 목록에서 글의 성격을 파악하기 어렵고, 나중에 태그별로 묶기도 어렵다.

필수 메타데이터

문서의 첫 부분은 아래 형식으로 고정했다.

제목: 글 제목
태그: 태그1, 태그2, 태그3,

# 대분류

## 세부 항목

Markdown 본문

제목은 한 문장으로 글의 핵심을 드러낸다.
태그는 여러 개를 사용할 수 있으며, 실제 글 내용으로 뒷받침되는 기술이나 주제만 넣는다.
본문은 일반 Markdown으로 작성하며, 대분류와 세부 주제의 깊이를 구분한다.

AI가 근거 없이 유행어처럼 태그를 늘리지 않도록 한 선택이다.

본문 Markdown 사용 원칙

본문은 글의 성격에 따라 다음 섹션을 선택해 사용한다.

# 오늘의 목표와 맥락
# 구현한 내용
# 설계와 판단
# 문제와 해결
# 검증한 내용
# 다음 단계

세부 설명이 필요하면 ##을 사용하고, 한 단계 더 세분화할 때만 ###을 사용한다. 반복되는 항목은 목록으로 정리하고, 중요한 판단이나 결론은 강조한다. 다만 실제 문제나 검증이 없었다면 해당 섹션을 억지로 채우지 않는다.

설계와 판단

가장 중요한 판단은 “AI가 알고 있는 것”과 “글에 써도 되는 것”을 구분하는 일이었다.

공개 범위 기본값

AI가 세션의 세부 맥락을 알고 있더라도 다음 정보는 공개 글의 소재가 될 수 없다.

로컬 절대 경로
인증 정보와 비밀 값
내부 주소와 고객 정보
사용자가 허용하지 않은 비공개 프로젝트 이름

따라서 스킬은 공개 여부가 분명하지 않은 정보를 기본적으로 비공개로 취급한다. 사용자가 명시적으로 허용하지 않은 프로젝트명이나 내부 환경 정보는 일반화하거나 생략한다. 비밀 값은 사용자가 허용하더라도 복사하지 않는다.

사실성 유지

개발로그는 회고 형식의 글이지만, AI가 자연스러운 서사를 만들기 위해 경험하지 않은 장애나 성과를 만들어 내면 기록의 신뢰도가 무너진다.

근거가 부족한 부분은 생략하거나 작성자가 나중에 확인할 질문으로 남긴다.

완료된 작업, 계획 중인 작업, 가정은 문장 안에서 명확히 구분한다.

검증한 내용

Codex와 Claude Code의 전역 스킬 경로에 같은 규칙 파일을 두고, 두 파일의 내용이 일치하는지 확인했다. 또한 스킬 형식 검증을 통과해 이름과 설명, Markdown 구조가 정상적으로 인식될 수 있는 상태임을 확인했다.

사용 예시

이제 어느 도구에서든 다음처럼 요청할 수 있다.

오늘 작업을 개발로그로 작성해 줘.

또는 명시적으로 다음과 같이 요청할 수 있다.

$manual-devlog 현재 세션을 상세 개발로그로 저장해 줘.

요청을 받은 AI는 프로젝트의 devlogs 폴더를 확인하고, 오늘 날짜에 이미 작성된 글이 있으면 다음 순번을 선택한다. 작성이 끝나면 저장 경로와 간단한 요약을 알려 주되, 발행하거나 외부 서비스에 전송하지 않는다.

다음 단계

이 규칙은 글의 초안을 안정적으로 남기는 데 초점을 둔다. 앞으로 필요해지면 블로그별 서식, 문체, 공개 전 체크리스트처럼 프로젝트마다 다른 요구 사항은 별도 규칙으로 덧붙일 수 있다.

하지만 기본 흐름은 유지하는 편이 좋다.

AI가 사실에 기반한 Markdown 초안을 만든다.
작성자가 내용을 검토하고 보완한다.
원하는 플랫폼에 직접 올린다.

이 단계가 남아 있어야 개발로그가 자동 생성된 기록이 아니라, 작성자의 경험과 판단이 담긴 글로 남는다.