README가 거짓말을 하니, 병합할 때마다/docs PR를 여는 봇을 만들었다.
출처: Dev.to
The README는 거짓말이다.
의도치 않게가 아니라, 그 사람이 쓴 당일엔 사실이었습니다. 그 후 함수가 이름이 바뀌었고, 플래그가 삭제되었으며, 환경 변수가 변경되고, 엔드포인트가 이동되었습니다 — 그런데 아무도 문서를 수정하지 않았어요, 왜냐하면 문서 관리는 직무가 아니었기 때문이죠. 그래서 README는 조용히 코드와 멀어지고, 처음으로 이를 알게 되는 사람은 복사‑붙여넣기한 스니펫을 시도하는 사람이라는 겁니다.
문서 페이지를 열고 코드 블록까지 스크롤한 적이 있다면 *’…이게 아직 실존하는 건가?’*이라고 생각한 경험이 있죠 — 당신은 이미 실패 모드를 알고 있습니다. 문서는 사람들이 게으르기 때문에 썩지 않습니다. 문서는 실제 변경이 일어난 루프 밖에서 수동으로 동기화를 맞추는 것이기 때문에 썩습니다.
통찰: 문서는 코드 머지라는 행위에서 부수적으로 나타나는 것이다.
디프는 이미 모든 것을 알고 있다. PR을 머지할 때, 변경 사항은 바로 그곳에 있다 — 이름이 바뀐 함수, 새로운 파라미터, 삭제된 플래그. 이것이/docs가 업데이트되어야 하는 정확한 시점이며, 동시에 모두가 다른 일로 바빠 있는 순간이다.
해결책은 ‘write better docs.‘가 아니라 머지하는 순간에/docs 업데이트가 자동으로 발생하도록 만드는 것이며, CI가 푸시될 때와 같은 방식이다. 문서를 머지라는 이벤트 기반 부수 효과로 취급하고, 나중에 할 일처럼 미루는 것이 아니라.
그것이 바로 제가 만든 것입니다. 이름은 docs-keeper이며, 이제야 출시되었습니다.
작동 방식
docs-keeper는 GitHub App으로 설치됩니다. 새로운 대시보드를 관리할 필요도 없고,/docs 플랫폼으로 이동할 필요도 없으며, 이미 사용하는 PR 흐름에 존재합니다.
코드 PR을 머지할 때,
- 디프(차이)를 읽습니다.
- 그 차이를 기반으로 grounded documentation + changelog 업데이트를 초안화합니다.
- 초안을 7가지 검증 게이트에 통과시킵니다.
- 리뷰용 docs PR을 열어줍니다.
그게 전부입니다. 자동으로 머지하지 않습니다. 일반적인 PR을 받게 되며, 읽고 병합하거나 닫습니다. 팀원 브랜치를 검토하는 것과 동일한 직관적 흐름을 가집니다.
머지 후 레포에 나타나는 대략적인 내용은 다음과 같습니다:
✓ merged: #482 "rename authClient → sessionClient"
└─ docs-keeper triggered on merge
reading diff… 6 files
drafting docs + changelog…
running 7 validation gates:
[1/7] grounding ........ pass
[2/7] structure ....... pass
[3/7] links .......... pass
[4/7] code-fences ...... pass
[5/7] changelog ........ pass
[6/7] style ........... pass
[7/7] safety ........... pass
→ opened PR #483 "docs: update for #482"
CHANGELOG.md | 4 ++
docs/auth.md | 12 +++---
~27s from merge → opened PR
review required · no auto-merge전체 화면 모드 진입
퇴出全屏模式 (전체 화면 모드 종료)
당신은 #483을 열고, 디프를 읽고, 결정을 내립니다. docs-keeper는 메인 브랜치에 표결권이 없습니다.
근접 게이트가 핵심이죠
LLM을/docs 근처에 두는 것을 신뢰하지 못하는 이유도 환각 때문이다 — LLM이 존재하지 않는 retryPolicy 옵션까지 자신감 있게 문서화합니다. 따라서 7가지 검증 게이트 중 가장 중요한 것은 근접 게이트입니다: 생성된/docs가 디프에 존재하지 않는 식별자를 언급하면 초안이 거부됩니다. 미스터리 함수도 없고, invent된 파라미터도 없고, 배포되지 않은 플래그도 없습니다.
제가 말하는 바가 무엇인지 명확히 하면: 이는 마법이 아니며, 완벽하거나 절대적인 것이 아닙니다. 초안을 뭔가 편집하고 싶은 형태로 만들 수 있습니다. 그래서 출력은 메인 브랜치에 바로 커밋되는 것이 아니라 검토용 PR입니다. 근접 게이트는 바닥선을 높이고, 당신은 여전히 상단(천장)입니다.
진실한 단위 경제학
~$0.004/docs PR당 평균 LLM 비용. 센트 미만.
머지 후 PR가 열린 데 ~27초.
PR가表示되기 전에 7가지 검증 게이트가 실행됩니다.
공개 레포는 무료입니다. 오픈 소스로 배포 중이라면 비용이 들지 않습니다.
모든 변경 사항을 검토합니다. 언제나 PR이며, 절대 자동 머지하지 않습니다.
docs-keeper가 적합한 곳과 그렇지 않은 곳
Mintlify나 ReadMe.com을 사용 중이라면, 멋진/docs 호스팅과 AI 라이터를 제공하지만 당신은 여전히 수동으로 업데이트를 진행합니다. они는 머지된 변화를 감지하지 못하죠. docs-keeper는 호스팅 플랫폼이 아니라, 머지된 것을 감지하고 초안을 작성하는 도구입니다.
Docusaurus나 MkDocs와 같은/docs-as-code환경에서는 오늘날 전부 수동입니다 — docs-keeper는 당신이 기억해야 할 PR을 자동으로 열어줍니다.
그리고 당신의 계획이 “Copilot에게 물어보거나 디프를 LLM에 붙여넣는다”는 것이라면, 그건 머지 트리거가 아니며, 가짜 식별자를 차단하는 근접 게이트도 없고, 리뷰 PR 워크플로도 없습니다. docs-keeper는 당신이 계속 미루고 있는 것을 자동으로 처리해 주는 평범한 버전입니다.
(프로+ 플랜에서는/docs-keeper가 프리머지 전 스캔을 수행합니다 — OWASP Top 10 및 비밀 정보 탐지 — 그리고 리뷰 전용 수정 PR을 열 수 있습니다. 철학은 동일합니다: PR을 열고, 당신은 결정을 내립니다. 나중에 더 자세히 다루겠습니다.)
공개 레포에서 시험해 보기
오픈 소스 레포지토리에 약간 솔직하지 않은 # TODO: docs out of date 가 있다면, 이는 테스트를 시작하기에 가장 낮은 위험 방식입니다:
- /docs-keeper GitHub App을 공개 레포에 설치합니다(공개 레포는 무료).
- PR을normally와 같이 머지합니다.
- 약 27초 안에 근접/docs PR이 나타나는 것을 확인합니다.
- 검토하고, 병합하거나 닫습니다. 어느 경우든 당신은 제어권이 있습니다.
시작하려면 → https://docs-keeper.com
드디어 출시됐어요 — 어디서 깨지는지 알려 주세요
솔직히 말하자면: docs-keeper는 아주 최신 제품입니다. 추천문이 없으며, 로고 월도 없고, “수천 명이 신뢰한다”는 문구도 없습니다 — 왜냐하면 아직 존재하지 않으며, 제가 invent(발명)하지 않을 것이기 때문입니다. 존재하는 것은 실제 운영 환경에서 검증된 작동 중인 봇입니다: 머지된 코드 PR이 근접/docs PR을 자동으로 열었고, 모든 게이트가 적용됐습니다.
솔직히 말하면, 제가 원하는 건 여러분이 ‘great’이라고 말하는 것보다 먼저它를 깨보는 시도입니다. 어려운 디프에它를 겨냥해 보세요. 근접 게이트가 유지되는지 확인하고, 초안이 잘못된 부분, 27초가 충분하지 않은 점, 혹은 게이트가 무언가를 잡지 못한 점을 알려 주세요. 댓글에 올려 주세요 — 지금 이 시점에 별 수보다 더 가치 있는 피드백입니다.
README는 충분히 오래 거짓말을 해왔습니다. 진실을 머지라는 부수 효과로 만들자.