별고래의 항해일지

[태그:] AI협업

  • 깃허브 오픈소스 도구 고르는 기준 — 별점 8만짜리도 안 골랐다

    요약 — 먼저 결론

    깃허브에서 비슷한 도구 4개를 두고 고민했다. 결국 하나만 골랐다.

    재밌는 건 안 고른 이유다. 별점 8만짜리도 뺐고, 라이선스 배지를 믿었다가 틀리기도 했다.

    결론부터. 별점은 인기지 내 상황에 맞는다는 뜻이 아니다. 그리고 배지 하나도 곧이곧대로 믿으면 안 된다 — 내가 그렇게 틀렸으니까.

    별점은 인기지 ‘fit’이 아니다

    가장 별이 많은 걸 골랐을까? 아니다. 별점 8만이 넘는 도구를 안 골랐다.

    그건 멀티에이전트 트레이딩 프레임워크였다(TradingAgents, 별 8만4천). 강력하다. 그런데 실거래는 진짜 돈이 걸리고, 지금 내게 필요한 게 아니었다.

    별점은 마치 식당 리뷰 수와 같다. 리뷰가 5만 개라고 내 입맛에 맞는 건 아니다. 별점은 ‘남들이 많이 본다’는 신호지, ‘나한테 맞다’는 보장이 아니다.

    배지를 믿었다가 틀렸다 — 라이선스 이야기

    여기서 내가 한 번 틀렸다. 정직하게 적는다.

    나는 한 금융 터미널(FinceptTerminal)을 “라이선스 함정(AGPL)”이라고 메모해 뒀다. 그런데 직접 확인해 보니 AGPL이 아니었다. 깃허브가 표준 라이선스로 인식 못 하는 NOASSERTION 상태였다.

    NOASSERTION은 “나쁘다”가 아니다. “성분표가 표준이 아니니 직접 까보라”는 뜻이다. 실제로 앤트로픽이 낸 보안 도구(defending-harness)도 똑같이 NOASSERTION이었다.

    라이선스 배지 하나로 판단하면 틀린다. 포장지만 보고 멀쩡한 걸 함정이라 부를 뻔했다. 배지는 직접 읽기 전까지 가설일 뿐이다.

    그래서 기준은 “좋냐”가 아니라 “맞냐”

    좋은 도구를 찾는 게 아니다. 내 스택·필요·리스크에 맞는 도구를 찾는 거다.

    도구 별점 라이선스 고른/안 고른 이유
    HyperFrames 2만6천 Apache-2.0 ✅ 골랐다 — 블로그를 영상으로, 바로 씀
    TradingAgents 8만4천 Apache-2.0 실거래 리스크 + 지금 필요 아님 → 보류
    FinceptTerminal 2만6천 NOASSERTION 라이선스 직접 읽어야 + C++(내 스택 아님) + 통째 앱인데 조각만 필요
    defending-harness 5천 NOASSERTION 좋지만 ‘직접 커스텀하는 참고용’이라 즉시 적용 아님

    전부 좋은 도구다. 다만 나한테 지금 맞는 건 하나였다.

    “다 좋다”고 하면 의심하라

    이 평가를 처음엔 AI 조수에게 맡겼다. 그랬더니 네 개를 다 좋게 말했다.

    내가 물었다. “전부 적용할 점이 있다는 거야?” 그제야 솔직한 순위가 나왔다.

    누구든 — AI든 리뷰어든 — 평가를 맡기면 띄우는 쪽으로 기운다. 그래서 물음을 바꿔야 한다. “뭐가 좋아?”가 아니라 “뭘 버려야 해?”

    한 줄 정리

    별점도, 배지도, ‘AI의 첫 대답’도 신호일 뿐이다. 직접 확인하고, “좋냐”가 아니라 “맞냐”로 골라라.

    확인한 것

    글에 적은 숫자는 추측이 아니라 직접 확인한 값이다.

    • 네 repo의 별점·라이선스·언어는 깃허브 API로 직접 확인(2026-06)
    • NOASSERTION = 깃허브가 표준 SPDX 라이선스로 식별 못 한 상태(비표준/커스텀) → 직접 LICENSE 파일 확인 필요

  • 블로그 자동발행 스킬을 만들었다 — 그리고 이 글이 그 첫 결과물이다

    요약 — 먼저 결론

    블로그에 글 하나 올리는 데 손이 너무 많이 갔다. 제목, 요약, 카테고리, 번역, 캐시 비우기까지 11단계.

    그래서 이 과정을 한 번에 처리하는 도구를 만들었다. 핵심은 “자동화”가 아니라 글이 읽히게 만드는 것이었다.

    그리고 만들면서 깨달았다. 만드는 건 쉽고, 내놓는 게 어렵다. 지금 읽는 이 글이 그 ‘내놓기’의 첫 결과물이다.

    왜 만들었나 — 같은 잔손질 11번

    글 하나 올릴 때마다 똑같은 일을 손으로 반복했다. 세어 보니 11개였다.

    1. 제목 짓기
    2. 요약 쓰기
    3. 카테고리 붙이기
    4. 태그 달기
    5. 한글판 올리기
    6. 영어판으로 번역
    7. 두 판을 번역쌍으로 연결
    8. 글을 웹용으로 변환
    9. 발행
    10. 캐시 비우기
    11. 주소가 살아있는지 확인

    한 번은 재밌다. 열 번째부턴 일이다. 빠뜨리는 것도 생긴다. 영어판 연결을 깜빡하거나, 캐시를 안 비워서 옛날 글이 보이거나.

    매번 같은 재료를 같은 순서로 써는 일이다. 레시피를 외울 게 아니라 밀키트를 만들어야 한다.

    진짜 문제는 자동화가 아니었다 — “읽히는가”

    자동화는 절반이었다. 더 중요한 건 올린 글이 실제로 읽히느냐였다.

    사람은 글을 안 읽는다. 훑는다. 닐슨 노먼 그룹(NN/g) 연구에서 사람은 웹페이지 글자의 20~28%만 읽는다.

    《스틱(Made to Stick)》엔 더 무서운 실험이 있다. 머릿속 노래의 박자를 두드리는 사람은, 듣는 사람이 곡을 맞힐 확률을 50%로 봤다. 실제론 40곡 중 1곡이었다.

    쓰는 사람 머릿속엔 멜로디가 흐르지만, 읽는 사람에겐 ‘똑똑’ 소리만 들린다. 이걸 “지식의 저주”라 부른다. 내가 아는 걸 남도 알 거라는 착각.

    그래서: 이해도를 ‘보안 게이트’처럼 만들었다

    읽히는 글을 강제하기로 했다. 통과 못 하면 발행이 안 되는 검사기를 짰다.

    비밀번호 검사를 떠올리면 된다. 너무 짧으면 가입이 안 되듯, 글도 기준을 못 넘으면 못 올라간다.

    검사 항목은 연구에서 그대로 뽑았다.

    • 결론이 맨 위에 있는가 — 각 단락 첫 문장이 곧 답
    • 한 단락이 너무 길지 않은가 — 길면 건너뛴다
    • 소제목이 충분한가 — 훑는 사람의 이정표
    • 한 문장이 너무 길지 않은가 — 숨이 차면 못 읽는다
    • 비유와 예가 있는가 — 추상적이면 안 박힌다

    이 글도 그 검사기에 걸렸다. 초안 끝에 멋 부린 마무리 한 문장을 넣었는데, 나는 겸손한 매듭이라 여겼다. 검사기는 “흔한 상투구”라며 막았다. 빼버렸다.

    쓰는 나에겐 멋이고, 읽는 쪽엔 군더더기. 이게 지식의 저주의 작은 실례다. 검사기가 그 간극을 대신 잡아줬다.

    뜻밖의 발견 — 한 번 잘 쓰면 세 곳에서 이득

    읽기 좋게 다듬었더니 효과가 한 군데가 아니었다. 세 군데였다.

    사람이 훑기 좋은 글은 검색·요약하는 AI도 뽑아 쓰기 좋다. 요즘 검색은 AI가 결과를 정리해 보여주는데, 결론이 위에 있고 단락이 짧은 글을 먼저 인용한다.

    그렇게 정리된 글은 공유하기도 좋다. 핵심 세 줄을 그대로 가져다 쓸 수 있으니까.

    레버 하나를 당겼는데 문이 셋 열렸다. 사람·AI·공유가 같은 방향을 본다.

    삽질 기록 — 날것 그대로

    깔끔하게 된 건 하나도 없었다. 막힌 것들을 그대로 적는다.

    도구가 글자를 거부했다. 글을 옮기는 한 방식이 보안 필터에 걸려 멈췄다. 다른 방식으로 우회했다.

    메뉴에 안 떴다. 스킬을 만들었는데 목록에 안 보였다. 파일 맨 위 설정 한 줄이 빠져 있었다. 잘 되는 도구와 비교해서야 찾았다.

    영어판 주소가 충돌했다. 한글판과 같은 주소를 쓰니 시스템이 뒤에 숫자를 붙였다. 영어판엔 고유 주소를 따로 줬다.

    매끈한 결과물 뒤엔 늘 이런 잔고장이 있다.

    도구 스택 — 인프라까지 공개

    뭘로 굴리는지도 숨기지 않는다.

    블로그는 집에 둔 작은 PC 한 대에서 돈다. 그 위에 도커로 워드프레스를 띄우고, 다국어 플러그인으로 한글·영어를 짝짓는다.

    밖에서 접속되게 하는 건 클라우드플레어 터널이다. 글 초안은 무료 gpt-4o에게 맡기고, 읽기 검사기는 파이썬으로 직접 짰다.

    진짜 배운 것 — 만드는 건 쉽고, 내놓는 게 어렵다

    이번에 가장 크게 남은 한 가지다. 도구를 만드는 일은 편하고, 내놓는 일은 불편하다.

    도구 만들기 내놓기
    통제 내 손안 남의 반응
    실수하면 고치면 끝 남이 본다
    기분 편함 불편함
    성장 적음 큼

    그래서 자꾸 도구만 더 만들고 싶어진다. 그게 편하니까. 하지만 성장은 불편한 쪽에 있다.

    그래서 이 글을 쓴다. 만든 이야기를 만든 채로 두지 않고 밖에 내놓는 것. 이 글 자체가 그 연습이다.

    한 줄 정리

    도구는 읽히는 글을 강제하려고 만들었지만, 진짜로 배운 건 따로 있다. 만드는 건 쉽고 내놓는 게 어렵다 — 그러니 내놓아라.

    참고한 것

    • 닐슨 노먼 그룹(NN/g), “How Users Read on the Web” — 글자의 20~28%만 읽음
    • 칩 히스·댄 히스, 《스틱(Made to Stick)》 — 지식의 저주, 두드리는 사람 실험
    • Diátaxis — 문서 유형 4분류(튜토리얼·how-to·참고·설명)