juspay/kolu

kolu 블로그 포스트 작성하기

kolu 블로그 포스트는 실제로 일어난 일을 바탕으로 한 1인칭 엔지니어링 에세이입니다. 막다른 길, 결정적인 결정, 교훈을 준 버그 등이 담깁니다. 진실의 원천은 가상의 마케팅 카피가 아니라 해당 작업을 생성한 Claude Code 세션 로그입니다.

이야기를 보여주고, 말로만 전하지 마세요. 좋은 포스트는 텍스트보다 시각 자료에 의존합니다. 궤적 차트, 전후 카드, 타임라인, 흐름 다이어그램, 비교 막대, 실제 스크린샷 — 시각화가 텍스트보다 더 많은 논증을 전달합니다. 모든 시각 자료는 실제 데이터(상태 타임스탬프, ps 출력, 측정된 기간)에 기반합니다. 차트는 논증이지 장식이 아닙니다. 이는 명백히 시각적인 포스트뿐 아니라 모든 포스트에 적용됩니다.

단계

1. 작업의 세션 찾기. 기능 뒤에 있는 Claude Code 세션 로그를 찾습니다(세션 로그는 ~/.claude/projects/ 아래에 있으며, 각 작업 디렉토리마다 하나의 디렉토리가 있습니다). PR → 브랜치 → 로그를 추적하여 결정론적으로 매핑하고, 키워드 검색에 의존하지 마세요.

2. 로그에서 이야기 발굴하기. 로그에서 인간/어시스턴트 내러티브를 읽고 결정 뒤의 이유, 어렵게 얻은 교훈과 막다른 길, 구체적인 메커니즘, 생생한 인용문을 추출하세요. 작업이 소수의 세션을 넘어서면 ultracode 워크플로를 사용하여 — 각 트랜스크립트당 하나의 에이전트가 구조화된 노트를 반환 — 확장한 다음, 노트를 단일 요약본으로 종합하고, 초안을 작성한 후, 적대적 편집 패스를 실행하세요. 요약본은 사실 확인된 뼈대입니다. 숫자, 날짜, 인용문, PR을 절대 조작하지 마세요.

3. 저자의 목소리로 작성하기. 별도 지시가 없으면 pg 스킬(Paul Graham 목소리)을 사용하고, 인라인 하우스 스타일을 미리 정하세요. 기존 포스트의 레지스터에 맞추세요. 새 포스트는 종종 기존 포스트의 후속편으로 짝을 이룹니다. 모호하지 않은 제목을 붙이세요. 프론트매터 title은 무슨 일이 일어났는지 명시하고 보상을 전달하는 평이하고 자명한 헤드라인입니다. 예를 들어 "Kolu의 macOS e2e CI 레인 14배 빠르게 만들기" — 슬러그나 독자가 끝까지 읽어야 해독할 수 있는 영리한 티저가 아닙니다. description은 구체적인 훅(64 GB 누수, 한 글자 오타)을 암시하도록 하세요. 이는 독자가 무엇을 배울지 미리 알 수 있도록 하는 의도적인 변화입니다. 모든 새 포스트에 적용하세요. 제목이 의도적으로 함축적일 경우(예: "코드의 시공간"), 프론트매터에 선택적 subtitle을 추가하세요. 이는 은유를 독자가 배울 내용으로 해독하는 한 줄입니다. 제목 아래 덱으로 렌더링됩니다.

