왜 문서가 중요할까

문서는 최신이고 정확한 문맥을 제공해. 그게 없으면 모델은 오래되거나 불완전한 학습 데이터를 쓰게 돼. 문서는 모델이 다음을 이해하는 데 도움을 줘:
  • 최신 API와 파라미터
  • 모범 사례
  • 조직 내 관례
  • 도메인 용어
그리고 더 많지. 컨텍스트 전환 없이 Cursor 안에서 문서를 제대로 쓰는 법을 계속 읽어봐.

모델 지식 컷오프

대규모 언어 모델은 특정 시점까지의 데이터로 학습되고, 그 시점을 “지식 컷오프”라고 불러. 이건 곧 다음을 의미해:
  • 최근 라이브러리 업데이트가 반영되지 않았을 수 있음
  • 새로운 프레임워크나 도구를 모를 수 있음
  • 컷오프 이후의 API 변경 사항을 놓칠 수 있음
  • 학습 이후 모범 사례가 달라졌을 수 있음
예를 들어, 모델의 지식 컷오프가 2024년 초라면, 2024년 후반에 나온 기능들은 인기 있는 프레임워크라도 알지 못해.

어떤 도구를 써야 할까?

이 결정 트리를 사용해서 문서화 요구에 가장 잘 맞는 접근 방식을 빠르게 정해봐:

멘탈 모델

Tool멘탈 모델
@Docs공식 문서를 둘러보고 읽는 느낌
@Web인터넷에서 해결책을 찾아보는 느낌
MCP내부 문서에 접근하는 느낌

Public documentation

외부 문서는 모델이 제한적이거나 오래됐을 수 있는 공개 정보들을 다뤄. Cursor는 이 정보에 접근하는 두 가지 주요 방법을 제공해.

@Docs 사용하기

@Docs는 Cursor를 인기 있는 도구와 프레임워크의 공식 문서에 연결해줘. 최신의 신뢰할 수 있는 정보가 필요할 때 써봐:
  • API 레퍼런스: 함수 시그니처, 매개변수, 반환 타입
  • 빠른 시작 가이드: 설치, 설정, 기본 사용법
  • 모범 사례: 원문에서 권장하는 패턴
  • 프레임워크별 디버깅: 공식 문제 해결 가이드
@
@Docs Next.js How do I set up dynamic routing with catch-all routes?
Agent⌘I
Auto

@Web 사용하기

@Web은 최신 정보, 블로그 글, 커뮤니티 토론을 실시간으로 찾아줘. 이런 게 필요할 때 써봐:
  • 최신 튜토리얼: 커뮤니티가 만든 콘텐츠와 예제
  • 비교 자료: 서로 다른 접근 방식을 비교한 글
  • 최근 업데이트: 막 올라온 업데이트나 공지
  • 여러 관점: 문제에 대한 다양한 접근 방식
@
@Web latest performance optimizations for React 19
Agent⌘I
Auto

내부 문서

내부 문서는 AI 모델이 학습 중에 접한 적 없는, 조직 특화 정보를 담고 있어. 예를 들면:
  • 내부 API: 커스텀 서비스와 마이크로서비스
  • 회사 표준: 코딩 컨벤션, 아키텍처 패턴
  • 독점 시스템: 커스텀 도구, 데이터베이스, 워크플로
  • 도메인 지식: 비즈니스 로직, 규정 준수 요구사항

MCP로 내부 문서에 접근하기

Model Context Protocol(MCP)는 개인 문서와 시스템을 Cursor로 가져오는 표준화된 방법을 제공해. MCP는 Cursor와 내부 리소스 사이의 얇은 레이어로 동작해. MCP가 중요한 이유:
  • 모델은 네 조직의 내부 컨벤션을 추측할 수 없어
  • 커스텀 서비스의 API 문서는 공개되어 있지 않아
  • 비즈니스 로직과 도메인 지식은 조직마다 고유해
  • 컴플라이언스와 보안 요구 사항은 회사마다 달라

일반적인 MCP 연동

IntegrationAccessExamples
Confluence회사 Confluence 스페이스아키텍처 문서, 내부 서비스용 API 스펙, 코딩 표준과 가이드라인, 프로세스 문서
Google Drive공유 문서와 폴더스펙 문서, 미팅 노트와 의사결정 기록, 설계 문서와 요구사항, 팀 지식베이스
Notion워크스페이스 데이터베이스와 페이지프로젝트 문서, 팀 위키, 지식베이스, 제품 요구사항, 기술 스펙
Custom내부 시스템과 데이터베이스사내 전용 API, 레거시 문서 시스템, 커스텀 지식베이스, 특화된 도구와 워크플로

커스텀 솔루션

특별한 요구가 있다면, 다음을 수행하는 커스텀 MCP 서버를 만들 수 있어:
  • 내부 웹사이트나 포털 스크레이핑
  • 전용 데이터베이스에 연결
  • 커스텀 문서 시스템에 접근
  • 내부 위키나 지식베이스에서 가져오기
커스텀 MCP 서버를 만들면, Cursor가 문서를 업데이트할 수 있는 툴도 노출할 수 있어
내부 문서를 스크레이핑하는 커스텀 MCP 서버 예시:
import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import TurndownService from "turndown";

// Create an MCP server for scraping internal docs
const server = new McpServer({
  name: "internal-docs",
  version: "1.0.0"
});

const turndownService = new TurndownService();

// Add tool to scrape internal documentation
server.tool("get_doc",
  { url: z.string() },
  async ({ url }) => {
    try {
      const response = await fetch(url);
      const html = await response.text();
      
      // Convert HTML to markdown
      const markdown = turndownService.turndown(html);
      
      return {
        content: [{ type: "text", text: markdown }]
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: `Error scraping ${url}: ${error.message}` }]
      };
    }
  }
);

// Start receiving messages on stdin and sending messages on stdout
const transport = new StdioServerTransport();
await server.connect(transport);

문서를 최신 상태로 유지하기

문서는 금방 낡아져. Cursor는 실제 코드와 개발 대화를 바탕으로 문서를 생성하고 업데이트해서, 최신이면서도 유용한 문서를 유지하도록 도와줘.

기존 코드에서

Cursor로 코드베이스에서 바로 문서를 만들어:
@
이 Express 라우터의 API 문서를 생성해. 모든 엔드포인트, 매개변수, 응답 형식을 포함해
Agent⌘I
Auto

채팅 세션에서

Cursor랑 주고받은 대화엔 문서로 바로 옮길 수 있는 가치 있는 내용이 담겨 있어.
복잡한 문제를 해결한 뒤:
@
팀 위키에 올릴 인증 설정 단계별 가이드를 우리 대화 내용으로 요약해 줘
Agent⌘I
Auto

핵심 정리

  • 문서를 컨텍스트로 쓰면 Cursor의 정확도와 최신성이 더 좋아져
  • 공식 문서는 @Docs, 커뮤니티 지식은 @Web을 써
  • MCP는 Cursor와 내부 시스템을 이어주는 다리야
  • 지식을 최신으로 유지하려면 코드와 대화에서 문서를 생성해
  • 폭넓게 이해하려면 외부와 내부 문서 소스를 함께 활용해