오픈소스 설명서가 바뀐 건 문장이 아니라 독자다

공개 10일 만에 별이 14,900개 붙은 프로젝트가 있다. 같은 10일 동안 그 저장소의 설치 안내서는 한 번 통째로 다시 쓰였다. 나는 그 두 판본을 모두 열어봤고, 바뀐 것이 문장이 아니라 독자라는 결론에 도달했다.

오픈소스를 깔아보려다 설명서에서 막힌 적이 있다면 이 글이 그 지점을 다룬다. 다루는 자료 13종 중 9종은 가입 없이 그냥 도는 프로그램이다.

이 글은 그 변화를 구조로 정리한 기록이다. 프로그램 사용법이 아니라, 안내 문서가 누구를 향해 쓰이기 시작했는지에 대한 이야기다.

설명서 첫머리가 왜 사람이 아니라 AI를 부르는가

내가 처음 열었을 때 그 문서의 팁 블록 첫 줄은 이렇게 시작했다. "코딩 못 하세요? AI한테 이 페이지를 통째로 시키세요." 다만 이건 권유가 아니라 실행 지시였다 — 바로 밑에 코딩 에이전트에 그대로 붙여넣을 문장이 통째로 들어 있었기 때문이다.

지금까지 오픈소스 설명서는 사람이 읽고 사람이 실행하는 문서였다. 읽을 줄 아는 사람만 쓸 수 있다는 뜻이기도 했다.

읽는 일을 AI가 대신하면 그 조건이 사라진다.

그러면 설명서는 누구를 위해 쓰는 문서가 되나

두 종류의 독자를 동시에 상대하는 문서가 된다. 사람에게는 무엇을 얻는지 알려주고, AI에게는 무엇을 어떤 순서로 하라고 지시한다. 다만 이 둘을 한 문단에 섞으면 양쪽 모두에게 흐려진다.

실제로 그 프로젝트는 둘을 블록으로 나눠 놓았다. 사람이 읽는 산문 아래, 그대로 복사할 지시문이 코드 블록으로 따로 있었다.

붙여넣기용 문장은 어떤 구조로 짜여 있었나

그 문장은 네 덩어리였다. 목적, 절차, 안전장치, 태도. 이 네 개가 다 있어야 에이전트가 중간에 멋대로 판단하지 않는다.

목적 — 이 프로젝트를 받아서 내 컴퓨터에 설치하라
절차 — 필요한 키를 받는 것도 단계별로 안내하라
안전장치 — 청구 알림과 사용량 상한부터 걸어라
태도 — 나는 개발자가 아니니 설명하면서 진행하라

세 번째가 이 문장의 핵심이다. 원문에는 "돈이 나갈 수 있는 단계 전에는 나한테 먼저 물어봐"라는 취지의 문구가 들어 있었다.

사람들이 AI에게 일을 시킬 때 가장 많이 빠뜨리는 것이 정확히 여기다. 대개는 목적 한 줄만 던지고 나머지 셋을 비워둔다.

이 네 가지는 다른 작업에도 그대로 쓸 수 있나

쓸 수 있다. 다만 안전장치에 들어갈 내용은 작업마다 다시 채워야 한다. 설치 작업에서는 요금이지만, 파일을 다루는 작업에서는 "덮어쓰기 전에 물어봐"가 그 대신 들어간다.

나는 이 네 가지를 그대로 떼어 내 작업 지시문의 틀로 쓰고 있다. 목적만 적고 던졌을 때와 비교하면, 되묻는 횟수가 눈에 띄게 줄었다.

안전장치를 안 적으면 실제로 무엇이 일어나나

에이전트는 막히면 멈추지 않고 진행할 방법을 찾는다. 결제 등록이 필요한 단계를 만나면 그 단계를 통과하는 쪽을 고른다. 그게 잘못이라기보다, 멈춰야 할 지점을 알려주지 않았기 때문이다.

그래서 안전장치는 금지 목록이 아니라 정지 지점 목록에 가깝다. 어디서 나에게 물어야 하는지를 적어주는 것이다.

내가 촬영 계획을 다시 짜야 했던 이유

처음 이 프로젝트를 다룰 때 나는 설명서의 한 문장을 사실로 믿었다. 아니었다. 그 문서는 발급받은 키 하나가 이 앱을 여는 값이라고 못 박고 있었다. 그래서 나는 발급 화면부터 찍을 계획을 세웠다.

그런데 확인 삼아 키를 하나도 넣지 않고 실행해봤더니 앱이 그냥 켜졌다. 위성사진 제공처를 알아서 다른 곳으로 갈아끼우고 있었다.

원인은 내가 문서를 현재형으로 읽은 데 있었다. 그 문장은 프로젝트가 스스로도 곧 폐기할 예정이던 과거의 전제였다.

실제로 내가 촬영하는 사이 원클릭 설치가 나왔고, 설명서 첫 줄은 "키도, 가입도, 설정 파일도 필요 없다"로 바뀌었다. 키는 나중에 앱 안에서 붙이는 선택지라는 설명이 뒤를 이었다. 나는 촬영분의 절반을 버리고 다시 찍었다.

이 실수를 다른 문서에서도 피하려면

문서의 단정문을 만나면 그 문장이 언제 쓰였는지부터 본다. 저장소라면 그 줄이 마지막으로 고쳐진 날짜를 확인할 수 있다.