4. 사이트에 연동하기. 포스트는 짧고 안정적인 슬러그 아래 website/src/content/blog/에 위치합니다(파일 이름이 URL입니다). 사이트의 컴포넌트를 사용하여 콜아웃, GitHub PR/이슈 참조 및 목차를 만드세요. 각 주장 뒤에 실제 PR을 인용하고, 포스트에 2단계 제목 개요를 제공하여 TOC가 중첩되도록 하세요. 각 섹션의 요점을 명확히 알리는 평이한 표지판으로 작성하고, 티저로 작성하지 마세요. 목차 목록이 축소된 논증으로 읽히도록 하세요. 모든 기술, 도구, 라이브러리, 형식 및 제품을 첫 번째 언급에서 링크하세요 — [Playwright](https://playwright.dev/), [ffmpeg](https://ffmpeg.org/), CDP 메서드의 문서 페이지 등. 기존 포스트가 하는 방식입니다. 링크가 없는 명명된 기술은 누락입니다. 콘텐츠가 일련의 단계 또는 짧은 열거형(예: 각각 실패하는 두 개의 API 메서드, 두 가지 주의사항)인 경우, 조밀한 단락 대신 마크다운 목록 또는 표를 사용하세요. 논증은 산문으로 유지하되, 열거 가능한 콘텐츠를 단락에 숨기지 마세요(pg 스킬의 "논증을 글머리 기호로 대체하지 마라" 규칙을 의도적으로 느슨하게 적용). 저자가 에이전트의 CLI 프롬프트 상자(Claude Code, Codex 등)에 문자 그대로 입력한 내용을 전환점으로 인용할 때는, 일반 블록 인용문이 아닌 Prompt 컴포넌트(website/src/components/Prompt.astro)로 렌더링하세요 — <Prompt>…</Prompt>. 사람이 에이전트의 입력 필드에 입력하는 것으로 읽히도록 합니다. 참조 사용법은 auto-demo.mdx를 참조하세요. 산문과 스크린샷 및 코드의 균형을 맞추세요. 이미지는 사이트에 호스팅하고, 외부 핫링크를 사용하지 마세요.

   시각 자료: 인라인 SVG 수동 작성, 테마 인식. 차트를 라이브러리 없이 MDX에서 직접 인라인 <svg>로 그립니다. 참조 그림은 macos-e2e-lane.mdx를 참조하세요. 모든 획과 채우기를 사이트의 --color-* CSS 사용자 정의 속성(--color-ink, --color-ink-dim, --color-ink-muted, --color-rule-strong, --color-amber, --color-live-alert, --color-live-lime, --color-void, …; 팔레트는 website/src/styles/global.css에 있음)으로 색칠하여 시각 자료가 자동으로 라이트/다크를 추적하도록 하세요. 절대 하드코딩된 16진수 값을 사용하지 마세요. 각각의 <svg>에 role="img"와 aria-label을 제공하여 표시하는 데이터를 설명하세요.

   MDX/SVG 주의사항 (macOS-lane 포스트에서 어렵게 얻은 팁). Astro의 MDX는 카멜케이스 SVG 프레젠테이션 속성(textAnchor, fontSize)을 문자 그대로 전달하며, SVG는 이를 조용히 무시합니다. 모든 레이블이 16px 왼쪽 정렬 기본값으로 렌더링됩니다. 각 속성의 실제 케밥케이스 SVG 철자를 사용하세요. text-anchor, font-size, font-weight, font-family, stroke-width, fill-opacity. viewBox와 같은 진정한 카멜케이스 SVG 속성은 그대로 유지됩니다. 눈으로 확인하면 놓칠 수 있습니다. 실제 브라우저에서 빌드된 사이트에 대해 getBBox()를 측정하여 잡아내세요.

5. 확인 및 배포. 사이트를 빌드하고 렌더링되는지 확인한 다음, chrome-devtools MCP를 사용하여 빌드된 출력물에 대해 라이트 및 다크 테마 모두에서 모든 시각 자료를 확인하세요. 레이블이 DOM에 존재하는 것뿐만 아니라 실제로 배치되었는지(getBBox()) 확인하세요. 그런 다음 PR을 엽니다. 문서 변경 사항이 건드릴 수 있는 CI 레인(웹사이트 빌드 및 포맷팅, 린트)만 실행하세요. ci 스킬을 참조하세요.