From 5b6da04a028929608b800f2dd24bd4f5aadca39b Mon Sep 17 00:00:00 2001
From: liuxiongfeng <liuxiongfeng@open-care.com>
Date: Wed, 11 Feb 2026 12:43:45 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20CI=20=E6=A3=80?=
 =?UTF-8?q?=E6=9F=A5=E6=B5=81=E7=A8=8B=EF=BC=8C=E5=BC=BA=E8=B0=83=E6=9C=AC?=
 =?UTF-8?q?=E5=9C=B0=E5=85=88=E6=89=A7=E8=A1=8C=E5=85=A8=E9=83=A8=E6=A3=80?=
 =?UTF-8?q?=E6=9F=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md | 35 +++++++++++++++++++++++++++--------
 CLAUDE.md | 35 +++++++++++++++++++++++++++--------
 2 files changed, 54 insertions(+), 16 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index ccac56d1..577d61c4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -798,18 +798,37 @@ PR 目标是上游官方仓库，**只包含通用功能改动**（bug fix、新
 
 推送到我们自己的 `develop` 或 `main` 分支时，包含所有改动（定制化 + 通用功能）。
 
-**推送流程**：
-1. 本地运行 `cd backend && make test-unit` 确保单元测试通过
-2. 本地运行 `cd backend && gofmt -l ./...` 确保格式正确
-3. 推送后确认 CI 和 Security Scan 两个 workflow 的 4 个 job 全部绿色 ✅
-4. 任何 job 失败必须立即修复，**禁止在 CI 未通过的状态下继续后续操作**
+**推送前必须在本地执行全部 CI 检查**（不要等 GitHub Actions）：
+
+```bash
+# 确保 Go 工具链可用（macOS homebrew）
+export PATH="/opt/homebrew/bin:$HOME/go/bin:$PATH"
+
+# 1. 单元测试（必须）
+cd backend && make test-unit
+
+# 2. 集成测试（推荐，需要 Docker）
+make test-integration
+
+# 3. golangci-lint 静态检查（必须）
+golangci-lint run --timeout=5m
+
+# 4. gofmt 格式检查（必须）
+gofmt -l ./...
+# 如果有输出，运行 gofmt -w <file> 修复
+```
+
+**推送后确认**：
+1. 使用 `gh run list --repo touwaeriol/sub2api --branch <branch>` 检查 GitHub Actions 状态
+2. 确认 CI 和 Security Scan 两个 workflow 的 4 个 job 全部绿色 ✅
+3. 任何 job 失败必须立即修复，**禁止在 CI 未通过的状态下继续后续操作**
 
 ### 发布版本
 
-1. 确保 `main` 分支最新提交的 4 个 CI job 全部通过
+1. 本地执行上述全部 CI 检查通过
 2. 递增 `backend/cmd/server/VERSION`，提交并推送
-3. 打 tag 推送后，确认 tag 触发的 3 个 workflow（CI、Security Scan、Release）全部通过
-4. **Release workflow 失败时禁止部署** — 必须先修复问题，删除旧 tag，重新打 tag
+3. 推送后确认 GitHub Actions 的 4 个 CI job 全部通过
+4. **CI 未通过时禁止部署** — 必须先修复问题
 5. 使用 `gh run list --repo touwaeriol/sub2api --limit 10` 确认状态
 
 ### 常见 CI 失败原因及修复
diff --git a/CLAUDE.md b/CLAUDE.md
index e855e961..c896482e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -839,18 +839,37 @@ PR 目标是上游官方仓库，**只包含通用功能改动**（bug fix、新
 
 推送到我们自己的 `develop` 或 `main` 分支时，包含所有改动（定制化 + 通用功能）。
 
-**推送流程**：
-1. 本地运行 `cd backend && make test-unit` 确保单元测试通过
-2. 本地运行 `cd backend && gofmt -l ./...` 确保格式正确
-3. 推送后确认 CI 和 Security Scan 两个 workflow 的 4 个 job 全部绿色 ✅
-4. 任何 job 失败必须立即修复，**禁止在 CI 未通过的状态下继续后续操作**
+**推送前必须在本地执行全部 CI 检查**（不要等 GitHub Actions）：
+
+```bash
+# 确保 Go 工具链可用（macOS homebrew）
+export PATH="/opt/homebrew/bin:$HOME/go/bin:$PATH"
+
+# 1. 单元测试（必须）
+cd backend && make test-unit
+
+# 2. 集成测试（推荐，需要 Docker）
+make test-integration
+
+# 3. golangci-lint 静态检查（必须）
+golangci-lint run --timeout=5m
+
+# 4. gofmt 格式检查（必须）
+gofmt -l ./...
+# 如果有输出，运行 gofmt -w <file> 修复
+```
+
+**推送后确认**：
+1. 使用 `gh run list --repo touwaeriol/sub2api --branch <branch>` 检查 GitHub Actions 状态
+2. 确认 CI 和 Security Scan 两个 workflow 的 4 个 job 全部绿色 ✅
+3. 任何 job 失败必须立即修复，**禁止在 CI 未通过的状态下继续后续操作**
 
 ### 发布版本
 
-1. 确保 `main` 分支最新提交的 4 个 CI job 全部通过
+1. 本地执行上述全部 CI 检查通过
 2. 递增 `backend/cmd/server/VERSION`，提交并推送
-3. 打 tag 推送后，确认 tag 触发的 3 个 workflow（CI、Security Scan、Release）全部通过
-4. **Release workflow 失败时禁止部署** — 必须先修复问题，删除旧 tag，重新打 tag
+3. 推送后确认 GitHub Actions 的 4 个 CI job 全部通过
+4. **CI 未通过时禁止部署** — 必须先修复问题
 5. 使用 `gh run list --repo touwaeriol/sub2api --limit 10` 确认状态
 
 ### 常见 CI 失败原因及修复