1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

多仓库场景示例（每个服务是独立的 git repo）：

~/projects/
├── CLAUDE.md / AGENTS.md              ← 多仓库共享层（projects 目录）
├── order-service/                      ← git repo ①
│   ├── CLAUDE.md / AGENTS.md          ← 项目级
│   └── src/
│       └── order/
│           └── CLAUDE.md              ← 子模块级（当前工作目录）
└── notify-service/                     ← git repo ②
    └── CLAUDE.md / AGENTS.md          ← 项目级

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

当前工作目录：~/projects/order-service/src/order/

加载顺序（启动时全量加载）：
  1. ~/.claude/CLAUDE.md                           ← 用户全局（独立加载，非遍历结果）
  2. ~/projects/CLAUDE.md                          ← 多仓库共享层（实测验证：越过 git root 继续向上）
  3. ~/projects/order-service/CLAUDE.md            ← 项目根目录
  4. ~/projects/order-service/src/CLAUDE.md        ← 遍历沿途（如存在）
  5. ~/projects/order-service/src/order/CLAUDE.md  ← 当前工作目录

子目录懒加载（按需）：
  当 Claude 读取 src/payment/ 中的文件时，
  才加载 src/payment/CLAUDE.md（如果存在）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

~/.claude/CLAUDE.md                    → 个人偏好，所有项目通用（语言、风格）

~/projects/CLAUDE.md                   → 多仓库共享约定
                                          - 技术栈统一规范
                                          - 服务目录（所有服务地址、职责）
                                          - 跨服务 HTTP 调用约定
                                          - 接口变更协作流程

~/projects/order-service/CLAUDE.md    → 本服务内容
                                          - 本服务职责与模块结构
                                          - 本服务对外暴露的接口
                                          - 本服务依赖的上游接口契约（重点！）

~/projects/order-service/src/*/CLAUDE.md → 子模块特殊说明（可选）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# 多服务共享规范

## 技术栈
- Java 8 + Spring Boot 2.x
- 服务间通信：HTTP REST，统一使用 Feign Client
- 统一响应结构：{ code: int, message: String, data: T }

## 服务目录
| 服务 | 职责 | 内网地址 |
|------|------|----------|
| user-service    | 用户账户、余额管理 | http://user-service:8001    |
| order-service   | 订单生命周期管理   | http://order-service:8002   |
| notify-service  | 短信/Push 通知     | http://notify-service:8003  |

## 跨服务开发约定
- 修改任何对外接口前，先确认所有下游调用方
- Feign Client 定义在各服务的 api 模块，不在 core 模块直接 HTTP 调用
- 接口字段变更（新增除外）需同步更新所有调用方

 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

# order-service

## 本服务职责
管理订单全生命周期：创建 → 支付确认 → 发货 → 完成 / 取消

## 模块结构
- order-api    对外 Feign Client 接口定义（供其他服务引用）
- order-core   业务逻辑层
- order-server 启动入口 + Controller

## 本服务对外接口
- POST /api/orders              创建订单
- PUT  /api/orders/{id}/pay    支付回调
- GET  /api/orders/{id}         查询订单详情

## 依赖的上游接口（修改时需同步）

### user-service
- GET  /api/users/{id}/balance
  响应：{ code: 0, data: { balance: BigDecimal } }
- POST /api/users/{id}/balance/freeze
  请求：{ amount: BigDecimal, orderId: String }
  响应：{ code: 0, data: { freezeId: String } }

### notify-service
- POST /api/notify/send
  请求：{ userId: String, type: "ORDER_CREATED"|"ORDER_PAID", bizId: String }
  响应：{ code: 0, data: { msgId: String } }

1
2
3
4
5
6
7
8

当前工作目录：~/projects/order-service/src/order/

加载顺序（仅三个固定路径，按顺序合并）：
  1. ~/.codex/AGENTS.md                      ← 用户全局
  2. ~/projects/order-service/AGENTS.md      ← git 仓库根目录
  3. ~/projects/order-service/src/order/AGENTS.md ← 当前工作目录（与仓库根不同时）

不会加载 ~/projects/AGENTS.md（不在固定路径内，直接忽略）。

1
2
3
4
5
6
7
8
9

~/.codex/AGENTS.md                     → 必须承担所有跨项目内容
                                          - 技术栈规范
                                          - 服务目录
                                          - 跨服务约定
                                          （内容较多时注意 token 消耗）

~/projects/order-service/AGENTS.md    → 本服务内容
                                          - 本服务职责与接口
                                          - 依赖的上游接口契约

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

当前工作目录：~/projects/order-service/src/order/

加载顺序：
  1. ~/.config/opencode/AGENTS.md              ← 用户全局
  2. 从当前目录向上遍历至 git root，每层取一个文件
     - ~/projects/order-service/src/order/AGENTS.md  ← 当前目录
     - ~/projects/order-service/src/AGENTS.md         ← 若存在
     - ~/projects/order-service/AGENTS.md              ← git root，停止
  3. opencode.json 中 instructions 字段引用的额外文件

不会加载 ~/projects/AGENTS.md（遍历止于 git root）。

1
2
3
4
5
6
7
8
9

~/projects/
├── _shared/                               ← 共享契约目录（非 git repo）
│   ├── conventions.md                     ← 技术栈、服务目录、跨服务约定
│   └── api-contracts/
│       ├── user-service.md
│       └── notify-service.md
└── order-service/
    ├── AGENTS.md                          ← 本服务职责与对外接口
    └── opencode.json                      ← 通过 instructions 引入共享内容

1
2
3
4
5
6
7
8
9

// ~/projects/order-service/opencode.json
{
  "instructions": [
    "./AGENTS.md",
    "~/_shared/conventions.md",
    "~/_shared/api-contracts/user-service.md",
    "~/_shared/api-contracts/notify-service.md"
  ]
}

1
2
3
4
5
6
7
8
9

// opencode.json
{
  "instructions": [
    "./AGENTS.md",
    "./docs/coding-standards.md",
    "packages/*/AGENTS.md",
    "https://example.com/shared-rules.md"
  ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

