tag · 11 posts

#ai

  • experience
  • develop
  • devops
  • ai
  • claude-code
  • shell
  • jq
  • cli

VSCode에서 돌리는 Claude Code 세션은 왜 안 잡힐까 — ccwhere 구축기

병렬로 띄운 Claude Code 세션을 한눈에 보는 도구를 찾다 기존 도구들이 VSCode 확장의 세션을 못 잡는 이유를 추적했습니다. 해법은 프로세스 추적이 아니라 세션 로그 파일을 직접 읽는 것이었습니다. jq의 16진수 미지원, command substitution 안에서 죽는 tput, 셸 변수 확장이 삼킨 jq 변수까지, 작은 셸 스크립트 하나에 박힌 함정들을 정리합니다.

read →
매일 쓰는 협업의 글, PR · 커밋 · 온보딩 - 개발자를 위한 기술문서 입문 ep.08
  • series
  • develop
  • frontend
  • backend
  • infra
  • devops
  • ai
  • commit
  • pull-request
  • onboarding
  • code-review

매일 쓰는 협업의 글, PR · 커밋 · 온보딩 - 개발자를 위한 기술문서 입문 ep.08

기술문서라고 하면 큰 글을 떠올리지만, 개발자가 가장 자주 쓰는 글은 커밋 메시지와 PR 설명입니다. 거기에 온보딩 문서가 더해지면, 팀의 일상이 만들어집니다. 이번 편은 좋은 커밋의 골격, 리뷰가 즐거워지는 PR, 그리고 첫 주를 단축시키는 온보딩을 다룹니다.

read →
본 시리즈 바깥의 인접 문서들 - 개발자를 위한 기술문서 입문 ep.09
  • series
  • develop
  • design
  • frontend
  • backend
  • infra
  • devops
  • ai
  • user-manual
  • design-doc
  • security
  • appendix

본 시리즈 바깥의 인접 문서들 - 개발자를 위한 기술문서 입문 ep.09

본 시리즈는 내부 개발 협업에서 쓰는 문서에 초점을 맞췄습니다. 그러나 그 바깥에도 자리한 문서들이 있습니다. 비개발자가 읽는 사용자 매뉴얼, 구현 직전에 동료에게 의견을 구하는 디자인 문서, 공개와 비공개 사이의 보안 문서. 이번 편은 각자의 위치를 짚어두며 시리즈를 마칩니다.

read →
왜, 무엇을, 어떻게 - 개발자를 위한 기술문서 입문 ep.00
  • series
  • cover
  • develop
  • frontend
  • backend
  • infra
  • devops
  • ai
  • technical-writing
  • documentation
  • diataxis

왜, 무엇을, 어떻게 - 개발자를 위한 기술문서 입문 ep.00

기술문서를 안 써본 개발자가 가장 자주 겪는 문제는 형식이 아니라 의도입니다. 이 시리즈는 Diátaxis 프레임워크로 문서의 좌표를 잡고, 실무에서 실제로 마주치는 여덟 가지 산출물을 한 편씩 다룹니다. ep.00은 그 지도를 펴 보이는 편입니다.

read →
프로젝트의 첫인상, README - 개발자를 위한 기술문서 입문 ep.01
  • series
  • develop
  • frontend
  • backend
  • infra
  • devops
  • ai
  • readme
  • documentation
  • open-source

프로젝트의 첫인상, README - 개발자를 위한 기술문서 입문 ep.01

README는 한 글이 아니라 여러 글의 시작점입니다. 평가자·사용자·기여자라는 세 유형의 독자를 30초·5분·30분이라는 시간 축으로 갈라보고, Hero / Quick Start / Deep 세 구간으로 골격을 잡습니다. 좋은 예와 나쁜 예, 그리고 체크리스트까지.

read →
처음 온 사람을 데려가는 길, 튜토리얼 - 개발자를 위한 기술문서 입문 ep.02
  • series
  • develop
  • frontend
  • backend
  • infra
  • devops
  • ai
  • tutorial
  • onboarding
  • learning

처음 온 사람을 데려가는 길, 튜토리얼 - 개발자를 위한 기술문서 입문 ep.02

