AI Agent 配置与指令文件路径参考

主流 Coding Agent 的指令文件、项目规则、用户配置和 Agent/Prompt 扩展路径速查；覆盖 Codex、Claude Code、OpenCode 与 GitHub Copilot，并强调不同文件的作用域和优先级。

#resource #evergreen #ai #windows #linux

[!info] related notes

所属 MOC: AI MOC, Agent MOC

Codex: OpenAI Codex

Claude Code: Claude Code

OpenCode: OpenCode

Copilot: GitHub Copilot

MCP: MCP 客户端配置

AI Agent 配置与指令文件路径参考

核验日期：2026-09-30。

这类路径和加载规则会随客户端版本变化。本文是速查，不替代官方文档；发现行为异常时优先运行客户端自带的 status/debug/context 命令并重新查官方文档。

先区分四类文件

类别	回答的问题
Instructions / Rules	Agent 做事时应遵守什么
Settings / Config	客户端、模型、权限、工具怎样运行
Agent profile	某个专门 Agent 的 prompt、model、tools、permissions
Prompt / Command / Skill	某个具体任务如何复用或按需加载

不要把项目行为规则、客户端设置和任务级流程混在同一个文件里。

一张表速查

工具	用户级 Instructions	项目级 Instructions	用户配置	项目配置
Codex	`~/.codex/AGENTS.md` / `AGENTS.override.md`	repo/root/subdir 的 `AGENTS.md` / `AGENTS.override.md`	`~/.codex/config.toml`	`.codex/config.toml`
Claude Code	`~/.claude/CLAUDE.md`	`CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md`, `AGENTS.md`, `.claude/rules/*.md`	`~/.claude/settings.json`	`.claude/settings.json`, `.claude/settings.local.json`
OpenCode	`~/.config/opencode/AGENTS.md`	workspace hierarchy 中的 `AGENTS.md`	`~/.config/opencode/opencode.json`	project root `opencode.json`
GitHub Copilot	`~/.copilot/copilot-instructions.md`（CLI）	`.github/copilot-instructions.md`, `.github/instructions/*/.instructions.md`, `AGENTS.md` 等	surface-specific	repo/IDE/CLI 各自配置

表格只表达主入口；不同 IDE、cloud agent、CLI 的支持面不完全相同。

Codex

Instructions

Codex 以 AGENTS.md 体系组织持久项目指导。

用户级：

~/.codex/AGENTS.md
~/.codex/AGENTS.override.md

项目级会从 repository root 到当前 working directory 按目录层级发现：

AGENTS.override.md
AGENTS.md
configured fallback filenames

更靠近当前工作目录的指令用于表达更窄的作用域。

Config

用户：~/.codex/config.toml
项目：.codex/config.toml

项目配置适合仓库级行为；用户配置适合机器和个人范围。

Claude Code

CLAUDE.md 与 AGENTS.md

当前 Claude Code 可以读取 CLAUDE.md，也支持 AGENTS.md。

常见层级：

~/.claude/CLAUDE.md

project/
├─ CLAUDE.md
├─ .claude/CLAUDE.md
├─ CLAUDE.local.md
└─ .claude/rules/
   ├─ testing.md
   └─ api.md

.claude/rules/**/*.md 适合模块化规则，并可按路径缩小作用域。

复杂、只在特定任务触发的多步骤流程更适合 skill，而不是全部永久塞进 CLAUDE.md。

Settings

用户：~/.claude/settings.json
团队共享：.claude/settings.json
个人项目覆盖：.claude/settings.local.json

另有 Claude Code 自己维护的 ~/.claude.json；它属于客户端内部/会话类状态，不应当作为普通团队设置文件维护。

OpenCode

Instructions

用户：~/.config/opencode/AGENTS.md
项目：AGENTS.md

项目中的 AGENTS.md 可以按 workspace / 子目录层级组织适用规则。

Config