优先级从高到低：

① 系统托管（不可被覆盖）
   macOS:   /Library/Application Support/ClaudeCode/managed-settings.json
   Linux:   /etc/claude-code/managed-settings.json
   Windows: C:\Program Files\ClaudeCode\managed-settings.json
            HKLM\SOFTWARE\Policies\ClaudeCode（注册表）

② 命令行参数（临时会话级覆盖）

③ 本地项目（个人私有，git 忽略）
   .claude/settings.local.json

④ 共享项目（团队共享，git 追踪）
   .claude/settings.json

⑤ 用户全局（最低优先级）
   ~/.claude/settings.json

1
2

CLAUDE.md      → 目录向上遍历，沿途所有文件全部加载（越过 git root 继续）
settings.json  → 固定 4 个路径，不做任何目录遍历

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

~/projects/
├── CLAUDE.md                          ✅ 会被加载（目录遍历）
├── .claude/settings.json              ❌ 不会被加载（不在固定路径）
│
├── order-service/                     git repo ①
│   ├── CLAUDE.md                      ✅ 会被加载
│   └── .claude/
│       ├── settings.json              ✅ 项目级权限（团队共享）
│       └── settings.local.json        ✅ 本地个人权限（git 忽略）
│
└── notify-service/                    git repo ②
    ├── CLAUDE.md                      ✅ 会被加载
    └── .claude/
        └── settings.json              ✅ 项目级权限（团队共享）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

// ~/.claude/settings.json（对所有项目生效）
{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(mvn *)",
      "Bash(npm run *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Read(./.env*)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(kubectl *)"
    ]
  }
}

1
2
3
4
5
6
7
8
9

// ~/projects/order-service/.claude/settings.json（仅 order-service 生效）
{
  "permissions": {
    "allow": [
      "Bash(java *)",
      "Bash(mvn spring-boot:run)"
    ]
  }
}

1
2
3
4
5
6
7
8
9

