跳到主要內容
maxstudioNews
AI 自動化DEV Community (Codex)約 17 分鐘

Claude Code、Cursor 與 Codex:從單一來源設定客製化子代理

Claude Code、Cursor 和 Codex 這三款工具都支援定義具備專屬指令與上下文視窗的客製化子代理。然而,這三款工具儲存子代理的方式與支援的欄位各有不同。本文將探討如何從單一來源設定子代理,並生成適用於這三款工具的檔案,同時點出常見的配置陷阱。

Claude Code、Cursor 與 Codex:從單一來源設定客製化子代理
圖片來源:DEV Community (Codex)

本文最初發表於 KitQuarry,由 Eliran Kotzero 為 KitQuarry 撰寫。簡而言之,Claude Code、Cursor 和 Codex 這三款工具都允許您定義具備專屬指令和上下文視窗的具名輔助代理(helper agent),但它們的儲存方式各不相同。

Claude Code 和 Cursor 使用帶有 YAML 前置資料(frontmatter)的 Markdown 檔案,而 Codex 則使用 TOML 檔案,且欄位僅部分重疊。「唯讀」功能在 Claude Code 中是工具清單,在 Cursor 中是唯讀旗標,而在 Codex 中則僅是指令。

以下將說明每款工具的查找位置、各欄位的功能、一個可從單一來源寫入這三種檔案的測試腳本,以及導致子代理靜默載入失敗的陷阱。

子代理(Subagent)還是技能(Skill)?技能會將指令新增到您目前的對話中。子代理則是一個獨立的工作者,它會以全新的上下文開始工作,完成任務後返回摘要,因此搜尋結果、日誌和檔案傾印(file dumps)不會佔用您的主執行緒。

Claude Code 的文件建議,當「次要任務會用您不會再次參考的搜尋結果、日誌或檔案內容淹沒您的主要對話」時,應使用子代理;當您「不斷生成具有相同指令的同類型工作者」時,則應使用客製化子代理。Cursor 的文件也做了同樣的區分:子代理用於長時間研究、平行工作和獨立檢查;技能則用於快速、單一目的的動作。

這三款工具都已內建輔助功能(Claude Code 的 Explore 和 Plan、Cursor 的 explore 和 browser、Codex 的 default、worker 和 explorer)。只有當您需要不同的指令或限制時,才應撰寫客製化的子代理。好的初始候選者包括無法編輯的審閱者、只報告失敗的測試執行器,以及只閱讀文件的研究員。

每款工具的查找位置:

專案:

