문서가 중요한 이유

문서는 최신이고 정확한 맥락을 제공해. 문서가 없으면 모델은 오래됐거나 불완전한 학습 데이터에 의존하게 돼. 문서는 모델이 다음과 같은 걸 이해하는 데 도움이 돼:
  • 최신 API와 매개변수
  • 모범 사례
  • 조직 내 규칙/관례
  • 도메인 용어
그리고 더 많아. 컨텍스트 전환 없이 Cursor 안에서 바로 문서를 어떻게 활용하는지 계속 읽어봐.

모델 지식 컷오프

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

어떤 도구를 써야 할까?

이 결정 트리로 문서화에 가장 적합한 접근 방식을 빠르게 골라봐:

멘탈 모델

도구멘탈 모델
@Docs공식 문서를 찾아보고 읽을 때처럼
@Web인터넷에서 해결책을 검색할 때처럼
MCP내부 문서에 접근할 때처럼

공개 문서

외부 문서는 모델이 제한적이거나 오래된 지식을 갖고 있을 수 있는 공개 정보를 다뤄. 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와 내부 시스템 사이를 이어줘
  • 지식을 최신으로 유지하려면 코드랑 대화에서 문서를 생성해
  • 더 폭넓게 이해하려면 외부랑 내부 문서 소스를 함께 써