// ~/projects/order-service/.claude/settings.local.json（个人本地，不提交 git）
{
  "permissions": {
    "allow": [
      "Bash(ssh *)",
      "Read(~/.ssh/config)"
    ]
  }
}

1
2
3
4
5
6
7
8
9

Codex CLI 没有权限配置文件，权限控制完全依赖启动参数：

  --approval-mode suggest    所有操作需用户确认（默认）
  --approval-mode auto-edit  文件编辑自动批准，shell 命令需确认
  --approval-mode full-auto  全自动执行（依赖 OS 沙箱隔离）

沙箱机制：
  macOS：Seatbelt（系统调用级别隔离）
  Linux：Docker 容器隔离

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

加载顺序（优先级从低到高）：

① 远程组织配置（最低）
   .well-known/opencode（通过 HTTP 拉取，组织级默认值）

② 用户全局配置
   ~/.config/opencode/opencode.json

③ 环境变量指定路径
   $OPENCODE_CONFIG 指向的文件

④ 项目配置（从当前目录向上遍历查找）
   ./opencode.json

⑤ .opencode 目录（agents/, commands/, plugins/ 等子目录）

⑥ 内联配置（最高）
   $OPENCODE_CONFIG_CONTENT 环境变量内容

 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

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(npm run *)",           // Bash 命令，支持通配符
      "Bash(git commit *)",
      "Read(./src/**)",            // 文件读取，gitignore 风格
      "Read(~/.zshrc)",            // 波浪号路径
      "Edit(/src/**/*.java)",      // 文件编辑
      "WebFetch(domain:github.com)", // 域名匹配
      "Glob(**/*.ts)",             // 文件搜索
      "Grep(./src/**)",            // 内容搜索
      "mcp__server__toolname"      // MCP 工具
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Read(./.env*)",             // 拒绝读取环境变量文件
      "Read(./secrets/**)"
    ],
    "ask": [
      "Bash(git push *)",          // 敏感操作需二次确认
      "Bash(docker *)"
    ]
  }
}

 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

// opencode.json
{
  "permission": {
    // 工具级别全局设置
    "read":      "allow",
    "edit":      "ask",
    "glob":      "allow",
    "grep":      "allow",
    "list":      "allow",
    "webfetch":  "ask",
    "task":      "allow",
    "lsp":       "allow",

    // bash 细粒度规则（最后匹配生效）
    "bash": {
      "*":              "ask",     // 默认：所有命令需确认
      "git status":     "allow",   // 精确匹配
      "git *":          "allow",   // 通配符
      "npm run *":      "allow",
      "rm *":           "deny",    // 拒绝危险命令
      "rm -rf *":       "deny"
    },

    // 全局快捷设置（覆盖所有工具）
    // "permission": "allow"       // 全部放行
    // "permission": "ask"         // 全部询问
    // "permission": "deny"        // 全部拒绝
  }
}

1
2
3
4
5
6
7

# 无配置文件，仅启动参数
codex --approval-mode suggest    # 全部询问（默认）
codex --approval-mode auto-edit  # 文件编辑自动放行
codex --approval-mode full-auto  # 沙箱内全自动

# 沙箱说明：
# full-auto 模式下网络访问被完全禁止，文件系统访问受 OS 限制

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

数组类字段（跨层级合并，去重）：
  permissions.allow
  permissions.deny
  permissions.ask
  sandbox.filesystem.allowWrite / denyWrite / denyRead
  hooks（各事件的 hook 列表）
  环境变量数组

示例：
  managed-settings.json:  allow: ["Bash(//opt/company-tools/*)"]
  ~/.claude/settings.json: allow: ["Bash(npm run *)"]
  .claude/settings.json:   allow: ["Bash(git *)"]
  最终生效：               allow: ["Bash(//opt/company-tools/*)", "Bash(npm run *)", "Bash(git *)"]

标量字段（高优先级完全覆盖低优先级）：
  model、theme 等配置项

deny 的特殊地位：
  任何层级的 deny 规则均生效，低层级无法解除 managed 的 deny

 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

