블로그 초안과 할 일을 따로 관리하기

Confluence에 기록이 쌓이면서 어떤 글을 작성 중이었는지 다시 확인하는 일이 많아졌습니다. 장비나 AI 도구를 바꾸면 앞선 대화만으로는 작업을 이어가기 어려웠습니다.

그래서 초안과 할 일을 대화 밖에 남기되, Confluence와 GitHub 이슈에 같은 정보를 두 번 관리하지 않도록 역할을 나눴습니다. Confluence는 원문과 글 상태를, GitHub 이슈는 실행할 작업을 맡도록 했습니다.

Confluence의 글 상태 관리

각 페이지 상단에 상태를 넣고 대시보드에서 모아 볼 수 있게 구성했습니다. 본문에 일반 텍스트로 쓰던 상태는 Page Properties로 옮기고, 상태에 맞는 라벨도 함께 관리했습니다.

속성과 라벨을 함께 바꾸는 이유는 대시보드가 라벨을 기준으로 문서를 모으기 때문입니다. 페이지 상태만 바꾸고 라벨을 남겨 두면 작성 중인 글이 이전 단계에 계속 표시될 수 있습니다.

GitHub 이슈의 역할

GitHub 이슈에는 특정 글 작성, 사이트 버그 수정처럼 실행할 일을 적었습니다. 글의 원문과 편집 판단은 Confluence에 남기고, 같은 상태표를 이슈에 다시 만들지는 않았습니다.

작업을 다시 시작할 때는 이슈에서 할 일을 확인하고, 대시보드에서 글 상태를 본 뒤 원문과 MDX를 읽습니다. 어느 대화에서 작업했는지 기억하지 못하더라도 저장된 문서와 소스에서 이어갈 수 있도록 한 순서입니다.

원문과 MDX를 연결하는 정보

글을 합칠 때 가장 먼저 필요한 것은 어느 기록이 어느 글로 들어갔는지 찾는 정보였습니다. 원문 하나가 글 하나가 되는 경우만 있다면 제목으로 찾을 수 있지만, 날짜별 기록을 합치면 제목만으로는 부족합니다.

지금 관리 파일에서는 대표 원문과 함께 들어간 원문 목록, 최종 MDX 경로를 연결합니다. 아래는 실제 값 대신 예시 식별자를 넣은 형태입니다.

{
  "title": "환경 준비와 실행 기록",
  "path": "content/example/environment-setup.mdx",
  "status": "Reviewing",
  "primarySource": "PAGE_ID_A",
  "sources": [
    {"id": "PAGE_ID_A", "title": "최초 환경 구성"},
    {"id": "PAGE_ID_B", "title": "설정 변경과 후속 확인"}
  ]
}

대표 문서에는 공개용 초안을 연결하고, 나머지 문서에도 어느 초안으로 합쳤는지 남깁니다. 원문을 삭제하거나 공개용 글로 덮어쓰지 않으므로 나중에 빠진 내용이 있는지 비교할 수 있습니다. MDX 경로는 제목이 바뀌어도 찾을 수 있는 연결점입니다.

Confluence의 속성은 다음처럼 역할을 나눕니다.

상태와 라벨을 맞추는 작업은 사이트 배포와 별도로 합니다. 배포 중 실패했다면 원문에 Published를 먼저 적지 않고 이전 단계에 둡니다. 대시보드에서 보이는 상태가 실제 공개 결과와 어긋나면 다음 장비에서 이어갈 때 다시 확인할 일이 생깁니다.

GitHub 이슈에 남길 작업의 크기

이슈에는 글 전체를 복제하기보다 끝났는지 판단할 수 있는 작업을 적습니다. 예를 들어 “글 개선”보다 “설치 명령을 현재 소스와 대조하고 로컬에서 코드 블록을 확인”이라고 적으면 확인 대상이 분명합니다.

제목: 환경 구성 글의 설치·실행 예시 보강
 
- 원문: Confluence의 대표 문서
- 대상: content/example/environment-setup.mdx
- 작업: 설치 전제, 실행 명령, 실패 조건 설명
- 확인: MDX 빌드, 내부 링크, 실제 로컬 화면
- 완료 기준: Reviewing 상태와 검토 주소를 원문에 반영

이것은 작업 작성 예시이며 새 이슈를 생성한 결과는 아닙니다. 할 일이 끝나도 공개 발행을 요청한 것은 아니면 초안 상태를 유지합니다. 반대로 문장 하나를 고치는 작업마다 원문의 모든 상태를 바꿀 필요도 없습니다. 글 상태는 편집 흐름을, 이슈는 이번에 수행할 변경을 보여주도록 범위를 나눴습니다.

글을 합치고 나누는 기준

기록을 옮기면서 날짜별 문서를 그대로 한 편씩 발행하지는 않았습니다. 처음 구현과 이후 구조 변경이 같은 주제라면 한 글 안에서 이유와 순서를 이어 설명하는 편이 읽기 좋았습니다.

반대로 같은 프로젝트라도 장애 원인이나 데이터 설계처럼 따로 설명할 내용이 충분하면 글을 나눴습니다. 프로젝트 이름이 같다는 이유만으로 모든 기록을 합치면 한 글의 범위가 너무 넓어집니다.

구성이 바뀌면 파일명과 이전·다음 링크, 용어와 코드 예시도 함께 맞췄습니다. 독자가 여러 글을 순서대로 읽을 때 초기 설정을 매번 다시 설명하지 않도록 했습니다.

변경 과정과 발행 상태

현재 운영 문서에는 지금 설정을 적고, 작업 기록에는 변경 전후와 이유를 남깁니다. 나중에 비슷한 문제를 겪었을 때 이전 구성을 왜 바꿨는지 확인할 수 있어야 하기 때문입니다.

원문 기록은 보존하고 공개용 본문을 따로 다듬습니다. 커밋이나 로컬 빌드만으로 상태를 Published로 올리지 않고, 실제 공개된 글의 제목과 주소를 확인한 뒤 반영합니다.