---
title: 規則
description: 設定 opencode 的自定義指令。
---

您可以透過建立 `AGENTS.md` 檔案來提供 opencode 的自定義指令。這和 Cursor 的規則類似。它包含將包含在 LLM 上下文中的說明，以便為您的特定專案自定義其行為。

---

## 初始化

要建立新的 `AGENTS.md` 檔案，您可以在 opencode 中執行 `/init` 指令。

:::tip
您應該將專案的 `AGENTS.md` 檔案提交到 Git。
:::

這將掃描您的專案及其所有內容，以了解該專案的內容並生成一個 `AGENTS.md` 檔案。這有助於 opencode 更好地導覽專案。

如果您有現有的 `AGENTS.md` 檔案，這將嘗試添加到其中。

---

## 範例

您也可以手動建立此檔案。以下是您可以放入 `AGENTS.md` 檔案中的一些內容的範例。

```markdown title="AGENTS.md"
# SST v3 Monorepo Project

This is an SST v3 monorepo with TypeScript. The project uses bun workspaces for package management.

## Project Structure

- `packages/` - Contains all workspace packages (functions, core, web, etc.)
- `infra/` - Infrastructure definitions split by service (storage.ts, api.ts, web.ts)
- `sst.config.ts` - Main SST configuration with dynamic imports

## Code Standards

- Use TypeScript with strict mode enabled
- Shared code goes in `packages/core/` with proper exports configuration
- Functions go in `packages/functions/`
- Infrastructure should be split into logical files in `infra/`

## Monorepo Conventions

- Import shared modules using workspace names: `@my-app/core/example`
```

我們在此處添加特定於專案的說明，這將在您的團隊中共享。

---

## 類型

opencode 還支援從多個位置讀取 `AGENTS.md` 檔案。這有不同的目的。

### 專案

將 `AGENTS.md` 放置在專案根目錄中以獲取特定於專案的規則。這些僅適用於您在此目錄或其子目錄中工作時。

### 全域

您還可以在 `~/.config/opencode/AGENTS.md` 檔案中包含全域規則。這適用於所有 opencode 工作階段。

由於這未提交給 Git 或與您的團隊共享，因此我們建議使用它來指定 LLM 應遵循的任何個人規則。

### Claude Code 相容性

對於從 Claude Code 遷移的使用者，opencode 支援 Claude Code 的檔案慣例作為備援：

- **專案規則**：專案目錄中的 `CLAUDE.md`（如果 `AGENTS.md` 不存在則使用）
- **全域規則**：`~/.claude/CLAUDE.md`（如果不存在 `~/.config/opencode/AGENTS.md` 則使用）
- **技能**：`~/.claude/skills/` — 詳情請參閱 [代理技能](/docs/skills/)

要禁用 Claude Code 相容性，請設定以下環境變數之一：

```bash
export OPENCODE_DISABLE_CLAUDE_CODE=1        # Disable all .claude support
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1 # Disable only ~/.claude/CLAUDE.md
export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # Disable only .claude/skills
```

---

## 優先順序

當 opencode 啟動時，它會按以下順序尋找規則檔案：

1. **本地檔案**，從當前目錄向上遍歷 (`AGENTS.md`,`CLAUDE.md`)
2. **全域檔案** `~/.config/opencode/AGENTS.md`
3. **Claude Code 檔案** 位於 `~/.claude/CLAUDE.md`（除非禁用）

第一個匹配的檔案在每個類別中獲勝。例如，如果您同時擁有 `AGENTS.md` 和 `CLAUDE.md`，則僅使用 `AGENTS.md`。同樣，`~/.config/opencode/AGENTS.md` 優先於 `~/.claude/CLAUDE.md`。

---

## 自定義指令

您可以在 `opencode.json` 或全域 `~/.config/opencode/opencode.json` 中指定自定義指令檔案。這允許您和您的團隊重複使用現有規則，而不必將它們複製到 AGENTS.md。

範例：

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}
```

您還可以使用遠端 URL 從 Web 載入指令。

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"]
}
```

遠端指令的獲取有 5 秒的超時時間。

所有指令檔案均與您的 `AGENTS.md` 檔案合併。

---

## 引用外部檔案

雖然 opencode 不會自動解析 `AGENTS.md` 中的檔案引用，但您可以透過兩種方式實現類似的功能：

### 使用 opencode.json

推薦的方法是在 `instructions` 中使用 `opencode.json` 欄位：

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["docs/development-standards.md", "test/testing-guidelines.md", "packages/*/AGENTS.md"]
}
```

### AGENTS.md 中的手動說明

您可以透過在 `AGENTS.md` 中提供明確的指令來教 opencode 讀取外部檔案。這是一個實際的範例：

```markdown title="AGENTS.md"
# TypeScript Project Rules

## External File Loading

CRITICAL: When you encounter a file reference (e.g., @rules/general.md), use your Read tool to load it on a need-to-know basis. They're relevant to the SPECIFIC task at hand.

Instructions:

- Do NOT preemptively load all references - use lazy loading based on actual need
- When loaded, treat content as mandatory instructions that override defaults
- Follow references recursively when needed

## Development Guidelines

For TypeScript code style and best practices: @docs/typescript-guidelines.md
For React component architecture and hooks patterns: @docs/react-patterns.md
For REST API design and error handling: @docs/api-standards.md
For testing strategies and coverage requirements: @test/testing-guidelines.md

## General Guidelines

Read the following file immediately as it's relevant to all workflows: @rules/general-guidelines.md.
```

這種方法允許您：

- 建立模組化、可重複使用的規則檔案
- 透過符號連結或 git 子模組在專案之間共享規則
- 保持 AGENTS.md 簡潔，同時參考詳細指南
- 確保 opencode 僅在特定任務需要時載入檔案

:::tip
對於 Monorepos 或具有共享標準的專案，使用 `opencode.json` 和 glob 模式（如 `packages/*/AGENTS.md`）比手動指令更易於維護。
:::