~/.config/opencode/opencode.json（用户全局）：
{
  "permission": {
    "read":  "allow",
    "edit":  "allow",
    "bash": {
      "*":       "ask",      // 默认所有 bash 命令需确认
      "git *":   "allow"     // git 命令放行
    }
  }
}

./opencode.json（项目级）：
{
  "permission": {
    "webfetch": "deny",      // 项目级禁止 HTTP 请求
    "bash": {
      "npm run *": "allow"   // 项目级追加：npm 命令放行
    }
  }
}

合并结果：
{
  "permission": {
    "read":     "allow",     // 来自全局
    "edit":     "allow",     // 来自全局
    "webfetch": "deny",      // 来自项目（新增字段）
    "bash": {
      "*":         "ask",    // 来自全局
      "git *":     "allow",  // 来自全局
      "npm run *": "allow"   // 来自项目（追加）
    }
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

合并后的 bash 规则：
  "*":         "ask"     ← 通配兜底
  "git *":     "allow"   ← 覆盖通配，git 命令放行
  "npm run *": "allow"   ← 覆盖通配，npm 命令放行

执行 "git commit -m fix" 时：
  匹配 "*"       → ask
  匹配 "git *"   → allow    ← 最后匹配，最终生效 ✅

执行 "curl http://..." 时：
  匹配 "*"       → ask      ← 只有这一条匹配，最终生效 ✅

执行 "rm -rf /tmp" 时：
  匹配 "*"       → ask      ← 最终生效 ✅（没有更具体的规则覆盖）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

opencode.json：
{
  "permission": {
    "bash": { "*": "ask", "git *": "allow" }   // 全局权限
  },
  "agent": {
    "reviewer": {
      "permission": {
        "read": "allow",
        "bash": "deny",    // ← 直接覆盖，不与全局 bash 规则合并
        "edit": "deny"
      }
    }
  }
}

reviewer agent 最终权限：
  read:  "allow"   ← 来自 agent 定义
  bash:  "deny"    ← 来自 agent 定义（全局的 git * allow 被完全忽略）
  edit:  "deny"    ← 来自 agent 定义

默认 agent 最终权限：
  bash:  { "*": "ask", "git *": "allow" }  ← 使用全局规则

 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

// .claude/settings.json（项目级，团队共享）
{
  "model": "claude-opus-4-6",

  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(mvn *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Read(./**)",
      "Edit(./src/**)",
      "Glob(**/*.java)",
      "Grep(./src/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push *)",
      "Bash(curl *)",
      "Read(./.env*)",
      "Read(./secrets/**)",
      "Read(./credentials/**)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(docker *)",
      "Bash(kubectl *)",
      "WebFetch(*)"
    ]
  },

  "env": {
    "JAVA_HOME": "/usr/lib/jvm/java-8-openjdk",
    "MAVEN_OPTS": "-Xmx2g"
  }
}

1
2
3
4
5
6
7
8
9

// .claude/settings.local.json（本地私有，git 忽略）
{
  "permissions": {
    "allow": [
      "Bash(ssh *)",
      "Read(~/.ssh/config)"
    ]
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

启动时加载（全量，按优先级从低到高）：
  /etc/claude-code/CLAUDE.md              → 系统策略
  ~/.claude/CLAUDE.md                     → 用户全局
  ~/projects/CLAUDE.md                    → 中间路径（如存在）
  ~/projects/my-app/CLAUDE.md             → 项目根目录
  ~/projects/my-app/src/api/CLAUDE.md     → 当前工作目录

按需加载（访问时触发）：
  ~/projects/my-app/src/auth/CLAUDE.md    → 当 Claude 读取 auth/ 中文件时加载
  ~/projects/my-app/test/CLAUDE.md        → 当 Claude 读取 test/ 中文件时加载

1
2
3
4
5

<!-- CLAUDE.md 中引用其他文件 -->
@./docs/coding-standards.md
@./docs/api-guidelines.md
@~/.claude/personal-preferences.md
@/absolute/path/to/shared-rules.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# 基础使用
codex "帮我重构这个函数"
codex --model gpt-4o "解释这段代码"

# 权限模式
codex --approval-mode suggest    # 默认：所有操作需确认
codex --approval-mode auto-edit  # 文件编辑自动批准
codex --approval-mode full-auto  # 全自动（需沙箱支持）

# 沙箱控制
codex --no-sandbox               # 禁用沙箱（不推荐）

# 上下文控制
codex --context ./README.md      # 指定额外上下文文件
codex --cwd ./src                # 指定工作目录

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# Project Rules

## Tech Stack
- Node.js 18+, TypeScript 5.x
- Express.js for REST APIs
- Prisma ORM with PostgreSQL

## Coding Standards
- Use async/await, avoid callbacks
- All functions must have TypeScript types
- Test files: *.test.ts

## Git Conventions
- Commit format: feat/fix/docs/refactor: description
- Never commit directly to main

 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

// opencode.json（项目级）
{
  // 默认模型
  "model": "anthropic/claude-sonnet-4-6",
  "small_model": "anthropic/claude-haiku-4-5",

  // 权限配置
  "permission": {
    "read":     "allow",
    "edit":     "allow",
    "glob":     "allow",
    "grep":     "allow",
    "list":     "allow",
    "webfetch": "ask",
    "bash": {
      "*":              "ask",
      "git *":          "allow",
      "npm run *":      "allow",
      "yarn *":         "allow",
      "cat *":          "allow",
      "ls *":           "allow",
      "find *":         "allow",
      "rm -rf *":       "deny",
      "curl *":         "deny",
      "wget *":         "deny"
    }
  },

  // 额外指令文件（支持 glob 和 URL）
  "instructions": [
    "./AGENTS.md",
    "./docs/coding-standards.md",
    "packages/*/AGENTS.md"
  ],

  // 自定义 Agent
  "agent": {
    "reviewer": {
      "model": "anthropic/claude-opus-4-6",
      "prompt": "You are a strict code reviewer focused on security and performance.",
      "permission": {
        "read":  "allow",
        "edit":  "deny",
        "bash":  "deny"
      }
    }
  },

  // MCP 服务器
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["mcp-server-filesystem", "./"]
    }
  },

  // 自动更新
  "autoupdate": true,

  // 文件快照（用于变更追踪）
  "snapshot": true
}

 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

{
  // 全局权限：bash 默认询问
  "permission": {
    "bash": { "*": "ask" }
  },

  "agent": {
    // build agent：继承全局 + 扩展允许
    "build": {
      "permission": {
        "bash": {
          "*":         "ask",     // 继承全局
          "npm *":     "allow",   // agent 扩展
          "make *":    "allow"
        }
      }
    },
    // plan agent：只读，覆盖全局
    "plan": {
      "permission": {
        "read":  "allow",
        "edit":  "deny",
        "bash":  "deny"
      }
    }
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

Claude Code（首个匹配）：
  规则顺序：deny → ask → allow
  第一个匹配的规则立即生效，后续规则被忽略
  适合：明确的白名单/黑名单，规则顺序无歧义

  示例：
    deny:  ["Bash(rm *)"]
    allow: ["Bash(rm -rf /tmp/*)"]  ← 永远不会生效（已被 deny 首先匹配）

OpenCode（最后匹配）：
  同一工具下，越靠后的规则优先级越高
  适合：从宽泛默认逐步精细化覆盖

  示例：
    "bash": {
      "*":            "ask",       // 默认询问
      "rm *":         "deny",      // 拒绝 rm
      "rm /tmp/*":    "allow"      // 最后匹配：/tmp 下 rm 允许 ✅
    }

1
2
3
4
5
6
7
8
9

权限体系成熟度：
  Claude Code  ████████████  最完整，企业级
  OpenCode     ████████░░░░  快速迭代，功能完善
  Codex CLI    ████░░░░░░░░  简单，靠 OS 沙箱兜底

指令文件机制：
  Claude Code  ████████████  最完整，懒加载 + Import
  Codex CLI    ████████░░░░  简单直接，全量合并
  OpenCode     ███████░░░░░  灵活，兼容性好，合并需显式配置