튜토리얼의 가장 흔한 실수는 설명을 하려 든다는 것입니다. 튜토리얼은 학습자에게 작은 성공을 안기는 글이고, 그 성공이 다음 학습으로 이어지는 글입니다. 하우투와 어떻게 다른지, 학습자 여정을 어떻게 설계하는지, 좋은 예와 나쁜 예까지 짚어봅니다.

read →
한 가지 목적을 해내는 절차, 하우투 가이드 - 개발자를 위한 기술문서 입문 ep.03
  • series
  • develop
  • frontend
  • backend
  • infra
  • devops
  • ai
  • how-to
  • guide
  • procedure

한 가지 목적을 해내는 절차, 하우투 가이드 - 개발자를 위한 기술문서 입문 ep.03

하우투는 목적이 있는 사람을 위한 글입니다. 골격은 단순합니다. 목적·전제·단계·검증·다음 행동. 그러나 분기를 잘못 다루는 순간 글은 무너집니다. 이번 편은 하우투의 골격을 짚고, 분기를 다루는 세 가지 패턴과 자주 망가지는 지점을 봅니다.

read →
정확한 사실의 색인, 레퍼런스와 API 문서 - 개발자를 위한 기술문서 입문 ep.04
  • series
  • develop
  • frontend
  • backend
  • infra
  • devops
  • ai
  • reference
  • api
  • openapi
  • docstring

정확한 사실의 색인, 레퍼런스와 API 문서 - 개발자를 위한 기술문서 입문 ep.04

레퍼런스는 가장 조용한 문서입니다. 처음부터 끝까지 읽으라고 만든 글이 아니라, 색인처럼 필요할 때 펼쳐 보라고 만든 글입니다. 그래서 미덕이 완전성과 일관성입니다. 이번 편은 레퍼런스 스펙트럼을 따라 docstring·시그니처·스펙을 짚고, 한 항목을 어떻게 써야 하는지 그 골격을 살핍니다.

read →
왜 이렇게 만들었는가, 아키텍처와 개념 설명 - 개발자를 위한 기술문서 입문 ep.05
  • series
  • develop
  • frontend
  • backend
  • infra
  • devops
  • ai
  • explanation
  • architecture
  • c4-model
  • diagram

왜 이렇게 만들었는가, 아키텍처와 개념 설명 - 개발자를 위한 기술문서 입문 ep.05

익스플레네이션은 왜의 글입니다. 결정의 배경, 다른 길과의 비교, 트레이드오프를 다룹니다. 이번 편은 C4 모델로 줌 레벨을 잡고, 여섯 가지 대표 다이어그램의 쓰임을 정리한 뒤, 설명문이 자주 빠지는 두 함정 — 묘사와 변호 — 을 짚습니다.

read →
의사결정의 기록, ADR과 RFC - 개발자를 위한 기술문서 입문 ep.06
  • series
  • develop
  • frontend
  • backend
  • infra
  • devops
  • ai
  • adr
  • rfc
  • decision-record
  • architecture

의사결정의 기록, ADR과 RFC - 개발자를 위한 기술문서 입문 ep.06

팀의 큰 결정은 어딘가에 적혀야 합니다. 결정 *전*의 글은 RFC, 결정 *후*의 글은 ADR입니다. 둘은 같은 주제를 다루지만 톤·구조·수명이 다릅니다. 이번 편은 ADR과 RFC의 위치 차이, 각자의 템플릿, 그리고 ADR의 상태 머신을 다룹니다.

read →
운영의 언어, 런북과 포스트모템 - 개발자를 위한 기술문서 입문 ep.07
  • series
  • develop
  • frontend
  • backend
  • infra
  • devops
  • ai
  • runbook
  • postmortem
  • incident
  • on-call
  • blameless

운영의 언어, 런북과 포스트모템 - 개발자를 위한 기술문서 입문 ep.07

운영 문서는 평소엔 안 읽힙니다. 읽힐 때는 누군가 잠에서 깬 새벽 3시이거나, 무언가가 막 망가진 직후입니다. 그래서 톤이 다릅니다. 군더더기가 없어야 하고, 감정이 빠져 있어야 하고, 사실이 우선해야 합니다. 이번 편은 런북의 응급 카드 구조와 포스트모템의 비난 없는 글쓰기를 다룹니다.

read →