Claude Code: .claude/agents/*.md

Cursor: .cursor/agents/*.md,以及 .claude/agents/ 和 .codex/agents/

Codex: .codex/agents/*.toml

個人:

Claude Code: ~/.claude/agents/

Cursor: ~/.cursor/agents/,~/.claude/agents/,~/.codex/agents/

Codex: ~/.codex/agents/

檔案格式:

Claude Code: Markdown,YAML 前置資料,主體 = 系統提示詞

Cursor: Markdown,YAML 前置資料,主體 = 提示詞

Codex: TOML,提示詞在 developer_instructions 中

相同名稱的處理方式:

Claude Code: 專案設定優先於個人設定;最接近工作目錄的巢狀 .claude/agents/ 勝出

Cursor: 專案設定優先於個人設定;.cursor/ 優先於 .claude/ 和 .codex/

Codex: 客製化代理若與內建代理同名(例如 explorer),則會取代內建代理

執行方式:

Claude Code: 在提示詞中命名,使用 @ 提及,或 claude --agent name

Cursor: 在提示詞中命名,或 name

Codex: 要求 Codex 以名稱生成;CLI 中的 /subagents 顯示執行緒

Claude Code 也會掃描 .claude/agents/ 的子資料夾,以及從工作目錄到儲存庫根目錄的所有 .claude/agents/,並透過 name 欄位而非檔案名稱來識別代理。Codex 也將 name 欄位作為事實的來源。當 name 遺失時,Cursor 會回退到使用檔案名稱。

每款工具讀取的欄位:

您想要的功能:

Claude Code:

必要欄位: name, description

何時委派: description

模型: model: sonnet, opus, haiku, fable, 完整的模型 ID, 或 inherit

不編輯檔案: tools 允許清單 (例如 Read, Grep, Glob) 或 disallowedTools: Write, Edit

在背景執行: background: true

額外功能: permissionMode, skills, mcpServers, hooks, memory, isolation: worktree, maxTurns, effort 等

Cursor:

必要欄位: 無 (name 預設為檔案名稱)

何時委派: description

模型: model: inherit (預設) 或模型 ID

不編輯檔案: readonly: true (不編輯檔案,不執行改變狀態的 shell 指令)

在背景執行: is_background: true

額外功能: 括號中的模型參數,例如 claude-opus-5[effort=high];features.shell_tool = false 和其他 features.* 開關;skills.config 關閉技能

Codex:

必要欄位: name, description, developer_instructions

何時委派: description (但請參閱下面的觸發條件)

模型: model 和 model_reasoning_effort;兩者都省略則使用父級設定

不編輯檔案: 無此欄位。沙盒來自父級會話

在背景執行: 非每個代理的欄位

額外功能: 無

這三款工具唯一共享的欄位是 name 和 description,以及提示詞本身。模型名稱也無法通用:sonnet 是 Claude Code 的別名,而 Cursor 接受 inherit 或模型 ID。在 Claude Code 和 Cursor 都可能讀取的 Markdown 檔案中,model: inherit 是兩者都支援的值。

陷阱一:唯讀功能在各工具中定義不同。Claude Code 透過工具清單強制執行唯讀。tools: Read, Grep, Glob 會讓子代理無法寫入檔案。若新增 Bash,它又可以透過 shell 更改檔案,因此請使用 permissions.deny 規則或 PreToolUse hook 來阻擋重要操作。

請注意,disallowedTools: Bash(git push *) 會移除整個 Bash 工具,而不僅僅是該指令。當您的主會話處於 bypassPermissions、acceptEdits 或 auto 模式時,permissionMode 會被忽略:子代理將以相同的模式執行。

Cursor 只有一個開關:readonly: true 會限制檔案編輯和改變狀態的 shell 指令。Codex 無法針對每個代理設定唯讀。子代理會繼承父級回合的沙盒和批准設定,而自訂代理檔案中的 sandbox_mode、approval_policy 或 mcp_servers 不會覆寫這些設定。

用文件中的話來說,自訂代理指令「可以要求代理避免編輯,但它們不會建立單獨的唯讀沙盒。」如果審閱者絕對不能寫入,請在委派之前以唯讀沙盒模式執行會話。

陷阱二:Cursor 也會讀取 Claude Code 的資料夾。Cursor 會載入 .claude/agents/ 以實現相容性,因此一個僅包含 Claude Code 子代理的儲存庫,其子代理也會在 Cursor 中可用。但 Cursor 的文件僅列出 name、description、model、readonly 和 is_background 這些欄位。

文件沒有說明 Cursor 如何處理僅限 Claude 的欄位(例如 tools),因此不要指望 Claude 的工具允許清單能讓代理在 Cursor 中變成唯讀。請在 .cursor/agents/ 中放置一個同名且設定 readonly: true 的 Cursor 副本:當名稱衝突時,Cursor 會使用 .cursor/ 檔案。

Cursor 也列出了 .codex/agents/,但其文件僅將子代理描述為 Markdown 檔案,並未說明是否讀取 Codex 的 TOML 檔案。我們無法確認這點,因此下面的腳本無論如何都會寫入一個 Cursor 檔案。

陷阱三:Codex 需要被明確要求。當任務與子代理的 description 相符時,Claude Code 和 Cursor 會自行委派,兩者的文件都建議使用「主動使用」等詞語來鼓勵這種行為。Codex 的文件指出,目前的本地版本會在「您直接要求或適用的 AGENTS.md 或技能指令提出請求」時生成子代理。

因此,對於 Codex,請將觸發條件新增到您的指令中,例如在 AGENTS.md 中加入:「更改程式碼後,在更改的檔案上生成 code-reviewer 代理,並在完成前修復其 Critical 發現。」

每個子代理都會執行自己的模型和工具工作,因此這三份文件都警告說,子代理比單一代理使用更多的 token。建議從兩三個子代理開始;Cursor 的文件將 50 個以上模糊的子代理稱為反模式,而 Claude Code 則會在啟動時,當所有客製化子代理的 description 總和超過 15,000 token 時發出警告。

陷阱四:Claude Code 會靜默跳過損壞的檔案。Claude Code 會「不報告錯誤」地忽略它不認識的前置資料欄位,因此 disallowed-tools 或 maxturns 等設定將不起作用。它還會在以下情況下跳過整個檔案,且會話中不會顯示任何訊息:沒有 name(它會將檔案視為文件),或者有 name 但沒有 description;開頭的 --- 不在第一行;name 以 - 開頭、包含 : 或超過 256 個字元;YAML 解析失敗。

執行 claude --debug 並搜尋日誌,或者使用 claude plugin validate .claude/agents 檢查資料夾(v2.1.233 或更高版本;它不會標記缺少 name 的情況)。如果您剛建立 agents 資料夾,請重新啟動:正在運行的會話只會監控啟動時已存在的資料夾。

單一來源,三種檔案。將每個子代理只保留一份在 agents-src/ 中,僅包含在所有地方都意義相同的欄位,然後生成三種原生檔案。來源格式刻意設計得很小:name、description 和一個可選的 readonly,然後是提示詞。

agents-src/code-reviewer.md:

---

name: code-reviewer

description: 審閱更改的程式碼是否存在錯誤、安全問題和缺少測試,不進行任何編輯。在程式碼更改後主動使用,或當使用者要求審閱當前差異時使用。

readonly: true

---

您是一位資深程式碼審閱者。您只負責審閱,絕不修改。

1. 閱讀父代理指定的所有檔案,以及每個更改所呼叫的程式碼。

2. 尋找錯誤、未處理的錯誤、安全問題(機密資訊、注入攻擊、缺少身份驗證檢查)以及沒有測試的行為更改。

3. 跳過樣式註解,除非它們隱藏了真正的錯誤。請將發現的問題分為「嚴重(Critical)」、「警告(Warning)」和「建議(Suggestion)」三組回覆。針對每個問題提供檔案:行號,並說明如何修復。如果沒有發現任何問題,請用一行文字說明。

scripts/sync_agents.py (Python 3,無需額外套件):

#!/usr/bin/env python3

"""從 agents-src/*.md 生成 Claude Code、Cursor 和 Codex 子代理檔案。

python3 scripts/sync_agents.py write .claude/agents, .cursor/agents, .codex/agents

python3 scripts/sync_agents.py --check 如果任何生成的檔案遺失或過期則退出並回傳 1

"""

import json, pathlib, re, sys

ROOT = pathlib.Path(__file__).resolve().parent.parent # repo root (script lives in scripts/)

SRC = ROOT / "agents-src"

KEYS = {"name", "description", "readonly"}

NAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")

CLAUDE_READONLY_TOOLS = "Read, Grep, Glob"

CODEX_READONLY_NOTE = "Do not edit files or run commands that change files, git state or anything outside the repo."

def parse(path):

text = path.read_text(encoding="utf-8")

m = re.match(r"---

(.*?)

---

(.*)", text, re.S)

if not m:

sys.exit(f"{path}: must start with a --- frontmatter block")

meta = {}

for line in m.group(1).splitlines():

if not line.strip():

continue

key, sep, value = line.partition(":")

key, value = key.strip(), value.strip()

if not sep or key not in KEYS:

sys.exit(f"{path}: unknown or malformed line {line!r} (allowed keys: {', '.join(sorted(KEYS))})")

meta[key] = value.strip('"')

for key in ("name", "description"):

if not meta.get(key):

sys.exit(f"{path}: missing {key}")

if not NAME_RE.match(meta["name"]):

sys.exit(f"{path}: name must be lowercase letters, digits and single hyphens")

if meta.get("readonly", "false") not in ("true", "false"):

sys.exit(f"{path}: readonly must be true or false")

meta["readonly"] = meta.get("readonly") == "true"

meta["body"] = m.group(2).strip() + "

"

return meta

def q(s): # a double-quoted string that is valid in both YAML and TOML

return json.dumps(s, ensure_ascii=True)

def claude(a):

lines = [

"---",

f"name: {a['name']}",

f"description: {q(a['description'])}",

"model: inherit",

]

if a["readonly"]:

lines.append(f"tools: {CLAUDE_READONLY_TOOLS}")

return "

".join(lines + ["---", "", a["body"]])

def cursor(a):

lines = [

"---",

f"name: {a['name']}",

f"description: {q(a['description'])}",

"model: inherit",

]

if a["readonly"]:

lines.append("readonly: true")

return "

".join(lines + ["---", "", a["body"]])

def codex(a):

body = (CODEX_READONLY_NOTE + "

" if a["readonly"] else "") + a["body"]

instr = f"'''

{body}'''" if "'''" not in body else q(body)

return f"name = {q(a['name'])}

description = {q(a['description'])}

developer_instructions = {instr}

"

TARGETS = [

(".claude/agents", ".md", claude),

(".cursor/agents", ".md", cursor),

(".codex/agents", ".toml", codex),

]

def main():

check = "--check" in sys.argv[1:]

agents = [parse(p) for p in sorted(SRC.glob("*.md"))]

if not agents:

sys.exit(f"no agents in {SRC}")

names = [a["name"] for a in agents]

if len(set(names)) != len(names):

sys.exit("duplicate agent names in agents-src/")

stale = 0

for folder, ext, render in TARGETS:

out = ROOT / folder

out.mkdir(parents=True, exist_ok=True)

for a in agents:

f, want = out / (a["name"] + ext), render(a)

have = f.read_text(encoding="utf-8") if f.exists() else None

if have == want:

continue

stale += 1

if check:

print(f"out of date: {f.relative_to(ROOT)}")

else:

f.write_text(want, encoding="utf-8")

if check and stale:

sys.exit(1)

if __name__ == "__main__":

main()

Share

覺得值得一看?分享給朋友。

以上為 AI 自動翻譯導讀。原文版權歸 DEV Community (Codex) 所有, 建議透過「閱讀原文」前往原始網站,以取得最完整資訊並支持原作者。

Newsletter

不用每天追,AI 重點每週寄給你

43 個來源、每 2 小時更新,太多看不完。電子報每週挑最值得看的幾則,附上 Max 的看法。

每週一封。Email 只用來寄電子報,每封信都能一鍵退訂。