十几个微服务放心交给 AI Agent：一套四层防线方案

services/
├── gateway/          # API 网关，HTTP → gRPC 转换
├── auth/             # 认证授权，JWT 签发
├── user/             # 用户管理
├── org/              # 组织/团队管理
├── billing/          # 计费订阅
├── payment/          # 支付处理（支付宝/微信/Stripe）
├── order/            # 订单生命周期
├── inventory/        # 库存管理
├── notification/     # 短信/邮件/推送
├── workflow/         # 工作流引擎
├── analytics/        # 数据分析
├── scheduler/        # 定时任务调度
└── shared/           # 公共库（proto 定义、工具函数）

# Payment Service

## 职责
处理支付创建、回调、退款。不处理订单状态变更（order 服务负责）。
不支持直接退款超过 72 小时的订单（需人工审批流程）。

## 架构约束
- 支付结果通过 gRPC 回调通知 order 服务，不直接写 order 的数据库
- 支付状态机：PENDING → SUCCESS / FAILED / REFUNDING → REFUNDED
- 所有金额使用 int64（分为单位），禁止使用 float64

## 关键文件
- internal/handler/     — HTTP 回调处理器（支付宝/微信/Stripe webhook）
- internal/service/     — 业务逻辑层
- internal/client/      — gRPC 客户端（调用其他服务）
- api/proto/payment.proto — API 契约定义

## 构建 & 测试
go build ./...                    # 编译
go test ./...                     # 单元测试
go test -tags=integration ./...   # 集成测试（需 docker compose up）

## 绝对不能做的事
- 不要修改 webhook 的 URL 路径，支付平台那边配死了
- 不要在 handler 里直接操作数据库，走 service 层
- 不要修改 shared/protos/ 下的 proto 文件（由架构组统一管理）
- 不要添加新的支付渠道，需要架构评审

# 系统架构概述

本仓库包含 13 个微服务，Go 编写，gRPC 通信。

## 服务列表
- gateway/      — HTTP 入口，路由转发
- auth/         — 认证（JWT + OAuth2）
- user/         — 用户 CRUD
- org/          — 组织管理
- billing/      — 计费逻辑
- payment/      — 支付处理（对接外部支付平台）
- order/        — 订单状态机
- inventory/    — 库存扣减
- notification/ — 通知发送（站内信/短信/邮件）
- workflow/     — 工作流引擎（DAG 执行）
- analytics/    — 数据聚合分析
- scheduler/    — 定时任务
- shared/       — 公共 proto 定义 + 工具库

## 服务间通信规则
- 所有服务间调用走 gRPC，禁止直接访问其他服务的数据库
- 领域事件通过 workflow 服务的消息总线传递
- shared/protos/ 下的 proto 文件修改需要架构评审

## Agent 工作规范
- 修改任何服务前，先读该服务目录下的 AGENTS.md
- 跨服务变更必须列出涉及的所有服务和修改点
- 每次 session 结束前：跑测试 → git commit（描述性信息）
- 不要直接修改 shared/ 下的公共库
- 遇到不确定的架构决策，停下来问，不要猜

{
  "story": "用户下单成功后发送站内通知",
  "created": "2026-06-15",
  "features": [
    {
      "id": "f1",
      "service": "order",
      "desc": "订单状态变为 SUCCESS 时，通过 gRPC 调用 notification 服务",
      "acceptance": "单元测试：mock gRPC client，验证调用参数正确",
      "passes": false
    },
    {
      "id": "f2",
      "service": "notification",
      "desc": "新增 SendOrderSuccess 接口，接收订单 ID 和用户 ID",
      "acceptance": "单元测试：验证创建站内通知记录",
      "passes": false
    },
    {
      "id": "f3",
      "service": "notification",
      "desc": "proto 文件添加 SendOrderSuccess 方法定义",
      "acceptance": "protoc 编译通过，生成代码无冲突",
      "passes": false
    },
    {
      "id": "f4",
      "service": "order",
      "desc": "集成测试：创建订单 → 验证 notification 被调用",
      "acceptance": "集成测试通过",
      "passes": false
    }
  ]
}

