1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
|
---
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`）比手動指令更易於維護。
:::
|
