AI가 읽는 문서로는 부족하다
Cloudflare Nimbus는 AI용 Markdown을 더하는 데서 멈추지 않는다. 에이전트가 문서 사이트를 읽고 고칠 수 있도록 소스 소유권, 검증 규칙, 변경 절차를 한 설계로 묶는다.
AI가 문서를 읽게 만드는 일은 이제 어렵지 않다. HTML 옆에 Markdown을 내놓고, llms.txt에 문서 목록을 적으면 된다. Cloudflare가 공개한 Nimbus는 그 다음 문제를 다룬다. 에이전트가 문서를 읽은 뒤 실제로 고치고, 빌드하고, 검증하게 하려면 문서 사이트가 어떤 구조여야 하는가.
cloudflare/nimbusNimbus의 대답은 소스 소유권이다. 레이아웃, 컴포넌트, 스타일, 라우트, 콘텐츠를 프로젝트 안의 실제 파일로 만든다. 프레임워크는 보이지 않는 배관만 패키지로 제공한다. 화면에서 보이는 요소가 외부 테마의 import 경계 뒤에 숨지 않으니 사람과 코딩 에이전트가 같은 저장소를 보고 수정할 수 있다.
읽기 좋은 문서와 고치기 좋은 문서는 다르다
Nimbus 사이트는 각 페이지의 .md 또는 .mdx 버전, 사이트 전체 색인인 llms.txt와 llms-full.txt, JSON-LD, 사이트맵을 기본으로 만든다. 검색 결과나 에이전트가 브라우저 화면을 긁지 않아도 문서의 본문과 구조를 가져갈 수 있다.
여기까지는 AI가 읽을 수 있는 문서다. Nimbus의 설계 철학은 유지보수까지 범위를 넓힌다. 에이전트가 페이지를 추가하려면 어느 파일을 고쳐야 하는지, 변경이 다른 레이아웃과 충돌하지 않는지, 빌드 뒤 어떤 검사를 통과해야 하는지까지 볼 수 있어야 한다. 문서가 답변용 데이터에서 작업 가능한 코드베이스로 바뀐다.
차이는 문서가 낡았을 때 드러난다. 읽기 전용 표면은 에이전트에게 오래된 답을 더 잘 전달한다. 수정 가능한 표면은 에이전트가 원문을 고치고, 링크와 구조를 검사하고, 실패한 빌드를 근거로 다시 수정하게 한다. 문서 품질의 병목이 검색에서 변경과 검증으로 이동한다.
기능을 설치하는 방식도 달라진다
Nimbus의 CLI는 단순한 파일 복사와 에이전트 작업을 구분한다. 컴포넌트처럼 결과가 정해진 항목은 소스 파일로 복사한다. 새 버전 문서나 404 페이지처럼 프로젝트 맥락을 읽어야 하는 기능은 Markdown 실행 절차를 에이전트에게 넘긴다. 에이전트는 기존 설치 여부를 확인하고, 변경 계획을 세우고, 파일을 수정한 뒤 빌드로 검증한다.
문서 린터도 같은 방향을 따른다. 단일 H1, 맨 URL, 링크 문구 같은 규칙에 안정적인 식별자를 붙이고 JSON 진단을 출력한다. 사람이 읽는 경고문과 에이전트가 처리하는 오류 형식이 따로 놀지 않는다. 콘텐츠 스키마에는 작성 주체와 인간 검토 여부 같은 provenance를 넣을 수 있다. 에이전트가 글을 쓰는 순간 생기는 “누가 만들었고 사람이 확인했는가”라는 질문을 문서 바깥의 관행이 아니라 데이터로 남긴다.
소스를 소유하면 업그레이드도 소유한다
이 설계의 비용은 명확하다. 테마가 대신 관리하던 레이아웃과 컴포넌트를 내 저장소로 가져오면 수정 자유와 함께 유지보수 책임도 따라온다. 보안 수정이나 접근성 개선이 상위 패키지 하나를 올리는 것으로 끝나지 않을 수 있다.
Nimbus도 현재 상태를 pre-1.0이라고 밝히며, minor release 사이에도 공개 표면이 바뀔 수 있으니 버전을 고정하고 changelog를 확인하라고 권한다. 지금은 안정된 표준보다 빠르게 움직이는 설계 제안에 가깝다.
에이전트 경계에도 거친 부분이 남아 있다. 현재 starter는 코딩 에이전트 안내 파일을 AGENT.md라는 단수 이름으로 만든다. 이를 표준 이름인 AGENTS.md로 바꾸자는 이슈 #38은 닫혔지만 scaffold에는 아직 반영되지 않았다. 기본 설정의 site 값도 https://example.com이므로, 그대로 빌드하면 canonical URL과 사이트맵이 잘못된 주소를 품을 수 있다.
기능을 에이전트용 실행 절차로 전달하는 방식은 신뢰 경계도 바꾼다. 패키지 코드를 검토하는 것만으로는 부족하다. 어떤 registry에서 어떤 절차를 받았는지, 실행 전에 사람이 무엇을 확인하는지, 적용 뒤 어떤 검증을 남기는지까지 운영 규칙이 필요하다.
프레임워크보다 먼저 가져올 네 가지
Nimbus로 전면 이주하지 않아도 핵심 설계는 기존 문서 시스템에 넣을 수 있다. 모든 페이지에 원문과 가까운 Markdown 표면을 제공하고, 전체 문서를 한 번에 찾을 수 있는 색인을 만든다. 작성 주체와 검토 상태를 스키마에 남기고, 문서 규칙을 사람이 읽는 가이드에서 기계가 판정하는 린트로 옮긴다.
이 네 가지가 갖춰지면 에이전트는 문서를 답변의 재료로만 쓰지 않는다. 어떤 파일을 바꿨는지, 왜 바꿨는지, 무엇을 통과했는지 남기며 문서의 수명주기에 참여할 수 있다.
도입 판단도 좁게 할 수 있다. 새 문서 프로젝트 하나에서 에이전트에게 페이지 추가와 링크 수정, 빌드 검증까지 맡겨본다. 사람이 맥락을 다시 설명한 시간, 실패를 찾은 검사, 변경 근거를 추적하는 시간을 잰다. 이 세 가지가 줄지 않는다면 agent-first라는 이름과 관계없이 운영 개선은 일어나지 않은 것이다.
주요 출처: Cloudflare, Nimbus 공개 저장소와 README; Nimbus, Philosophy; Nimbus, Agent surfaces; Nimbus, CLI. 문서를 “읽기 표면”에서 “변경·검증 표면”으로 확장해야 한다는 해석, registry 기반 실행 절차의 신뢰 경계, 좁은 파일럿 제안은 Zero Draft Lab의 분석입니다.