#!/bin/bash
# create-agent-workspace.sh
# 用法: ./create-agent-workspace.sh agent-1 payment

AGENT_NAME=$1
SERVICE_SCOPE=$2  # 可选，限定某个服务目录
WORKSPACE_ROOT=/tmp/agent-workspaces

WORKSPACE_DIR="${WORKSPACE_ROOT}/${AGENT_NAME}"

# 用 shallow clone + reference 创建隔离副本
git clone --depth=50 --reference=. . "${WORKSPACE_DIR}"

# 如果指定了服务范围，只保留相关文件以减少干扰
if [ -n "$SERVICE_SCOPE" ]; then
    # 在 CLAUDE.md 里记录工作范围
    echo "" >> "${WORKSPACE_DIR}/CLAUDE.md"
    echo "## 当前任务范围" >> "${WORKSPACE_DIR}/CLAUDE.md"
    echo "本次 session 只修改 services/${SERVICE_SCOPE}/ 目录。" >> "${WORKSPACE_DIR}/CLAUDE.md"
    echo "不要修改其他服务。" >> "${WORKSPACE_DIR}/CLAUDE.md"
fi

echo "Agent workspace created: ${WORKSPACE_DIR}"
echo "Start Claude Code with: cd ${WORKSPACE_DIR} && claude"

# Agent-1 做支付相关的工作
./create-agent-workspace.sh agent-1 payment

# Agent-2 做订单相关的工作（同时进行）
./create-agent-workspace.sh agent-2 order

# 各自启动 Claude Code
cd /tmp/agent-workspaces/agent-1 && claude
cd /tmp/agent-workspaces/agent-2 && claude

cd /tmp/agent-workspaces/agent-1
# 创建 feature branch 并 push
git checkout -b agent-1/payment-refactor
git push origin agent-1/payment-refactor
# 然后在主仓库 merge 或 create PR

## 调试规范：Trace, Don't Patch

当修复一个 bug 时，Agent 必须遵守以下步骤：
1. 找到错误首次出现的位置（生产者/源头）
2. 理解数据从生产者到消费者的完整流转路径
3. 在生产者端修复根本原因
4. 如果消费者端需要添加防御性代码，必须同时修复生产者

禁止行为：
- 不要在消费者端添加"万能兼容"函数来掩盖生产者的 bug
- 不要在多个消费者里复制粘贴相同的容错逻辑
- 如果生产者是第三方服务（支付宝回调等），在 consumer 端加防御性代码可以，
  但必须添加注释说明为什么不能修生产者

{
  "boundaries": [
    {
      "name": "payment-service",
      "allow": ["services/payment/...", "shared/protos/..."],
      "deny": ["services/order/...", "services/user/..."]
    },
    {
      "name": "order-service",
      "allow": ["services/order/...", "shared/protos/..."],
      "deny": ["services/payment/...", "services/billing/internal/..."]
    }
  ]
}

# 1. 同步主仓库
git pull origin main

# 2. 看今天的 feature list
cat .ai/features.json

# 3. 为今天的任务创建 Agent workspace
./create-agent-workspace.sh today order

cd /tmp/agent-workspaces/today && claude

读 .ai/features.json，选择一个 passes: false 的功能去做。
做完后：写测试验证 → 更新 features.json → git commit。
只做一个功能，做完就停。

# 在 workspace 里 commit
git add -A && git commit -m "feat(order): 订单成功后通过 gRPC 调用 notification 服务

- 添加 order → notification 的 gRPC client 初始化
- 在订单状态机 SUCCESS 状态触发通知调用
- 单元测试：mock gRPC client 验证调用参数

Feature: f1 of '用户下单成功后发送站内通知'"

# 合并回主仓库
cd /path/to/main/repo
git fetch /tmp/agent-workspaces/today
git merge FETCH_HEAD

# 清理 workspace
rm -rf /tmp/agent-workspaces/today

# 检查今天的 feature list 进度
cat .ai/features.json | grep '"passes": false' | wc -l  # 剩余未完成

CLAUDE_CODE_DISABLE_1M_CONTEXT=1
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70