Hello, I'm an open source software engineer in my late 30s living in #Seoul, #Korea, and an avid advocate of #FLOSS and the #fediverse.
I'm the creator of @fedify, an #ActivityPub server framework in #TypeScript, @hollo, an ActivityPub-enabled microblogging software for single users, and @botkit, a simple ActivityPub bot framework.
Libghostty is coming. 👻 The first library will be libghostty-vt: a zero-dependency (not even libc!) library that provides an API for parsing terminal sequences and maintaining terminal state, extracted directly from Ghostty's real-world proven core. https://mitchellh.com/writing/libghostty-is-coming
그렇습니다. 우울하지 않은 사람도 "우울할 때에는 상담하기"를 평소에 열심히 외워 둘 필요가 있습니다. 왜냐?
심리학에는 결핍의 덫(scarcity trap)이라는 개념이 있는데요. 사람은 시간이나 금전 등 어떤 자원이 결핍(scarce)되면, 심리적 압박을 받아 시야가 좁아집니다(tunnel vision). 이로 인해 올바른 결정과 실행을 못하게 됩니다. 그러면 자원의 결핍(scarcity)이 더 심해집니다.
이렇게 얘기하면 떠오르는 전형적인 예시가 있습니다. 열악한 노동 조건과 저임금에 시달리는 노동자가, 스트레스 때문에 퇴근 후 술이나 도박 등의 즉각적 쾌락에 돈과 시간과 건강을 다 탕진해 버리는 것이죠. 하지만, 높은 소득과 지위를 누리던 대기업 간부도 투신자살을 해서 충격을 주곤 합니다.
사람이 이 덫에 빠지게 되는 계기가 한두 가지가 아닙니다. 환경적 요인으로 인해 우울감이 발생하기도 하고, 반대로 우울감이 사회생활에 지장을 초래해 환경적 요인을 조성하기도 합니다. 그리고 어떤 식으로든 이 덫에 빠지면,
- 심리적 압박으로 시야가 좁아지고 - 그로 인해 어리석은 판단을 하게 되고 - 그 어리석은 판단으로 인해 더욱 궁지에 몰리고 - 심리적 압박이 더 커키고 - 더 어리석은 짓을 저지를 수가 있습니다.
이 악순환이 누적되면, 돈 많다는 사람들에게도, 똑똑하고 가방끈 길다는 사람들에게도, 얼마든지 비극이 일어나는 것입니다.
우울장애의 가장 큰 무서움이 이것입니다. 현대 사회가 개인에게 도움을 제공하는 모든 체계에는 전제가 있습니다. "개인이 적어도 이기적 동기는 잘 가지고 있을 것." 우울감이 지속되면 이 전제가 깨집니다. 스스로에게 이로운, 이기적인 판단조차 제대로 할 수 없게 됩니다.
그러니 "우울할 때에는 상담하기"를 기억합시다. 평소에 외워 두지 않으면, 우울할 때에 떠오르지 않습니다.
물론 한국은 우울장애에 대한 인지적 관점이 많이 부족한 사회입니다. 그러나 연락처 목록을 뒤져 보면 한두 명 정도는 믿고 이야기할 사람이 있을 것입니다.
주변 사람들을 못 믿겠다면, 일면식도 없는 전문가를 찾읍시다. 한국의 정신과 전문의나 상담심리사 등, 우울한 사람에게 도움을 줄 분들의 숙련도나 전문성은 뜻밖에도 전반적으로 뛰어난 편입니다. 믿고 도움을 청해 봅시다.
제발 힘들면 힘들다고 이야기해주십쇼 속에만 쌓아두다가 소울스트림 가지 마시고.. 해결까지는 장담 못해드리지만 들어드릴 수는 있으니 저 뿐만이 아니라도 주변 믿을 수 있는 친구에게라도 이야기를 해주세요. 소울스트림으로 훌쩍 떠나버리시면 당신을 바라보던 남아있는 사람들도 많이 힘들어요. 제발.. 제발 부탁드립니다.
최근 개방 소셜 네트워크의 지형이 급격하게 변화하고 있다. 빅테크 플랫폼을 대체할 소셜 네트워크를 만든다는 것은 원래부터 근본적으로 정치적인 프로젝트였지만, 미국의 현 시국으로 인해 또 다른 차원의 위기감이 닥치고 있다. 중도 논객들은 블루스카이를 좌편향 플랫폼으로 규정하는 데 온 신경을 쏟고 있고, X 렉카들은 블루스카이 사용자들이 찰리 커크의 죽음을 희화화(celebration)한다는 날조된 내러티브를 확대재생산하며, 블루스카이를 포함해 모든 민주진보 플랫폼을 폐쇄하고 기소하라는 파시즘적인 목소리는 커져만 간다. 빅테크의 대체 플랫폼을 세우는 프로젝트는 미 의회의 검열 움직임과 앱 장터에서 블루스카이를 내리라는 요구 속에서 권위주의 미국과 충돌하고 있다.
블루스카이즘(Blueskyism)
미국의 정치 논객 네이트 실버는 9월 초에 블루스카이즘에 대해 다룬 적이 있다. 글은 블루스카이에서 사용자 활동이 감소하고 있다는 통계를 제시하면서 시작한다 (이는 사실이다). 실버는 블루스카이즘은 블루스카이 이전부터 이미 있었던 것이라는 논지로 글을 이어가고, 블루스카이즘을 정치 스펙트럼의 반대쪽에 있는 사람들을 비난하고, 학술적 권위를 중시하며, 현상에 지나치게 불만을 품는 태도로 설명하며 이를 거부한다.
블로거 겸 중도 논객인 노아 스미스 역시 실버의 이 글과 관련해 미국 좌익의 블루스카이화(The Bluesky-ization of the American left)라는 글을 작성했다. 2010년 후반에 바리 웨이스가 트위터에서 지나친 비판을 받은 것을 속상해하고, 자멜 부이가 본인을 '반사회적인 괴짜 루저'라고 지칭한 것에 대해 화내는 것이 글의 요지다.
포면적으로만 보면 두 글 모두 SNS에 상주하는 어떤 중도 논객이 본인이 블루스카이에서 욕을 먹고 있다고 화내는 내용에 불과하다. 이들은 블루스카이가 망해가는 SNS라는 그림을 그리고 있다. 두 글에서 언급하지 않는 사실이지만, 일단 실버는 학술계에서 블루스카이가 얼마나 중요한 위치를 차지하고 있는지를 공개적으로 인정한 바가 있다.
그러나 두 글이 작성된 진짜 목적은 따로 있다.
X 활동을 그만두는 것을 고민하는 사람들에게 블루스카이는 어차피 진짜 대안이 될 수 없다는 논리로 X에 남아도 된다는 도덕적 핑계를 제시한다.
블루스카이는 민주진보 플랫폼이라는 인식이 있다는 인정 구조(permission structure)를 만들어낸다. 여기서 이 두 글을 언급한 이유가 이것이다. 개인적으로 글의 내용 자체도 옹졸하고 주제 역시 잘 이해하지 못하고 있다고 느껴지지만, 블루스카이가 '좌편향'된 플랫폼이라는 시각을 확산시키는 데 이는 중요하지 않다.
찰리 커크의 피살
찰리 커크 얘기는 지겹도록 들었을 테니, 핵심만 요약하겠다.
블루스카이는 찰리 커크의 죽음을 희화화하는 플랫폼이라는 인식이 생겼으며, 특히 팀 어번의 "블루스카이에 올라오는 모든 글이 암살을 희화화하고 있다. 믿을 수 없이 역겨운 사람들이다."라는 글에 일론 머스크가 "냉혹한 살인을 축하하고 있는 것이다"라며 인용한 것이 2600만 조회수를 기록하면서 이런 관점의 확대재생산에 일조하고 있다.
이에 대해 슬레이트는 블루스카이는 찰리 커크의 죽음을 희화화하고 있지 않다(No, Bluesky Isn't Celebrating the Death of Charlie Kirk)라는 반박 기사에서 [블루스카이] 플랫폼의 실상을 확인하고, 일론 머스크가 확산시킨 게시물들이 거짓부렁임을 밝혔다. 개방된 데이터가 바로 블루스카이의 강점이고, Catch Up과 같은 피드에서도 어제 하루 동안 플랫폼 전체에서 좋아요를 가장 많이 받은 게시물을 확인할 수 있다. 이와 같은 방식으로 플랫폼의 '시대정신'이 무엇인지 상당히 객관적으로 확인할 수 있으며, 인기 게시물 중 커크의 죽음을 희화화하는 것이 없었다는 것 역시 확인된다.
커크는 합리적인 말을 하는 기독교 자기계발 스피커와 혐오로 점철된 스피커라는 사실상 두 얼굴을 가지고 있다. 듣기 좋은 말을 해주는 자기계발 스피커라는 커크의 거짓을 혐오자로서의 커크가 까발리기 때문에 후자는 존재할 수 없었다. 본인이 형성하고 싶은 거짓된 현실을 커크 본인의 발언이 위협하는 것이 본인의 세계관이라면, 커크의 피살을 심도 있게 다루는 것이 '희화화'처럼 보일 수 있겠다.
머스크를 비롯한 파시스트들이 블루스카이를 왜 그렇게 싫어하는지도 두 얼굴의 커크로 설명할 수 있다. 블루스카이는 합리적인 말을 하는 자기계발 스피커 커크라는 거짓을 까발리는 발언을 허용하는 곳이다. 파시즘의 핵심은 지배이며, 자신의 권력을 이용해 거짓된 현실을 사람들에게 강요하는 것이다. 블루스카이와 같이 사람들이 이런 조작된 내러티브를 거부할 수 있는 개방 네트워크는 권위적 통제라는 계획 자체에 존재론적 위협이 된다.
모더레이션 문제
찰리 커크의 피살 직후 살인범에 대해 아무런 정보도 없었던 시점에 X에서는 '좌파'에 대한 비난이 시작되었고, 전쟁도 불사하겠다는 극단적인 주장이 생겨나기도 했다. 한편 블루스카이에서는 정치 지형이 바뀌었으니 앞으로의 행보에 유의해야 한다는 발빠른 인식을 가졌다.
블루스카이 CEO 제이 그레이버와 COO 로즈 왕 모두 정치적 폭력을 반대한다는 입장을 내세웠다. 그레이버가 블루스카이 CEO로서 정치 상황에 대해 입장을 낸 것은 이번이 처음으로, 이번 사건이 블루스카이라는 기업에 악영향을 미칠 수 있음을 분명히 알고 있었던 것이다.
블루스카이의 신뢰·안전팀에서는 모더레이션에 자사 규정을 엄격하게 적용하기 시작했으며, 과소 제재보다는 과잉 제재가 낫다는 방향을 잡은 듯하다. 이로 인해 블루스카이 측의 지나친 모더레이션으로 인해 계정이 부당하게 정지되었다고 호소하는 사례 역시 발생하고 있다. 개별적인 결정을 모두 평가하지는 않겠지만, 개인적으로 실제 현실만큼이나 현실에 대한 인식 역시 중요하다고 본다. 블루스카이의 모더레이션 결정이 옳았든 아니든, 사용자층 다수의 인식은 블루스카이의 제재가 잘못되었다는 쪽으로 기울게 된 것이다.
이 인식 변화에서 가장 주목할 만한 사례는 블루스카이가 커크의 피살에 대해 "rest in piss"(역자 주: '삼각 고인돌에 면봉을 비빕니다'에 빗댈 수 있는 표현)라고 작성한 사용자에게 24시간 계정 정지 조치를 시작했다는 것이다. 이 정책으로 인해 네이선 그레이슨 역시 피해를 입었으며, 애프터매스에 블루스카이 모더레이션의 현 주소를 분석한 기사를 기고하기도 했다. 이 기사에서는 어떤 글은 삭제하고, 어떤 낚시성 글은 무시하고, 일부 게시물이나 계정의 제재는 명확한 소통 없이 갑자기 취소되기도 하는 등 규정이 일관성 없이 적용되는 블루스카이 모더레이션의 혼란스러운 실상을 확인할 수 있다.
한편 CTO 폴 프레이지는 다른 주제에 관한 대화에서 성의 없이 "rest in piss 제재는 취소했음"이라고 언급한 것을 찾아볼 수 있다. 제재 조치에서 실수가 있었음을 공개적으로 밝힌 것이 CEO도 신뢰·안전팀의 팀장도 아닌 CTO라는 것 자체가 블루스카이 모더레이션의 무능을 방증한다. 제재가 취소된 사용자들에게 아무런 통보도 없었다는 것은 말할 필요도 없다.
블루스카이는 지금 난처한 상황에 처해 있다. 규정을 위반하는 게시물을 삭제하라는 정치적 압력이 그 어느 때보다도 높다. 일론 머스크를 비롯해 지구상에서 가장 큰 권력을 가진 자들이 블루스카이에서 커크의 죽음을 희화화하는 게시물을 찾아다니고, 찾아낸 게시물을 통해 블루스카이에 정치적 압박을 가하고 있다. 그레이버가 청문회에 소환되어 블루스카이 규정을 위반하고 우익 엘리트층에게도 불리한 게시물을 제재하지 않은 이유를 해명해야 할 위협 역시 실재한다. 이 맥락에서 Bluesky PBC가 자사 플랫폼을 과잉 제재하는 분위기로 흐른 것은 이해할 수 있다. 하지만 파시스트에 대한 유화책은 해결책이 되지 못한다. 머스크가 블루스카이에서 커크의 죽음을 희화화하는 인기 게시물을 더 이상 찾지 못하자 한 행동은 가짜 계정의 게시물임이 역력히 드러나는 재게시 0건, 좋아요 0건의 게시물 스크린샷을 공유하는 것이었다. 머스크는 스크린샷을 인용하면서 "맞서 싸우지 않으면 우리를 다 죽일 것"이라는 글을 남겼고, 이는 1000만 회 이상의 조회수를 기록하고 있다. 머스크는 사악한 블루스카이라는 본인의 내러티브를 계속 재생산하고 블루스카이는 사용자층에게서 신뢰를 잃었으니 결국 두 마리 토끼를 모두 놓친 셈이다.
정치적 여파
찰리 커크의 피살은 정계에 많은 영향을 미치고 있으며, 그 중 블루스카이와 관련이 있는 것을 나열하면 다음과 같다.
대통령 비서실장 스티븐 밀러의 말대로 미국 정부는 커크의 피살을 정적을 탄압할 기회로 활용하고 있으며, 이는 블루스카이가 좌파와 민주당 지지자들[만]을 위한 플랫폼이라는 정치 논객들의 프레이밍 강화로 이어지는 악순환이 된다. 미국 정부가 블루스카이를 '좌편향' 플랫폼으로 인식할수록 블루스카이가 정치 탄압의 표적이 될 확률 역시 높아진다. 이 시나리오가 실제로 발생할 개연성이 얼마나 되는지에 대한 분석은 권위주의 정권에서의 정치적 음모를 잘 아는 전문가에게 맡기겠지만, 내가 보기에는 미국 정부와 이해관계가 일치하는 자들이 '좌편향' 플랫폼을 탄압하라며 압박을 가하고 있는 상황에 블루스카이를 '좌편향' 플랫폼으로 프레이밍하려는 노골적인 압력이 같이 있다는 것 자체가 특기할 만하다.
보수 매체인 페더럴리스트는 한 발짝 더 나아가 민주적인 플랫폼을 탄압해야 한다고 주장하고 있다. 해당 기사에서는 "애플, 아마존, 구글은 2021년 국회의사당 습격에 연루되어 있다는 거짓 의혹을 받은 소셜 미디어 앱 Parler를 플랫폼에서 내렸지만, 디스코드와 블루스카이가 정치적 폭력을 희화화하고 장려하고 있다는 사실에는 침묵하고 있다. 빅테크 과점 체제에 법적 책임이라는 이름의 매가 필요할 때이다."라는 내용을 찾아볼 수 있다.
페더럴리스트는 오늘날 정보 환경에서 권력의 하부 구조를 잘 이해하고 있다. 절대 다수의 사람들은 휴대폰에 설치된 앱을 통해 인터넷에 접속한다. 구글과 애플은 모든 사람들의 휴대폰에 설치될 수 있는 앱과 없는 앱을 통제함으로써 문고리 권력을 톡톡히 누리고 있다. 이 두 기업이 개방 소셜 웹에 접속하는 앱을 양대 스토어에서 거부한다면 블루스카이/AT 프로토콜뿐만 아니라 연합우주/ActivityPub 역시 막을 방법이 없다.
하원 의원 클레이 히긴스는 메타, 유튜브, 틱톡, X, 트루스소셜, 블루스카이의 CEO에게 서한을 보내 "찰리 커크의 정치적 암살을 희화화하는 글 일체를 즉각 삭제할 것, 또한 작성자를 식별해 플랫폼에서 차단하고 새로운 페이지 생성 역시 제재할 것"을 요구하고, 위원회 소속으로서의 권한으로 해당 기업에 이행을 강제할 수 있다는 점 역시 들었다. 이 서한은 명백히 정부에 의한 합법적 표현 검열의 예시로 들 수 있으며, 한편으로는 미국 정부의 구성원이 블루스카이를 사용자의 표현의 자유를 제한해야 할 통제의 대상으로 보고 있다는 점 역시 확인할 수 있다.
회복탄력성이 있는 네트워크를 만들려면
블루스카이가 창립된 것은 빅테크 플랫폼의 역학과 이들의 행동이 사회에 악영향으로 돌아오는 현상이 엔시티피케이션(enshittification)이라는 단어로 설명이 잘 되던 때였다. 이 글에서 사용하는 엔시티피케이션은 코리 닥터로의 원래 설명 그대로 플랫폼이 과점 지위를 악용해 예측 가능한 패턴으로써 가치를 착취하는 것을 말하며, 사용자에게 인센티브를 주어 시장 점유율을 확보하고, 비즈니스 고객을 위해 사용자 경험을 저하시킨 뒤, 결국 네트워크 효과로 록인이 발생하면 확보한 모든 사용자를 쥐어짜는 세 단계로 이루어진다.
빅테크 플랫폼들이 그 어느 때보다도 큰 규모와 권력을 가지고 있지만, 급변하는 환경 속에서 빅테크의 권력은 권위주의 정부와 일치된 이해관계를 만들어냈다. 빅테크 플랫폼에서의 경험이 더 나빠진 요인 역시 여기서 나온다. 빅테크와 미국의 권위주의 정부의 이해관계가 일치하면서 어떤 표현이 허용되고 장려되는지의 경계를 바꾸었다. (가자지구의 집단학살을 다루는 글 등) 좌익으로 취급되는 이슈에 관한 대화는 알고리즘이 밀어내는 한편, 이민자에 대한 노골적인 혐오는 수익 창출에 전혀 문제가 되지 않는다.
이제 블루스카이는 두 가지 문제에 직면해 있다.
블루스카이는 트위터와 비슷하지만 트위터의 고질적인 문제(특히 플랫폼 록인)를 해결한 플랫폼, 그리고 이를 가능케 하는 AT 프로토콜 모두가 핵심이다. 이는 웹사이트의 태그라인인 "소셜 미디어는 소수의 기업에서 통제하기에는 너무나도 중요합니다. [블루스카이는] 우리 모두가 소셜 미디어의 미래를 그릴 수 있도록 소셜 인터넷의 열린 기반을 만들어 나가고 있습니다."에서 특히 잘 드러난다. 블루스카이에서 프로토콜 개발의 중심에 놓은 '신뢰할 수 있는 출구'(credible exit)라는 개념 역시 여기에서 비롯된다. 원한다면 블루스카이를 떠나서 다른 플랫폼으로 갈 수 있어야 한다는 것이다. '출구' 부분은 프로토콜의 인프라 아키텍처로써 구현되며, 실제로 블루스카이를 떠나 다른 플랫폼으로 가는 것이 가능하다. 하지만 '신뢰' 부분은 더 어려운 문제다. 블루스카이는 프로토콜의 2위 플랫폼과 비교해 최소 4자리의 규모 차이가 있기 때문에 집단적인 수준에서는 딱히 신뢰할 수 없는 출구가 된다. 개인 차원의 탈출은 가능하지만, 나머지 생태계는 아직 블루스카이급의 사용자 수와 트래픽을 감당할 수 없다.
엔시티피케이션과 이에 대한 방어책은 회사 측의 유해한 의사결정으로부터 사용자를 보호하는 것이며, 노골적으로 자유롭고 합법적인 표현을 검열하려고 하는 권위주의 정부에 대항할 수 있는 네트워크를 만드는 데는 다른 위협 모델이 필요하다. 하지만 블루스카이는 첫 번째 문제를 해결하는 데만 골몰해 있다. 웹사이트의 설명인 "대중에게는 생동하는 온라인 공간이 필요합니다. 우리는 결코 개인이나 기업에게 팔리지 않는 공간을 만드는 데 전념합니다."에서도 명백하게 블루스카이와 AT 프로토콜이 엔시티피케이션을 예방할 것이라는 점을 다루고, 플랫폼에 대한 정부의 간섭에 대한 언급은 전혀 없다. 트럼프가 재선에 성공한 뒤 9개월 동안 세상에 얼마나 빠르게 바뀌었는지를 생각하면 이 역시 이해할 수 있지만, 페더럴리스트의 주장을 받아들여서 양대 스토어에서 ATmosphere에 접속하는 앱을 내리게 하는 정부에 대항하려면 신뢰할 수 있는 출구를 제공하는 것이 아닌 다른 위협 모델이 필요하다.
2025년에 회복탄력성이 있는 네트워크를 만들려면 엔시티피케이션에 대항하는 것뿐만 아니라 권위주의에도 대항할 수 있는 아키텍처가 필요하다. 블루스카이가 자랑하는 '신뢰할 수 있는 출구'의 인프라는 프로토콜 안에서 다른 플랫폼으로 이동하는 것뿐만 아니라 개방 소셜 생태계 전체의 이해가 앱 장터 및 정부와 충돌하는 경우까지 고려해야 할 것이다. 권위주의 정부와 빅테크 과점 체제가 합심해서 정적의 공간을 파괴한다면, 기술적이든 사회적이든 솔루션은 이 새로운 위협 역시 막아내어야 한다. 유해한 경영 판단뿐만 아니라 조직적인 정치 탄압에도 살아남을 수 있는 인프라를 상상하고 구현할 수 있을지가 우리의 시험대이다. 지금 회복탄력성이 있는 소셜 네트워크를 만든다는 것은 '좌편향' 플랫폼으로 낙인찍힌 앱이 앱 장터에서 내려갈 수 있고, 개방 프로토콜을 유지관리하는 것이 저항 운동이 되는 미래에 대비하는 것이기도 하다.
@jihyeok Thanks for letting me know, and thanks for the offer of support! But money at the moment is not the issue. Unfortunately, I just don't have time at the moment to implement proper monitoring and making the system more resilient. For now, I fixed it manually, so it should work again.
假稱 「Fedify Studio」라는 웹 基盤의 ActivityPub 디버깅 및 開發 道具를 만들어 볼까 생각 中입니다. fedify inbox 커맨드나 ActivityPub.Academy의 強化版 같은 것으로, 액티비티 테스트, 액터 인스펙터, 聯合 이슈 디버거 等을 제대로 된 UI로 提供하는 느낌인데요. ActivityPub 開發者 분들께 需要가 좀 있으려나요?
Thinking about building “#Fedify Studio” (tentative name)—a web-based #ActivityPub debugging & development toolkit, like a supercharged version of ActivityPub.Academy and fedify inbox command. Imagine having a proper UI for testing activities, inspecting actors, debugging federation issues… Would this be useful for other ActivityPub developers out there?
ALT text detailsScreenshot of a context menu opened on a social media post. The context menu shows a lot of menu items, but one of them is the Boost/Quote menu/button which shows both boost count and quote count. It is shown as "44+2".
ALT text detailsScreenshot of a social media post and underneath shows a prominent Boost/Quote button with both boost count and quote count. It is shown as "51+2".
#fediforumfriday: this week I've mostly been working on a side project experimenting with OAuth for decentralized & distributed web; To bootstrap this, rather than writing it all from scratch, I worked on reusing the atproto/oauth-provider package, which provides a LOT of functionality (including user registration & authorisation flows)
The OAuth profile is basically OAuth 2.1 + Client ID Metadata Documents + Pushed Authorization Requests + DPoP binding (prevents token theft) + Protected Resource Metadata (discover the authorization server from the resource)
The cool thing? All the SDKs for AT Proto for implementing OAuth servers & clients should mostly be reusable, easing adoption.
I was also involved in conversations that lead to FEP-8967, which recommends software use Link objects in the attachment's to Objects (i.e, Notes) that the software or publisher wishes to prioritise the display of (rather than parsing out the first link in the content). This would also work for previews for links being federated in the future.
요즘 많은 사람들이 그러하듯이 나 역시 최근에는 LLM과 함께 코딩하는 일이 많아졌다. 내가 LLM과 함께 코딩한다고 말하면 의외라는 듯이 반응하는 사람들도 있고, 어떤 식으로 LLM을 활용하냐는 질문도 종종 받는다. 그래서 생각난 김에 내가 LLM을 코딩에 어떻게 활용하는지를 대략적으로 적어보고자 한다.
전제
당연하지만 내가 LLM을 활용하는 방식은 내가 주로 다루는 종류의 작업에 맞춰져 있다. 따라서 일반적인 다른 코딩에는 잘 맞지 않을 수도 있다. 내가 주로 다루는 작업이란 협업자들이나 소비자들과 주로 서면을 통해 비동기로 의사 소통을 하는 오픈 소스 프로젝트이며, 그것도 주로 애플리케이션 개발이 아닌 라이브러리 개발이다. 주로 사용하는 프로그래밍 언어는 TypeScript로 상당히 LLM이 잘 다루는 축에 속한다. 한편으로는 비교적 기존 지식의 도태가 빠르게 이뤄지는 생태계이기도 해서, 어떤 면에서는 불리한 점도 있다고 볼 수 있다.
어찌 되었든 내 LLM 활용 방식은 내가 주로 다루는 종류의 작업에 맞춰져 있으나, 그럼에도 이 글에서는 일반적인 코딩에 두루 적용할 수 있는 팁을 공유하려고 노력했다.
맥락이 왕이다
LLM 활용에 있어서 모델 자체의 성능 등 여러 고려 사항들이 있지만, 사람들이 LLM을 사용하는 것을 관찰했을 때 가장 흔히 놓치는 것이 충분한 맥락의 제공이다. 사람들은 자신이 무언가를 판단할 때 얼마나 많은 맥락에 의존하는지 의식하지 못한다. 머릿속 사소한 기억 조각부터 내가 접근 가능한 최신 문서들, 이슈에 담긴 캡처 이미지까지… 이들 대부분은 LLM이 기본적으로는 혼자서 접근할 수 없는 경우가 많다. 제아무리 LLM이 똑똑하다고 해도 필요한 맥락이 주어지지 않으면 엉뚱한 결과를 내놓기 마련이다. 주변에서 「LLM은 코딩을 너무 못한다」고 토로하는 경우를 보면 정말로 LLM이 풀기 어려운 문제를 주로 다루는 분들도 계셨지만, 대부분의 경우에는 LLM에게 충분히 맥락을 제공하지 못해서 그럴 때가 많았다.
아마도 이 글에서 다룰 대부분의 이야기는 결국 「어떻게 LLM에게 맥락을 잘 제공할까?」라는 고민에서 나온 팁들이라고 봐도 무방하다.
내가 쓰는 모델과 코딩 에이전트
2025년 9월 현재, 나는 거의 대부분의 작업에 Claude Code를 사용한다. 지난 몇 달 간 Claude Code를 주로 사용해 왔으며, 주기적으로 다른 도구들도 시도해 보고 있으나 여전히 Claude Code가 나에게 가장 맞다고 판단했다. 실은, 나는 대부분의 프로그래머에게 Claude Code가 가장 적합할 거라고 생각한다. 엄밀한 벤치마크에 근거한 것은 아니고, 체감일 따름이지만… 이유는 다음과 같다:
다른 모델들은 도구 호출을 잘 못한다. 도구를 제공하면 필요한 순간에 도구를 활용할 수 있어야 한다. Claude 모델들은 이 부분에서 확실히 뛰어나다. 도구 호출은 풍부한 맥락을 제공하기 위해서는 반드시 필요하기 때문에, 도구 호출의 성능이 떨어지면 결과적으로 LLM을 동반한 코딩 자체의 성과가 떨어진다.
다른 모델들은 질답이 길어질 때 성능이 떨어진다. 적어도 나는 LLM과 코딩할 때 한 방(one-shot)에 결과를 내놓는 방식, 즉 바이브 코딩(vibe coding)을 선호하지 않는다. 따라서 모델의 멀티턴(multi-turn) 성능이 중요한데, 다른 모델들은 질답이 길어짐에 따라 앞서 했던 이야기를 망각하는 경향이 있다.
똑같이 Claude의 모델을 사용하더라도 Claude Code 자체의 성능이 다른 LLM 코딩 에이전트에 비해 뛰어나다. 이건 파인 튜닝이나 시스템 프롬프트 등에 비법 소스가 있기 때문이라고 여겨진다. 이 때문에 Claude Code를 Claude가 아닌 모델과 함께 쓸 수 있게 해주는 비공식 프록시 등도 존재한다.
물론, Claude 및 Claude Code에도 단점이 있다:
상대적으로 문맥 윈도(context window)가 짧다. 그래서 토큰을 아껴야 한다. Claude Code의 대화 압축(conversation compaction)은 그럭저럭 잘 동작하는 편이긴 해도, 여전히 스트레스이긴 하다. (이를테면, 대화 압축은 영어로 이뤄지기 때문에 후속 세션에서는 갑자기 영어로 대답하기 시작한다. 아, 나는 프롬프트를 한국어로 적는다.)
일부 LLM 코딩 에이전트들이 제공하는 LSP 지원이 아직 없다. 따라서 타입 오류나 린트 오류 등을 명령어 실행 등을 통해 따로 보여줄 수 있어야 한다. 대신 Claude Code에서는 훅(hooks) 기능이 제공되므로, 이를 잘 활용하면 어느 정도는 비슷한 효과를 볼 수 있다.
하지만 장점이 단점을 압도하기 때문에 앞으로도 상황에 큰 변화가 없다면 Claude Code를 주로 쓸 것 같다.
세부 지시는 서면으로
지시(prompt)는 세부적일 수록 좋다. 지시가 한 문장으로 끝난다면 좋은 지시가 아닐 가능성이 높다. 때로는 지시를 만드는 지시가 필요하기도 하다. 나의 지시 방식은 다음과 같다.
우선 대부분의 지시는 GitHub 이슈에 작성한다. 필요한 충분한 링크를 제공해야 하고, 가급적이면 캡처 이미지나 도표와 같은 시각적 정보에는 크게 의존하지 않아야 한다. 물론, 이슈는 기본적으로 LLM을 위한 것이 아니라 사람을 위한 것이므로 LLM에게만 필요한 정보는 이슈에 담고 싶지 않을 수 있다. 그런 건 이슈에 담지 않아도 된다.[1] 이미 남이 만든 이슈가 있다면 그 이슈를 활용해도 된다. 남이 만든 이슈에 맥락이 충분하지 않다고 여겨지면, 댓글로 맥락을 보충한다.
때로는 이슈 자체도 LLM으로 작성하기도 한다. 관련 문서나 상황을 충분히 공유하여 이슈를 작성해 달라고 하는 식이다. 예를 들면, 다음은 내가 만든 이메일 전송 라이브러리인 Upyo에 Plunk 트랜스포트를 추가하는 이슈 #11 Plunk transport를 작성하기 위해 사용했던 지시문이다:
Plunk라는 이메일 전송 프로바이더가 있습니다. Plunk의 트랜스포트를 Upyo에 추가하면 좋을 것 같은데요. 이슈 트래커에 일단 이슈를 먼저 만들고자 합니다. 이슈 제목과 내용을 영어로 작성해 주실 수 있을까요? 너무 문제 정의 및 해결책 제시가 구분되는 식의 형식적인 글 대신, 좀 더 사람이 쓴 것 같은 자연스러운 톤으로 부탁드립니다. 너무 길 필요도 없고요. 한두 문단 정도면 충분할 것 같습니다.
정확히는, 나는 이슈 링크를 제공하는 대신 이슈 번호만 제공하고 GitHub MCP를 이용해서 이슈를 직접 읽도록 하는 걸 선호한다. HTML이 아니라 Markdown 형식으로 이슈를 읽기 때문에 본문에 걸린 링크 등을 더 잘 따라가기 때문이다. 링크가 정말 중요한 경우 Claude Code의 지시에서 한 번 더 적기도 한다. 이슈에 미처 적지 못했던 LLM만을 위한 정보도 이 때 모두 적는다.
구현할 때 살펴봐야 할 소스 파일이 무엇인지 잘 알고 있다면, 그런 정보도 함께 제공하면 더 좋다. LLM이 코드베이스를 탐색하느라 삽질을 훨씬 덜 하고, 토큰도 덜 쓰기 때문이다.
나는 GitHub 이슈를 세부 지시를 적는 용도로 썼지만, PLAN.md 같은 문서 파일을 만들어서 거기다 적는 방법도 많이 쓰인다고 알고 있다.
설계는 사람이, 구현은 LLM이
내가 LLM을 코딩에 활용할 때의 기본적인 원칙은 큰 설계는 내 스스로 하고, 세부적인 구현은 LLM에게 맡긴다는 것이다. 지시할 때는 설계 의도를 정확히 제시하고, 구현 과정에서 실수할 수 있을 것 같은 우려점에 대해서 충분히 짚고 넘어간다. 특히, 나는 프로젝트를 처음 시작할 때 디렉터리나 패키지 구조를 여전히 직접 손으로 할 때가 많다. (하지만 이 부분은 내가 원체 LLM 시대 이전부터 쿠키커터 류의 프로젝트 템플릿도 좋아하지 않았기 때문일 수도 있다. 템플릿을 쓰든 LLM을 쓰든 내 마음에 들게 나오지 않기에.)
LLM은 자신이 가장 익숙한 기술로 문제를 해결하려는 경향이 있기 때문에, 기술 선택에 있어서도 명시적으로 지시를 하는 것이 좋다. 아직은 사소한 라이브러리 하나조차도 사람이 검토할 필요가 있다. LLM에게 모든 것을 맡기다 보면 보안 패치도 안 된 옛날 버전을 가져다 쓰거나 하는 일이 흔하기 때문이다. 나 같은 경우에는 후술할 AGENTS.md 문서에서 라이브러리를 설치하기 전에는 npm view 명령어를 통해 해당 패키지의 최신 버전이 무엇인지 먼저 확인하라는 지시를 포함시키기도 한다.
추상화를 할 때도, 적어도 API 설계는 여전히 내가 직접할 때가 많다. 어째서일까, LLM이 설계한 API는 아직은 별로일 때가 많다. 내가 받은 인상은, LLM은 구현해 나가며 필요할 때 API를 즉석(ad-hoc)에서 설계할 때가 잦다는 것이다. 물론, 사람이라도 이런 방식을 선호할 수 있는데, 그런 경우에는 LLM이 설계한 API에 불만이 없을지도 모른다. 하지만 적어도 내 경우에는 불만족스러울 때가 많다.
결국에는 LLM을 만능 노예가 아니라 똑똑하기도 하지만 미숙한 점도 많은 동료로 보고 LLM이 서툰 부분에는 최대한 사람이 도와서 일을 해낸다는 관점이 필요한 것 같다.
AGENTS.md
대부분의 LLM 코딩 에이전트들은 AGENTS.md 내지는 그에 준하는 기능을 제공하고 있다. 예를 들어 Claude Code는 CLAUDE.md 파일을 바라보며, Gemini CLI는 GEMINI.md를 바라보는 식인데, 점차 AGENTS.md 파일로 표준화되고 있는 추세이다. 나는 특정 벤더에서만 쓰는 파일들을 모조리 AGENTS.md로 심볼릭 링크를 건 다음 AGENTS.md 파일만을 정본으로 삼게 하고 있다. 이렇게 하면 나와 다른 LLM 코딩 에이전트를 사용하는 협업자들과 같은 지침을 공유할 수 있다.
아무튼, AGENTS.md 문서의 역할은 간단하다. 이 프로젝트에 대한 지침, 즉 시스템 프롬프트이다. 대부분의 LLM 코딩 에이전트들은 이 파일을 자동으로 생성하는 기능을 제공하는데, 안 쓸 이유는 없다. 자동으로 생성하게 한 후, 잘못된 부분만 고쳐서 써도 된다. 그보다 더 중요한 건 시간이 흐르면서 AGENTS.md 문서가 낡게 되는 것을 피하는 것이다. AGENTS.md 문서는 꾸준히 갈고 닦아야 한다. 특히, 대규모 리팩터링이 있거나 한 뒤에는 반드시 AGENTS.md 문서를 갱신해야 한다. 이 지시 자체도 AGENTS.md 문서에 넣어두는 게 좋다.
그러면 AGENTS.md 문서에는 어떤 내용을 넣을까? 나의 경우에는 다음과 같은 내용을 넣는다:
프로젝트의 목표와 개요. 저장소 URL을 적어두는 것도 의외로 GitHub MCP 등을 활용할 때 쓸모가 있다.
프로젝트가 사용하는 개발 도구. 예를 들어 npm은 절대 쓰지 않으며 pnpm만 쓴다는 식의 지시를 포함한다.
디렉터리 구조와 각 디렉터리의 역할.
빌드 및 테스트 방법. 특히, 그 프로젝트만의 특수한 절차가 있다면 반드시 기술한다. 예를 들어, 빌드나 테스트 전에 반드시 코드 생성을 해야 한다면, 이에 관해 적어야 한다—물론, 가장 좋은 것은 빌드 스크립트로 그러한 절차를 자동화하는 것이다. 그 편이 사람에게도 좋고, 토큰을 아끼는 데에도 좋다.
코딩 스타일이나 문서 스타일. 포매터를 쓰는 방법을 적는 것도 좋다.
개발 방법론. 이를테면 버그를 고칠 때는 회귀 테스트를 먼저 작성하고, 테스트가 실패하는 것으로 버그가 재현되는 것을 확인한 다음에 버그 수정을 하라는 지침 같은 것들.
일단은 위와 같이 시작하고, LLM 코딩 에이전트를 활용하면서 눈에 밟히는 실수들을 LLM이 할 때마다 지침을 추가하는 것을 권한다. 예를 들어, 나는 TypeScript 프로젝트에서 any 타입이나 as 키워드를 피하라는 지침을 추가하는 편이다.
LLM에 지식 컷오프가 있다는 건 잘 알려져 있다. 방금 갓 나온 모델이 아닌 한, 내가 쓰는 라이브러리나 런타임 등의 API, CLI 도구 등에 대해 다소 낡은 지식을 가지고 있을 가능성이 높다는 뜻이다. 게다가 만약 비주류 프로그래밍 언어나 프레임워크 등을 쓰고 있다면 이 문제는 더욱 커진다.
따라서 내가 사용하는 프로그래밍 언어나 프레임워크 등에 대한 지식을 제공해야 하는데, 가장 쉽고 효율적인 방법은 Context7을 MCP로 붙이는 것이다. Context7은 다양한 기술 문서를 비교적 최신판으로 유지하면서 벡터 데이터베이스에 색인하고, LLM이 요청할 경우 관련된 문서 조각을 제공하는 RAG 서비스이다. 새로운 문서를 추가하는 것도 쉬워서, 만약 내가 필요한 문서가 등록되어 있지 않다면 얼마든지 새로 추가해서 사용할 수도 있다. 다만, 특별히 지시하지 않는 한 Context7을 따로 활용하지 않을 때도 있기 때문에, 「Context7 MCP를 통해 관련 문서를 확인해 보라」는 식의 지시가 필요할 수 있다.
RFC 같은 기술 명세 문서를 제공할 때는 평문(plain text) 형식이 제공되므로 평문 문서의 링크를 제공하는 게 좋다. 나의 경우 연합우주(fediverse) 관련 개발을 많이 하다 보니 FEP 문서를 제공해야 할 일이 많은데, 이 때도 HTML으로 렌더링 된 웹 페이지가 아닌 Markdown 소스 파일의 링크를 직접 제공하는 식으로 사용하고 있다.
이 외에도 웹사이트에서 /llms.txt 및 /llms-full.txt 파일을 제공하는 관행이 퍼지고 있으므로, 이를 활용하는 것도 좋다. (내가 만든 소프트웨어 라이브러리들의 경우 프로젝트 웹사이트에서 모두 /llms.txt 및 /llms-full.txt 파일을 제공하고 있다.)
다만 아무리 LLM에게 친화적인 평문이라고 해도 기술 문서 전체를 다 제공하는 건 아무래도 토큰 낭비가 심하기 때문에, Context7을 쓸 수 있다면 Context7을 쓰는 것을 추천한다.
계획 모드의 활용
Claude Code를 포함해 최근의 많은 LLM 코딩 에이전트는 계획 모드를 제공한다. 냅다 구현하는 것을 방지하고, 구현 계획을 LLM 스스로 세우게 한 뒤 사람이 먼저 검토할 수 있게 하는 것이다. 특히, 나는 계획 모드에서는 비싼 Claude Opus 4.1을 사용하고 실제 구현에서는 비교적 저렴한 Claude Sonnet 4를 사용하는 “Opus Plan Mode”를 사용하고 있다.[3]
나는 계획을 면밀히 검토하고 조금이라도 내 성에 차지 않으면 얼마든지 계획 수정을 요구한다. 작업에 따라 다르지만, 어떤 작업이든 적어도 서너 번 이상은 수정을 요구하는 것 같다. 반대로 얘기하면, 이 정도로 계획을 다듬지 않으면 내가 원하는 방향으로 구현하지 않을 가능성이 높다. LLM은 나와는 다른 전제를 품을 때가 많아서, 여러 세부 계획에서 나와는 동상이몽을 하고 있을 가능성이 높다. 그런 것들을 사전에 최대한 제거하여 내 의도에 일치시켜야 한다.
알아서 피드백 루프를 돌게
LLM 코딩 에이전트로 개발을 할 때 가장 중요하다고 여겨지는 부분은 바로, 스스로 웬만큼 방향을 조정할 수 있도록 여건을 마련하는 일이다. LLM의 각종 구현 실수를 하나하나 내가 지적하는 게 아니라, 각종 자동화된 테스트와 정적 분석을 통해 스스로 깨닫고 구현을 고칠 수 있도록 해주는 것이다.
예를 들어, CSS 버그를 고칠 때를 생각해 보자. LLM이 CSS 코드를 고치게 한 뒤, 내가 웹 브라우저를 확인하는 방식은 너무 번거롭다. 대신, Playwright MCP를 붙여서 스스로 화면을 볼 수 있게 하는 게 낫다. 요는, LLM의 작업 결과가 요구 사항을 충족하는지를 스스로 판단할 수 있게 하여, 요구 사항이 충족될 때까지 작업을 계속하게 만드는 것이다.
비슷한 이유에서, 구현하기에 앞서 테스트 코드를 먼저 작성하도록 지시하는 것이 여러모로 편하다. 테스트 코드를 작성하는 과정까지만 사람이 지켜보면 되고, 그 뒤는 상대적으로 신경을 덜 써도 되기 때문이다. 실은, 나는 LLM 코딩 에이전트를 활용할 때도 가끔은 테스트를 직접 짜기도 한다. 프롬프트로 요구 사항을 정확하게 검증하는 테스트 코드를 짜게 하는 것보다 내가 직접 테스트 코드를 짜는 게 빠르겠다고 느낄 때 그렇다.
이런 작업 흐름을 선호하다 보니, 좀 더 엄밀한 타입 시스템을 갖춘 프로그래밍 언어, 좀 더 엄격한 린트 규칙 등이 LLM 코딩 에이전트를 활용할 때 훨씬 유리하다고 생각하게 되었다. LLM 시대 이전에도 생각은 비슷하긴 했지만 말이다.
가끔은 손 코딩
하지만 여전히 LLM에 많은 한계점이 있기 때문에, 나는 아직도 가끔은 손 코딩을 한다. API를 설계할 때도 그렇고, 엄밀한 테스트 코드를 짜고 싶을 때도 그렇다. (LLM은 테스트 코드를 좀 대충 짜는 경향이 있다.) 그리고 무엇보다, 재밌을 것 같은 코딩은 내가 한다!
바이브 코딩에 깊게 심취했다가 코딩의 재미가 사라졌다는 소프트웨어 프로그래머들의 얘기를 종종 듣는다. 내 생각에는, 재미있는 부분은 LLM에게 시키지 않는 게 좋다. 결과의 품질 때문이 아니라, 소프트웨어 프로그래머로서 모티베이션을 유지하기 위해서 그렇다. 재미 없고 지루한 부분, 그러니까 코딩하기 싫어지게 하는 작업에서 최대한 LLM을 활용하는 것이 LLM과 공존하는 좋은 전략이 아닐까 생각한다. 뭐, 적어도 내게는 이 방식이 잘 먹히는 것 같다.
이건 한 가지 팁인데, LLM에게만 필요한 정보를 <!-- … --> 주석 안에 적는 방법도 있다. ↩︎
요즘 많은 사람들이 그러하듯이 나 역시 최근에는 LLM과 함께 코딩하는 일이 많아졌다. 내가 LLM과 함께 코딩한다고 말하면 의외라는 듯이 반응하는 사람들도 있고, 어떤 식으로 LLM을 활용하냐는 질문도 종종 받는다. 그래서 생각난 김에 내가 LLM을 코딩에 어떻게 활용하는지를 대략적으로 적어보고자 한다.
전제
당연하지만 내가 LLM을 활용하는 방식은 내가 주로 다루는 종류의 작업에 맞춰져 있다. 따라서 일반적인 다른 코딩에는 잘 맞지 않을 수도 있다. 내가 주로 다루는 작업이란 협업자들이나 소비자들과 주로 서면을 통해 비동기로 의사 소통을 하는 오픈 소스 프로젝트이며, 그것도 주로 애플리케이션 개발이 아닌 라이브러리 개발이다. 주로 사용하는 프로그래밍 언어는 TypeScript로 상당히 LLM이 잘 다루는 축에 속한다. 한편으로는 비교적 기존 지식의 도태가 빠르게 이뤄지는 생태계이기도 해서, 어떤 면에서는 불리한 점도 있다고 볼 수 있다.
어찌 되었든 내 LLM 활용 방식은 내가 주로 다루는 종류의 작업에 맞춰져 있으나, 그럼에도 이 글에서는 일반적인 코딩에 두루 적용할 수 있는 팁을 공유하려고 노력했다.
맥락이 왕이다
LLM 활용에 있어서 모델 자체의 성능 등 여러 고려 사항들이 있지만, 사람들이 LLM을 사용하는 것을 관찰했을 때 가장 흔히 놓치는 것이 충분한 맥락의 제공이다. 사람들은 자신이 무언가를 판단할 때 얼마나 많은 맥락에 의존하는지 의식하지 못한다. 머릿속 사소한 기억 조각부터 내가 접근 가능한 최신 문서들, 이슈에 담긴 캡처 이미지까지… 이들 대부분은 LLM이 기본적으로는 혼자서 접근할 수 없는 경우가 많다. 제아무리 LLM이 똑똑하다고 해도 필요한 맥락이 주어지지 않으면 엉뚱한 결과를 내놓기 마련이다. 주변에서 「LLM은 코딩을 너무 못한다」고 토로하는 경우를 보면 정말로 LLM이 풀기 어려운 문제를 주로 다루는 분들도 계셨지만, 대부분의 경우에는 LLM에게 충분히 맥락을 제공하지 못해서 그럴 때가 많았다.
아마도 이 글에서 다룰 대부분의 이야기는 결국 「어떻게 LLM에게 맥락을 잘 제공할까?」라는 고민에서 나온 팁들이라고 봐도 무방하다.
내가 쓰는 모델과 코딩 에이전트
2025년 9월 현재, 나는 거의 대부분의 작업에 Claude Code를 사용한다. 지난 몇 달 간 Claude Code를 주로 사용해 왔으며, 주기적으로 다른 도구들도 시도해 보고 있으나 여전히 Claude Code가 나에게 가장 맞다고 판단했다. 실은, 나는 대부분의 프로그래머에게 Claude Code가 가장 적합할 거라고 생각한다. 엄밀한 벤치마크에 근거한 것은 아니고, 체감일 따름이지만… 이유는 다음과 같다:
다른 모델들은 도구 호출을 잘 못한다. 도구를 제공하면 필요한 순간에 도구를 활용할 수 있어야 한다. Claude 모델들은 이 부분에서 확실히 뛰어나다. 도구 호출은 풍부한 맥락을 제공하기 위해서는 반드시 필요하기 때문에, 도구 호출의 성능이 떨어지면 결과적으로 LLM을 동반한 코딩 자체의 성과가 떨어진다.
다른 모델들은 질답이 길어질 때 성능이 떨어진다. 적어도 나는 LLM과 코딩할 때 한 방(one-shot)에 결과를 내놓는 방식, 즉 바이브 코딩(vibe coding)을 선호하지 않는다. 따라서 모델의 멀티턴(multi-turn) 성능이 중요한데, 다른 모델들은 질답이 길어짐에 따라 앞서 했던 이야기를 망각하는 경향이 있다.
똑같이 Claude의 모델을 사용하더라도 Claude Code 자체의 성능이 다른 LLM 코딩 에이전트에 비해 뛰어나다. 이건 파인 튜닝이나 시스템 프롬프트 등에 비법 소스가 있기 때문이라고 여겨진다. 이 때문에 Claude Code를 Claude가 아닌 모델과 함께 쓸 수 있게 해주는 비공식 프록시 등도 존재한다.
물론, Claude 및 Claude Code에도 단점이 있다:
상대적으로 문맥 윈도(context window)가 짧다. 그래서 토큰을 아껴야 한다. Claude Code의 대화 압축(conversation compaction)은 그럭저럭 잘 동작하는 편이긴 해도, 여전히 스트레스이긴 하다. (이를테면, 대화 압축은 영어로 이뤄지기 때문에 후속 세션에서는 갑자기 영어로 대답하기 시작한다. 아, 나는 프롬프트를 한국어로 적는다.)
일부 LLM 코딩 에이전트들이 제공하는 LSP 지원이 아직 없다. 따라서 타입 오류나 린트 오류 등을 명령어 실행 등을 통해 따로 보여줄 수 있어야 한다. 대신 Claude Code에서는 훅(hooks) 기능이 제공되므로, 이를 잘 활용하면 어느 정도는 비슷한 효과를 볼 수 있다.
하지만 장점이 단점을 압도하기 때문에 앞으로도 상황에 큰 변화가 없다면 Claude Code를 주로 쓸 것 같다.
세부 지시는 서면으로
지시(prompt)는 세부적일 수록 좋다. 지시가 한 문장으로 끝난다면 좋은 지시가 아닐 가능성이 높다. 때로는 지시를 만드는 지시가 필요하기도 하다. 나의 지시 방식은 다음과 같다.
우선 대부분의 지시는 GitHub 이슈에 작성한다. 필요한 충분한 링크를 제공해야 하고, 가급적이면 캡처 이미지나 도표와 같은 시각적 정보에는 크게 의존하지 않아야 한다. 물론, 이슈는 기본적으로 LLM을 위한 것이 아니라 사람을 위한 것이므로 LLM에게만 필요한 정보는 이슈에 담고 싶지 않을 수 있다. 그런 건 이슈에 담지 않아도 된다.[1] 이미 남이 만든 이슈가 있다면 그 이슈를 활용해도 된다. 남이 만든 이슈에 맥락이 충분하지 않다고 여겨지면, 댓글로 맥락을 보충한다.
때로는 이슈 자체도 LLM으로 작성하기도 한다. 관련 문서나 상황을 충분히 공유하여 이슈를 작성해 달라고 하는 식이다. 예를 들면, 다음은 내가 만든 이메일 전송 라이브러리인 Upyo에 Plunk 트랜스포트를 추가하는 이슈 #11 Plunk transport를 작성하기 위해 사용했던 지시문이다:
Plunk라는 이메일 전송 프로바이더가 있습니다. Plunk의 트랜스포트를 Upyo에 추가하면 좋을 것 같은데요. 이슈 트래커에 일단 이슈를 먼저 만들고자 합니다. 이슈 제목과 내용을 영어로 작성해 주실 수 있을까요? 너무 문제 정의 및 해결책 제시가 구분되는 식의 형식적인 글 대신, 좀 더 사람이 쓴 것 같은 자연스러운 톤으로 부탁드립니다. 너무 길 필요도 없고요. 한두 문단 정도면 충분할 것 같습니다.
정확히는, 나는 이슈 링크를 제공하는 대신 이슈 번호만 제공하고 GitHub MCP를 이용해서 이슈를 직접 읽도록 하는 걸 선호한다. HTML이 아니라 Markdown 형식으로 이슈를 읽기 때문에 본문에 걸린 링크 등을 더 잘 따라가기 때문이다. 링크가 정말 중요한 경우 Claude Code의 지시에서 한 번 더 적기도 한다. 이슈에 미처 적지 못했던 LLM만을 위한 정보도 이 때 모두 적는다.
구현할 때 살펴봐야 할 소스 파일이 무엇인지 잘 알고 있다면, 그런 정보도 함께 제공하면 더 좋다. LLM이 코드베이스를 탐색하느라 삽질을 훨씬 덜 하고, 토큰도 덜 쓰기 때문이다.
나는 GitHub 이슈를 세부 지시를 적는 용도로 썼지만, PLAN.md 같은 문서 파일을 만들어서 거기다 적는 방법도 많이 쓰인다고 알고 있다.
설계는 사람이, 구현은 LLM이
내가 LLM을 코딩에 활용할 때의 기본적인 원칙은 큰 설계는 내 스스로 하고, 세부적인 구현은 LLM에게 맡긴다는 것이다. 지시할 때는 설계 의도를 정확히 제시하고, 구현 과정에서 실수할 수 있을 것 같은 우려점에 대해서 충분히 짚고 넘어간다. 특히, 나는 프로젝트를 처음 시작할 때 디렉터리나 패키지 구조를 여전히 직접 손으로 할 때가 많다. (하지만 이 부분은 내가 원체 LLM 시대 이전부터 쿠키커터 류의 프로젝트 템플릿도 좋아하지 않았기 때문일 수도 있다. 템플릿을 쓰든 LLM을 쓰든 내 마음에 들게 나오지 않기에.)
LLM은 자신이 가장 익숙한 기술로 문제를 해결하려는 경향이 있기 때문에, 기술 선택에 있어서도 명시적으로 지시를 하는 것이 좋다. 아직은 사소한 라이브러리 하나조차도 사람이 검토할 필요가 있다. LLM에게 모든 것을 맡기다 보면 보안 패치도 안 된 옛날 버전을 가져다 쓰거나 하는 일이 흔하기 때문이다. 나 같은 경우에는 후술할 AGENTS.md 문서에서 라이브러리를 설치하기 전에는 npm view 명령어를 통해 해당 패키지의 최신 버전이 무엇인지 먼저 확인하라는 지시를 포함시키기도 한다.
추상화를 할 때도, 적어도 API 설계는 여전히 내가 직접할 때가 많다. 어째서일까, LLM이 설계한 API는 아직은 별로일 때가 많다. 내가 받은 인상은, LLM은 구현해 나가며 필요할 때 API를 즉석(ad-hoc)에서 설계할 때가 잦다는 것이다. 물론, 사람이라도 이런 방식을 선호할 수 있는데, 그런 경우에는 LLM이 설계한 API에 불만이 없을지도 모른다. 하지만 적어도 내 경우에는 불만족스러울 때가 많다.
결국에는 LLM을 만능 노예가 아니라 똑똑하기도 하지만 미숙한 점도 많은 동료로 보고 LLM이 서툰 부분에는 최대한 사람이 도와서 일을 해낸다는 관점이 필요한 것 같다.
AGENTS.md
대부분의 LLM 코딩 에이전트들은 AGENTS.md 내지는 그에 준하는 기능을 제공하고 있다. 예를 들어 Claude Code는 CLAUDE.md 파일을 바라보며, Gemini CLI는 GEMINI.md를 바라보는 식인데, 점차 AGENTS.md 파일로 표준화되고 있는 추세이다. 나는 특정 벤더에서만 쓰는 파일들을 모조리 AGENTS.md로 심볼릭 링크를 건 다음 AGENTS.md 파일만을 정본으로 삼게 하고 있다. 이렇게 하면 나와 다른 LLM 코딩 에이전트를 사용하는 협업자들과 같은 지침을 공유할 수 있다.
아무튼, AGENTS.md 문서의 역할은 간단하다. 이 프로젝트에 대한 지침, 즉 시스템 프롬프트이다. 대부분의 LLM 코딩 에이전트들은 이 파일을 자동으로 생성하는 기능을 제공하는데, 안 쓸 이유는 없다. 자동으로 생성하게 한 후, 잘못된 부분만 고쳐서 써도 된다. 그보다 더 중요한 건 시간이 흐르면서 AGENTS.md 문서가 낡게 되는 것을 피하는 것이다. AGENTS.md 문서는 꾸준히 갈고 닦아야 한다. 특히, 대규모 리팩터링이 있거나 한 뒤에는 반드시 AGENTS.md 문서를 갱신해야 한다. 이 지시 자체도 AGENTS.md 문서에 넣어두는 게 좋다.
그러면 AGENTS.md 문서에는 어떤 내용을 넣을까? 나의 경우에는 다음과 같은 내용을 넣는다:
프로젝트의 목표와 개요. 저장소 URL을 적어두는 것도 의외로 GitHub MCP 등을 활용할 때 쓸모가 있다.
프로젝트가 사용하는 개발 도구. 예를 들어 npm은 절대 쓰지 않으며 pnpm만 쓴다는 식의 지시를 포함한다.
디렉터리 구조와 각 디렉터리의 역할.
빌드 및 테스트 방법. 특히, 그 프로젝트만의 특수한 절차가 있다면 반드시 기술한다. 예를 들어, 빌드나 테스트 전에 반드시 코드 생성을 해야 한다면, 이에 관해 적어야 한다—물론, 가장 좋은 것은 빌드 스크립트로 그러한 절차를 자동화하는 것이다. 그 편이 사람에게도 좋고, 토큰을 아끼는 데에도 좋다.
코딩 스타일이나 문서 스타일. 포매터를 쓰는 방법을 적는 것도 좋다.
개발 방법론. 이를테면 버그를 고칠 때는 회귀 테스트를 먼저 작성하고, 테스트가 실패하는 것으로 버그가 재현되는 것을 확인한 다음에 버그 수정을 하라는 지침 같은 것들.
일단은 위와 같이 시작하고, LLM 코딩 에이전트를 활용하면서 눈에 밟히는 실수들을 LLM이 할 때마다 지침을 추가하는 것을 권한다. 예를 들어, 나는 TypeScript 프로젝트에서 any 타입이나 as 키워드를 피하라는 지침을 추가하는 편이다.
LLM에 지식 컷오프가 있다는 건 잘 알려져 있다. 방금 갓 나온 모델이 아닌 한, 내가 쓰는 라이브러리나 런타임 등의 API, CLI 도구 등에 대해 다소 낡은 지식을 가지고 있을 가능성이 높다는 뜻이다. 게다가 만약 비주류 프로그래밍 언어나 프레임워크 등을 쓰고 있다면 이 문제는 더욱 커진다.
따라서 내가 사용하는 프로그래밍 언어나 프레임워크 등에 대한 지식을 제공해야 하는데, 가장 쉽고 효율적인 방법은 Context7을 MCP로 붙이는 것이다. Context7은 다양한 기술 문서를 비교적 최신판으로 유지하면서 벡터 데이터베이스에 색인하고, LLM이 요청할 경우 관련된 문서 조각을 제공하는 RAG 서비스이다. 새로운 문서를 추가하는 것도 쉬워서, 만약 내가 필요한 문서가 등록되어 있지 않다면 얼마든지 새로 추가해서 사용할 수도 있다. 다만, 특별히 지시하지 않는 한 Context7을 따로 활용하지 않을 때도 있기 때문에, 「Context7 MCP를 통해 관련 문서를 확인해 보라」는 식의 지시가 필요할 수 있다.
RFC 같은 기술 명세 문서를 제공할 때는 평문(plain text) 형식이 제공되므로 평문 문서의 링크를 제공하는 게 좋다. 나의 경우 연합우주(fediverse) 관련 개발을 많이 하다 보니 FEP 문서를 제공해야 할 일이 많은데, 이 때도 HTML으로 렌더링 된 웹 페이지가 아닌 Markdown 소스 파일의 링크를 직접 제공하는 식으로 사용하고 있다.
이 외에도 웹사이트에서 /llms.txt 및 /llms-full.txt 파일을 제공하는 관행이 퍼지고 있으므로, 이를 활용하는 것도 좋다. (내가 만든 소프트웨어 라이브러리들의 경우 프로젝트 웹사이트에서 모두 /llms.txt 및 /llms-full.txt 파일을 제공하고 있다.)
다만 아무리 LLM에게 친화적인 평문이라고 해도 기술 문서 전체를 다 제공하는 건 아무래도 토큰 낭비가 심하기 때문에, Context7을 쓸 수 있다면 Context7을 쓰는 것을 추천한다.
계획 모드의 활용
Claude Code를 포함해 최근의 많은 LLM 코딩 에이전트는 계획 모드를 제공한다. 냅다 구현하는 것을 방지하고, 구현 계획을 LLM 스스로 세우게 한 뒤 사람이 먼저 검토할 수 있게 하는 것이다. 특히, 나는 계획 모드에서는 비싼 Claude Opus 4.1을 사용하고 실제 구현에서는 비교적 저렴한 Claude Sonnet 4를 사용하는 “Opus Plan Mode”를 사용하고 있다.[3]
나는 계획을 면밀히 검토하고 조금이라도 내 성에 차지 않으면 얼마든지 계획 수정을 요구한다. 작업에 따라 다르지만, 어떤 작업이든 적어도 서너 번 이상은 수정을 요구하는 것 같다. 반대로 얘기하면, 이 정도로 계획을 다듬지 않으면 내가 원하는 방향으로 구현하지 않을 가능성이 높다. LLM은 나와는 다른 전제를 품을 때가 많아서, 여러 세부 계획에서 나와는 동상이몽을 하고 있을 가능성이 높다. 그런 것들을 사전에 최대한 제거하여 내 의도에 일치시켜야 한다.
알아서 피드백 루프를 돌게
LLM 코딩 에이전트로 개발을 할 때 가장 중요하다고 여겨지는 부분은 바로, 스스로 웬만큼 방향을 조정할 수 있도록 여건을 마련하는 일이다. LLM의 각종 구현 실수를 하나하나 내가 지적하는 게 아니라, 각종 자동화된 테스트와 정적 분석을 통해 스스로 깨닫고 구현을 고칠 수 있도록 해주는 것이다.
예를 들어, CSS 버그를 고칠 때를 생각해 보자. LLM이 CSS 코드를 고치게 한 뒤, 내가 웹 브라우저를 확인하는 방식은 너무 번거롭다. 대신, Playwright MCP를 붙여서 스스로 화면을 볼 수 있게 하는 게 낫다. 요는, LLM의 작업 결과가 요구 사항을 충족하는지를 스스로 판단할 수 있게 하여, 요구 사항이 충족될 때까지 작업을 계속하게 만드는 것이다.
비슷한 이유에서, 구현하기에 앞서 테스트 코드를 먼저 작성하도록 지시하는 것이 여러모로 편하다. 테스트 코드를 작성하는 과정까지만 사람이 지켜보면 되고, 그 뒤는 상대적으로 신경을 덜 써도 되기 때문이다. 실은, 나는 LLM 코딩 에이전트를 활용할 때도 가끔은 테스트를 직접 짜기도 한다. 프롬프트로 요구 사항을 정확하게 검증하는 테스트 코드를 짜게 하는 것보다 내가 직접 테스트 코드를 짜는 게 빠르겠다고 느낄 때 그렇다.
이런 작업 흐름을 선호하다 보니, 좀 더 엄밀한 타입 시스템을 갖춘 프로그래밍 언어, 좀 더 엄격한 린트 규칙 등이 LLM 코딩 에이전트를 활용할 때 훨씬 유리하다고 생각하게 되었다. LLM 시대 이전에도 생각은 비슷하긴 했지만 말이다.
가끔은 손 코딩
하지만 여전히 LLM에 많은 한계점이 있기 때문에, 나는 아직도 가끔은 손 코딩을 한다. API를 설계할 때도 그렇고, 엄밀한 테스트 코드를 짜고 싶을 때도 그렇다. (LLM은 테스트 코드를 좀 대충 짜는 경향이 있다.) 그리고 무엇보다, 재밌을 것 같은 코딩은 내가 한다!
바이브 코딩에 깊게 심취했다가 코딩의 재미가 사라졌다는 소프트웨어 프로그래머들의 얘기를 종종 듣는다. 내 생각에는, 재미있는 부분은 LLM에게 시키지 않는 게 좋다. 결과의 품질 때문이 아니라, 소프트웨어 프로그래머로서 모티베이션을 유지하기 위해서 그렇다. 재미 없고 지루한 부분, 그러니까 코딩하기 싫어지게 하는 작업에서 최대한 LLM을 활용하는 것이 LLM과 공존하는 좋은 전략이 아닐까 생각한다. 뭐, 적어도 내게는 이 방식이 잘 먹히는 것 같다.
이건 한 가지 팁인데, LLM에게만 필요한 정보를 <!-- … --> 주석 안에 적는 방법도 있다. ↩︎
ALT text detailsApp Store の更新画面のスクリーンショット。「辞書 by 物書堂」「前回のアップデートでは、皆さまと共に 17 年にわたり創り上げてきた UI を台無しにしてしまい本当に申し訳ありませんでした。今回のアップデートでは以前の UI を改良したものにいたしました。今後はこの UI に対して不用意に手を入れないようにいたします。申し訳ありませんでした。」
Composing: - Only can embed quote post by pressing Quote button/menu? - How about pasting post link in composer? Immediately resolve to quote post or ask user if want to embed? What if there's already a quote post embeded while pasting a post link? 🤪 - After embed, can remove? (Mastodon web shows “x” button). Then how to add back or undo?
Rendering: - For official Mastodon web & apps, links to posts will still open web view instead of native view. They don’t unfurl. - Do we stop rendering non-native quote posts if the post contains a native quote post? Or render both? How to (visually?) differentiate native vs non-native? - Is quotes count separated from boost count? Mastodon web sums them up when shown on timeline, separate them on post page.
となっていたが 1 日で戻っていてちょっと笑った。誠実ｗ