用户：~/.config/opencode/opencode.json
项目：opencode.json

OpenCode 配置采用 merge 模型：后加载的高优先级来源覆盖冲突 key，其他 key 仍保留。

Agent profiles

全局：~/.config/opencode/agents/<name>.md
项目：.opencode/agents/<name>.md

Agent profile 适合专门 reviewer / planner / specialist，不应替代项目统一规则。

GitHub Copilot

Copilot customization 已经不只有一个 repository instruction 文件。

Repository-wide instructions

.github/copilot-instructions.md

Path-specific instructions

.github/instructions/**/*.instructions.md

Agent instructions

不同 surface 支持范围不同，常见包括：

AGENTS.md
CLAUDE.md
GEMINI.md

不要假设 IDE、code review、cloud agent 对三者支持完全一致。

Prompt files

.github/prompts/*.prompt.md

Prompt file 是可复用任务模板，不是 always-on rule。

Custom agents

.github/agents/<agent-name>.md

Skills

项目级常见：

.github/skills/<skill-name>/SKILL.md
.claude/skills/<skill-name>/SKILL.md
.agents/skills/<skill-name>/SKILL.md

Copilot CLI 用户级常见：

~/.copilot/skills/<skill-name>/SKILL.md
~/.agents/skills/<skill-name>/SKILL.md

Copilot CLI Personal Instructions

~/.copilot/copilot-instructions.md
~/.copilot/instructions/**/*.instructions.md

用户级 MCP 配置：

~/.copilot/mcp-config.json

怎么判断一个内容该放哪

项目所有任务都要遵守

例如构建命令、架构约束、测试要求：

→ Instructions / Rules。

客户端运行方式

例如 model、provider、permissions、MCP、sandbox：

→ Settings / Config。

只描述一个专门角色

例如 reviewer、planner：

→ Agent profile。

只在特定任务需要

例如 release、migration、design review：

→ Skill / Prompt / Command。

Monorepo 原则

不要在 repository root 写一份巨大规则文件，让所有任务永久加载。

更稳：

repo root
→ 全局架构/命令/共同规则

packages/frontend/
→ frontend-specific instructions

packages/backend/
→ backend-specific instructions

task-specific workflow
→ skill

作用域越窄的知识，越靠近真正适用的目录或按需扩展。

Windows / WSL

先确认 Agent 进程实际运行在哪个环境。

Windows native
→ Windows user home

WSL/Linux
→ Linux home

例如 Windows 的 C:\Users\user\.claude 与 WSL 的 /home/user/.claude 是两套不同路径。

最常见的错误

把 instructions 和 settings 混在一起；
把 team-shared config 与 personal override 混在一起；
把 task-specific 大流程塞进 always-on instructions；
假设所有产品都只认 AGENTS.md；
假设同一产品的 CLI / IDE / cloud surface 支持完全相同；
看到旧博客路径后直接照抄，不检查官方 current docs。

使用检查

排查“Agent 为什么没读到配置”时依次问：

这是 instruction、settings、agent profile 还是 skill？
当前运行的是 Windows native 还是 WSL/Linux？
当前 working directory / project root 在哪里？
目标文件是否位于该产品实际发现路径？
是否存在更高优先级或更具体 scope？
项目是否 trusted？
当前 surface（CLI/IDE/cloud）是否支持这种 customization？
能否用客户端 status/debug/context 命令确认最终加载结果？

官方资料入口

Codex: https://developers.openai.com/codex/guides/agents-md
Codex Config: https://developers.openai.com/codex/config-reference
Claude Code Memory: https://code.claude.com/docs/en/memory
Claude Code Settings: https://code.claude.com/docs/en/settings
OpenCode Config: https://opencode.ai/docs/config
OpenCode Instructions: https://opencode.ai/docs/instructions
GitHub Copilot customization: https://docs.github.com/en/copilot/reference/customization-cheat-sheet