1
2
3
4
5
6
7
8
9

~/projects/
├── CLAUDE.md / AGENTS.md              ← 多仓库共享层
├── 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

当前工作目录：~/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

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

加载顺序：
  1. ~/.config/opencode/AGENTS.md                   ← 用户全局
  2. ~/projects/order-service/src/order/AGENTS.md   ← 当前目录
  3. ~/projects/order-service/src/AGENTS.md         ← 若存在
  4. ~/projects/order-service/AGENTS.md             ← git root，停止

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

1
2
3
4

@./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

{
  "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

~/.claude/CLAUDE.md
  → 个人偏好（沟通语言、代码风格）

~/projects/CLAUDE.md
  → 多仓库共享约定（技术栈、服务目录、跨服务调用约定）

~/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 模块直接调用
- 接口字段变更（新增除外）需同步更新所有调用方

 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

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

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

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

# 全局规范

## 技术栈
- Java 8 + Spring Boot 2.x，Feign Client 跨服务调用
- 统一响应结构：{ code, message, data }

## 服务目录
- user-service:8001   用户账户余额管理
- order-service:8002  订单生命周期
- notify-service:8003 消息通知

## 约定
- Feign Client 定义在 api 模块
- 接口变更必须同步更新调用方

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

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