레퍼런스

로컬 디렉터리와 Git 저장소를 프로젝트 레퍼런스로 추가하세요.

레퍼런스는 OpenCode가 현재 프로젝트 외부의 디렉터리에 접근할 수 있게 해줍니다. 작업하는 동안 문서, 공유 라이브러리, 예제, 또는 다른 저장소를 사용할 수 있도록 하는 데 사용하세요.

레퍼런스는 opencode.json 또는 opencode.jsonc에서 별칭(alias)으로 설정됩니다.

{
  "$schema": "https://opencode.ai/config.json",
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "Use for product behavior and documentation conventions",
    },
    "sdk": {
      "repository": "anomalyco/opencode-sdk-js",
      "branch": "main",
      "description": "Use for JavaScript SDK implementation details",
    },
  },
}

로컬 디렉터리

path를 사용하여 로컬 디렉터리를 참조하세요.

{
  "references": {
    "docs": {
      "path": "../docs",
    },
  },
}

경로는 다음일 수 있습니다:

• 레퍼런스를 정의하는 설정 파일 기준 상대 경로
• /home/user/docs 같은 절대 경로
• ~/docs 같은 홈 디렉터리 기준 상대 경로

문자열 축약형을 사용할 수도 있습니다:

{
  "references": {
    "docs": "../docs",
  },
}

Git 저장소

repository를 사용하여 Git 저장소를 참조하세요. OpenCode는 저장소를 로컬 저장소 캐시에 구체화(materialize)하고, 체크아웃된 소스를 레퍼런스 디렉터리로 사용할 수 있게 만듭니다.

{
  "references": {
    "effect": {
      "repository": "Effect-TS/effect",
      "branch": "main",
    },
  },
}

repository는 Git URL, host/path 레퍼런스, GitHub owner/repo 축약형을 받습니다. 선택적인 branch 필드로 브랜치나 ref를 선택합니다. branch가 없으면, OpenCode는 저장소의 기본 브랜치를 사용합니다.

브랜치, 설명, 또는 다른 옵션이 필요 없다면 문자열 축약형을 사용할 수 있습니다:

{
  "references": {
    "effect": "Effect-TS/effect",
  },
}

참고: Git 레퍼런스는 비동기적으로 새로 고쳐집니다. 새로 설정한 저장소는 클론 또는 업데이트를 완료하는 데 잠시 시간이 걸릴 수 있습니다.

사용 설명 추가

에이전트가 언제 레퍼런스를 사용해야 하는지 설명하려면 description을 추가하세요.

{
  "references": {
    "design-system": {
      "path": "../design-system",
      "description": "Use when implementing UI components or design tokens",
    },
  },
}

OpenCode는 설명이 있는 레퍼런스를 에이전트 컨텍스트에 포함합니다. 설명은 비슷한 내용을 가진 레퍼런스를 구분할 수 있을 만큼 짧고 구체적이어야 합니다. 설명이 없는 레퍼런스는 자동완성과 직접 사용을 통해서는 계속 사용할 수 있지만, 에이전트에게는 안내되지 않습니다.

자동완성 항목 숨기기

TUI의 @ 자동완성에서 레퍼런스를 제외하려면 hidden을 true로 설정하세요.

{
  "references": {
    "internal": {
      "path": "../internal",
      "description": "Use for internal implementation details",
      "hidden": true,
    },
  },
}

hidden은 자동완성에만 영향을 줍니다. 설명이 있는 숨겨진 레퍼런스는 에이전트 컨텍스트에는 계속 포함됩니다.

레퍼런스 사용하기

설정된 레퍼런스는 TUI @ 자동완성에 나타납니다. @alias를 입력하여 레퍼런스 루트를 첨부하거나, @alias/를 입력하여 그 안의 파일을 검색하세요.

Compare this implementation with @sdk/src/client.ts

에이전트는 또한 설명이 있는 설정된 레퍼런스의 해석된 경로와 설명을 시스템 컨텍스트에서 받으므로, 사용자가 수동으로 첨부하지 않아도 관련이 있을 때 레퍼런스를 조사할 수 있습니다.

OpenCode는 외부 디렉터리 권한 경계를 통해 레퍼런스 디렉터리를 자동으로 허용합니다. 일반적인 도구 권한은 여전히 적용됩니다. 예를 들어, 파일을 편집할 수 없는 에이전트는 디렉터리가 레퍼런스로 설정되어 있다고 해서 편집 접근 권한을 얻지 않습니다.

설정 필드

레퍼런스 별칭은 비어 있거나 /, 공백, 백틱, 쉼표를 포함할 수 없습니다.