나는 이번 일 이후로 설명서를 읽을 때 커밋 기록을 같이 연다. 문장은 현재형인데 기록은 반년 전인 경우가 생각보다 많다.

문서와 코드가 어긋나면 무엇이 조용히 죽는가

공식 보안 안내는 발급한 키에 "내 사이트에서만 쓰이도록" 제한을 걸라고 한다. 원칙적으로 맞는 말이지만, 이 프로젝트에 그대로 적용하면 기능 두 개가 오류 없이 멈춘다.

주변 시설 검색과, 카메라가 없는 지역에서 대신 보여주는 화면이다.

이유는 호출 주체에 있다. 이 두 기능은 브라우저가 아니라 서버가 대신 부른다. 그래서 "내 사이트에서 왔다"는 표시가 요청에 붙지 않고, 구글은 그 요청을 제한 위반으로 보고 차단한다.

핵심은 어느 한쪽이 틀렸다는 게 아니다. 보안 문서는 일반적인 웹앱을 전제로 쓰였고, 이 프로젝트는 서버가 일부 호출을 대신하는 구조다. 문서와 구현이 서로 다른 전제 위에 서 있으면, 그 어긋남은 에러가 아니라 침묵으로 나타난다.

이런 어긋남은 어떻게 미리 찾나

권고를 적용하기 전에 그 권고가 전제하는 구조와 내 구조가 같은지 본다. 이번 경우 전제는 "모든 호출이 브라우저에서 나간다"였고, 실제 구조는 아니었다.

찾는 방법은 단순하다. 기능이 멈췄을 때 브라우저 개발자 도구의 네트워크 기록을 열어보면 된다. 거기 안 찍히는 호출이 있으면 그건 서버 쪽에서 나간 것이다.

그래서 키 제한을 걸어야 하나 말아야 하나

정답이 하나로 나오지 않는다. 보안을 우선하면 제한을 다 걸고 그 두 기능을 포기하는 쪽이 맞고, 기능을 쓰려면 다른 방어선을 세워야 한다.

나는 사이트 제한 대신 쓸 수 있는 기능 목록을 좁히고 사용량 상한을 낮게 거는 쪽을 택했다. 공식 권고와 다른 선택이라는 걸 알고 쓰고 있다.

여기서 한 가지는 분명히 해두는 게 좋겠다. 알림과 상한은 다른 장치다. 알림은 메일이 올 뿐 지출을 멈추지 않는다.

별 14,900개는 기능 때문인가

단정할 수 없다. 다만 같은 기간에 설치 문턱을 두 번 낮춘 것은 사실이다. 한 번은 AI에게 설치를 넘기는 안내문으로, 한 번은 원클릭 설치와 키 없이 켜지는 기본값으로.

기능이 늘어난 게 아니라 진입 조건이 줄었다. 이건 내 해석이고, 프로젝트가 그렇게 밝힌 적은 없다.

내가 이 결론에서 틀릴 수 있는 부분

이 글의 약한 고리는 표본이 하나라는 점이다. 프로젝트 하나에서 관찰한 것을 두고 문서 작성 방식이 바뀌고 있다고 말하고 있다.

두 번째 판본에서 그 AI 지시문이 사라진 것도 반대 해석이 가능하다. 원클릭 설치가 생겨 필요 없어졌다고 볼 수도 있고, 그 방식이 잘 안 먹혀 접었다고 볼 수도 있다. 나는 전자로 읽었지만 확인한 것은 아니다.

이 변화가 다른 프로젝트에도 번질까

번질 조건은 있다. 설치 절차가 길고, 대상 사용자가 개발자가 아니고, 요금이 걸린 프로젝트라면 같은 유인이 생긴다.

반면 개발자만 쓰는 라이브러리는 그럴 이유가 없다. 그쪽 독자는 이미 문서를 읽을 줄 알기 때문이다.

이 변화에서 가져갈 것

내가 이 프로젝트에서 배운 건 지도 기술이 아니라 문서를 쓰는 방식이었다. 위의 사례 네 가지를 그대로 행동으로 옮기면 이렇게 된다.

설치 안내를 쓸 때 사람이 읽을 문장과 AI에게 그대로 넘길 문장을 나눠 둔다
에이전트에 일을 시킬 때 목적·절차·안전장치·태도 네 가지를 채운다
문서의 단정문을 만나면 그 문장이 언제 쓰였는지부터 확인한다
공식 권고를 적용하기 전에 내 구조가 그 권고의 전제와 같은지 본다

네 번째가 가장 자주 빠진다. 앞의 안전장치 항목이 비는 것과 같은 이유다. 나도 이번에 문서와 코드를 나란히 열어보지 않았다면 기능 두 개가 왜 멈췄는지 한참 찾았을 것이다.

직접 확인해보려면

이 프로젝트는 공개돼 있고 키 없이도 켜진다. 앞에서 적은 13종 가운데 9종이 가입 없이 그대로 도는 쪽이다.

실제 화면과 설치 과정은 영상에 담았다. 글로 남긴 건 그 화면 뒤의 구조다.

당신이 지금 쓰고 있는 도구의 설명서를 한번 열어보길 권한다. 그 문서는 사람에게 말을 걸고 있는가, 아니면 이미 AI를 향해 쓰이고 있는가?