기록을 한곳에 모두 넣으면 생기는 문제
프로젝트를 진행하면서 작업 로그와 트러블슈팅을 남기기로 했을 때 먼저 정해야 할 것은 “무엇을 쓸까”보다 “어디까지가 원본인가”입니다. 모든 commit을 블로그 글로 만들면 작은 변경이 중요한 기술 사례를 밀어냅니다. 반대로 GitHub에만 문서를 두면 채용 담당자가 여러 저장소와 디렉터리를 직접 찾아야 합니다.
기록의 목적도 서로 다릅니다. 진행 중 할 일, 완료한 변경, 되돌리기 어려운 결정, 실제 장애와 다른 사람에게 설명할 글은 같은 형식으로 관리하기 어렵습니다. 그래서 GitHub 원본, 블로그 해설, 프로젝트 상세 색인의 세 층으로 나눴습니다.
GitHub는 코드와 가까운 원본이다
GitHub 공식 문서는 Issues를 구체적인 작업·개선·버그를 논의하는 곳으로, Pull Request를 실제 변경과 리뷰를 연결하는 곳으로 구분합니다. 진행 중 작업은 Issues와 Projects에서 추적하고, 완료한 사실은 코드와 같은 저장소에 남깁니다.
프로젝트 저장소의 문서는 다음 책임을 가집니다.
docs/
worklog/YYYY-MM-DD-topic.md
adr/NNNN-topic.md
troubleshooting/slug.md작업 로그에는 날짜, 목적, 중요한 변경, 영향 범위, 실제로 실행한 검증과 남은 작업을 씁니다. ADR은 구조나 인프라처럼 되돌리는 비용이 큰 선택에만 작성하고, 선택한 안뿐 아니라 검토한 대안과 재검토 조건을 남깁니다.
트러블슈팅은 단순히 “오류를 고쳤다”는 일지가 아닙니다. 기대와 실제, 영향, 재현, 가설, 증거, 원인, 대안, 해결, 복구 후 검증, 재발 방지와 남은 위험이 있어야 합니다. 실제 장애가 아닌 routine 작업을 면접용 사건으로 꾸미지는 않습니다.
블로그는 선별한 문제를 읽을 수 있게 다시 쓴다
블로그에는 모든 작업 로그를 복제하지 않습니다. 성능 병목을 실행계획과 부하 테스트로 좁힌 사례, 배포·인증·동시성·데이터 정합성 장애, 큰 구조 선택, AI 평가와 guardrail, 공모전의 핵심 가설처럼 하나의 기술 질문에 답할 수 있는 기록만 고릅니다.
원본 문서가 시간순 사실을 보존한다면 블로그 글은 다음 순서로 맥락을 다시 구성합니다.
- 사용자 문제와 기대 동작
- 제약과 직접 맡은 범위
- 검토한 선택지와 선택 이유
- 구현과 실패한 가설
- 실제 검증과 결과
- 일반화할 수 없는 한계와 다음 작업
글 마지막이나 프로젝트 상세에서 관련 ADR, Issue, PR, commit과 트러블슈팅 원문을 연결합니다. 독자는 짧은 해설로 문제를 이해하고, 더 확인하고 싶을 때 코드에 가까운 근거로 돌아갈 수 있습니다.
진행 중인 프로젝트는 진행 중이라고 쓴다
완성되지 않은 공모전이나 팀 프로젝트도 숨길 필요는 없습니다. 대신 기획·준비 중, 프로토타입·작업 중, 운영·개선 중을 구분하고 현재 확인한 것과 다음 검증을 적습니다. 계획한 Kubernetes나 AI 모델을 이미 사용한 기술처럼 나열하지 않고, 데이터 스파이크나 Day-1 가용성 확인처럼 다음 판단 기준을 보여줍니다.
팀·비공개 저장소는 원문 링크보다 공개 범위가 먼저입니다. 팀원의 코드, 내부 URL과 데이터를 복사하지 않고 개인 역할과 공개 가능한 계약·검증만 요약합니다. 기여 귀속이 확인되지 않은 협업 프로젝트는 기술적으로 흥미로워도 공개 글을 보류합니다.
이 블로그에 적용한 방식
각 프로젝트 상세에는 현재 상태, 활동 유형, 직접 역할과 함께 작업 로그와 트러블슈팅 영역을 추가했습니다. 공개 저장소에 ADR나 troubleshooting이 있으면 원문을 연결하고, 아직 없거나 비공개라면 어떤 기준으로 기록을 공개할지 설명합니다.
앞으로 새 작업은 저장소에서 먼저 사실과 검증을 남깁니다. 그중 면접에서 깊게 설명할 수 있고 다른 프로젝트에도 재사용할 판단만 블로그 글로 발전시킵니다. 글의 수보다 코드, 실패와 검증이 서로 연결되는지를 기록 품질의 기준으로 삼습니다.