문서화가 중요한 이유

문서화는 현재의 정확한 컨텍스트를 제공합니다. 문서화가 없으면 모델은 오래되거나 불완전한 훈련 데이터를 사용하게 됩니다. 문서화는 모델이 다음과 같은 것들을 이해하는 데 도움을 줍니다:
  • 현재 API와 매개변수
  • 모범 사례
  • 조직 규칙
  • 도메인 용어
그리고 훨씬 더 많은 것들을 말이죠. 컨텍스트를 전환하지 않고도 Cursor에서 바로 문서화를 사용하는 방법을 알아보려면 계속 읽어보세요.

모델 지식 컷오프

대규모 언어 모델은 “지식 컷오프”라고 불리는 특정 시점까지의 데이터로 훈련됩니다. 이는 다음을 의미합니다:
  • 최근 라이브러리 업데이트가 반영되지 않을 수 있음
  • 새로운 프레임워크나 도구를 알지 못할 수 있음
  • 컷오프 날짜 이후의 API 변경사항을 놓칠 수 있음
  • 훈련 이후 모범 사례가 발전했을 수 있음
예를 들어, 모델의 지식 컷오프가 2024년 초라면, 인기 있는 프레임워크라도 2024년 말에 출시된 기능에 대해서는 알지 못할 것입니다.

어떤 도구를 사용해야 할까요?

이 의사결정 트리를 사용하여 문서화 요구사항에 가장 적합한 접근 방식을 빠르게 결정하세요:

멘탈 모델

도구멘탈 모델
@Docs공식 문서를 탐색하고 읽는 것과 같음
@Web인터넷에서 해결책을 검색하는 것과 같음
MCP내부 문서에 접근하는 것과 같음

공개 문서

외부 문서는 모델이 제한적이거나 오래된 지식을 가지고 있을 수 있는 공개적으로 사용 가능한 정보를 다룹니다. Cursor는 이러한 정보에 접근하는 두 가지 주요 방법을 제공합니다.

@Docs 사용하기

@Docs는 Cursor를 인기 있는 도구와 프레임워크의 공식 문서에 연결합니다. 다음과 같은 최신의 권위 있는 정보가 필요할 때 사용하세요:
  • API 참조: 함수 시그니처, 매개변수, 반환 타입
  • 시작 가이드: 설정, 구성, 기본 사용법
  • 모범 사례: 소스에서 권장하는 패턴
  • 프레임워크별 디버깅: 공식 문제 해결 가이드
@
@Docs Next.js catch-all 라우트를 사용한 동적 라우팅을 어떻게 설정하나요?
Agent⌘I
Auto

@Web 사용하기

@Web은 실시간 인터넷에서 최신 정보, 블로그 게시물, 커뮤니티 토론을 검색합니다. 다음과 같은 경우에 사용하세요:
  • 최신 튜토리얼: 커뮤니티에서 생성된 콘텐츠와 예제
  • 비교: 다양한 접근 방식을 비교하는 글
  • 최신 업데이트: 매우 최근의 업데이트나 공지사항
  • 다양한 관점: 문제에 대한 다양한 접근 방식
@
@Web React 19의 최신 성능 최적화
Agent⌘I
Auto

내부 문서

내부 문서는 AI 모델이 훈련 과정에서 접한 적이 없는 조직 특화 정보를 포함합니다. 여기에는 다음이 포함될 수 있습니다:
  • 내부 API: 커스텀 서비스 및 마이크로서비스
  • 회사 표준: 코딩 규칙, 아키텍처 패턴
  • 독점 시스템: 커스텀 도구, 데이터베이스, 워크플로우
  • 도메인 지식: 비즈니스 로직, 규정 준수 요구사항

MCP를 통한 내부 문서 접근

Model Context Protocol (MCP)은 개인 문서와 시스템을 Cursor로 가져오는 표준화된 방법을 제공합니다. MCP는 Cursor와 내부 리소스 사이의 얇은 레이어 역할을 합니다. MCP가 중요한 이유:
  • 모델은 내부 규칙을 추측할 수 없습니다
  • 커스텀 서비스의 API 문서는 공개적으로 사용할 수 없습니다
  • 비즈니스 로직과 도메인 지식은 조직마다 고유합니다
  • 규정 준수 및 보안 요구사항은 회사마다 다릅니다

일반적인 MCP 통합

통합접근예시
Confluence회사 Confluence 공간아키텍처 문서, 내부 서비스 API 명세서, 코딩 표준 및 가이드라인, 프로세스 문서
Google Drive공유 문서 및 폴더명세서 문서, 회의록 및 결정 기록, 설계 문서 및 요구사항, 팀 지식 베이스
Notion워크스페이스 데이터베이스 및 페이지프로젝트 문서, 팀 위키, 지식 베이스, 제품 요구사항, 기술 명세서
커스텀내부 시스템 및 데이터베이스독점 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";

// 내부 문서 스크래핑을 위한 MCP 서버 생성
const server = new McpServer({
  name: "internal-docs",
  version: "1.0.0"
});

const turndownService = new TurndownService();

// 내부 문서 스크래핑 도구 추가
server.tool("get_doc",
  { url: z.string() },
  async ({ url }) => {
    try {
      const response = await fetch(url);
      const html = await response.text();
      
      // HTML을 마크다운으로 변환
      const markdown = turndownService.turndown(html);
      
      return {
        content: [{ type: "text", text: markdown }]
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: `Error scraping ${url}: ${error.message}` }]
      };
    }
  }
);

// stdin에서 메시지 수신 및 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와 내부 시스템 간의 격차를 해소합니다
  • 코드와 대화에서 문서를 생성하여 지식을 최신 상태로 유지하세요
  • 포괄적인 이해를 위해 외부 및 내부 문서 소스를 결합하세요