요약
- 이 글은 블로그를 처음 열 때 세운 운영 원칙을 정리한 기록이다.
- 현재 글 작성의 세부 기준은 repo의
AGENTS.md를 기준으로 관리한다. - 공개 글은 실제 맥락을 살리되, 증거와 검증 범위, 공개하면 안 되는 정보를 명확히 나눠야 한다.
상황
이 블로그는 완성된 튜토리얼을 모으기보다 실제 프로젝트를 만들고 운영하면서 배운 점을 기록하기 위해 시작한다.
좋은 기록은 나중에 다시 읽었을 때 바로 쓸 수 있어야 한다. 그래서 글마다 문제 상황, 확인한 증거, 판단 과정, 다음에 반복하지 않을 기준을 남긴다.
처음에는 이 글 자체가 작성 기준에 가까웠다. 하지만 글이 늘어나면서 이미지, Excalidraw 도식, SEO metadata, private 글 처리, 공개 전 보안 점검처럼 repo에 더 가까운 규칙이 생겼다.
그래서 현재의 세부 작성 기준은 AGENTS.md에 둔다. 이 글은 "왜 이런 방식으로 기록하는가"를 설명하는 초기 운영 원칙으로 남긴다.
글의 기본 구조
앞으로 프로젝트 기록은 가능하면 아래 흐름을 따른다.
## 상황
## 문제
## 처음 생각한 가설
## 확인한 증거
## 해결한 방식
## 검증
## 배운 점
## 다음에는 이렇게 할 것
## 참고모든 글이 이 순서를 그대로 따라야 하는 것은 아니다. 회고 글은 피드백과 행동 변화 중심으로, 실험 글은 가설과 결과 중심으로, 장애 기록은 증거와 검증 중심으로 바꿀 수 있다. 다만 ## 요약, 문제 상황, 확인한 증거, 다음 기준은 가능하면 남긴다.
공개 기준
프로젝트 기록을 공개할 때는 실제 맥락을 남기되 공개하면 안 되는 정보는 제거한다.
- 토큰, 계정, 내부 URL, 고객명은 쓰지 않는다.
- 장애나 비용 기록은 원인과 판단 기준 중심으로 정리한다.
- 코드 조각은 문제를 설명하는 데 필요한 만큼만 남긴다.
- 추측과 확인된 사실을 구분한다.
- private 글도 보안 저장소처럼 취급하지 않는다. 공개 전 민감정보와 스크린샷을 먼저 정리한다.
이미지와 도식 기준
가능하면 글의 첫머리에 상황 설명 도식을 둔다.
도식은 본문을 대신하지 않는다. 색, 화살표, 박스는 문제 구조를 빠르게 보여주는 보조 장치이고, 핵심 판단은 본문 문장으로 다시 설명한다.
스크린샷이나 실험 이미지는 "무엇이 보이는지"가 alt text와 주변 문단에 드러나야 한다. 이미지가 근거라면 독자가 어디를 봐야 하는지도 같이 적는다.
태그 기준
태그는 나중에 다시 찾기 쉬운 단어로 붙인다.
debuggingdeploymentanalyticsfrontendbackendinfraproductretrospectivesecurityseo
첫 운영 원칙
길게 쓰려고 미루지 않는다. 한 프로젝트에서 하나만 배워도 글 하나로 남긴다.
대신 공개할 때는 대충 내보내지 않는다. 현재 기준은 단순하다.
- 내가 실제로 확인한 것만 쓴다.
- 검증하지 않은 결과를 성공처럼 말하지 않는다.
- 외부 문서는 공식 문서를 먼저 본다.
AGENTS.md를 기준으로 frontmatter, 이미지, 공개 범위, 검증을 확인한다.
