docs(agents): add comprehensive git workflow and review spec #1

JOJO · 2026-04-27T23:18:10+08:00

JOJO commented

2026-04-27 23:18:10 +08:00

改动说明

将 AGENTS.md 第 6 节从 4 行扩展为完整的 Git 工作流规范
新增「场景一：修改源代码」— AI 引导用户走分支→commit→PR 流程
新增「场景二：Review 代码」— AI 自主 checkout→diff→report→approve/reject
新增 tea CLI 安装指南与常用命令速查表
新增合并后清理步骤

为什么改

之前第 6 节只有简单的 commit 格式和 PR 描述要求，缺少完整的工作流指导。现在 AGENTS.md 可以驱动 AI 在开发和 review 两种场景下自动执行标准化流程。

如何验证

本 PR 本身即是新流程的首次实战：切分支 → commit → push → tea pulls create
Review 后使用 tea pulls merge --style squash 合并

风险

无破坏性变更，仅文档修改
AGENTS.md 为 AI 行为指导文件，不影响代码运行

## 改动说明 - 将 AGENTS.md 第 6 节从 4 行扩展为完整的 Git 工作流规范 - 新增「场景一：修改源代码」— AI 引导用户走分支→commit→PR 流程 - 新增「场景二：Review 代码」— AI 自主 checkout→diff→report→approve/reject - 新增 tea CLI 安装指南与常用命令速查表 - 新增合并后清理步骤 ## 为什么改之前第 6 节只有简单的 commit 格式和 PR 描述要求，缺少完整的工作流指导。现在 AGENTS.md 可以驱动 AI 在开发和 review 两种场景下自动执行标准化流程。 ## 如何验证 - 本 PR 本身即是新流程的首次实战：切分支 → commit → push → tea pulls create - Review 后使用 tea pulls merge --style squash 合并 ## 风险 - 无破坏性变更，仅文档修改 - AGENTS.md 为 AI 行为指导文件，不影响代码运行

JOJO added 1 commit 2026-04-27 23:18:11 +08:00

docs(agents): add comprehensive git workflow and review spec 4091730bea

- Expanded section 6 from 4 lines to full workflow guide
- Added 6.2: development scenario (branch → commit → PR)
- Added 6.3: AI review scenario (checkout → diff → report → approve/reject)
- Added tea CLI install guide and command reference

JOJO commented

2026-04-27 23:23:19 +08:00

Review 意见 — PR #1

🔍 需要修改的问题（按优先级）

1. 🟡 approve/reject 操作与安全约束矛盾

6.2 节明确写"禁止 AI 在未经用户确认的情况下执行 git push 或 tea pulls merge"，但 6.3 节第5步却允许 AI 直接执行 tea pulls approve。approve 同样是 PR 状态变更操作，应与 merge 保持一致的确认策略。

👉 建议：在 6.3 节也加入"输出 Review Report 后等待用户确认，再执行 approve/reject"。

2. 🟡 场景一缺少脏工作区处理

6.2 节第1步 git checkout main && git pull origin main 假设工作区干净（无未暂存改动），但日常开发中常有未提交变更导致 checkout 失败。

👉 建议：前置添加 git status 检查，或给出 git stash 回退提示。

3. 🟢 scene 一缺少 tea 前置检查

第3步推送后第4步直接创建 PR，但若 tea 未安装/未认证会卡住。6.5 节是独立说明，流程中未引用。

👉 建议：场景一开头加一句"确保 tea CLI 已安装并认证（详见 6.5 节）"。

4. 🟢 review 后分支清理未说明

tea pulls checkout 会创建本地分支，review 完缺少清理步骤，长久会堆积临时分支。

👉 建议：6.3 节末尾或 6.4 节补充 git checkout main && git branch -D pr-<编号>。

✅ 做得好的

场景驱动设计清晰，AI 容易判定路径
命令示例完整可复制
Squash Merge 策略合理
安全底线明确

结论

🟡 需修改后重新提交。 6 个问题均为建议级别，不影响实质逻辑。修复后可直接通过。

## Review 意见 — PR #1 ### 🔍 需要修改的问题（按优先级） **1. 🟡 approve/reject 操作与安全约束矛盾** 6.2 节明确写"禁止 AI 在未经用户确认的情况下执行 git push 或 tea pulls merge"，但 6.3 节第5步却允许 AI 直接执行 `tea pulls approve`。`approve` 同样是 PR 状态变更操作，应与 merge 保持一致的确认策略。 👉 **建议**：在 6.3 节也加入"输出 Review Report 后等待用户确认，再执行 approve/reject"。 --- **2. 🟡 场景一缺少脏工作区处理** 6.2 节第1步 `git checkout main && git pull origin main` 假设工作区干净（无未暂存改动），但日常开发中常有未提交变更导致 checkout 失败。 👉 **建议**：前置添加 `git status` 检查，或给出 `git stash` 回退提示。 --- **3. 🟢 scene 一缺少 tea 前置检查** 第3步推送后第4步直接创建 PR，但若 tea 未安装/未认证会卡住。6.5 节是独立说明，流程中未引用。 👉 **建议**：场景一开头加一句"确保 tea CLI 已安装并认证（详见 6.5 节）"。 --- **4. 🟢 review 后分支清理未说明** `tea pulls checkout` 会创建本地分支，review 完缺少清理步骤，长久会堆积临时分支。 👉 **建议**：6.3 节末尾或 6.4 节补充 `git checkout main && git branch -D pr-<编号>`。 --- ### ✅ 做得好的 - 场景驱动设计清晰，AI 容易判定路径 - 命令示例完整可复制 - Squash Merge 策略合理 - 安全底线明确 --- ### 结论 **🟡 需修改后重新提交。** 6 个问题均为建议级别，不影响实质逻辑。修复后可直接通过。

JOJO closed this pull request

2026-04-27 23:38:07 +08:00

JOJO referenced this pull request

2026-04-27 23:44:39 +08:00

docs(agents): add CLI troubleshooting and fix cleanup commands #2